CASCADA Framework

Appearance

Layer Hierarchy - Strict Abstraction ​

Overview ​

The engine is built on the principle of strict layer hierarchy, where each layer depends only on lower layers.

Main Principle: Layer abstraction must always be maintained, otherwise the engine cannot be extracted into a separate package!

Layer Hierarchy ​

Visualization: ​

┌─────────────────────────────────────────────────┐
│              DEPENDENCIES                       │
│  Phaser, Vue, TypeScript, pnpm packages          │
│  External libraries                             │
└────────────────────┬────────────────────────────┘
                     │ uses
┌────────────────────▼────────────────────────────┐
│              PLATFORM LAYER                     │
│  Basic Phaser configuration                     │
│  - base.config.ts                               │
│  ✗ DOES NOT import: Core, Game                  │
│  ✓ Imports: Phaser                              │
└────────────────────┬────────────────────────────┘
                     │ uses
┌────────────────────▼────────────────────────────┐
│              CORE LAYER                         │
│  Universal systems for any game                 │
│  - UIManager, VueUIBridge                       │
│  - EntityRegistry                               │
│  - SphereOfInfluenceSystem                      │
│  - EventCASCADASystem                           │
│  - Themes, Models, Utils                        │
│  ✗ DOES NOT import: Game                        │
│  ✓ Imports: Platform, Phaser, Vue               │
└────────────────────┬────────────────────────────┘
                     │ uses
┌────────────────────▼────────────────────────────┐
│              GAME LAYER                         │
│  Specific logic for your game                   │
│  - game.config.ts (extends baseConfig)          │
│  - Scenes (MainMenu, GameScene, etc.)           │
│  - Game logic (Node/Edge, Territory)            │
│  - Vue UI components (specific)                 │
│  ✓ Imports: Core, Platform, Phaser              │
└─────────────────────────────────────────────────┘

📋 Dependency Rules ​

Allowed: ​

PLATFORM:

typescript
import Phaser from "phaser";
import { resolve } from "path";
//  Only external dependencies

CORE:

typescript
import Phaser from "phaser";
import { baseConfig } from "@platform/base.config";
import { createApp } from "vue";
//  Platform + external dependencies

GAME:

typescript
import { baseConfig } from "@platform/base.config";
import { UIManager } from "@core/ui/UIManager";
import { EntityRegistry } from "@core/systems/EntityRegistry";
//  Core + Platform + external dependencies

Forbidden: ​

PLATFORM:

typescript
import { UIManager } from "@core/ui/UIManager"; // 
import { MyScene } from "@game/scenes/MyScene"; //

CORE:

typescript
import { TerritoryGameScene } from "@game/territory/..."; // 
import MyUI from "@game/ui/MyUI.vue"; //

Compliance Checking ​

Automatic Check: ​

bash
# Platform MUST NOT import @core/@game
grep -r "@core\|@game" src/platform/
# Expected: no matches 

# Core MUST NOT import @game
grep -r "@game" src/core/ --exclude="*.md"
# Expected: no matches 

# Game CAN import @core/@platform
grep -r "@core\|@platform" src/game/
# Expected: many matches

📂 Layer Contents ​

PLATFORM (src/platform/) ​

What it contains:

  • base.config.ts - basic Phaser configuration
    • Canvas settings
    • Physics engine
    • Scale manager
    • FPS settings

What it DOES NOT contain:

  • Scenes (they're in Game)
  • UI systems (they're in Core)
  • Game logic

Principle: Minimal base to launch Phaser, nothing more!

CORE (src/core/) ​

What it contains:

UI (ui/):

  • UIManager.ts - HTML/CSS UI management
  • VueUIBridge.ts - Vue 3 integration
  • README.md - documentation

Systems (systems/):

  • EntityRegistry.ts - entity tracking
  • SphereOfInfluenceSystem.ts - IoS
  • EventCASCADASystem.ts - event cascading
  • ActionValidator.ts - validation
  • GameModeManager.ts - mode switching

Models (models/):

  • Region.ts - abstract regions
  • Action.ts - abstract actions
  • GameMode.ts - mode types

Config (config/):

  • theme-manager.ts - universal theme manager
  • minimal-palette.ts - basic palette

Utils (utils/):

  • ViewportManager.ts - adaptive viewport

Rendering (rendering/):

  • GeometryRenderer.ts - procedural graphics

What it DOES NOT contain:

  • Game-specific logic
  • Game-specific Vue components
  • Game-specific constants

Principle: Universal systems that can be used in any game!

GAME (src/game/) ​

What it contains:

Config (config/):

  • game.config.ts - game config (extends baseConfig)
  • linx-themes.ts - game-specific themes

Scenes (scenes/):

  • BootScene.ts - initialization
  • PreloaderScene.ts - loading
  • MainMenuSceneVue.ts - menu with Vue
  • GameScene.ts - main game

Territory (territory/):

  • TerritoryGameScene.ts - LINX logic
    • Node/Edge gameplay
    • Polygon territories
    • Energy economy

UI (ui/):

  • MainMenuUI.vue - LINX menu
  • GameHUD.vue - LINX HUD

Core (core/):

  • GameController.ts - wrapper over Core (optional)

Principle: Everything that's specific to LINX!

Game Abstraction Levels (Game Modes) ​

Besides architectural layers (Platform/Core/Game), the engine supports game abstraction levels:

NANO   (MODE_1) → Micro-management (cell, unit)
  ↓
MICRO  (MODE_2) → Tactical level (squad)
  ↓
MESO   (MODE_3) → Operational level (base)
  ↓
MACRO  (MODE_4) → Strategic level (region)
  ↓
MEGA   (MODE_5) → Global level (world)

Features:

  • Adaptive switching (by device/screen)
  • Sphere of Influence for each level
  • Event CASCADA between levels
  • Actions don't get lost, don't ruin each other

Example:

typescript
// Mobile → NANO (detailed unit control)
// Desktop → MACRO (army command)
// Data aggregates/decomposes automatically!

More about Game Modes →
IoS for multi-level →

Benefits of Strict Hierarchy ​

1. Reusability ​

bash
# Engine (Platform + Core) can be extracted:
npm create @mycompany/phaser-vue-engine

# Any game uses:
pnpm install @mycompany/phaser-vue-engine

2. Parallel Development ​

Team 1: Platform (base improvements)
Team 2: Core (new systems)
Team 3: Game (gameplay)

They don't interfere!

3. Testing ​

bash
# Test layers independently:
pnpm test src/platform/  # Phaser base
pnpm test src/core/      # Systems
pnpm test src/game/      # Game

4. Scaling ​

New game?
  → Use Platform + Core
  → Create new src/game/
  → Done!

New system?
  → Add to src/core/
  → Available to all games!

🎓 Best Practices ​

1. When adding code: ​

Ask yourself:

  • Is it universal? → Core
  • Is it basic Phaser setup? → Platform
  • Is it specific to my game? → Game

2. When importing: ​

Check:

typescript
//  In Platform:
import { ... } from "@core/..."; // NOT ALLOWED!

//  In Core:
import { ... } from "@game/..."; // NOT ALLOWED!

//  In Game:
import { ... } from "@core/..."; // ALLOWED!
import { ... } from "@platform/..."; // ALLOWED!

3. When refactoring: ​

Moving from Game to Core?

  • Remove game-specific logic
  • Make it universal
  • Update documentation

Moving from Core to Platform?

  • Remove dependencies on Core
  • Only basic Phaser
  • Minimalism!

Tools ​

Layer hierarchy check script: ​

bash
#!/bin/bash
# check-layers.sh

echo "Checking Platform..."
if grep -r "@core\|@game" src/platform/ 2>/dev/null; then
  echo " Platform imports Core/Game!"
  exit 1
fi

echo "Checking Core..."
if grep -r "@game" src/core/ --exclude="*.md" 2>/dev/null; then
  echo " Core imports Game!"
  exit 1
fi

echo " Hierarchy maintained!"

Add to package.json:

json
{
  "scripts": {
    "check-layers": "./check-layers.sh"
  }
}

📚 See Also ​

Strict hierarchy = clean architecture = scalability!

MIT Licensed

Copyright © 2025