本文件将世界语义映射为通信消息。协议只传递共同事实、命令和确认,不传递渲染器内部状态。
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. 版本演进
- 增加可选字段属于向后兼容变更。
- 修改字段语义、坐标系或时间解释必须提升主协议版本。
- 未知可选字段应忽略;未知消息类型不得默默当作已处理。
- 服务端应在握手阶段明确支持的版本。
- 旧规则解释器保留到相关事件全部被清理。