房间机制（概览）

在 xymj-colyseus-server 里，Colyseus 房间（Room） 是实时对战、匹配大厅、聊天频道等业务的核心载体：客户端通过 WebSocket 与某个 房间名（roomName） 下的服务端逻辑进程通信，而不是每个 HTTP 请求单独短连接。

房间在整体架构中的位置

维度	HTTP API	Colyseus 房间
连接方式	请求 / 响应，用完即结束	长连接，可长时间保持
典型用途	登录注册、支付、配置拉取	对局状态、匹配排队、频道聊天、帧同步输入
鉴权	Authorization: Bearer 等	进房时在 joinOrCreate / joinById 的 options 里带 JWT（约定见 JWT 与房间鉴权）

常见流程：REST 登录拿到 token → 客户端再连 Colyseus 并进房。同一用户可同时存在于多个房间（例如一边在 matchmaker_room 排队，另一边已进入 chat_team_room），只要你方客户端发起多次 join。

本仓库注册的房间类型（客户端 roomName）

与 src/app.config.ts 中注册一致（详见 项目结构）：

房间名	服务端类（示意）	典型用途	备注
my_room	MyRoom	示例 / 模板	熟悉 Schema、消息注册
matchmaker_room	MatchmakerRoom	主动匹配、Party 房间码	依赖 Redis（队列、跨进程通知）
game_room	GameRoomExample（示例实现）	帧同步对局	多由匹配下发 joinById；含 input、重连；正式项目宜 fork 自有房间类
chat_world_room 等	WorldChatRoom 等	世界 / 工会 / 附近 / 队伍聊天	世界频道常配合 Redis 跨实例同步
loadtest_room	LoadTestRoom	压连接 / 吞吐	无 JWT，仅测试；生产建议关闭

同一玩法不要混用房间名：例如「路人匹配」与「好友房」共用协议层消息（如 match:find）但仍在 matchmaker_room 内完成；真正对战在进入 game_room 后才开始。

两种同步手段：Schema 状态 vs 自定义消息

• Schema 状态（@colyseus/schema）：房间内有 Room.state，服务端修改字段后 Colyseus 自动增量同步给所有订阅客户端，适合「盘面数据」「血量字典」等结构化状态。详见 状态同步（Schema）。
• room.send / onMessage：适合一次性事件、指令响应、聊天文本等；不必进入 Schema。约定集中写在 消息协议，专题见 多模式聊天、匹配与开房。

很多房间 两者并用：例如 game_room 用 Schema 保存帧相关状态，用消息下发 frameSync、playerOffline 等事件。

何时拆成多个房间

• 按玩法隔离：匹配 / 大厅（matchmaker_room）与单局对战（game_room）分离，避免大厅广播冲击对局逻辑。
• 按频道隔离：世界 / 工会 / 附近 / 队伍使用不同 chat_*_room，进房 options（guildId、teamId、坐标）决定谁能收到聊天。
• 按人数与生命周期：一局结束可销毁 game_room 实例；聊天房可按业务常驻或短 TTL。

环境与依赖（与房间相关）

• Redis：匹配队列、部分聊天跨进程、match:found 投递、会话与重连键等多处使用；本地跑 Matchmaking / 多实例 前请先启动 Redis（见 配置说明）。
• MySQL / TypeORM：偏 HTTP 与持久化业务；房间内存状态仍以 Colyseus 房间与 Redis 为主。

推荐阅读顺序

1. 生命周期 — 回调顺序、客户端与服务端视角
2. 鉴权与权限（细则：JWT 与房间鉴权）
3. 状态同步（Schema）
4. 多模式聊天
5. 匹配与开房（matchmaker_room + Redis / 房间码）
6. 帧同步与游戏房（game_room、input、重连）

更多按玩法选型可先看 应用场景概览。