FishROV/FishROV/Docs/local-avoidance-benchmark-notes.md

本地避障压测说明

目标

这个 Unity 工程用于横向压测本地避障方案。不同方案之间唯一应该变化的变量，是 AvoidanceFrameworkKind 选择后由 AvoidanceAdapterRegistry 创建的 adapter。

共享运行入口

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

Adapter 边界

框架接入应主要修改：

Assets/Scripts/Benchmark/FrameworkAdapters/

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

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

当前基线

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

A* RVO、RVO2、Unity NavMesh 都通过同一个调试面板选择，用同一套场景、数量、相机和指标进行对比。

A* Pathfinding Project Pro RVO Adapter

AstarRvoAdapter 位于 Assets/Scripts/Benchmark/FrameworkAdapters/，由 AvoidanceFrameworkKind.AstarRvo 选择。

• adapter 通过反射查找 Pathfinding.RVO.RVOController 和 Pathfinding.RVO.RVOSimulator，所以没有导入 A* Pro 时工程仍可编译。
• 如果缺少 A* Pro RVO 类型，Game 视口状态会提示缺包，并退回基线移动。
• 如果类型存在，adapter 会创建运行时 RVOSimulator，给 benchmark 对象添加 RVOController，把期望速度送入 A* RVO，再把反射得到的避障速度写回 BenchmarkAgent.ApplyVelocity。
• 共享场景、HUD、数量档、指标和相机逻辑不变。

RVO2 Adapter

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

• 选择 RVO2 时，adapter 会优先命中导入后的 RVO.Simulator。
• 如果之后移除 RVO2 源码，工程仍可编译；Game 视口状态会提示缺包，并退回基线移动。
• adapter 会查找类似 RVO.Simulator、RVO2.Simulator、RVO3D.Simulator、RVO.Simulator3D 的 Simulator 类型。
• 必要方法包括 addAgent / AddAgent、setAgentPrefVelocity / SetAgentPrefVelocity、getAgentVelocity / GetAgentVelocity、doStep / DoStep。
• 如果存在 setAgentPosition / SetAgentPosition，adapter 每次设置期望速度前会同步 Unity Transform 位置，避免 RVO 内部位置和 benchmark 边界夹取结果漂移。
• 2D 和 2.5D 使用 RVO 的 Vector2 风格类型，把 Unity x/z 映射到 RVO x/y；3D 模式在可用时绑定 Vector3 风格类型。

Unity NavMesh Adapter

UnityNavMeshAdapter 使用内置 UnityEngine.AI.NavMeshAgent 做对照组。

• adapter 会使用 NavMeshBuilder.BuildNavMeshData 为 benchmark 场景运行时生成一张平面 NavMesh，不需要手动烘焙场景。
• 如果运行时 NavMesh 构建失败，Game 视口状态会提示，并退回基线移动，不会添加无效 NavMeshAgent。
• 因为 NavMesh 是平面数据，3D 压测更适合作为 2D / 2.5D 对照；完整 3D 体积避障仍需要专门方案。