Multiplayer (Colyseus)

MMO-ready architecture for CASCADA

Status

Planned for Implementation

CASCADA was designed with MMO in mind from the start:

• Sphere of Influence - ready for multiplayer
• Region-based isolation - optimization
• Event CASCADA System - state synchronization
• Colyseus integration - in development

---

Why Colyseus?

Colyseus is the perfect choice for CASCADA:

Advantages

1. TypeScript Native

   • Client and server in one language
   • Shared types between frontend and backend
   • Strict state typing

2. Room-Based Architecture

   • Perfect for Region-based games
   • Automatic isolation
   • Scalability

3. State Synchronization

   • Automatic state synchronization
   • Delta-compression out of the box
   • Minimal traffic

4. Open Source + MIT

   • Free for commercial use
   • No royalties
   • Full control

---

Planned Architecture

Client-Server Model

┌─────────────────────────────────────────┐
│           Colyseus Server               │
│                                         │
│  ┌───────────┐  ┌───────────┐         │
│  │  Room A   │  │  Room B   │  ...    │
│  │ (Region)  │  │ (Region)  │         │
│  └───────────┘  └───────────┘         │
│       ↓              ↓                  │
│  EventCASCADA   EventCASCADA           │
│  Aggregation    Aggregation            │
└─────────────────────────────────────────┘
         ↑                ↑
         │                │
    ┌────┴────┐      ┌────┴────┐
    │ Client  │      │ Client  │
    │ (NANO)  │      │ (MACRO) │
    └─────────┘      └─────────┘

Room = Region

Each Region = Colyseus Room:

// server/rooms/RegionRoom.ts
import { Room, Client } from "colyseus";
import { RegionState } from "./schema/RegionState";

export class RegionRoom extends Room<RegionState> {
  maxClients = 100; // Optimization

  onCreate(options: any) {
    this.setState(new RegionState());

    // Event CASCADA System on server
    this.setupEventCASCADA();
  }

  onJoin(client: Client, options: any) {
    const playerMode = options.mode; // NANO, MICRO, etc

    // Add player to corresponding level
    this.state.addPlayer(client.sessionId, playerMode);
  }

  onMessage(client: Client, message: any) {
    // Validation via ActionValidator
    if (this.validateAction(message, client)) {
      this.processAction(message, client);
    }
  }
}

---

Event CASCADA in Multiplayer

Synchronization Between Clients

// NANO player delivers cargo
client1.send("action", {
  type: "cargo_delivered",
  level: "NANO",
  data: { cargo: "sugar", value: 100 },
});

// Server:
// 1. Validates action (ActionValidator)
// 2. Updates NANO state
// 3. CASCADAs up (NANO → MEGA)
// 4. Synchronizes with clients

// MACRO player sees:
room.state.onChange = (changes) => {
  // Receives aggregated changes
  // Sees: "Port prospers +100"
  // DOESN'T see: cargo details
};

Sphere of Influence in Colyseus

// server/rooms/RegionRoom.ts
class RegionRoom extends Room {
  validateAction(action: Action, client: Client): boolean {
    const player = this.state.players.get(client.sessionId);
    const validator = new ActionValidator(player.position, player.mode);

    return validator.validate(action).valid;
  }

  processAction(action: Action, client: Client) {
    const player = this.state.players.get(client.sessionId);

    // Apply locally
    this.applyNanoAction(action);

    // CASCADA up
    this.cascadeUp(action);

    // Colyseus syncs automatically!
  }
}

---

Installation (when ready)

# Client (already present)
ppnpm install colyseus.js

# Server
cd server
ppnpm install colyseus
ppnpm install @colyseus/monitor  # Admin panel

---

Launch (future)

# Terminal 1: Server
cd server
pnpm dev
# → Colyseus on :2567

# Terminal 2: Client
pnpm dev
# → Game on :5173

---

Usage Examples

Trade Winds MMO

// client/src/multiplayer/TradeWindsClient.ts
import { Client, Room } from "colyseus.js";

class TradeWindsClient {
  client: Client;
  room: Room;

  async connect() {
    this.client = new Client("ws://localhost:2567");

    // Connect to "caribbean" region
    this.room = await this.client.joinOrCreate("caribbean", {
      mode: GameModeAlias.NANO, // I'm a ship captain
    });

    this.setupListeners();
  }

  setupListeners() {
    // Receive state changes
    this.room.state.ports.onAdd = (port, key) => {
      console.log("New port:", port.name);
    };

    this.room.state.onChange = (changes) => {
      // CASCADA events from other players
      this.handleCASCADAEvents(changes);
    };
  }

  deliverCargo(cargo: Cargo) {
    // Send action to server
    this.room.send("action", {
      type: "cargo_delivered",
      data: cargo,
    });
  }
}

---

Planned Features

1. Session Persistence

• Short sessions (10-20 minutes)
• State saved to DB
• Return to same region

2. Cross-Region Travel

• Movement between regions
• Automatic Room switching
• Seamless transition

3. NPC Bots

• AI NPCs when few players
• Fill gaps
• Create living world

4. Admin Panel

• Region monitoring (Colyseus Monitor)
• Player management
• Real-time statistics

---

Roadmap

Phase 1: Prototype (Q1 2025)

• SphereOfInfluenceSystem
• EventCASCADASystem
• Basic Colyseus integration

Phase 2: MVP (Q2 2025)

• One game concept (Trade Winds)
• Region-based rooms
• Basic state sync

Phase 3: Production (Q3 2025)

• Multiple regions
• Session persistence
• NPC bots
• Admin panel

---

📚 Resources

• Colyseus Documentation
• Colyseus Examples
• Phaser + Colyseus Tutorial

---

🤝 Contributing

Want to help with multiplayer?

1. Study Colyseus documentation
2. Check out Sphere of Influence
3. Create a PR with a prototype!

---

Status: In Development
Planned Release: Q2 2025

← Back to guide