Core Framework - Overview

Welcome to the CASCADA Framework core! This directory contains universal, reusable systems that are independent of any specific game and can be used in any Phaser project.

---

What's Included

UI Layer (src/core/ui/)

System for managing HTML/CSS user interface, integrated with Vue 3.

Features:

• Centralized UI component management
• Bidirectional UI ↔ Game communication via Event Bus
• 100% reactivity with Vue 3 (Wrapper Component pattern)
• Responsive and styleable via CSS
• Support for any UI framework

Documentation:

• UI Layer - Complete Guide
• Vue Integration - Ready-to-use
• UIManager API

Entity Registry (src/core/systems/entity-registry.ts)

Centralized registry for tracking all game entities (nodes, edges, territories, players).

Features:

• Automatic object registration
• Indexing by region/owner/type
• Automatic visual object destruction
• Event Bus for entity lifecycle events

Documentation:

• EntityRegistry
• Architecture Update

Sphere of Influence System (IoS) (src/core/systems/sphere-of-influence-system.ts)

System for managing multi-level data, validating actions, and cascading events between different game world abstraction levels.

Features:

• Region management with multi-level data
• Player action validation
• Event cascading between levels (NANO, MICRO, MACRO)

Documentation:

• Sphere of Influence - Technical
• IoS Integration Plan

Game Mode Manager (src/core/systems/game-mode-manager.ts)

System for managing different game modes and switching between them.

Features:

• Abstract modes (MODE_1, MODE_2, ...)
• Mode aliases (NANO, MICRO, MESO, MACRO, MEGA)
• Mode switching based on viewport or user input

Documentation:

• Game Modes

Viewport Manager (src/core/utils/viewport-manager.ts)

Utility for adaptive management of visible game area based on screen size and orientation.

Features:

• Dynamic visible area adjustment
• Proportional scaling
• Mobile device and browser window resize adaptation

Documentation:

• Viewport Manager

Visual Themes (src/core/config/visual-themes.ts)

Centralized visual theme management.

Features:

• Define color palettes, effects, sizes
• Switch themes with localStorage persistence
• Integration with tsParticles for background animations

Documentation:

• Visual Themes
• Minimal Palette

Geometry Renderer (src/core/rendering/geometry-renderer.ts)

Utility for rendering geometric primitives without sprites.

Features:

• Procedural geometry generation
• Effects (glow, particles)
• Neo Tokyo / Synthwave style support

Documentation:

• GeometryRenderer

---

How to Use Core Framework

All Core Framework systems are designed as independent modules. You can import and use only the parts you need.

Example:

// src/game/scenes/my-game-scene.ts
import { UIManager } from "@core/ui/ui-manager";
import { VueUIBridge } from "@core/ui/vue-ui-bridge";
import MyUI from "@game/ui/my-ui.vue"; // Your Vue component

export class MyGameScene extends Phaser.Scene {
  private uiManager!: UIManager;
  private vueBridge!: VueUIBridge;

  create() {
    this.uiManager = new UIManager(this);
    this.vueBridge = new VueUIBridge(this.uiManager);

    this.vueBridge.mount("ui", MyUI, {
      props: { score: 0 },
      events: { action: () => this.handleAction() },
    });

    this.vueBridge.show("ui");
  }

  handleAction() {
    console.log("Action from UI!");
  }

  shutdown() {
    this.vueBridge.unmountAll();
    this.uiManager.shutdown();
  }
}

---

Complete Documentation

Topic	Document
UI Layer	ui-layer.md
Vue Integration	vue-integration.md
IoS System	sphere-of-influence.md
Architecture	architecture.md
Game Modes	game-modes.md

---

Core Framework Roadmap

v0.1.0 - Foundation

• Basic project structure
• Phaser 3 + TypeScript + Vite
• Adaptive Viewport
• Multi-Scale Gameplay (abstractions)

v0.2.0 - Current

• UI Layer (UIManager + VueUIBridge)
• EntityRegistry
• Visual Themes (ThemeManager)
• Node/Edge Terminology

v0.3.0 - Planned

• Full IoS integration
• Event-driven architecture
• ActionValidator

v0.4.0 - Future

• 🔮 Physics helpers
• 🔮 AI utilities
• 🔮 Networking abstractions