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:

// 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):

windForce = new Vector2(8, 0);  // Strong horizontal push

Downdraft (obstacle):

windForce = new Vector2(0, -7);  // Downward force

Angled Wind:

windForce = new Vector2(3, 5);  // Diagonal force
isWorldSpace = false;  // Rotate with transform

Bouncy Surface Variants

Weak Bounce:

bounceMultiplier = 1.2f;

Super Bounce:

bounceMultiplier = 2.5f;
maxBounceVelocity = 30f;

Angled Bouncer:

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