Phaser 4 Client
├── 渲染
├── 输入
├── UI
├── 音频
├── 插值
└── 客户端预测

Colyseus Realtime
├── 房间
├── 权威状态
├── 游戏循环
├── 消息验证
├── 状态同步
├── 重连
└── 对局结算触发

Hono API
├── 登录
├── 用户资料
├── Realtime Ticket
├── 存档
├── 历史记录
└── 排行榜

PostgreSQL
└── 永久数据

Redis
├── Presence
├── Driver
├── 临时票据
└── 分布式协调

place_node
upgrade_tower
activate_ability
select_technology
move_unit
ready

set_lumen_9999
enemy_dead
match_win
set_damage_500
unlock_reward

BattleRoom
├── 处理房间生命周期
├── 处理网络消息
├── 管理玩家连接
└── 调用 BattleSimulation

BattleSimulation
├── 经济系统
├── 建筑系统
├── 能量网络
├── 战斗系统
├── 敌人系统
├── 波次系统
└── 胜负判定

apps/
├── client/
│   └── src/
│       ├── game/
│       ├── scenes/
│       ├── network/
│       ├── entities/
│       └── ui/
│
├── realtime/
│   ├── src/
│   │   ├── rooms/
│   │   │   ├── BattleRoom.ts
│   │   │   └── LobbyRoom.ts
│   │   ├── schema/
│   │   │   ├── BattleState.ts
│   │   │   ├── PlayerState.ts
│   │   │   ├── NodeState.ts
│   │   │   └── EnemyState.ts
│   │   ├── simulation/
│   │   │   ├── BattleSimulation.ts
│   │   │   ├── SimulationClock.ts
│   │   │   └── RandomSource.ts
│   │   ├── commands/
│   │   │   ├── PlaceNodeCommand.ts
│   │   │   ├── UpgradeNodeCommand.ts
│   │   │   └── CommandDispatcher.ts
│   │   ├── auth/
│   │   │   └── verifyRealtimeTicket.ts
│   │   ├── persistence/
│   │   │   └── MatchResultRepository.ts
│   │   ├── config/
│   │   │   └── env.ts
│   │   └── app.config.ts
│   └── package.json
│
└── api/
    └── src/

packages/
├── contracts/
│   ├── messages.ts
│   ├── errors.ts
│   └── room-options.ts
├── game-core/
├── game-config/
└── test-kit/

client
  └── contracts/public

realtime
  ├── contracts
  ├── game-core
  └── game-config

api
  ├── contracts
  └── persistence

client → realtime
client → server-only game-core
client → database

cd apps/realtime

bun add colyseus
bun add @colyseus/schema
bun add @colyseus/bun-websockets
bun add zod

bun add -d @colyseus/testing
bun add -d @colyseus/loadtest
bun add -d @colyseus/playground
bun add -d @colyseus/monitor

bun add @colyseus/redis-presence
bun add @colyseus/redis-driver

cd apps/client

bun add @colyseus/sdk

colyseus.js

@colyseus/sdk

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "experimentalDecorators": true,
    "useDefineForClassFields": false,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "skipLibCheck": true
  }
}

// src/schema/PlayerState.ts

import { Schema, type } from "@colyseus/schema";

export class PlayerState extends Schema {
  @type("string")
  playerId = "";

  @type("string")
  displayName = "";

  @type("boolean")
  connected = true;

  @type("boolean")
  ready = false;

  @type("float32")
  cursorX = 0;

  @type("float32")
  cursorY = 0;
}

// src/schema/NodeState.ts

import { Schema, type } from "@colyseus/schema";

export class NodeState extends Schema {
  @type("string")
  id = "";

  @type("string")
  ownerId = "";

  @type("uint8")
  nodeType = 0;

  @type("float32")
  x = 0;

  @type("float32")
  y = 0;

  @type("uint8")
  level = 1;

  @type("float32")
  health = 100;

  @type("boolean")
  powered = false;
}

// src/schema/EnemyState.ts

import { Schema, type } from "@colyseus/schema";

export class EnemyState extends Schema {
  @type("string")
  id = "";

  @type("uint8")
  enemyType = 0;

  @type("float32")
  x = 0;

  @type("float32")
  y = 0;

  @type("float32")
  health = 100;

  @type("uint8")
  status = 0;
}

// src/schema/BattleState.ts

import { MapSchema, Schema, type } from "@colyseus/schema";
import { PlayerState } from "./PlayerState";
import { NodeState } from "./NodeState";
import { EnemyState } from "./EnemyState";

export enum MatchPhase {
  WAITING = 0,
  PREPARING = 1,
  RUNNING = 2,
  VICTORY = 3,
  DEFEAT = 4,
  ABORTED = 5,
}

export class BattleState extends Schema {
  @type("uint8")
  phase = MatchPhase.WAITING;

  @type("uint32")
  serverTick = 0;

  @type("float32")
  elapsedSeconds = 0;

  @type("int32")
  lumen = 100;

  @type("float32")
  coreHealth = 100;

  @type({ map: PlayerState })
  players = new MapSchema<PlayerState>();

  @type({ map: NodeState })
  nodes = new MapSchema<NodeState>();

  @type({ map: EnemyState })
  visibleEnemies = new MapSchema<EnemyState>();
}

class EnemyState extends Schema {
  @type("string")
  fullJsonConfig = JSON.stringify(config);
}

class EnemyState extends Schema {
  @type("uint8")
  enemyType = 2;
}

// packages/contracts/src/messages.ts

export const ClientMessage = {
  READY: "player.ready",
  PLACE_NODE: "build.place-node",
  UPGRADE_NODE: "build.upgrade-node",
  ACTIVATE_ABILITY: "ability.activate",
  PING: "system.ping",
} as const;

export const ServerMessage = {
  COMMAND_REJECTED: "command.rejected",
  EFFECT: "game.effect",
  PONG: "system.pong",
  MATCH_RESULT: "match.result",
} as const;

export interface PlaceNodePayload {
  requestId: string;
  nodeType: number;
  x: number;
  y: number;
  rotation: number;
}

export interface CommandRejectedPayload {
  requestId: string;
  code:
    | "INVALID_PHASE"
    | "INVALID_PAYLOAD"
    | "INSUFFICIENT_LUMEN"
    | "POSITION_BLOCKED"
    | "OUT_OF_RANGE"
    | "RATE_LIMITED";
}

领域.动作

player.ready
build.place-node
build.upgrade-node
ability.activate
match.surrender
system.ping

msg1
action
event
update
command

// src/rooms/BattleRoom.ts

import {
  Client,
  Room,
  validate,
  type AuthContext,
} from "colyseus";
import { z } from "zod";

import { BattleState, MatchPhase } from "../schema/BattleState";
import { PlayerState } from "../schema/PlayerState";
import { NodeState } from "../schema/NodeState";

const placeNodeSchema = z.object({
  requestId: z.string().min(8).max(64),
  nodeType: z.number().int().min(0).max(10),
  x: z.number().finite().min(0).max(4096),
  y: z.number().finite().min(0).max(4096),
  rotation: z.number().finite().min(-Math.PI * 2).max(Math.PI * 2),
});

interface RoomAuth {
  playerId: string;
  displayName: string;
}

interface BattleRoomOptions {
  mapId?: string;
  difficulty?: number;
  realtimeTicket?: string;
}

export class BattleRoom extends Room {
  state = new BattleState();

  maxClients = 4;
  autoDispose = true;
  patchRate = 100;

  private nextNodeId = 1;

  async onAuth(
    client: Client,
    options: BattleRoomOptions,
    context: AuthContext,
  ): Promise<RoomAuth> {
    const auth = await verifyRealtimeTicket(options.realtimeTicket);

    if (!auth) {
      throw new Error("UNAUTHORIZED");
    }

    return {
      playerId: auth.playerId,
      displayName: auth.displayName,
    };
  }

  onCreate(options: BattleRoomOptions): void {
    this.setMetadata({
      mapId: options.mapId ?? "seedfall_standard",
      difficulty: options.difficulty ?? 1,
    });

    this.setSimulationInterval((deltaTime) => {
      this.updateSimulation(deltaTime);
    }, 50);
  }

  onJoin(
    client: Client,
    _options: BattleRoomOptions,
    auth: RoomAuth,
  ): void {
    const player = new PlayerState();

    player.playerId = auth.playerId;
    player.displayName = auth.displayName;
    player.connected = true;

    this.state.players.set(client.sessionId, player);
  }

  messages = {
    "player.ready": (
      client: Client,
      payload: { ready?: boolean },
    ) => {
      const player = this.state.players.get(client.sessionId);

      if (!player) {
        return;
      }

      player.ready = payload.ready === true;
      this.tryStartMatch();
    },

    "build.place-node": validate(
      placeNodeSchema,
      (
        client: Client,
        payload: z.infer<typeof placeNodeSchema>,
      ) => {
        this.handlePlaceNode(client, payload);
      },
    ),

    "system.ping": (
      client: Client,
      payload: { timestamp?: number },
    ) => {
      client.send("system.pong", {
        timestamp: payload.timestamp ?? Date.now(),
        serverTime: Date.now(),
      });
    },
  };

  async onLeave(
    client: Client,
    code: number,
  ): Promise<void> {
    const player = this.state.players.get(client.sessionId);

    if (!player) {
      return;
    }

    player.connected = false;

    const consented = code === 1000;

    if (consented) {
      this.state.players.delete(client.sessionId);
      return;
    }

    try {
      await this.allowReconnection(client, 60);
      player.connected = true;
    } catch {
      this.state.players.delete(client.sessionId);
    }
  }

  onDispose(): void {
    // 释放非 Colyseus 管理的资源：
    // 数据库连接句柄、订阅、文件、外部计时器等。
  }

  private tryStartMatch(): void {
    if (this.state.phase !== MatchPhase.WAITING) {
      return;
    }

    if (this.state.players.size === 0) {
      return;
    }

    const allReady = Array.from(this.state.players.values())
      .every((player) => player.ready);

    if (allReady) {
      this.state.phase = MatchPhase.RUNNING;
    }
  }

  private handlePlaceNode(
    client: Client,
    payload: z.infer<typeof placeNodeSchema>,
  ): void {
    if (this.state.phase !== MatchPhase.RUNNING) {
      client.send("command.rejected", {
        requestId: payload.requestId,
        code: "INVALID_PHASE",
      });
      return;
    }

    const player = this.state.players.get(client.sessionId);

    if (!player) {
      return;
    }

    const cost = 20;

    if (this.state.lumen < cost) {
      client.send("command.rejected", {
        requestId: payload.requestId,
        code: "INSUFFICIENT_LUMEN",
      });
      return;
    }

    if (this.isPositionBlocked(payload.x, payload.y)) {
      client.send("command.rejected", {
        requestId: payload.requestId,
        code: "POSITION_BLOCKED",
      });
      return;
    }

    this.state.lumen -= cost;

    const node = new NodeState();
    node.id = `node-${this.nextNodeId++}`;
    node.ownerId = player.playerId;
    node.nodeType = payload.nodeType;
    node.x = payload.x;
    node.y = payload.y;

    this.state.nodes.set(node.id, node);
  }

  private isPositionBlocked(x: number, y: number): boolean {
    for (const node of this.state.nodes.values()) {
      const dx = node.x - x;
      const dy = node.y - y;

      if (dx * dx + dy * dy < 64 * 64) {
        return true;
      }
    }

    return false;
  }

  private updateSimulation(deltaTimeMs: number): void {
    if (this.state.phase !== MatchPhase.RUNNING) {
      return;
    }

    this.state.serverTick += 1;
    this.state.elapsedSeconds += deltaTimeMs / 1000;

    // 后续改为：
    // this.simulation.update(deltaTimeMs);
    // this.statePresenter.apply(simulationSnapshot, this.state);
  }
}

async function verifyRealtimeTicket(
  ticket: string | undefined,
): Promise<RoomAuth | null> {
  if (!ticket) {
    return null;
  }

  // 示例占位。
  // 正式实现应校验：
  // - 签名
  // - exp
  // - scope
  // - nonce
  // - region
  // - 是否已经使用

  return {
    playerId: `player-${ticket.slice(0, 8)}`,
    displayName: "Keeper",
  };
}

// src/app.config.ts

import { defineRoom, defineServer } from "colyseus";
import { BunWebSockets } from "@colyseus/bun-websockets";

import { BattleRoom } from "./rooms/BattleRoom";

const port = Number(process.env.PORT ?? 2567);

export default defineServer({
  transport: new BunWebSockets({
    port,
    hostname: process.env.HOST ?? "0.0.0.0",
  }),

  rooms: {
    battle: defineRoom(BattleRoom),
  },

  express: (app) => {
    app.get("/health/live", (_req, res) => {
      res.json({
        status: "ok",
        service: "realtime",
      });
    });

    app.get("/health/ready", (_req, res) => {
      res.json({
        status: "ready",
      });
    });
  },
});

{
  "scripts": {
    "dev": "colyseus start --watch",
    "start": "colyseus start",
    "typecheck": "tsc --noEmit",
    "test": "bun test"
  }
}

bun run dev

http://localhost:2567

// apps/client/src/network/RealtimeClient.ts

import {
  Callbacks,
  Client,
  type Room,
} from "@colyseus/sdk";

import type { BattleState } from "@beacon/contracts/schema";

export class RealtimeClient {
  private readonly client: Client;
  private room: Room<BattleState> | null = null;

  constructor(endpoint: string) {
    this.client = new Client(endpoint);
  }

  async joinBattle(options: {
    realtimeTicket: string;
    mapId: string;
    difficulty: number;
  }): Promise<Room<BattleState>> {
    if (this.room) {
      await this.leave();
    }

    this.room = await this.client.joinOrCreate<BattleState>(
      "battle",
      options,
    );

    return this.room;
  }

  getRoom(): Room<BattleState> {
    if (!this.room) {
      throw new Error("REALTIME_ROOM_NOT_JOINED");
    }

    return this.room;
  }

  send<T>(type: string, payload?: T): void {
    this.getRoom().send(type, payload);
  }

  async leave(): Promise<void> {
    const room = this.room;
    this.room = null;

    if (room) {
      await room.leave(true);
    }
  }
}

const endpoint = import.meta.env.PROD
  ? "https://play.example.com"
  : "http://localhost:2567";

export const realtimeClient = new RealtimeClient(endpoint);

http → ws
https → wss

// BattleScene.ts

import Phaser from "phaser";
import { Callbacks, type Room } from "@colyseus/sdk";

import type {
  BattleState,
  NodeState,
  PlayerState,
} from "@beacon/contracts/schema";

export class BattleScene extends Phaser.Scene {
  private room!: Room<BattleState>;

  private playerViews = new Map<string, Phaser.GameObjects.Container>();
  private nodeViews = new Map<string, Phaser.GameObjects.Container>();

  async create(): Promise<void> {
    this.room = await realtimeClient.joinBattle({
      realtimeTicket: await this.fetchRealtimeTicket(),
      mapId: "seedfall_standard",
      difficulty: 1,
    });

    this.bindRoomState();
    this.bindRoomMessages();
    this.bindRoomLifecycle();
    this.bindInput();
  }

  private bindRoomState(): void {
    const callbacks = Callbacks.get(this.room);

    callbacks.onAdd(
      "players",
      (player: PlayerState, sessionId: string) => {
        const view = this.createPlayerView(player);
        this.playerViews.set(sessionId, view);

        callbacks.listen(player, "connected", (connected) => {
          view.setAlpha(connected ? 1 : 0.4);
        });

        callbacks.listen(player, "ready", (ready) => {
          this.updateReadyIndicator(view, ready);
        });
      },
    );

    callbacks.onRemove(
      "players",
      (_player: PlayerState, sessionId: string) => {
        this.playerViews.get(sessionId)?.destroy();
        this.playerViews.delete(sessionId);
      },
    );

    callbacks.onAdd(
      "nodes",
      (node: NodeState, nodeId: string) => {
        const view = this.createNodeView(node);
        this.nodeViews.set(nodeId, view);

        callbacks.listen(node, "health", (health) => {
          this.updateNodeHealth(view, health);
        });

        callbacks.listen(node, "powered", (powered) => {
          this.updateNodePower(view, powered);
        });
      },
    );

    callbacks.onRemove(
      "nodes",
      (_node: NodeState, nodeId: string) => {
        this.nodeViews.get(nodeId)?.destroy();
        this.nodeViews.delete(nodeId);
      },
    );

    callbacks.listen("lumen", (value) => {
      this.events.emit("hud:lumen", value);
    });

    callbacks.listen("coreHealth", (value) => {
      this.events.emit("hud:core-health", value);
    });

    callbacks.listen("phase", (value) => {
      this.events.emit("match:phase", value);
    });
  }

  private bindRoomMessages(): void {
    this.room.onMessage(
      "command.rejected",
      (message: { requestId: string; code: string }) => {
        this.events.emit("command:rejected", message);
      },
    );

    this.room.onMessage(
      "game.effect",
      (message: {
        effectType: string;
        x: number;
        y: number;
      }) => {
        this.playEffect(message);
      },
    );
  }

  private bindRoomLifecycle(): void {
    this.room.onError((code, message) => {
      console.error("Colyseus room error", {
        code,
        message,
      });
    });

    this.room.onLeave((code) => {
      console.warn("Left room", { code });
      this.scene.start("ReconnectScene");
    });
  }

  private bindInput(): void {
    this.input.on(
      "pointerdown",
      (pointer: Phaser.Input.Pointer) => {
        this.room.send("build.place-node", {
          requestId: crypto.randomUUID(),
          nodeType: 1,
          x: pointer.worldX,
          y: pointer.worldY,
          rotation: 0,
        });
      },
    );
  }

  private async fetchRealtimeTicket(): Promise<string> {
    const response = await fetch("/api/v1/realtime/ticket", {
      method: "POST",
      credentials: "include",
    });

    if (!response.ok) {
      throw new Error("FAILED_TO_GET_REALTIME_TICKET");
    }

    const body = await response.json() as { ticket: string };
    return body.ticket;
  }

  private createPlayerView(
    _player: PlayerState,
  ): Phaser.GameObjects.Container {
    return this.add.container();
  }

  private createNodeView(
    node: NodeState,
  ): Phaser.GameObjects.Container {
    return this.add.container(node.x, node.y);
  }

  private updateReadyIndicator(
    _view: Phaser.GameObjects.Container,
    _ready: boolean,
  ): void {}

  private updateNodeHealth(
    _view: Phaser.GameObjects.Container,
    _health: number,
  ): void {}

  private updateNodePower(
    _view: Phaser.GameObjects.Container,
    _powered: boolean,
  ): void {}

  private playEffect(
    _message: {
      effectType: string;
      x: number;
      y: number;
    },
  ): void {}
}

update(): void {
  for (const [id, node] of this.room.state.nodes) {
    this.destroyAndRecreateNode(id, node);
  }
}

Schema onAdd
  → 创建 Phaser View

Schema listen/onChange
  → 更新 View 目标值

Schema onRemove
  → 销毁 View

const nodeViews = new Map<string, NodeView>();
const enemyViews = new Map<string, EnemyView>();
const playerViews = new Map<string, PlayerView>();

interface NetworkTransform {
  currentX: number;
  currentY: number;
  targetX: number;
  targetY: number;
}

view.x = Phaser.Math.Linear(
  view.x,
  view.targetX,
  0.2,
);

Phaser Render Rate
服务端 Simulation Rate
Colyseus Patch Rate

Phaser 渲染：60 FPS
服务端模拟：20 Hz
Patch Rate：10 Hz
敌人决策：5 Hz
经济聚合：5 Hz

export class BattleRoom extends Room {
  patchRate = 100;

  onCreate(): void {
    this.setSimulationInterval(
      (deltaTime) => this.updateSimulation(deltaTime),
      50,
    );
  }
}

Simulation Interval 50 ms = 20 Hz
Patch Rate 100 ms = 10 Hz

1. 玩家点击地图
2. 客户端显示半透明 Pending 建筑
3. 客户端发送 place-node
4. 服务端验证
5A. 成功：Schema 中增加正式 Node
5B. 失败：返回 command.rejected
6. 客户端移除 Pending 建筑

1. 用户登录 Hono API
2. API 返回 Access Token 或安全 Cookie
3. 客户端请求 POST /v1/realtime/ticket
4. API 签发短期 Ticket
5. 客户端使用 Ticket 加入 Colyseus Room
6. BattleRoom.onAuth 校验 Ticket
7. 服务端把 playerId 写入 auth context

interface RealtimeTicketPayload {
  sub: string;
  sessionId: string;
  scope: "room:join";
  region: string;
  nonce: string;
  iat: number;
  exp: number;
}

30～120 秒

playerId
displayName
role
level
inventory
entitlements
admin

async onLeave(
  client: Client,
  code: number,
): Promise<void> {
  const player = this.state.players.get(client.sessionId);

  if (!player) {
    return;
  }

  player.connected = false;

  const normalLeave = code === 1000;

  if (normalLeave) {
    this.removePlayer(client.sessionId);
    return;
  }

  try {
    await this.allowReconnection(client, 60);
    player.connected = true;
  } catch {
    this.removePlayer(client.sessionId);
  }
}

localStorage.setItem(
  "colyseus.reconnectionToken",
  room.reconnectionToken,
);

const token = localStorage.getItem(
  "colyseus.reconnectionToken",
);

if (token) {
  try {
    const room = await client.reconnect(token);
    return room;
  } catch {
    localStorage.removeItem(
      "colyseus.reconnectionToken",
    );
  }
}

服务端发送全部敌人
客户端判断是否显示

服务端计算视野
只同步客户端允许看到的数据

BattleState.visibleEnemies

await client.create("battle", options);
await client.join("battle", options);
await client.joinOrCreate("battle", options);
await client.joinById(roomId, options);

快速合作
  → joinOrCreate

私人房间
  → create + joinById

好友邀请
  → 保存 roomId + joinById

大厅列表
  → LobbyRoom 或业务 API

onCreate(options: {
  mapId?: string;
  difficulty?: number;
  private?: boolean;
}): void {
  this.setMetadata({
    mapId: options.mapId ?? "seedfall_standard",
    difficulty: options.difficulty ?? 1,
    private: options.private ?? false,
    phase: "waiting",
  });
}

await this.setMetadata({
  ...this.metadata,
  phase: "running",
});

LocalPresence
LocalDriver

bun add @colyseus/redis-presence
bun add @colyseus/redis-driver

import { defineRoom, defineServer } from "colyseus";
import { BunWebSockets } from "@colyseus/bun-websockets";
import { RedisPresence } from "@colyseus/redis-presence";
import { RedisDriver } from "@colyseus/redis-driver";

import { BattleRoom } from "./rooms/BattleRoom";

const redisUrl = process.env.REDIS_URL;

if (!redisUrl) {
  throw new Error("REDIS_URL_IS_REQUIRED");
}

export default defineServer({
  transport: new BunWebSockets({
    port: Number(process.env.PORT ?? 2567),
    hostname: "0.0.0.0",
  }),

  presence: new RedisPresence(redisUrl),
  driver: new RedisDriver(redisUrl),

  rooms: {
    battle: defineRoom(BattleRoom),
  },
});

Client
  │
  ▼
Dynamic Proxy
  ├── realtime-1
  ├── realtime-2
  └── realtime-3
       │
       ├── Redis Presence
       └── Redis Driver

房间创建
  → 加载玩家和关卡配置

房间运行
  → 内存权威状态

每 15～30 秒
  → 保存恢复快照，可选

比赛结束
  → 生成 MatchResult

MatchResult
  → Hono 内部 API 或 Outbox

Persistence Worker
  → PostgreSQL 幂等写入

interface MatchResult {
  matchId: string;
  settlementVersion: number;
  status: "victory" | "defeat" | "aborted";
  startedAt: string;
  endedAt: string;
  durationSeconds: number;
  mapId: string;
  difficulty: number;
  players: Array<{
    playerId: string;
    reward: number;
    score: number;
  }>;
}

match_id + settlement_version

1. 停止创建新房间
2. Readiness 返回不可用
3. 等待现有房间结束
4. 保存必要快照
5. 通知客户端
6. 关闭连接
7. 进程退出

process.on("SIGTERM", () => process.exit(0));

export type RealtimeErrorCode =
  | "AUTH_FAILED"
  | "ROOM_NOT_FOUND"
  | "ROOM_FULL"
  | "MATCH_STARTED"
  | "VERSION_MISMATCH"
  | "RATE_LIMITED"
  | "NETWORK_ERROR"
  | "RECONNECT_FAILED";

client.send("error", error.stack);

client.send("command.rejected", {
  requestId,
  code: "POSITION_BLOCKED",
});

logger.error({
  event: "place_node_failed",
  roomId: this.roomId,
  sessionId: client.sessionId,
  playerId,
  error,
});

const cooldownComplete =
  payload.clientTime > ability.readyAt;

const cooldownComplete =
  this.clock.elapsedTime >= ability.readyAt;

private processedRequests = new Map<string, number>();

private isDuplicate(requestId: string): boolean {
  if (this.processedRequests.has(requestId)) {
    return true;
  }

  this.processedRequests.set(
    requestId,
    Date.now(),
  );

  return false;
}

mapId
enemyType
nodeType
abilityId

enemy.status = "moving_towards_beacon_core";

enemy.status = EnemyStatus.MOVING;

基础模拟：20 Hz
敌人目标选择：5 Hz
路径重算：2 Hz
经济统计：5 Hz
排行榜统计：1 Hz
数据库快照：每 15 秒

每 Room 玩家：4
每 Room 节点：100
每 Room 建筑：200
每 Room 可见敌人峰值：500
每 Room 同步对象峰值：800

export class BattleSimulation {
  constructor(
    private readonly random: RandomSource,
  ) {}

  update(deltaMs: number): void {
    // 纯游戏规则
  }

  placeNode(command: PlaceNodeCommand): CommandResult {
    // 验证和状态修改
  }
}

import { describe, expect, test } from "bun:test";

describe("BattleSimulation.placeNode", () => {
  test("资源不足时拒绝建造", () => {
    const simulation = createSimulation({
      lumen: 10,
    });

    const result = simulation.placeNode({
      playerId: "player-1",
      nodeType: 1,
      x: 100,
      y: 100,
    });

    expect(result.ok).toBe(false);

    if (!result.ok) {
      expect(result.code).toBe(
        "INSUFFICIENT_LUMEN",
      );
    }
  });
});

1. 启动测试服务器
2. 创建第一个客户端
3. joinOrCreate battle
4. 创建第二个客户端
5. 加入同一房间
6. 两个玩家 Ready
7. 检查 phase 变为 RUNNING
8. 玩家发送 place-node
9. 检查 nodes 增加
10. 检查 lumen 减少
11. 发送非法命令
12. 检查 command.rejected
13. 模拟断线
14. 完成重连
15. 结束房间

WebSocket 能连接

1,000 个客户端
每个客户端保持连接
不发送游戏命令

100 个 Room
每 Room 4 人
每秒每玩家 2 个命令
每 Room 300 个敌人
Simulation 20 Hz
Patch 10 Hz

大量非法消息
超大 Payload
重复请求
频繁加入退出
Redis 短暂不可用
单实例重启

timestamp
level
service
environment
version
region
instanceId
roomId
matchId
sessionId
playerId
requestId
event
durationMs
errorCode

colyseus_active_connections
colyseus_active_rooms
colyseus_room_create_total
colyseus_room_dispose_total
colyseus_join_failure_total
colyseus_reconnect_success_total
colyseus_reconnect_failure_total
colyseus_tick_duration_ms
colyseus_patch_bytes
colyseus_messages_total
colyseus_command_rejected_total
runtime_event_loop_lag_ms
runtime_heap_bytes

match_duration_seconds
match_completion_total
match_abort_total
enemy_peak_count
node_peak_count
lumen_generated_total
lumen_spent_total
core_damage_total

NODE_ENV=development

HOST=0.0.0.0
PORT=2567

REDIS_URL=redis://localhost:6379/0
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/beacon

REALTIME_TICKET_SECRET=replace-me
INTERNAL_API_URL=http://api:3000
INTERNAL_API_TOKEN=replace-me

LOG_LEVEL=debug
REGION=local
BUILD_VERSION=dev

import { z } from "zod";

const envSchema = z.object({
  NODE_ENV: z.enum([
    "development",
    "test",
    "production",
  ]),
  PORT: z.coerce.number().int().positive(),
  REDIS_URL: z.string().url(),
  REALTIME_TICKET_SECRET: z.string().min(32),
  REGION: z.string().min(1),
});

export const env = envSchema.parse(
  process.env,
);

FROM oven/bun:1 AS base

WORKDIR /app

COPY package.json bun.lock ./
COPY apps/realtime/package.json ./apps/realtime/
COPY packages ./packages

RUN bun install --frozen-lockfile

COPY apps/realtime ./apps/realtime
COPY tsconfig.json ./

WORKDIR /app/apps/realtime

ENV NODE_ENV=production
ENV PORT=2567

EXPOSE 2567

CMD ["bun", "run", "start"]

HEALTHCHECK \
  --interval=10s \
  --timeout=3s \
  --retries=3 \
  CMD bun -e \
  "const r=await fetch('http://localhost:2567/health/live'); process.exit(r.ok?0:1)"

两个浏览器能够进入同一房间
State 能够同步
玩家离开后对象删除

修改客户端资源不能作弊
非法坐标被拒绝
重复请求不重复执行

断线 60 秒内恢复
过期 Ticket 无法加入
伪造 playerId 无效

不同实例可以共享房间查询
客户端能连接到房间所属实例
停止一个实例不影响其他实例的新房间

room.state.lumen = 9999;

room.send("build.place-node", payload);

BattleRoom.ts
超过 5,000 行

Room
Command
Simulation
System
Repository
Presenter

位置显著变化时发送
固定 10～20 Hz 发送
停止移动时发送最终坐标

apps/realtime/src/rooms/BattleRoom.ts

packages/game-core

apps/client/src/network

apps/client/src/scenes

apps/api

Phaser Input
  → Colyseus Message
  → Message Validation
  → Command Dispatcher
  → BattleSimulation
  → Authoritative State
  → Schema Patch
  → Phaser Callback
  → View Update