AppleHillsProduction/docs/airplane_minigame_setup.md

# Airplane Minigame - Unity Setup Guide

**Implementation Status**: ✅ Code Complete  
**Setup Time**: ~20 minutes  
**Assets Required**: 0 ScriptableObjects (all settings-based!)

---

## What's Been Implemented

### Core Features
✅ **3 Airplane Types** - Jet, Bobbing, Drop (settings-based configuration)  
✅ **3 Unique Abilities** - Hold to boost, tap to jump, tap to dive  
✅ **Pre-Game Selection UI** - Choose airplane before game starts  
✅ **In-Flight Ability Button** - Shows icon, cooldown, and handles input  
✅ **Pre-Spawn System** - Airplane visible at slingshot before launch  
✅ **Cooldown Management** - Visual fill animation and state tracking  
✅ **InputManager Integration** - Proper touch handling (no legacy Input)  
✅ **Adaptive Spawning** - Retry keeps same obstacles, success regenerates  
✅ **Person Reactions** - Success/failure behaviors with proper sequencing  

### Game Flow
```
Game Start → Airplane Selection → Intro → Person Turn → Aiming (airplane at slingshot) 
→ Launch → Flying (ability button active) → Hit/Miss → Reaction → Next Person/Retry
```

---

## Unity Setup Steps

### STEP 1: Configure Airplane Settings (5 minutes)

**Location**: `Tools > Settings > Airplane Settings`

You'll see collapsible sections for each airplane type. Configure:

#### **Jet Plane**
```
Display Name: "Jet Plane"
Prefab: [Assign airplane prefab with sprite/model]
Preview Sprite: [Assign for selection UI]
Ability Type: Jet (already set)

Physics Overrides (optional):
☐ Override Mass
☐ Override Gravity Scale  
☐ Override Drag
```

#### **Jet Ability**
```
Ability Name: "Jet Boost"
Ability Icon: [Assign sprite for button]
Cooldown Duration: 5.0 seconds
Jet Speed: 15.0
Jet Angle: 0 (flies horizontally)
```

#### **Bobbing Plane**
```
Display Name: "Bobbing Plane"
Prefab: [Assign airplane prefab]
Preview Sprite: [Assign for selection UI]
Ability Type: Bobbing (already set)

Physics Overrides (optional):
☐ Override Mass
☐ Override Gravity Scale
☐ Override Drag
```

#### **Bobbing Ability**
```
Ability Name: "Air Hop"
Ability Icon: [Assign sprite for button]
Cooldown Duration: 3.0 seconds
Bob Jump Force: 10.0
Speed Reduction: 0.7 (70% of original speed)
```

#### **Drop Plane**
```
Display Name: "Drop Plane"
Prefab: [Assign airplane prefab]
Preview Sprite: [Assign for selection UI]
Ability Type: Drop (already set)

Physics Overrides (optional):
☐ Override Mass
☐ Override Gravity Scale
☐ Override Drag
```

#### **Drop Ability**
```
Ability Name: "Dive Bomb"
Ability Icon: [Assign sprite for button]
Cooldown Duration: 4.0 seconds
Drop Force: 20.0
Drop Distance: 5.0
☑ Zero Horizontal Velocity
```

#### **Default Selection**
```
Default Airplane Type: Jet (or your preference)
```

**Note**: If all 3 airplane prefabs are the same, that's fine! The abilities are what differentiate them.

---

### STEP 2: Build Selection UI (10 minutes)

**Create Hierarchy**: `Canvas/AirplaneSelectionPanel`

```
AirplaneSelectionPanel (GameObject)
├── BackgroundImage (Image - semi-transparent dark overlay)
├── TitleText (TextMeshPro)
│   └── Text: "Choose Your Airplane"
├── ButtonContainer (GameObject + Horizontal Layout Group)
│   ├── JetButton (Button)
│   │   ├── Background (Image)
│   │   ├── Icon (Image - jet plane icon)
│   │   └── Label (TextMeshPro: "Jet Plane")
│   ├── BobbingButton (Button)
│   │   ├── Background (Image)
│   │   ├── Icon (Image - bobbing plane icon)
│   │   └── Label (TextMeshPro: "Bobbing Plane")
│   └── DropButton (Button)
│       ├── Background (Image)
│       ├── Icon (Image - drop plane icon)
│       └── Label (TextMeshPro: "Drop Plane")
└── ConfirmButton (Button)
    └── Label (TextMeshPro: "Confirm")
```

**Add Component**: `AirplaneSelectionUI` to `AirplaneSelectionPanel`

**Configure Component**:
- Jet Plane Button → Drag `JetButton`
- Bobbing Plane Button → Drag `BobbingButton`
- Drop Plane Button → Drag `DropButton`
- Confirm Button → Drag `ConfirmButton`
- Selected Color: `#FFFF00` (yellow)
- Normal Color: `#FFFFFF` (white)

**Important**: ☑ Set panel **inactive** in Inspector (checkbox next to name)

---

### STEP 3: Build Ability Button (5 minutes)

**Create Hierarchy**: `Canvas/GameplayUI/AbilityButton`

```
AbilityButton (GameObject)
├── ButtonBackground (Image - circular)
├── AbilityIcon (Image - set dynamically)
├── CooldownFill (Image)
│   └── Image Type: Filled
│   └── Fill Method: Radial 360
│   └── Fill Origin: Top
│   └── Clockwise: ☑
└── CooldownText (TextMeshPro - optional)
```

**Add Component**: `AirplaneAbilityButton` to `AbilityButton`

**Configure Component**:
- Button → Drag Button component reference
- Ability Icon → Drag `AbilityIcon` Image
- Cooldown Fill → Drag `CooldownFill` Image
- Cooldown Text → Drag `CooldownText` (optional)
- Ready Color: `#FFFFFF` (white)
- Cooldown Color: `#808080` (gray)
- Active Color: `#FFFF00` (yellow)

**Position**: Bottom-right corner (accessible for thumb on mobile)

**Important**: ☑ Set button **inactive** in Inspector (checkbox next to name)

---

### STEP 4: Wire Game Manager (2 minutes)

**GameObject**: `AirplaneGameManager`

**Assign New References**:
- Selection UI → Drag `AirplaneSelectionPanel`
- Ability Button → Drag `AbilityButton`

**Verify Existing References** (should already be assigned):
- Person Queue
- Camera Manager
- Launch Controller
- Target Validator
- Spawn Manager

---

## Testing Checklist

### Selection UI
- [ ] Panel appears on game start
- [ ] Clicking button highlights it (turns yellow)
- [ ] Confirm button enables after selection
- [ ] Clicking confirm hides panel and starts game

### Airplane Spawning
- [ ] Selected airplane appears at slingshot
- [ ] Airplane stays in place (not falling)
- [ ] Trajectory preview works
- [ ] Launching works correctly

### Jet Ability (Hold to Activate)
- [ ] Button appears after launch with jet icon
- [ ] **Hold button** → Airplane flies straight (no gravity)
- [ ] **Release button** → Gravity returns
- [ ] Cooldown fill animates 1.0 → 0.0
- [ ] Button grays out during cooldown
- [ ] Can use again after cooldown ends

### Bobbing Ability (Tap to Activate)
- [ ] Button appears after launch with bobbing icon
- [ ] **Tap button** → Airplane jumps upward
- [ ] Speed reduces after jump
- [ ] Cooldown starts immediately
- [ ] Can use multiple times per flight

### Drop Ability (Tap to Activate)
- [ ] Button appears after launch with drop icon
- [ ] **Tap button** → Airplane drops straight down
- [ ] Stops dropping after configured distance
- [ ] Cooldown starts after drop ends
- [ ] Can use again after cooldown

### Integration
- [ ] Ability button hides after turn ends
- [ ] Retry uses same airplane type
- [ ] Success switches to next person (can choose again if cycling)
- [ ] No console errors
- [ ] Performance is smooth

---

## How Abilities Work

### Jet Ability - "Jet Boost"
**Input**: Hold button down  
**Effect**: Flies straight at constant speed, ignoring gravity  
**Duration**: While held (player controlled)  
**Cooldown**: After release  
**Use Case**: Fly over obstacles, reach distant targets

### Bobbing Ability - "Air Hop"
**Input**: Tap button  
**Effect**: Jump upward, lose horizontal speed  
**Duration**: Instant  
**Cooldown**: After activation  
**Use Case**: Gain altitude, avoid low obstacles, extend flight time

### Drop Ability - "Dive Bomb"
**Input**: Tap button  
**Effect**: Drop straight down for fixed distance  
**Duration**: Until distance reached  
**Cooldown**: After drop completes  
**Use Case**: Precision strikes, hitting low targets

---

## Architecture Overview

### Settings-Based System (No Assets Required!)

**Old Way** (NOT used):
- Create JetAbility.asset
- Create BobbingAbility.asset
- Create DropAbility.asset
- Create JetPlaneType.asset
- Create BobbingPlaneType.asset
- Create DropPlaneType.asset
- Wire references everywhere

**New Way** (Implemented):
- Configure everything in `AirplaneSettings` (one file!)
- Abilities created at runtime from settings
- Enum-based selection (`AirplaneAbilityType.Jet/Bobbing/Drop`)
- No asset management needed

### Code Structure

```
AirplaneSettings (ScriptableObject)
├─ Jet Plane Config + Jet Ability Config
├─ Bobbing Plane Config + Bobbing Ability Config
└─ Drop Plane Config + Drop Ability Config

AbilityFactory
└─ Creates ability instances from settings at runtime

BaseAirplaneAbility (abstract class)
├─ JetAbility (hold to fly straight)
├─ BobbingAbility (tap to jump)
└─ DropAbility (tap to dive)

Game Flow
├─ AirplaneSelectionUI (choose type)
├─ AirplaneController (initialized with type)
├─ AirplaneAbilityButton (shows during flight)
└─ AbilityFactory (creates ability on demand)
```

### Input System Integration

✅ Uses project's `InputManager` (no legacy Unity Input)  
✅ Implements `ITouchInputConsumer` interface  
✅ Override consumer registration for priority input  
✅ Proper hold/release detection for Jet ability  
✅ Works on mobile and desktop  

---

## Troubleshooting

### Selection UI doesn't appear
- Check `AirplaneGameManager.selectionUI` is assigned
- Verify panel is inactive by default
- Check console for errors

### Airplane doesn't spawn at slingshot
- Verify prefab is assigned in settings for selected type
- Check `LaunchController` has launch anchor assigned
- Check console for "Cannot spawn" errors

### Ability button doesn't appear
- Verify `AirplaneGameManager.abilityButton` is assigned
- Check button is inactive by default
- Ensure airplane was initialized with type
- Check console for ability creation errors

### Hold doesn't work for Jet ability
- Verify `InputManager` exists in scene
- Check button implements `ITouchInputConsumer`
- Try click-and-hold with mouse first
- Check console for registration messages

### Cooldown fill doesn't animate
- Verify `CooldownFill` Image is assigned
- Check Fill Type is set to "Filled"
- Verify Fill Method is "Radial 360"
- Check fill amount starts at 0

### Wrong airplane spawns
- Check which type was selected in Selection UI
- Verify correct prefab is assigned in settings
- Check console logs for "Selected airplane: [type]"

---

## Advanced Configuration

### Physics Tuning Per Airplane

You can override physics per airplane type in settings:

**Lighter Airplane** (faster, less stable):
```
☑ Override Mass: 0.8
☑ Override Gravity Scale: 0.9
☑ Override Drag: 0.1
```

**Heavier Airplane** (slower, more stable):
```
☑ Override Mass: 1.2
☑ Override Gravity Scale: 1.1
☑ Override Drag: 0.3
```

### Ability Balance

**Make abilities more powerful**:
- Increase Jet Speed (15 → 20)
- Increase Bob Jump Force (10 → 15)
- Increase Drop Force (20 → 30)

**Make abilities have shorter cooldowns**:
- Jet: 5s → 3s
- Bobbing: 3s → 2s
- Drop: 4s → 3s

**Make abilities last longer**:
- Drop Distance: 5 → 8 (drops farther)

---

## Common Questions

**Q: Do I need different airplane prefabs for each type?**  
A: No! You can use the same prefab for all three. The abilities differentiate them.

**Q: Can I add a 4th airplane type?**  
A: Yes! Add enum value → Create config classes → Add to settings → Update factory. See full docs for details.

**Q: Can I skip the selection UI?**  
A: Yes! Leave `selectionUI` unassigned in GameManager. The default type from settings will be used.

**Q: What if I don't assign ability icons?**  
A: The button will work but show no icon. It's recommended to assign icons for clarity.

**Q: Can abilities be disabled?**  
A: Currently no, but you could set cooldown to 999 to effectively disable them.

**Q: How do I test a specific airplane without the selection UI?**  
A: Set the default type in settings, then don't assign the selection UI to GameManager.

---

## Performance Notes

- Abilities are created once per airplane (lightweight)
- Cooldown updates every frame (negligible cost)
- UI updates only during cooldown (efficient)
- No GC allocations during ability use
- Factory pattern avoids reflection overhead

---

## Summary

### What Code Does (Already Implemented)
✅ Manages game state and flow  
✅ Creates abilities from settings at runtime  
✅ Handles airplane spawning and initialization  
✅ Updates cooldowns and ability state  
✅ Proper input handling via InputManager  

### What You Do (Unity Setup)
1. Configure 3 airplane types + abilities in settings (**5 min**)
2. Build selection UI panel with buttons (**10 min**)
3. Build ability button with cooldown fill (**5 min**)
4. Wire 2 references to GameManager (**2 min**)
5. Test! (**5 min**)

**Total Time: ~27 minutes to full functionality** ⚡

---

## Quick Start Checklist

Setup:
- [ ] Open `AirplaneSettings`, configure 3 airplane types
- [ ] Assign prefabs and sprites for all types
- [ ] Assign ability icons for all abilities
- [ ] Set default airplane type
- [ ] Create `AirplaneSelectionPanel` with 3 buttons
- [ ] Add `AirplaneSelectionUI` component, wire buttons
- [ ] Create `AbilityButton` with icon + cooldown fill
- [ ] Add `AirplaneAbilityButton` component, wire references
- [ ] Assign both UI references to `AirplaneGameManager`
- [ ] Set both UI elements inactive by default

Testing:
- [ ] Play → Selection appears
- [ ] Select → Confirm → Airplane spawns
- [ ] Launch → Ability button appears
- [ ] Use ability → Works correctly
- [ ] Cooldown → Animates and resets
- [ ] Turn ends → Button hides
- [ ] Retry → Same airplane
- [ ] Success → Next person

When all checked → System complete! 🎉

---

**Documentation Version**: 1.0  
**Last Updated**: December 6, 2025  
**Implementation**: Settings-Based Architecture  
**Assets Required**: 0 ScriptableObjects ✅