AppleHillsProduction/docs/airplane_unity_setup_quickref.md

# Airplane Minigame - Unity Setup Quick Reference

## Scene Hierarchy Setup

### 1. Game Manager (Empty GameObject)
- **Name**: `AirplaneGameManager`
- **Component**: `AirplaneGameManager` script
- **Configure**:
  - Person Queue: Assign PersonQueue GameObject
  - Camera Manager: Assign AirplaneCameraManager GameObject
  - Launch Controller: Assign AirplaneLaunchController GameObject
  - Target Validator: Assign AirplaneTargetValidator GameObject
  - Spawn Manager: Assign AirplaneSpawnManager GameObject
  - All Targets: Assign all AirplaneTarget components in scene

### 2. Person Queue (Empty GameObject)
- **Name**: `PersonQueue`
- **Component**: `PersonQueue` script
- **Configure**:
  - People In Queue: Assign Person GameObjects in order (index 0 goes first)
  - Shuffle Duration: 0.5f (time for people to shuffle when someone succeeds)
  - Shuffle Distance: 2f (how far people move during shuffle)

### 3. People (Create one per participant)
- **Name**: Person's name (e.g., "Alice", "Bob", "Charlie")
- **Component**: `Person` script
- **Add Child**: TextMeshPro - Text component for debug messages
- **Configure Person Component**:
  - Person Name: Auto-fills from GameObject name
  - Target Name: The target this person needs to hit (e.g., "TargetA")
  - Debug Text: Assign the TextMeshPro child component
  - Show Debug Logs: Optional, for debugging
- **Position**: Place in scene where you want people to stand

### 4. Camera Manager (Empty GameObject)
- **Name**: `AirplaneCameraManager`
- **Component**: `AirplaneCameraManager` script
- **Configure**:
  - Intro Camera: Camera for game introduction
  - Next Person Camera: Camera for person transitions
  - Aiming Camera: Camera for aiming/launching
  - Follow Camera: Camera that follows airplane (should have FollowTarget component)
  - Blend Duration: 1.0f (camera transition time)

### 5. Launch Controller
- **Name**: `LaunchController`
- **Component**: `AirplaneLaunchController` script (inherits from DragLaunchController)
- **Configure**:
  - Airplane Prefab: Assign airplane prefab with AirplaneController
  - Launch Point: Where airplane spawns
  - Max Drag Distance: Maximum slingshot pull distance
  - Launch Force Multiplier: Strength of launch
  - Trajectory Preview: Assign TrajectoryPreview component

### 6. Trajectory Preview (Attach to Launch Controller or separate)
- **Component**: `TrajectoryPreview` script
- **Component**: `LineRenderer` (auto-required)
- **Configure**:
  - Trajectory Points: 50
  - Time Step: 0.1f
  - Ground Level: Y position where trajectory stops
  - Line Color: Yellow (or preferred color)
  - Line Width: 0.1f

### 7. Target Validator (Empty GameObject)
- **Name**: `TargetValidator`
- **Component**: `AirplaneTargetValidator` script
- No configuration needed (targets are set at runtime)

### 8. Spawn Manager (Empty GameObject with child containers)
- **Name**: `SpawnManager`
- **Component**: `AirplaneSpawnManager` script
- **Create Children**:
  - `SpawnedObjects` (empty, for organization)
  - `GroundTiles` (empty, for organization)
- **Configure**:
  - Target Prefabs: Array of target key/prefab pairs
    - Key: Must match Person's Target Name (e.g., "TargetA")
    - Prefab: Target prefab with SpriteRenderer (for icon)
  - Positive Object Prefabs: Array of collectible/good prefabs
  - Negative Object Prefabs: Array of obstacle/bad prefabs
  - Ground Tile Prefabs: Array of ground/platform prefabs
  - Target Display UI: Assign TargetDisplayUI component
  - Spawned Objects Parent: Assign SpawnedObjects child
  - Ground Tiles Parent: Assign GroundTiles child

### 9. Target Display UI (Canvas child)
- **Name**: `TargetDisplayUI`
- **Component**: `TargetDisplayUI` script
- **Create Children**:
  - `TargetIcon` (Image component) - Shows target sprite
  - `DistanceText` (TextMeshProUGUI) - Shows distance remaining
- **Configure**:
  - Target Icon: Assign TargetIcon Image component
  - Distance Text: Assign DistanceText component
  - Distance Format: "{0:F1}m" (or preferred format)
  - Update Interval: 5 (frames between updates, 0=every frame)
- **Position**: Top corner or preferred UI location

### 10. Targets (Create multiple)
- **Name**: Target identifier (e.g., "TargetA", "TargetB")
- **Component**: `AirplaneTarget` script
- **Component**: `Collider2D` with "Is Trigger" enabled
- **Component**: `SpriteRenderer` (required for icon extraction)
- **Configure AirplaneTarget**:
  - Target Name: Unique identifier (e.g., "TargetA")
  - Show Debug Logs: Optional

### 11. Airplane Prefab (Create as prefab)
- **Component**: `AirplaneController` script
- **Component**: `Rigidbody2D` set to Kinematic mode (physics calculated manually)
- **Component**: `Collider2D` with "Is Trigger" enabled
- **Configure AirplaneController**:
  - Drag Coefficient: 0.01f
  - Timeout Duration: 10f (auto-stop after this time)
  - Show Debug Logs: Optional

## Settings Configuration

### Airplane Settings Asset
1. Open Settings Window: `Tools > Settings > Airplane Settings`
2. **If not visible**: Add `AirplaneSettings` to `SettingsEditorWindow.cs` (see Settings README)
3. **Configure**:
   
   **Slingshot Settings**:
   - Max Drag Distance: 5f
   - Launch Force Multiplier: 10f
   - Min Launch Force: 2f
   - Drag Speed: 5f
   - Mass: 1f (projectile mass for trajectory calculations)
   
   **Flight Settings**:
   - Airplane Mass: 1f
   - Max Flight Time: 10f
   
   **Spawn System** (NEW):
   - Dynamic Spawn Threshold: 10f (X position where spawning begins)
   - Target Min Distance: 30f
   - Target Max Distance: 50f
   - Object Spawn Min Interval: 1f (seconds between object spawns)
   - Object Spawn Max Interval: 3f
   - Positive Negative Ratio: 0.5f (0=all negative, 1=all positive)
   - Spawn Distance Ahead: 15f (how far ahead to spawn objects)
   - Ground Spawn Interval: 5f (distance between ground tiles)
   
   **Timing**:
   - Intro Duration: 1f
   - Person Intro Duration: 1f
   - Evaluation Duration: 1f

## Testing Checklist

### Pre-Flight Check
- [ ] All Person components have Debug Text assigned
- [ ] PersonQueue has all people assigned in correct order
- [ ] Each Person has a unique Target Name assigned
- [ ] Matching Targets exist in scene with same names
- [ ] Camera Manager has all 4 cameras assigned
- [ ] Launch Controller has Airplane Prefab assigned
- [ ] AirplaneGameManager has all systems assigned
- [ ] Spawn Manager has target prefabs with matching keys
- [ ] Spawn Manager has positive/negative/ground prefabs assigned
- [ ] Target Display UI is created and assigned in Spawn Manager
- [ ] All target prefabs have SpriteRenderer components

### Test Flow
1. **Start Game** → Should blend to intro camera
2. **Introductions** → Each person should display greeting message
3. **First Turn** → Should blend to aiming camera
4. **Target Spawned** → Target appears at configured distance
5. **UI Display** → Target icon and distance shown
6. **Aiming** → Drag to aim, trajectory preview should show
7. **Launch** → Airplane should fly along predicted path
8. **Threshold Cross** → Dynamic spawning begins
9. **Objects Spawn** → Positive/negative objects appear ahead of plane
10. **Ground Spawns** → Ground tiles appear at intervals
11. **Distance Updates** → UI distance decreases as plane approaches
12. **Hit Target** → Person celebrates, gets removed, queue shuffles
13. **Cleanup** → All spawned objects destroyed
14. **Miss Target** → Person shows disappointment, stays in queue
15. **Next Turn** → New target spawned, repeat
16. **Game Over** → When queue is empty

## Common Issues

### Trajectory doesn't match flight path
- Ensure airplane prefab has Rigidbody2D with correct mass
- Verify Slingshot Settings mass matches projectile
- Check gravity scale in Rigidbody2D settings

### People don't show messages
- Assign TextMeshPro component to Debug Text field
- Check that text GameObject is a child of Person

### Camera doesn't follow airplane
- Ensure Follow Camera has FollowTarget component
- Verify AirplaneCameraManager has Follow Camera assigned

### Targets not detected
- Ensure both airplane and targets have Collider2D components
- Set "Is Trigger" on both colliders
- Check layer collision matrix in Project Settings

### Launch doesn't work
- Verify Input Manager is properly configured
- Check Launch Controller is enabled
- Ensure Airplane Prefab is assigned

### Target doesn't spawn
- Check Person's Target Name matches Spawn Manager key exactly
- Verify target prefab is assigned in Target Prefabs array
- Ensure target prefab has SpriteRenderer for icon

### Wrong target icon displayed
- Verify target prefab has SpriteRenderer component
- Check SpriteRenderer has sprite assigned
- Try adding SpriteRenderer as direct child of root

### Objects spawn too early/late
- Adjust Dynamic Spawn Threshold setting
- Check plane transform is passed to StartTracking

### Positive/negative ratio not maintained
- Algorithm self-adjusts after first 5 spawns
- Verify Positive Negative Ratio is 0-1
- Spawn more objects to see ratio converge

### Distance not updating
- Check Target Display UI is assigned in Spawn Manager
- Verify Update Interval is not too high
- Ensure UI is shown when tracking starts

## Script References

### Core Scripts
- `AirplaneGameManager.cs` - Main game orchestrator
- `PersonQueue.cs` - Manages person queue and transitions
- `Person.cs` - Individual person data and reactions
- `AirplaneSpawnManager.cs` - Dynamic spawning system (NEW)

### Gameplay Scripts
- `AirplaneLaunchController.cs` - Handles aiming and launching
- `AirplaneController.cs` - Airplane flight behavior
- `AirplaneTarget.cs` - Target collision detection
- `AirplaneTargetValidator.cs` - Validates hits vs expected targets

### UI Scripts
- `TargetDisplayUI.cs` - Target distance display (NEW)

### Camera Scripts
- `AirplaneCameraManager.cs` - Camera state management

### Common/Shared Scripts
- `DragLaunchController.cs` - Base slingshot mechanics
- `CameraManager<T>.cs` - Generic camera state system
- `TrajectoryPreview.cs` - Visual trajectory prediction

### Settings
- `IAirplaneSettings` - Settings interface
- `AirplaneSettings.cs` - Settings implementation

## Next Steps

1. **Visual Polish**: Replace debug text with proper animations
2. **Audio**: Add sound effects for launch, hit, miss, celebrations, spawns
3. **VFX**: Add particle effects for launch, flight trail, hit impact, spawns
4. **UI**: Add score display, turn counter, success rate, combo meter
5. **Targets**: Add visual feedback when hit/missed
6. **People**: Add character models and animations
7. **Airplane**: Add proper airplane model with flight animations
8. **Spawned Objects**: Add collision/scoring logic to positive/negative objects
9. **Ground Tiles**: Add seamless scrolling ground system
10. **Power-ups**: Add special spawned objects with unique effects

## Additional Documentation

For detailed information about the spawn system:
- See `docs/airplane_spawn_system_guide.md` for complete spawn system documentation
- See `docs/person_integration_summary.md` for person queue system
- See `docs/airplane_implementation_summary.md` for overall architecture