# 本地避障压测说明

## 目标

这个 Unity 工程用于压测本地避障方案。当前阶段先收束到两条主线：

- `Rvo2Adapter`：成熟 RVO2 / ORCA 基准。
- 项目自研 RVO2 思想版本：用于验证可控性、可调参空间和性能上限。

当前工程入口只保留 `NoAvoidance`、`Rvo2` 和自研版。不同方案之间唯一应该变化的变量，是 `AvoidanceFrameworkKind` 选择后由 `AvoidanceAdapterRegistry` 创建的 adapter。

## 共享运行入口

- 场景：`Assets/Scenes/AvoidancePerfDemo.unity`
- 入口脚本：`AvoidancePerfBootstrap`
- Game 视口调试面板：
  - 避障方案选择：无避障、RVO2、自研版
  - 测试场景选择
  - 2D / 2.5D / 3D 模式
  - 观察视角切换
  - 鱼数量预设和滑条
  - 暂停 / 继续 / 重置
  - 平均 FPS、1% Low FPS、模拟耗时、GC 分配
  - 碰撞调试：XZ 平面重叠对数、3D 空间重叠对数、最近清空间距
- 表现对象：鱼为运行时圆锥，圆锥尖头表示朝向。
- 共享场景：
  - 自由巡游
  - 对向穿流
  - 狭窄通道
  - 圆阵高压

## Adapter 边界

框架接入应主要修改：

```text
Assets/Scripts/Benchmark/FrameworkAdapters/
```

adapter 可以给运行时创建的对象追加框架自己的组件，但不应改变：

- 场景生成逻辑
- 鱼数量档
- Game 视口调试控件
- 指标名称
- 相机/视角模式
- spawn 参数，除非框架确实需要很小且有文档说明的兼容调整

## 当前基线

`NoAvoidanceAdapter` 是对照基线：只按期望速度移动，不做避障。

当前压测结论主线只比较 RVO2 原版和基于 RVO2 思想的自研版本。编辑器压测入口已经只保留无避障、RVO2 和自研版，避免无关选项干扰当前结论。

## 当前压测口径

- 分辨率：标准移动端竖屏 `1080x1920`。
- 环境：先在 Unity 编辑器下跑同一套场景，再到百元机真机复测。
- 场景：理想空旷、双向穿流、圆阵向心、高密度聚集、初始重叠、狭窄通道、单目标争抢。
- 数量档：建议至少覆盖 `100 / 500 / 1000 / 3000 / 5000`。
- 指标：平均 FPS、1% Low FPS、模拟耗时、最大模拟耗时、GC 分配、XZ 平面重叠对数、3D 空间重叠对数、最近清空间距、平均速度损失。
- 公平条件：半径、最大速度、`timeStep`、目标生成、积分方式、邻居范围、日志采样策略必须一致。

## 日志策略

编辑器和百元机都需要日志，但日志不能拖慢性能测试。

- 日志目录：`Application.persistentDataPath/AvoidanceBenchmarkLogs/`。
- 编辑器下通常在用户目录的 `AppData/LocalLow/.../AvoidanceBenchmarkLogs/`。
- 真机下在 App 的 persistent data path 里，使用面板的“导出日志”按钮或结束/重置测试自动写出。
- 不要每帧 `Debug.Log`。
- 不要在热路径里拼接字符串。
- 不要每帧写文件。
- 不要让某个 adapter 单独输出额外明细，导致对比不公平。
- 建议只在内存中记录结构化数值样本。
- 当前实现固定每 `0.5s` 采样一次，先写入内存列表。
- 单轮重置、退出或点击“导出日志”时一次性导出 CSV。
- Console 只打印一行摘要，例如算法、场景、数量、平均 FPS、1% Low、平均模拟耗时、最大耗时、重叠对峰值。

百元机真机日志建议额外记录：

- 设备型号。
- 目标帧率。
- 实际分辨率是否为 `1080x1920`。
- Unity 图形 API。
- 是否 Development Build。
- 是否连接调试器。
- 是否出现明显发热、降频或后台干扰。

## RVO2 Adapter

当前已在 `Assets/ThirdParty/RVO2-CS/` 导入 `snape/RVO2-CS` 的核心 `RVOCS` 源码，并保留 Apache-2.0 许可证说明。

- `Rvo2Adapter` 已从反射桥改为直接调用 `RVO.Simulator`，避免每个 agent 每帧多次反射调用污染性能对比。
- 每帧设置期望速度前会同步 Unity Transform 位置，避免 RVO 内部位置和 benchmark 边界夹取结果漂移。
- RVO2-CS 是 2D 算法，2D 和 2.5D 使用 Unity `x/z` 到 RVO `x/y` 的映射；3D 模式会投影到 XZ 平面。

## 采样避障学习版

`SamplingLocalAvoidanceAdapter` 是项目内自写的学习算法，用来和成熟框架做横向对比。

- 使用空间哈希查找近邻，避免全量 O(n²) 扫描。
- 对每个 agent 采样多组候选速度，并用目标偏差、速度平滑、预测碰撞、当前重叠、边界越界惩罚打分。
- 它不是完整 ORCA，也不保证无碰撞；当前只作为自研候选的弱基线，表现明显差于 RVO2 是预期内结果。
- 如果它在某些场景比 RVO2 更稳，只能说明当前启发式适合该场景，不代表算法理论上更强。
