痕迹模型

# 痕迹模型

痕迹是世界对一次经过的短暂记忆。系统保存路径事件及时间,不保存脚印最终像素。

## 1. 核心对象

### Trace

一段连续活动形成的逻辑痕迹。

```text
Trace
├── trace_id
├── origin
├── world_id
├── started_at
├── last_segment_at
└── status
```

### TraceSegment

为了上传、同步和区域查询而切分的一小段连续路径。

```text
TraceSegment
├── schema_version
├── event_type
├── event_id
├── trace_id
├── segment_id
├── world_id
├── region_id
├── origin
├── started_at
├── ended_at
├── points
├── surface
├── initial_strength
├── decay_profile
└── ruleset_version
```

### TracePoint

路径中的采样点,不等于一枚具体脚印。

```text
TracePoint
├── offset_ms
├── x
├── z
├── heading
└── strength(可选)
```

客户端根据路径、物种、步幅和地形,生成具体左右脚或爪印。

## 2. 为什么保存路径片段

不把每枚脚印作为独立事件,原因包括:

- 降低消息和存储数量;
- 保留连续运动语义;
- 允许不同设备使用不同渲染精度;
- 不把当前脚印 mesh 固化进协议;
- 便于验证速度、连续性和区域边界;
- 允许在生命周期内重建同一条路径。

## 3. 来源

`origin.kind` 的 MVP 值:

```text
human
animal
```

未来可以增加 `environment`,但环境造成的大面积变化优先使用环境事件,而不是伪造大量痕迹点。

示例:

```json
{
  "kind": "animal",
  "variant": "desert_fox"
}
```

不得在发送给其他用户的 `origin` 中包含稳定账户 ID。

## 4. 示例事件

```json
{
  "schema_version": 1,
  "event_type": "trace.segment.created",
  "event_id": "evt_01J...",
  "world_id": "desert_main",
  "region_id": "region_12_08",
  "trace_id": "trace_01J...",
  "segment_id": "segment_01J...",
  "origin": {
    "kind": "human",
    "variant": "walker"
  },
  "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,
      "strength": 0.91
    },
    {
      "offset_ms": 740,
      "x": 182.8,
      "z": 76.6,
      "heading": 1.84,
      "strength": 0.89
    }
  ],
  "surface": "fine_dry_sand",
  "initial_strength": 0.91,
  "decay_profile": "human_footprint_v1",
  "ruleset_version": "desert_decay_v1"
}
```

## 5. 时间语义

- `started_at` 和 `ended_at` 使用服务端校正后的世界时间。
- `offset_ms` 相对 `started_at`,避免每个点重复完整时间戳。
- 客户端提交的时间只是候选值,服务端可以校正或拒绝。
- `ended_at` 必须不早于 `started_at`。
- 相邻片段允许少量时间重叠用于去抖,但服务端必须去重。

## 6. 衰减模型

当前视觉状态由以下函数决定:

```text
trace_state = decay(
  trace_age,
  initial_strength,
  surface,
  overlapping_environment_events,
  decay_profile,
  ruleset_version
)
```

规范输出至少包含:

```text
phase: fresh | softening | fading | forgotten
visible: boolean
purge_eligible: boolean
normalized_life: 0..1
```

渲染器可以再根据 `normalized_life` 推导深度、颜色、边缘侵蚀和透明度。

## 7. 标准生命周期

```yaml
profile: human_footprint_v1
phases:
  fresh:
    range: [0.0, 0.15]
  softening:
    range: [0.15, 0.65]
  fading:
    range: [0.65, 1.0]
  forgotten:
    after: 1.0
```

这里的数值是标准化生命周期,不是分钟。实际寿命由世界参数决定:

```text
lifetime =
  base_lifetime
  × surface_factor
  × strength_factor
  × weather_factor
```

MVP 可以使用简单分段曲线,但输入、阶段和清理判断必须稳定。

## 8. 环境影响

风不修改每个脚印事件。系统查询痕迹生命周期内覆盖该区域的环境事件,再计算加速衰减。

要求:

- 同一环境事件不能被重复计入;
- 环境事件结束后仍保留到受其影响的痕迹全部过期;
- 规则版本必须说明多个环境事件如何叠加;
- 强风可以缩短剩余寿命,但不能让客户端和服务端产生不同的 `forgotten` 判断。

## 9. 服务端验证

服务端接受人类路径片段前至少检查:

- 消息大小和点数上限;
- 时间范围是否合法;
- 速度和转向是否在允许范围;
- 路径是否连续;
- 是否跨越不可达区域;
- `client_segment_id` 是否重复;
- 会话是否有权在该区域提交;
- 坐标和数值是否有限且非 NaN。

验证目的是保护共享空间,避免恶意客户端瞬间画满整片沙漠,而不是建立竞技反作弊系统。

## 10. 明确不保存的字段

以下字段不得进入权威痕迹记录:

```text
opacity
blur_radius
mesh_id
texture_id
particle_state
animation_progress
current_pixel_mask
client_camera
render_lod
```

如果某个功能要求保存这些字段,应先证明它为什么不能由路径、时间和规则推导。