消息协议

以下为 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）、可选 region / skill / tags。其中 region 与 modeId、playersPerMatch 等共同决定 Redis 排队键（典型 queue:{modeId}:{playersPerMatch}:{region}），详见 匹配与开房 · 队列维度与 region。
match:cancel	取消当前排队。
party:create	创建房间码队伍；body 含 modeId、playersPerMatch、可选 region（与 match:find 的 region 字段同义，见 队列维度与 region）。
party:join	body：partyCode。
party:leave	离开队伍。
party:start	房主开局（人数需满）。

服务端 → 客户端

消息名	说明
mm:ready	加入匹配房后下发，含 sessionId。
match:queued	排队成功，含 queueKey。
match:cancelled	取消结果，含 ok。
match:found	对局就绪；含 roomName（game_room）、roomId、matchId、seatIndex、reconnectKey、joinOptions。
party:created / party:joined / party:update / party:left	队伍生命周期与人数同步。
party:error	业务错误文案。

对局房 game_room

进入方式：收到 match:found 后使用 roomId 与 joinOptions（并携带 JWT）加入。帧同步与重连见 帧同步与游戏房。

客户端 → 服务端

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

服务端 → 客户端（节选）

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