AppleHillsProduction/docs/airplane_abilities_settings_based.md

Airplane Selection & Abilities - SETTINGS-BASED IMPLEMENTATION

Date: December 6, 2025
Status: ✅ COMPLETE - Pure Settings Configuration

---

🎯 SIMPLIFIED ARCHITECTURE

NO ScriptableObject assets needed! Everything configured in AirplaneSettings.

Key Changes from Previous Design:

• ❌ No AirplaneTypeData ScriptableObjects to create
• ❌ No ability ScriptableObjects to create
• ✅ All configuration in AirplaneSettings asset
• ✅ Abilities created from settings at runtime
• ✅ Simple enum selection (Jet/Bobbing/Drop)

---

📋 IN-ENGINE SETUP (3 SIMPLE STEPS)

STEP 1: Configure Settings (5 minutes)

Open Tools > Settings > Airplane Settings

You'll see collapsible sections for each airplane type:

Jet Plane Configuration

Display Name: "Jet Plane"
Prefab: [Assign jet airplane prefab]
Preview Sprite: [Assign preview image]
Ability Type: Jet
Override Mass: □ (optional)
Override Gravity Scale: □ (optional)
Override Drag: □ (optional)

Jet Ability:
├─ Ability Name: "Jet Boost"
├─ Ability Icon: [Assign icon sprite]
├─ Cooldown Duration: 5.0
├─ Jet Speed: 15.0
└─ Jet Angle: 0

Bobbing Plane Configuration

Display Name: "Bobbing Plane"
Prefab: [Assign bobbing airplane prefab]
Preview Sprite: [Assign preview image]
Ability Type: Bobbing

Bobbing Ability:
├─ Ability Name: "Air Hop"
├─ Ability Icon: [Assign icon sprite]
├─ Cooldown Duration: 3.0
└─ Bob Force: (7, 10)
    • X = Forward force (horizontal momentum)
    • Y = Upward force (vertical lift)

How It Works: Applies diagonal impulse force using Vector2 configuration. X controls forward momentum, Y controls upward lift. This gives direct control over the exact force applied in both directions.

Examples:

• (0, 15) - Pure vertical jump
• (10, 10) - 45° diagonal boost
• (12, 5) - More forward than upward

Drop Plane Configuration

Display Name: "Drop Plane"
Prefab: [Assign drop airplane prefab]
Preview Sprite: [Assign preview image]
Ability Type: Drop

Drop Ability:
├─ Ability Name: "Dive Bomb"
├─ Ability Icon: [Assign icon sprite]
├─ Cooldown Duration: 4.0
├─ Drop Force: 20.0
├─ Drop Distance: 5.0
└─ Zero Horizontal Velocity: ☑

Default Selection

Default Airplane Type: Jet

STEP 2: Build UI (10 minutes)

Selection Panel:

AirplaneSelectionPanel (+ AirplaneSelectionUI component)
├── TitleText ("Choose Your Airplane")
├── JetPlaneButton
├── BobbingPlaneButton
├── DropPlaneButton
└── ConfirmButton

Component Configuration:

• Jet Plane Button → Assign button
• Bobbing Plane Button → Assign button
• Drop Plane Button → Assign button
• Confirm Button → Assign button
• Selected Color: Yellow
• Normal Color: White
• ☑ Start inactive

NO airplane type assets to assign!

Ability Button:

AbilityButton (+ AirplaneAbilityButton component)
├── Background (Image)
├── AbilityIcon (Image)
├── CooldownFill (Image - Radial 360)
└── CooldownText (TextMeshPro)

Component Configuration:

• Assign Button, Icon, Fill, Text references
• Ready: White, Cooldown: Gray, Active: Yellow
• ☑ Start inactive

STEP 3: Wire GameManager (2 minutes)

In AirplaneGameManager:

• Selection UI → Assign AirplaneSelectionPanel
• Ability Button → Assign AbilityButton

Done! ✅

---

🎮 HOW IT WORKS

Runtime Flow:

1. Game Start
   ↓
2. Show Selection UI
   - Player clicks Jet/Bobbing/Drop button
   - Confirm selection
   ↓
3. System loads config from settings
   - Gets AirplaneTypeConfig for selected type
   - Gets ability config (Jet/Bobbing/Drop)
   ↓
4. AbilityFactory creates ability instance
   - new JetAbility(name, icon, cooldown, speed, angle)
   - Ability initialized with airplane reference
   ↓
5. Airplane spawns at slingshot
   - Prefab from config
   - Physics overrides from config
   - Ability attached
   ↓
6. Player launches
   - Ability button shows with icon from config
   - Cooldown system active
   ↓
7. Player uses ability
   - Jet: Hold to fly straight
   - Bobbing: Tap to jump
   - Drop: Tap to dive

Code Architecture:

AirplaneSettings (ScriptableObject)
├─ JetPlaneConfig (serializable class)
├─ JetAbilityConfig (serializable class)
├─ BobbingPlaneConfig (serializable class)
├─ BobbingAbilityConfig (serializable class)
├─ DropPlaneConfig (serializable class)
└─ DropAbilityConfig (serializable class)

AbilityFactory (static)
└─ CreateAbility(type, settings) → BaseAirplaneAbility
    ├─ Jet → new JetAbility(...)
    ├─ Bobbing → new BobbingAbility(...)
    └─ Drop → new DropAbility(...)

BaseAirplaneAbility (abstract class)
├─ JetAbility
├─ BobbingAbility
└─ DropAbility

---

📊 COMPARISON

OLD Design (ScriptableObject-based):

Steps to add new airplane:
1. Create ability ScriptableObject asset
2. Configure ability in Inspector
3. Create airplane type ScriptableObject asset
4. Link ability to airplane type
5. Assign airplane type to selection UI
6. Test

Assets created: 2 per airplane type

NEW Design (Settings-based):

Steps to add new airplane:
1. Open Settings
2. Configure airplane + ability
3. Test

Assets created: 0 (all in settings!)

Result: 66% fewer steps, 100% fewer assets! 🎉

---

🔧 EXTENDING THE SYSTEM

Adding a 4th Airplane Type:

1. Add enum value:

// AirplaneAbilityType.cs
public enum AirplaneAbilityType
{
    None,
    Jet,
    Bobbing,
    Drop,
    Glider // NEW
}

2. Create ability config class:

// AirplaneAbilityConfig.cs
[System.Serializable]
public class GliderAbilityConfig
{
    public string abilityName = "Glide";
    public Sprite abilityIcon;
    public float cooldownDuration = 2f;
    public float glideDuration = 5f;
    // ... other fields
}

3. Create ability class:

// GliderAbility.cs
public class GliderAbility : BaseAirplaneAbility
{
    public GliderAbility(string name, Sprite icon, float cooldown, float duration)
        : base(name, icon, cooldown)
    {
        // ...
    }
    
    public override void Execute()
    {
        // Implementation
    }
}

4. Add to settings:

// AirplaneSettings.cs
[Header("Glider Plane")]
[SerializeField] private Data.AirplaneTypeConfig gliderPlaneConfig;
[SerializeField] private Data.GliderAbilityConfig gliderAbilityConfig;

5. Update factory:

// AbilityFactory.cs
case AirplaneAbilityType.Glider => CreateGliderAbility(settings),

6. Add UI button:

Add gliderPlaneButton to selection UI

Done! No ScriptableObject assets needed.

---

✅ BENEFITS

For Designers:

✅ Single location - All config in one settings file
✅ No asset management - No separate files to track
✅ Collapsible sections - Clean Inspector organization
✅ Fast iteration - Change values, play test immediately
✅ No references to wire - Settings accessed by code

For Developers:

✅ Less boilerplate - No CreateAssetMenu attributes
✅ Runtime creation - Abilities instantiated from settings
✅ Type-safe - Enum-based selection
✅ Factory pattern - Clean ability creation
✅ Easy extension - Add new types with minimal code

For Players:

✅ Same experience - Gameplay unchanged
✅ Faster loading - No asset references to load
✅ Consistent behavior - All from one source of truth

---

📝 FILES CREATED/MODIFIED

New Files:

1. AirplaneAbilityConfig.cs - Config classes for abilities
2. AbilityFactory.cs - Factory for creating abilities

Modified Files:

1. BaseAirplaneAbility.cs - No longer ScriptableObject
2. JetAbility.cs - Constructor-based
3. BobbingAbility.cs - Constructor-based
4. DropAbility.cs - Constructor-based
5. AirplaneSettings.cs - Added all airplane/ability configs
6. IAirplaneSettings.cs - Updated interface
7. AirplaneController.cs - Uses factory to create abilities
8. AirplaneLaunchController.cs - Works with enum types
9. AirplaneSelectionUI.cs - Works with enum types
10. AirplaneGameManager.cs - Works with enum types

Deleted Files:

1. AirplaneTypeData.cs - No longer needed!

---

🧪 TESTING

Same as before, but no assets to create first!

1. ▶️ Play
2. Selection UI shows
3. Click airplane type
4. Confirm
5. Airplane spawns at slingshot
6. Launch and use ability
7. Cooldown works
8. ✅ Success!

---

🚀 MIGRATION FROM OLD SYSTEM

If you had the ScriptableObject-based system:

1. Note your configurations from existing assets
2. Delete old ScriptableObject assets:
   • Delete JetAbility.asset
   • Delete BobbingAbility.asset
   • Delete DropAbility.asset
   • Delete JetPlaneType.asset
   • Delete BobbingPlaneType.asset
   • Delete DropPlaneType.asset
3. Open Settings and enter values from step 1
4. Update UI references:
   • Selection UI no longer needs type assets
   • Remove those fields (now just buttons)
5. Test - Should work immediately!

---

💡 ADVANCED TIPS

Inspector Organization:

Use [Header] attributes to create collapsible sections:

[Header("=== AIRPLANE TYPES ===")]
[Header("Jet Plane")]
// ... jet config fields
[Header("Bobbing Plane")]
// ... bobbing config fields

Default Values:

Initialize configs with sensible defaults:

private Data.JetAbilityConfig jetAbilityConfig = new Data.JetAbilityConfig
{
    abilityName = "Jet Boost",
    cooldownDuration = 5f,
    jetSpeed = 15f
};

Validation:

Add validation in OnValidate():

private void OnValidate()
{
    if (jetAbilityConfig.cooldownDuration < 0f)
        jetAbilityConfig.cooldownDuration = 0f;
}

---

✅ FINAL CHECKLIST

Configuration:

• Jet plane config complete
• Jet ability config complete
• Bobbing plane config complete
• Bobbing ability config complete
• Drop plane config complete
• Drop ability config complete
• Default type selected
• All sprites assigned

UI Setup:

• Selection panel created
• Three buttons assigned
• Ability button created
• Button components assigned

Integration:

• GameManager references assigned
• Settings saved
• No compilation errors

Testing:

• Selection works
• Spawning works
• Jet ability works (hold)
• Bobbing ability works (tap)
• Drop ability works (tap)
• Cooldowns work
• No console errors

When all checked → Settings-based system complete! 🎉

---

📖 SUMMARY

Converted from: ScriptableObject asset-based system
Converted to: Pure settings-based system
Assets eliminated: 6 (3 abilities + 3 types)
Setup time reduced: ~15 minutes saved
Maintenance complexity: Significantly reduced
Extensibility: Improved (add types faster)

The system is now designer-friendly, maintainable, and requires NO external asset creation!