# 本地避障压测说明

## 目标

这个 Unity 工程用于压测 FishROV 的本地避障方案。当前主线已经收束为：

- `NoAvoidanceAdapter`：无避障对照基线。
- `Rvo2Adapter`：成熟 RVO2 / ORCA 本地避障基准，也是当前可用主线。

此前的独立启发式避障方案已经从工程入口移除。后续复杂鱼群行为不再通过重写局部避障求解器推进，而是在 RVO2 外层增加行为参数、preferred velocity 生成、RVO2 参数映射和运动后处理。

## 共享运行入口

- 场景：`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` 是对照基线：只按期望速度移动，不做避障。

`Rvo2Adapter` 是当前主线：

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

## 后续扩展方向

复杂鱼群场景优先做在 RVO2 外层：

- 行为层：胆小、攻击性、群体倾向、追逐、逃逸、领地、避障优先级。
- 参数映射：按鱼种或状态调整 `radius`、`neighborDist`、`maxNeighbors`、`timeHorizon`、`maxSpeed`。
- 期望速度生成：把目标、水流、群体队形、垂直偏好合成 preferred velocity。
- 后处理：转向速度限制、加速度限制、动画姿态和视觉平滑。

只有当 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`。
- 不要在热路径里拼接字符串。
- 不要每帧写文件。
- 建议只在内存中记录结构化数值样本。
- 当前实现固定每 `0.5s` 采样一次，先写入内存列表。
- 单轮重置、退出或点击“导出日志”时一次性导出 CSV。

真机日志建议额外记录：

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