通信协议

本文件将世界语义映射为通信消息。协议只传递共同事实、命令和确认,不传递渲染器内部状态。

1. 基本约定

  • 传输:区域快照可用 HTTP,实时消息使用 WebSocket。
  • 编码:MVP 使用 UTF-8 JSON。
  • 时间:ISO 8601 UTC,服务端时间权威。
  • 版本:每条消息携带 protocol_version。
  • 标识:事件和片段使用不可预测、全局唯一的字符串 ID。
  • 幂等:客户端提交命令携带 client_message_id。

公共消息不得包含稳定账户 ID。

2. 消息分类

Command:客户端请求世界接受某个动作
Event:服务端宣布已经成立的共同事实
Snapshot:服务端提供某一区域当前有效事实集合
Ack/Error:服务端确认或拒绝客户端命令
Presence:只在连接期间有效的短暂状态

客户端提交的路径不是事实。trace.segment.accepted 只确认命令已被接受;服务端广播的 trace.segment.created 才是共享世界事实。

3. 通用消息封装

{
  "protocol_version": 1,
  "type": "message.type",
  "message_id": "msg_01J...",
  "server_time": "2026-10-21T00:00:00.000Z",
  "payload": {}
}

客户端命令可以没有 server_time,但必须有:

{
  "protocol_version": 1,
  "type": "command.type",
  "client_message_id": "client_01J...",
  "payload": {}
}

4. 加入区域

客户端发送:

{
  "protocol_version": 1,
  "type": "region.join",
  "client_message_id": "client_01J...",
  "payload": {
    "world_id": "desert_main",
    "region_id": "region_12_08",
    "known_snapshot_version": null
  }
}

服务端返回:

{
  "protocol_version": 1,
  "type": "region.snapshot",
  "message_id": "msg_01J...",
  "server_time": "2026-10-21T00:00:00.000Z",
  "payload": {
    "world_id": "desert_main",
    "region_id": "region_12_08",
    "snapshot_version": "snap_01J...",
    "world_seed": "desert-main-v1",
    "terrain_version": 1,
    "decay_ruleset": "desert_decay_v1",
    "traces": [],
    "creatures": [],
    "environment_events": [],
    "presences": []
  }
}

快照只能包含在 server_time 时仍有效的事件。

5. 提交路径片段

客户端发送:

{
  "protocol_version": 1,
  "type": "trace.segment.submit",
  "client_message_id": "client_01J...",
  "payload": {
    "world_id": "desert_main",
    "region_id": "region_12_08",
    "trace_id": "trace_01J...",
    "client_segment_id": "local_01J...",
    "started_at": "2026-10-21T00:00:00.000Z",
    "ended_at": "2026-10-21T00:00:04.200Z",
    "points": [
      {"offset_ms": 0, "x": 182.4, "z": 76.1, "heading": 1.82},
      {"offset_ms": 740, "x": 182.8, "z": 76.6, "heading": 1.84}
    ]
  }
}

服务端接受:

{
  "protocol_version": 1,
  "type": "trace.segment.accepted",
  "message_id": "msg_01J...",
  "server_time": "2026-10-21T00:00:04.500Z",
  "payload": {
    "client_message_id": "client_01J...",
    "client_segment_id": "local_01J...",
    "event_id": "evt_01J...",
    "segment_id": "segment_01J...",
    "authoritative_started_at": "2026-10-21T00:00:00.100Z",
    "authoritative_ended_at": "2026-10-21T00:00:04.300Z"
  }
}

接受后,服务端向相关区域广播规范化后的 trace.segment.created 事件。

6. 拒绝路径片段

{
  "protocol_version": 1,
  "type": "command.rejected",
  "message_id": "msg_01J...",
  "server_time": "2026-10-21T00:00:04.500Z",
  "payload": {
    "client_message_id": "client_01J...",
    "code": "PATH_SPEED_EXCEEDED",
    "retryable": false
  }
}

MVP 错误码:

INVALID_MESSAGE
UNSUPPORTED_VERSION
NOT_IN_REGION
PATH_TOO_LARGE
PATH_TIME_INVALID
PATH_SPEED_EXCEEDED
PATH_DISCONTINUOUS
DUPLICATE_MESSAGE
RATE_LIMITED
SERVER_UNAVAILABLE

不得在错误中回显内部安全标识或其他用户数据。

7. 在线状态

客户端定期发送移动意图或心跳,服务端广播低频、量化后的存在状态:

{
  "protocol_version": 1,
  "type": "presence.updated",
  "message_id": "msg_01J...",
  "server_time": "2026-10-21T00:00:02.000Z",
  "payload": {
    "presence_id": "temporary_4f91",
    "region_id": "region_12_08",
    "x": 182.8,
    "z": 76.6,
    "heading": 1.84
  }
}

约束:

  • presence_id 只在当前会话有效;
  • 消息不提供资料查询入口;
  • 断线或超时后发送 presence.left;
  • 客户端自行插值,不要求高频竞技级同步。

8. 动物经过

{
  "protocol_version": 1,
  "type": "creature.traverse.scheduled",
  "message_id": "msg_01J...",
  "server_time": "2026-10-21T01:09:50.000Z",
  "payload": {
    "creature_id": "creature_ephemeral_01J...",
    "species": "desert_fox",
    "region_id": "region_12_08",
    "starts_at": "2026-10-21T01:10:00.000Z",
    "path": [
      {"offset_ms": 0, "x": 10.2, "z": 4.8},
      {"offset_ms": 8400, "x": 18.1, "z": 7.2},
      {"offset_ms": 19700, "x": 31.5, "z": 12.9}
    ],
    "trace_profile": "fox_tracks_v1",
    "ruleset_version": "desert_decay_v1"
  }
}

客户端晚于 starts_at 收到消息时,应按权威时间定位动物当前进度,而不是从头播放。

9. 环境事件

{
  "protocol_version": 1,
  "type": "environment.wind.changed",
  "message_id": "msg_01J...",
  "server_time": "2026-10-21T00:30:00.000Z",
  "payload": {
    "event_id": "env_01J...",
    "region_id": "region_12_08",
    "starts_at": "2026-10-21T00:30:00.000Z",
    "ends_at": "2026-10-21T00:42:00.000Z",
    "intensity": 0.74,
    "direction": 2.1,
    "ruleset_version": "desert_decay_v1"
  }
}

10. 重连与补偿

  • 断线后客户端不假设本地状态仍权威。
  • 重连先请求新快照,再处理快照版本之后的增量事件。
  • 已提交但未确认的路径可以凭同一个 client_message_id 重试。
  • 服务端幂等返回原确认,不能创建重复痕迹。
  • 已经过期的痕迹不会因为重连重新返回。

11. 版本演进

  • 增加可选字段属于向后兼容变更。
  • 修改字段语义、坐标系或时间解释必须提升主协议版本。
  • 未知可选字段应忽略;未知消息类型不得默默当作已处理。
  • 服务端应在握手阶段明确支持的版本。
  • 旧规则解释器保留到相关事件全部被清理。