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

Local Avoidance Benchmark Notes

Goal

This Unity project is a controlled benchmark for local avoidance frameworks. The only intended variable between framework branches is the implementation selected by AvoidanceFrameworkKind and created through AvoidanceAdapterRegistry.

Shared Runtime Surface

• Scene: Assets/Scenes/AvoidancePerfDemo.unity
• Entry point: AvoidancePerfBootstrap
• Game view debug panel:
  • framework selection
  • scenario selection
  • 2D / 2.5D / 3D mode
  • view mode switching
  • fish count presets and slider
  • pause / resume / reset
  • average FPS, 1% low FPS, simulation ms, GC allocation
• Shared agent representation: runtime-created cubes and capsules.
• Shared scenarios:
  • Free Swim
  • Cross Flow
  • Shark Charge
  • Narrow Passage
  • Dense Circle Stress

Adapter Boundary

Framework branches should keep benchmark logic stable and make changes primarily under:

Assets/Scripts/Benchmark/FrameworkAdapters/

Adapter implementations may add package-specific components to created agents, but should not change:

• scenario generation
• fish/shark count presets
• debug panel controls
• metric names
• camera/view modes
• spawn parameters unless the framework requires a narrowly documented compatibility adjustment

Current Baseline

NoAvoidanceAdapter is the control group. It moves agents directly by preferred velocity and does not perform avoidance.

The A* RVO, RVO2, and Unity NavMesh adapters currently start as placeholders so their worktree diffs stay easy to review.

Unity NavMesh Adapter Notes

UnityNavMeshAdapter uses the built-in UnityEngine.AI.NavMeshAgent API when NavMesh data is already available at runtime. The benchmark scene creates its fish and shark primitives dynamically, so a normal empty runtime cube scene may not have baked NavMesh data. In that case the adapter reports the missing NavMesh in the HUD status and falls back to baseline movement instead of adding invalid NavMeshAgent components.

To exercise Unity's NavMesh avoidance path, provide NavMesh data before selecting UnityNavMesh. A baked scene NavMesh is sufficient. If the project should build the benchmark floor at runtime, enable com.unity.ai.navigation and add a runtime NavMeshSurface setup before the adapter initializes.