CASCADA Framework

Appearance

Mode Toggle System ​

How to enable/disable game modes without affecting others

🎯 Concept ​

╔════════════════════════════════════════════════════╗
║                                                    ║
║  PROBLEM: How to make modular mode system?        ║
║                                                    ║
║  SOLUTION: Isolation + Configuration              ║
║                                                    ║
║  1. Each mode in its own folder                   ║
║  2. Modes do NOT depend on each other             ║
║  3. One config file to enable/disable             ║
║  4. Dynamic loading in Phaser                     ║
║                                                    ║
╚════════════════════════════════════════════════════╝

📁 File Structure ​

Mode Isolation ​

src/game/territory/
│
├── shared/                # Shared base (can't disable)
│   ├── systems/
│   │   └── BaseGameScene.ts
│   ├── types/
│   │   └── GameTypes.ts
│   └── utils/
│
└── modes/                 # Isolated modes
    ├── classic/          # Base ❌
    ├── fractal/          # Optional ✅
    ├── ascension/        # Optional ✅
    └── temporal/         # Optional ✅

Rule: Modes do NOT import each other!

typescript
// ✅ GOOD
import { BaseGameScene } from "../../shared/systems/BaseGameScene";
import { CollapseSystem } from "./CollapseSystem"; // Own file

// ❌ BAD
import { AbilitySystem } from "../ascension/AbilitySystem"; // Different mode!

⚙️ Configuration ​

game-modes-config.ts ​

Single file controlling all modes:

typescript
// src/game/config/game-modes-config.ts

export const GAME_MODES_CONFIG = [
  {
    id: "classic",
    name: "Classic Mode",
    sceneKey: "ClassicMode",
    enabled: true,
    isBase: true, // ← CAN'T disable
    description: "∞ Infinite rounds, NANO only",
  },
  {
    id: "fractal",
    name: "Fractal Mode",
    sceneKey: "FractalMode",
    enabled: true, // ← CAN change to false
    isBase: false,
    description: "🔬 NANO → MEGA evolution",
  },
  {
    id: "ascension",
    name: "Ascension Mode",
    sceneKey: "AscensionMode",
    enabled: true, // ← CAN change to false
    isBase: false,
    description: "📈 Rise & fall between levels",
  },
  {
    id: "temporal",
    name: "Temporal Mode",
    sceneKey: "TemporalMode",
    enabled: true, // ← CAN change to false
    isBase: false,
    description: "⏰ Control time speed",
  },
];

🔄 How It Works ​

1. Configuration Checked ​

typescript
// game-modes-config.ts
export function isModeEnabled(id: string): boolean {
  const mode = GAME_MODES_CONFIG.find((m) => m.id === id);
  return mode ? mode.enabled : false;
}

2. Phaser Dynamically Loads ​

typescript
// phaser.config.ts
scene: [
  ClassicModeScene, // Always

  ...(isModeEnabled("fractal") ? [FractalModeScene] : []),
  ...(isModeEnabled("ascension") ? [AscensionModeScene] : []),
  ...(isModeEnabled("temporal") ? [TemporalModeScene] : []),
];

3. Menu Dynamically Shows ​

vue
<!-- MainMenuUIv2.vue -->
<ModeCard
  v-for="mode in enabledModes"
  :key="mode.id"
  @select="startMode(mode.id)"
/>

📝 Usage Examples ​

Scenario 1: Disable All Except Classic ​

When needed: Testing base mechanics

typescript
// game-modes-config.ts
classic: enabled: true,     // ✅
fractal: enabled: false,    // ❌
ascension: enabled: false,  // ❌
temporal: enabled: false    // ❌

Result:

Main Menu:
┌────────────────┐
│ CLASSIC MODE  │ ← Only 1 card
└────────────────┘

Phaser loads:
- BootScene
- PreloaderScene
- MainMenuScene
- ClassicModeScene  ← Only 1 game scene!

Bundle size: minimal

Scenario 2: Demo for Investor ​

When needed: Show complete + wow-factor

typescript
// game-modes-config.ts
classic: enabled: true,   // ✅ Baseline
fractal: enabled: true,   // ✅ WOW!
ascension: enabled: false,// ❌ Not ready
temporal: enabled: false  // ❌ Not ready

Result:

Main Menu:
┌────────────────┐
│ CLASSIC MODE  │
│ FRACTAL MODE  │ ← Show collapse!
└────────────────┘

Only ready modes!

Scenario 3: Developing Ascension Mode ​

When needed: Focus on one mode

typescript
classic: enabled: true,     // ✅ For comparison
ascension: enabled: true,   // ✅ Developing
fractal: enabled: false,    // ❌ Disabled
temporal: enabled: false    // ❌ Disabled

Result:

Fast compilation
Clear focus
Easy testing

🛡️ Error Protection ​

Attempt to Disable Classic Mode ​

typescript
// game-modes-config.ts
classic: enabled: false; // ❌ TRYING TO DISABLE

// phaser.config.ts
scene: [
  ClassicModeScene, // ALWAYS LOADED (not conditional!)
  // ...
];

// Result: Classic always loads regardless of config!
// Can't break the base!

🔍 Debug Mode Disabling ​

Check What's Disabled ​

typescript
// In browser console
console.log(GAME_MODES_CONFIG.filter((m) => !m.enabled));
// → [ { id: 'fractal', enabled: false }, ... ]

Check Loaded Scenes ​

typescript
// In Phaser scene
console.log(this.scene.manager.keys);
// → { MainMenu: ..., ClassicMode: ..., AscensionMode: ... }
// Note: FractalMode missing!

💡 Best Practices ​

1. Use Feature Flags ​

typescript
//  GOOD - Declarative
const config = {
  fractal: {
    enabled: process.env.FEATURE_FRACTAL === "true",
  },
};

//  BAD - Hardcoded everywhere
if (process.env.FEATURE_FRACTAL) {
  /* ... */
}

2. Document Status ​

typescript
// game-modes-config.ts
{
  id: "fractal",
  enabled: false, // TODO: Enable after collapse system ready
  isBase: false,
  // Added: 2025-10-15
  // Status: In development
}

3. Git Branching ​

bash
# Each mode has own branch
git checkout -b feature/fractal-mode
# Only change fractal/ folder
# Don't touch other modes

🎯 Testing Scenarios ​

All Modes Enabled ​

typescript
classic: true,
fractal: true,
ascension: true,
temporal: true

Test: Menu shows 4 cards, all work

Only Classic ​

typescript
classic: true,
fractal: false,
ascension: false,
temporal: false

Test: Menu shows 1 card, others don't load

🎯 Recommendations ​

For Development ​

typescript
// Enable only what you're working on
classic: true,    // Baseline
yourMode: true,   // Developing
others: false     // Disabled

For Testing ​

typescript
// Enable what needs testing
classic: true,
fractal: true,   // Just implemented
others: false

For Production ​

typescript
// Enable only ready modes
classic: true,
fractal: true,   // Production ready
ascension: false,// Still in dev
temporal: false

🚀 Summary ​

╔════════════════════════════════════════════════════╗
║                                                    ║
║  ONE FILE CONTROLS EVERYTHING                     ║
║                                                    ║
║  src/game/config/game-modes-config.ts             ║
║                                                    ║
║  Change enabled → mode appears/disappears         ║
║  Modes isolated → can't break each other          ║
║  Dynamic loading → smaller bundles                ║
║                                                    ║
║  Perfect for MVP + incremental development! ✨    ║
║                                                    ║
╚════════════════════════════════════════════════════╝

Mode Toggle System is production-ready! 🎮

Use it to ship modes incrementally as they're completed.

MIT Licensed

Copyright © 2025