生命周期

服务端 Room 从创建到销毁会经历一组固定回调；客户端则经历 连接 → 进房 → 收发 → 离房 / 断线重连。理解顺序有助于排查「消息还没注册就收到」「鉴权在错误阶段执行」等问题。

服务端：Room 回调（Colyseus）

下列方法在 src/rooms/*.ts 各房间类中覆写（具体类名见项目结构）。

阶段	回调	典型职责
房间创建	`onCreate(options: Partial<T>)`	初始化 `state`、注册 `onMessage`、启动定时器；`options` 含创建房间时传入的 metadata
成员加入	`onJoin(client, options)`	JWT / 业务校验（如 `@RequireAuth()`、`guildId`）、写入座位或在线列表；每个客户端进房都会触发一次
成员离开	`onLeave(client, consented: boolean)`	清理该 seat、广播离线；`consented === true` 多表示用户主动 `leave()`，false 多表示断线或异常关闭
房间销毁	`onDispose()`	停定时器、退订 Redis、释放外部资源

调用顺序（要点）

首个客户端执行 joinOrCreate("roomName", options) 时，若尚无实例，服务端先 onCreate，再对该客户端 onJoin。
后续客户端 joinOrCreate / joinById 同一房间：不再执行 onCreate，只 onJoin。
若在 onJoin 中 抛错或拒绝连接，该客户端不会稳定留在房内，也不会触发正常的「加入成功」路径。
当 maxClients 已满 或自定义逻辑拒绝时，应在文档与客户端提示「房间已满 / 拒绝原因」。

本项目多数业务房在 onJoin 侧做 JWT 与 options 校验（见鉴权与权限）。

消息注册时机

务必在 onCreate（或至少在任意 onJoin 收到客户端消息前）完成 this.onMessage(...) 注册。否则早期到达的消息可能无人处理。延迟注册常见于错误重构，应避免。

客户端：连接与房间

阶段	说明
建立传输层	`Client` 指向 WebSocket 入口（与 HTTP 同源不同路径，见 Colyseus 文档）
进房	`joinOrCreate(roomName, options)` 或 `joinById(roomId, options)`（匹配成功后常用）
进行中	`send` / `onMessage`、可选监听 Schema `onChange`
主动离开	`room.leave()` → 服务端对该 client 走 `onLeave(..., consented=true)`
异常断线	连接断开 → 服务端 `onLeave(..., consented=false)`；若在允许窗口内可用重连恢复同一逻辑玩家（`game_room` 见帧同步与游戏房）

客户端 options 必须与文档一致（如 token、matchId、seatIndex、reconnectKey），否则服务端校验失败。

整体时序（示意）

mermaid

sequenceDiagram
  participant C as 客户端
  participant R as Room 实例

  Note over R: 首个连接创建房间时
  R->>R: onCreate
  C->>R: join / joinById
  R->>R: onJoin（鉴权、写入状态）
  C->>R: send / 状态由 Schema 推送
  Note over C,R: 业务进行中…
  C->>R: leave 或断线
  R->>R: onLeave
  Note over R: 无人且满足销毁条件时
  R->>R: onDispose

（具体是否立即 onDispose 与 是否允许空房常驻、是否手动 disconnect() 等实现有关，以各 Room 源码为准。）

与本项目几类房间的对应关系

场景	生命周期上的特点
`matchmaker_room`	长时间驻留、大量客户端进出；不依赖单局 Schema，重在消息（`match:`、`party:`）与 Redis 队列
`game_room`	对局开始后人齐进入；结束时释放实例；关注重连窗口、`playerOffline` / `reconnect:ok`
`chat_*`	可按频道长期存在；世界频道注意 Redis 订阅生命周期（见多模式聊天）
`loadtest_room`	无鉴权，仅压测；生产务必关闭（见人数压力测）

常见实践清单

onCreate：创建 state、注册全部 onMessage、初始化 Redis / 定时器。
onJoin：RequireAuth、校验 guildId / teamId / matchId 等与玩法相关的 options。
onLeave：更新在线人数、广播 playerLeft 或聊天侧下线提示；区分主动离开与断线。
onDispose：清理定时器、clearInterval、Redis unsubscribe、关闭自定义句柄。

生命周期 ​

服务端：Room 回调（Colyseus） ​

调用顺序（要点） ​

消息注册时机 ​

客户端：连接与房间 ​

整体时序（示意） ​

与本项目几类房间的对应关系 ​

常见实践清单 ​

延伸阅读 ​