消息协议

以下为 Colyseus 房间通信中的常用消息约定（与 xymj-colyseus-server 实现一致）。聊天频道选型、进房参数与 Redis 说明见专题 多模式聊天。

加入房间

客户端通过 joinOrCreate(roomName, options) 传入参数：

（客户端代码）

TypeScript

{
  token: "jwt-access-token",
  guildId: "1001",
  teamId: "team-a",
  x: 0,
  y: 0
}

C#

// using System.Collections.Generic;
new Dictionary<string, object>
{
    { "token", "jwt-access-token" },
    { "guildId", "1001" },
    { "teamId", "team-a" },
    { "x", 0 },
    { "y", 0 }
};

GDScript

{
    "token": "jwt-access-token",
    "guildId": "1001",
    "teamId": "team-a",
    "x": 0,
    "y": 0,
}

token 与 accessToken 语义等效，至少传一个。

常见消息

• chat：发送聊天文本
• updatePosition：更新附近频道坐标（仅附近频道相关）

chat 下行消息示例

（客户端代码）

{
  channel: "guild",
  message: "hello",
  sender: {
    sessionId: "xxx",
    userId: "u001",
    username: "playerA"
  },
  timestamp: 1710000000000
}

频道说明

• chat_world_room：世界频道，支持跨实例 Redis 同步
• chat_guild_room：工会频道，按 guildId 过滤
• chat_nearby_room：附近频道，按坐标范围过滤
• chat_team_room：队伍频道，按 teamId 过滤

匹配房 matchmaker_room

在已加入 matchmaker_room 且完成鉴权的前提下，客户端与服务端消息约定如下（详情见 匹配与开房）。

客户端 → 服务端

消息名	说明
match:find	主动排队；body：modeId、playersPerMatch（2～100）、可选 gameRoomName / region / skill / tags。region 与 modeId、playersPerMatch 决定排队键（典型 queue:{modeId}:{playersPerMatch}:{region}）。当前默认实现：skill / tags 仅写入票据，不参与 FIFO 撮合。
match:cancel	取消当前排队。
party:create	创建房间码队伍；body：modeId、playersPerMatch、可选 gameRoomName / region、可选 user（展示资料，userId 以 JWT 为准）。
party:join	body：partyCode；可选 user。
party:leave	离开队伍。
party:start	仅房主；人数 ≥ playersPerMatch 可开局，不自动满员开局。

服务端 → 客户端

消息名	说明
mm:ready	加入匹配房后下发，含 sessionId。
match:queued	排队成功，含 queueKey。
match:cancelled	取消结果，含 ok。
match:found	对局就绪。roomName 为房间类型名（默认 game_room，可由排队/建房时的 gameRoomName 或 MATCH_MODE_GAME_ROOM_MAP 决定）；进房用 roomId + joinOptions + JWT。reconnectKey 在顶层；Party 路径的 joinOptions 可能不含 reconnectKey，须合并后再 joinById。
match:error	组局或 createRoom 失败等，含 message。
party:created / party:joined / party:update / party:left	队伍生命周期；party:update 含 members（userId + profile）。
party:error	业务错误文案。

对局房（默认 game_room）

框架默认注册的房间类型名为 game_room（示例实现 GameRoomExample）。匹配成局时也可创建其它已在 app.config 中 define 的类型名，由 match:find / party:create 的 gameRoomName 或服务端 MATCH_MODE_GAME_ROOM_MAP 决定；match:found.roomName 会标明本局实际类型。

进入方式：收到 match:found 后调用 joinById(roomId, { ...joinOptions, reconnectKey, token })，不要依赖 joinOrCreate("game_room") 去「碰」本局实例。帧同步与重连见 帧同步与游戏房、匹配与开房 · 对局房间名。

客户端 → 服务端

消息名	说明
input	帧输入；建议 { inputs, frame? }。
chat	广播聊天（除自己外）。

服务端 → 客户端（节选）

消息名	说明
frameSync	当前帧与目标 FPS。
playerJoined / playerLeft	人数变化。
playerOnline / playerOffline	重连窗口与在线状态。
playerAction	示例玩法广播（移动 / 攻击 / 跳跃等）。
reconnect:ok	重连或同用户去重成功。