联机协议参考

01拓扑：服务器星型

StartRide 的联机是 服务器星型：所有客户端都只和服务器说话，彼此之间不发生任何直连。

        ┌──────────────┐
        │   中继服务器   │   ← 只转发，不判定
        └──┬───┬───┬───┘
     ┌─────┘   │   └─────┐
     ▼         ▼         ▼
  客户端A   客户端B   客户端C   ← 全部判定都在这里

02分帧与字节布局

本地桥（游戏内 Lua ↔ 启动器）用的是最简单的长度前缀分帧，因为两端都是我们自己的代码，没必要上更复杂的协议。

┌────────────────────┬─────────────────────────┐
│ 4 字节长度（小端）  │   JSON 负载（UTF-8）     │
└────────────────────┴─────────────────────────┘
         ↑ 只算负载长度，不含这 4 个字节本身

• 长度只算负载，不包括长度字段自己 —— 这里差 4 个字节，表现是解析出一堆乱码或者永远等不到完整包。
• 一次读取不保证拿到完整包。必须先读满 4 字节头，再按长度读满负载，中间要处理粘包与拆包。
• 单条消息不要做得特别大。位姿这类高频消息应该小而密，别攒一大批再发。

03消息封套

每条消息都是一个 JSON 对象。传输层不校验字段，字段的含义由收发两端约定。

{
  "type": "pose",          // 消息类型，派发靠它分流
  "room": "4821",          // 房间号（房间作用域内的消息才有）
  "from": "player-7f3a",   // 发送者标识
  "ts":   1730000000000,   // 发送时间戳（毫秒）
  "data": { "...": "..." } // 与 type 对应的负载
}

04本地桥

本地桥是游戏内 Lua 和启动器之间的一条本机通道，监听 127.0.0.1:4444。

为什么要有它

• 游戏内的 Lua 不自己开 socket：让 Lua 处理网络连接、重连、心跳，是给自己找麻烦。
• 所有网络细节（重连、心跳、认证）都留在启动器这一侧，Lua 只做「发一条 JSON、收一条 JSON」。
• 出问题时排查面很小：桥是通的，问题就在上层；桥不通，问题就在启动器或游戏进程。

05中继入口

中继服务器同时暴露两条入口，承载的内容完全一致，客户端按运行环境选一条：

• 两条入口在服务器内部汇合到同一个会话管理器，所以一个走 TCP 的客户端和一个走 WS 的客户端可以在同一个房间里互相看见。
• 走 WS 时的分帧由 WebSocket 协议自己负责，消息体是同样的 JSON。
• 房间作用域在服务器侧维护：消息进来先看 room，再决定转发给哪些连接。

06房间与会话

会话标识

• 每条连接在建立时拿到一个唯一的会话标识，它跟着连接走，不跟着账户走。
• 同一个人重连会拿到新的会话标识，所以「按会话标识去重」比「按账户去重」更可靠。
• 房间号是字符串，不要假设它是数字 —— 别做数学运算。

07心跳与超时

长连接必须有心跳，否则「线断了但没人知道」这件事会一直挂着，房间里就会出现永远不动也不消失的幽灵玩家。

08会话生命周期

                connect
                   │
                   ▼
              [ 已连接 ]
                   │  join(room)
                   ▼
              [ 在房间内 ] ── 收发同步与玩法消息
                   │
        ┌──────────┼───────────┐
        │          │           │
   主动离开    心跳超时      被踢 / 关房
        │          │           │
        └──────────┴───────────┘
                   │
                   ▼
            [ 会话结束 ] → ★ 本机必须复位到 lobby

1. 连接客户端与中继建立长连接，拿到会话标识。
2. 入房会话被挂到某个房间作用域，开始收发该房间的消息。
3. 广播同步消息在房间内转发；玩法消息在玩法模块之间流转。
4. 结束主动退出、心跳超时、被踢、关房，四种路径都要走同一套清理。

09同步模型

同步层只做一件事：让每个人的屏幕上，别人的车看起来在正确的位置。

远程车怎么被驱动

• 远程车不是「瞬移过去」的。直接设置整体位姿会让物理引擎和碰撞求解器打架，结果是车穿墙、抖动、互相弹开。
• 正确做法是逐节点施加力去逼近目标状态，让物理引擎自己算——看起来才是连续、可碰撞的。
• 节点级驱动必然有误差，所以才需要持续的修正节奏，而不是一次到位。

10版本协商

客户端与服务器在握手阶段交换版本号。策略是宁可拒绝，不要勉强兼容。

11失败与降级

12硬规则清单

1. 玩法逻辑一律不下发到服务器，服务器不认识玩法。
2. 消息派发必须显式处理每种已知类型，并且要有兜底出口。缺兜底出口的派发会把没识别的消息静默丢弃 —— 不报错、不日志。
3. 玩家中途离开要有宽限期，别因为一次网络抖动就判掉线。
4. 共享的玩家列表会被多个线程读写，改动它必须加锁或用快照。
5. 新增一种消息，就要在派发里加一个分支，并且同步更新审计门禁的覆盖范围。
6. 位姿广播只发变化量；高频消息要小而密，不要攒批。
7. 远程车用逐节点施加力驱动，不直接写整体位姿。
8. 会话结束的清理收敛到一个函数，所有结束路径都调它。