AppleHillsProduction/docs/airplane_interactive_elements_readme.md

# Airplane Interactive Elements - MVP Collection

This collection provides 5 interactive elements (boons and obstacles) for the airplane minigame MVP.

## 📦 Components Overview

### ✅ Positive Effects (Boons)

#### 1. **AirplaneWindZone** - Updraft Helper
**Purpose:** Provides constant upward force to help keep airplane airborne.

**Setup:**
- Add component to GameObject with 2D Collider (Box/Circle)
- Set `Wind Force` to `(0, 5)` for gentle updraft
- Enable `Is World Space` for consistent direction
- Optional: Attach ParticleSystem for visual wind effect

**Use Cases:**
- Updrafts after difficult sections
- Safe zones between obstacles
- Wind tunnels that guide toward target

---

#### 2. **AirplaneBouncySurface** - Trampoline
**Purpose:** Bounces airplane on contact with configurable multiplier.

**Setup:**
- Add component to GameObject with 2D Collider
- Set `Bounce Multiplier` to `1.5` (default) or `2.0` for strong bounce
- Set `Bounce Direction` to `(0, 1)` for upward bounce
- Enable `Use Reflection` to bounce based on impact angle
- Optional: Add Animator and AudioSource for feedback

**Use Cases:**
- Springboards to reach high targets
- Angled bouncers to redirect flight path
- Fun trick shots

---

#### 3. **AirplaneSpeedRing** - Boost Collectible
**Purpose:** Increases velocity when airplane passes through.

**Setup:**
- Add component to GameObject with 2D Circle Collider
- Set `Velocity Multiplier` to `1.5`
- Set `Boost Duration` (currently instant, can be extended)
- Enable `One Time Use` to make it a collectible
- Optional: Add ParticleSystem and AudioSource

**Use Cases:**
- Checkpoint rings along flight path
- Speed boosts before difficult sections
- Collectibles that reward exploration

---

### ❌ Negative Effects (Obstacles)

#### 4. **AirplaneTurbulenceZone** - Chaotic Wind
**Purpose:** Adds random forces that make control unpredictable.

**Setup:**
- Add component to GameObject with 2D Collider (usually Box)
- Set `Turbulence Strength` to `3` (moderate) or `5` (strong)
- Set `Change Frequency` to `0.1` for rapid changes
- Enable `Prevent Upward Force` if you want only downward chaos
- Optional: Add ParticleSystem for swirling effect

**Use Cases:**
- Storm clouds that destabilize flight
- Dangerous zones between safe paths
- Areas that require ability usage to survive

---

#### 5. **AirplaneGravityWell** - Danger Zone
**Purpose:** Pulls airplane toward center, creating hazard to avoid.

**Setup:**
- Add component to GameObject with 2D Circle Collider
- Set `Pull Strength` to `5` (moderate pull)
- Enable `Use Inverse Square` for realistic gravity falloff
- Adjust `Pull Falloff` curve for custom attraction profile
- Optional: Add rotating sprite and particle effect

**Use Cases:**
- Black holes or vortexes to avoid
- Creates skill-based navigation challenges
- Forces players to use abilities to escape

---

## 🎮 Integration with Spawn System

All components check for `AirplaneController` and `IsFlying` status, so they only affect active airplanes.

### Spawning as Obstacles/Boons

To integrate with your existing spawn system:

```csharp
// In AirplaneSpawnManager or similar
public GameObject updraftPrefab;
public GameObject turbulencePrefab;
public GameObject speedRingPrefab;

void SpawnRandomElements(float xPosition)
{
    // Randomly spawn helpful or harmful elements
    float roll = Random.value;
    
    if (roll < 0.3f)
    {
        // Spawn updraft (30%)
        SpawnElement(updraftPrefab, xPosition);
    }
    else if (roll < 0.5f)
    {
        // Spawn turbulence (20%)
        SpawnElement(turbulencePrefab, xPosition);
    }
    else if (roll < 0.7f)
    {
        // Spawn speed ring (20%)
        SpawnElement(speedRingPrefab, xPosition);
    }
}
```

---

## 🎨 Visual Setup Recommendations

### Updraft (Wind Zone)
- **Color:** Light blue/cyan
- **Particles:** Upward flowing particles
- **Sound:** Gentle whoosh

### Bouncy Surface
- **Color:** Orange/yellow
- **Animation:** Compress on impact
- **Sound:** "Boing" spring sound

### Speed Ring
- **Color:** Golden yellow
- **Particles:** Spark burst on collect
- **Sound:** Satisfying "ding" or chime

### Turbulence Zone
- **Color:** Dark gray/purple
- **Particles:** Chaotic swirling
- **Sound:** Storm/wind ambience

### Gravity Well
- **Color:** Magenta/purple
- **Particles:** Inward spiral
- **Sound:** Low ominous hum
- **Visual:** Rotating vortex sprite

---

## 🔧 Configuration Tips

### Balancing Positive vs Negative

**For easier gameplay:**
- More updrafts and speed rings
- Weaker turbulence (strength 2-3)
- Smaller gravity wells

**For harder gameplay:**
- Stronger turbulence (strength 5-7)
- Larger gravity wells with higher pull
- Fewer boons, more obstacles

### Placement Strategy

**Good Flow:**
1. Start with safe updrafts
2. Introduce single obstacle (turbulence)
3. Provide speed ring as reward
4. Place gravity well with clear path around it
5. Updraft after dangerous section

**Challenge Flow:**
1. Turbulence → Gravity Well combo
2. Narrow path with bouncy surfaces on sides
3. Speed ring that leads into obstacle (trap!)
4. Multiple gravity wells requiring weaving

---

## 🐛 Debugging

All components have:
- `showDebugLogs` - Enable console logging
- Gizmo visualization in Scene view
- Color-coded for easy identification

**Gizmo Colors:**
- 🟢 Green = Positive force (updraft)
- 🔴 Red = Negative force (downdraft/danger)
- 🟡 Yellow = Neutral/collectible
- 🟠 Orange = Turbulence
- 🟣 Magenta = Gravity well

---

## ⚙️ Advanced Customization

### Wind Zone Variants

**Crosswind (pushes sideways):**
```csharp
windForce = new Vector2(8, 0);  // Strong horizontal push
```

**Downdraft (obstacle):**
```csharp
windForce = new Vector2(0, -7);  // Downward force
```

**Angled Wind:**
```csharp
windForce = new Vector2(3, 5);  // Diagonal force
isWorldSpace = false;  // Rotate with transform
```

### Bouncy Surface Variants

**Weak Bounce:**
```csharp
bounceMultiplier = 1.2f;
```

**Super Bounce:**
```csharp
bounceMultiplier = 2.5f;
maxBounceVelocity = 30f;
```

**Angled Bouncer:**
```csharp
bounceDirection = new Vector2(1, 1).normalized;  // 45° bounce
useReflection = false;
```

---

## 📊 Performance Considerations

- All components use `OnTriggerStay2D` which is called every physics frame
- Wind and Turbulence zones are most expensive (constant force application)
- Speed rings are cheapest (one-time trigger)
- Consider pooling for frequently spawned elements
- Use `oneTimeUse` on speed rings to auto-cleanup

---

## 🚀 Next Steps for Full Version

**Additional Elements to Consider:**
- Checkpoint Hoops (with score/time bonus)
- Gravity Flip Zones (inverts gravity temporarily)
- Portals (teleportation)
- Spinning Hazards (rotating obstacles)
- Launch Pads (explosive boost)
- Sticky Zones (slow down effect)

**System Improvements:**
- Element spawning rules based on difficulty
- Combination elements (updraft + speed ring)
- Progressive difficulty scaling
- Visual effects library
- Sound effect integration

---

## 📝 Quick Reference Table

| Component | Type | Primary Effect | Strength Range |
|-----------|------|---------------|----------------|
| WindZone | Boon/Obstacle | Constant force | 3-10 |
| BouncySurface | Boon | Velocity reflection | 1.2-2.5x |
| SpeedRing | Boon | Velocity boost | 1.3-2.0x |
| TurbulenceZone | Obstacle | Random chaos | 3-7 |
| GravityWell | Obstacle | Pull to center | 5-15 |

---

**Created:** December 2025  
**Version:** 1.0 MVP  
**Status:** Ready for Unity integration