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 ✅