Project Architecture

Three-Layer Architecture

Project is organized in three independent layers:

┌─────────────────────────────────────────┐
│         GAME LAYER                      │
│    (Your product - the game)            │
│  ├─ Scenes                              │
│  ├─ Entities                            │
│  └─ Mechanics                           │
└─────────────────┬───────────────────────┘
                  │ uses
┌─────────────────▼───────────────────────┐
│         CORE LAYER                      │
│  (Reusable systems)                     │
│  ├─ ViewportManager                     │
│  ├─ GameModeManager                     │
│  ├─ Constants                           │
│  └─ Utilities                           │
└─────────────────┬───────────────────────┘
                  │ uses
┌─────────────────▼───────────────────────┐
│       PLATFORM LAYER                    │
│    (Phaser 3 configuration)             │
│  └─ base.config.ts                      │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│       Phaser 3 Engine                   │
└─────────────────────────────────────────┘

Structure

Platform Layer

src/platform/
├── README.md
└── base.config.ts          # Phaser configuration

Responsibility: Phaser initialization

Core Layer

src/core/
├── README.md
├── config/
│   ├── constants.ts        # Constants (SIZES, COLORS, TEXT...)
│   └── theme-manager.ts    # Universal theme system
├── systems/
│   ├── GameModeManager.ts  # Game mode system
│   ├── EntityRegistry.ts   # Entity tracking
│   └── SphereOfInfluenceSystem.ts
├── ui/
│   ├── UIManager.ts        # UI management
│   └── VueUIBridge.ts      # Vue 3 integration
├── utils/
│   └── ViewportManager.ts  # Adaptive viewport
└── models/
    ├── GameMode.ts         # Mode types + aliases
    ├── Region.ts           # Regions
    └── Action.ts           # Actions

Responsibility: Reusable systems

Game Layer

src/game/
├── README.md
├── config/
│   ├── game.config.ts      # Game config (extends base)
│   └── linx-themes.ts      # LINX themes
├── scenes/                 # Your scenes
│   ├── BootScene.ts
│   ├── PreloaderScene.ts
│   ├── MainMenuSceneVue.ts
│   └── GameScene.ts
├── territory/              # LINX game logic
│   └── scenes/
│       └── TerritoryGameScene.ts
└── ui/                     # Vue components
    ├── MainMenuUI.vue
    └── GameHUD.vue

Responsibility: Your game

Dependencies

Rule: Dependencies only downward!

Game     ──✓──>  Core      ✓ Allowed
Core     ──✓──>  Platform  ✓ Allowed
Platform ──✓──>  Phaser    ✓ Allowed

Core     ──✗──>  Game      ✗ FORBIDDEN!
Platform ──✗──>  Game      ✗ FORBIDDEN!

Path Aliases

Simplified aliases for layers:

@platform/*  →  src/platform/*
@core/*      →  src/core/*
@game/*      →  src/game/*

Import Examples:

// Platform
import { baseConfig } from "@platform/base.config";

// Core
import { ViewportManager } from "@core/utils/ViewportManager";
import { GameModeManager } from "@core/systems/GameModeManager";
import { GameModeAlias } from "@core/models/GameMode";
import { COLORS, SIZES } from "@core/config/constants";

// Game
import { TerritoryGameScene } from "@game/territory/scenes/TerritoryGameScene";
import MainMenuUI from "@game/ui/MainMenuUI.vue";

Where to Put New Code?

Question: Where to place new code?

Platform

Only if:
✓ It's Phaser configuration
✓ Base engine settings

Core

If:
✓ Reusable in other games
✓ Doesn't depend on specific gameplay
✓ General utility
✓ System without game ties

Game

If:
✓ Specific to your game
✓ Gameplay mechanic
✓ Entity class
✓ Content

Examples

PathFinding system - where?

Question: Universal A* navigation?
├─ Used in any game?
└─ Answer: Core! ✓

src/core/utils/PathFinding.ts

Node entity - where?

Question: Node specific to LINX?
├─ Used only in this game?
└─ Answer: Game! ✓

src/game/territory/entities/Node.ts

ThemeManager - where?

Question: Theme manager - universal or game-specific?
├─ Universal class → Core
├─ Specific themes → Game
└─ Answer: Both!

src/core/config/theme-manager.ts (universal class)
src/game/config/linx-themes.ts (LINX themes)

Core Reusability

Scenario: Creating Second Game

# Project 1: LINX
games/
└── src/
    ├── platform/
    ├── core/       ← These systems
    └── game/

# Project 2: New Game
new-game/
└── src/
    ├── platform/
    ├── core/       ← Copy from here!
    └── game/       ← New game

# Core systems work immediately!

Or as npm Package:

# Publish Core
pnpm publish @your-org/cascade-engine

# Use in any project
pnpm install @your-org/cascade-engine

import { ViewportManager, UIManager } from "@your-org/cascade-engine";

Best Practices

1. Core Must Be Universal

// ✓ GOOD - in Core
class ViewportManager {
  getSize() { ... }  // Works for any game
}

// ✗ BAD - NOT in Core
class LinxViewportManager {
  getNodePosition() { ... }  // Game-specific!
}

2. Game Uses Core

// ✓ GOOD
import { COLORS } from "@core/config/constants";

const node = this.add.circle(0, 0, 10);
node.setFillStyle(COLORS.PLAYER);

// ✗ BAD
const node = this.add.circle(0, 0, 10);
node.setFillStyle(0x00ff00); // Hardcoded!

3. Dependencies Only Downward

// ✓ GOOD - Game uses Core
// src/game/scenes/GameScene.ts
import { GameModeManager } from "@core/systems/GameModeManager";

// ✗ BAD - Core MUST NOT know about Game!
// src/core/systems/SomeSystem.ts
import { Node } from "@game/territory/entities/Node"; // FORBIDDEN!

Layer Documentation

• Platform Layer - see src/platform/
• Core Layer - see src/core/
• Game Layer - see src/game/

See Also

• Layer Hierarchy
• Project Structure
• API Reference