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