数据包与事件参考

01消息模型

每条消息是一个 JSON 对象。传输层只负责原样转发，字段的含义由收发两端约定。

有一条规则比字段名更重要，它值得单独占一个提示框：

02封套与负载

{
  "type":  "score",                 // 类型：派发靠它分流
  "from":  "player-7f3a",           // 谁发的
  "room":  "4821",                  // 房间作用域
  "ts":    1730000000000,           // 发送时刻（毫秒）
  "data":  { "delta": 1, "reason": "hit" }
}

03消息分类总表

04会话类消息

05同步类消息

06玩法类消息

玩法消息在玩法模块之间流转，服务器只负责把它们原样转给同房间的人。

07派发与兜底

派发器是整个消息系统里唯一「不认识就别丢掉」的地方。写两段对比就清楚了：

// ✗ 错误：没有兜底出口，未识别的类型静默消失
switch (msg.Type) {
    case "pose":  HandlePose(msg);  break;
    case "chat":  HandleChat(msg);  break;
}

// ✓ 正确：兜底出口把未知类型暴露出来
switch (msg.Type) {
    case "pose":  HandlePose(msg);  break;
    case "chat":  HandleChat(msg);  break;
    default:
        HandleUnknown(msg);   // 至少记一条日志，最好能转给玩法包
        break;
}

-- Lua 侧同理
local function dispatch(kind, msg)
  if kind == "phase" then return onPhase(msg) end
  if kind == "round" then return onRound(msg) end
  -- 兜底：转给玩法包，别让消息落地
  return onGamePacket(kind, msg)
end

• 兜底分支别写成「什么都不做」—— 那样和不写没区别，还是静默。至少记一条日志。
• 更好的做法是：兜底分支把消息转交给玩法包，让扩展功能有机会消费它。
• 上行和下行两段派发都要有兜底出口。只补一段，另一半照样丢。

08注册与生命周期

玩法包是独立的消息消费者。它通过主模块导出的注册接口把自己的处理函数挂上去，而不是去改主模块的派发逻辑。

09阶段状态清零清单

进入新阶段（尤其是换房、重开一局）时，下面这些必须逐项清零。漏一项，它就会跨局存活：

10新增一种消息的完整步骤

1. 定义类型名与负载字段，并确认旧版本收到它会安全忽略。
2. 在上行派发里加分支；没需要的方向也要显式忽略，别掉进兜底日志里刷屏。
3. 在下行派发里加分支。
4. 确认兜底出口仍然存在，并且新类型不会被它截走。
5. 如果是玩法消息，在玩法包里注册处理函数，并确认注册早于绑定。
6. 如果是阶段相关的状态，把它加进阶段清零清单。
7. 同步更新审计门禁脚本的覆盖范围，并用一份故意改坏的副本确认门禁会失败。

11排查：消息丢了怎么查

按这个顺序走，每一步都能砍掉一半可能性：

1. 确认发送端真的发了在发送点加一行日志。这一步经常直接命中 —— 有时候是条件分支根本没进。
2. 确认本地桥收到了在桥的收包点加日志。桥通、消息没到，说明上半段有问题。
3. 确认派发器分到了正确的分支打印收到的 type。如果打出来是「未知类型」，说明是类型名对不上。
4. 确认兜底出口没有把消息吃掉临时在兜底分支里把消息也打出来。
5. 确认处理函数真的被注册了打印注册表。空的，就是注册时机太晚。
6. 确认结果被写进了状态打印处理后的状态。处理跑了但状态没变，说明落点字段写错了。