Working? MVP of the minigame

2025-12-07 20:34:12 +01:00
parent 421c4d5cbd
commit ffdde1f5e1
67 changed files with 8370 additions and 192 deletions
--- a/docs/airplane_interactive_elements_readme.md
+++ b/docs/airplane_interactive_elements_readme.md
@@ -0,0 +1,296 @@
+# 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
+