通信协议

# 通信协议

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

## 1. 基本约定

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

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

## 2. 消息分类

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

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

## 3. 通用消息封装

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

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

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

## 4. 加入区域

客户端发送:

```json
{
  "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
  }
}
```

服务端返回:

```json
{
  "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. 提交路径片段

客户端发送:

```json
{
  "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}
    ]
  }
}
```

服务端接受:

```json
{
  "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. 拒绝路径片段

```json
{
  "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 错误码:

```text
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. 在线状态

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

```json
{
  "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. 动物经过

```json
{
  "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. 环境事件

```json
{
  "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. 版本演进

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