Navigation3D debugging and diagnostics

Layered debug draw, console commands, runtime tuning, volume self-checks, and a troubleshooting table.

Layered debug draw

cvar nav3d_debugDraw:

Level	Value	Draws
Off	`0`	Everything off (default)
Paths	`1`	Active trajectories (green), desired velocity (yellow), VO cones (cyan); filtered by `nav3d_debugAgent`
Full	`2`	Above + SVO wireframes, occupied subvoxels, cost zones, domain links, climb graph

Helper: nav3d_debugDrawRadius (default 256.0 m distance cull).

nav3d_debugDraw 2
nav3d_debugAgent 12345
nav3d_debugDrawRadius 128

Console commands

Command	Purpose
`nav3d_dumpStats`	Scheduler mode / queue depth / expansions per tick, plus per-volume tier / chunk / memory
`nav3d_debugAgent <entityId>`	Focus draw on one agent (no arg clears)
`nav3d_setQueryBudget <ms> <expansions>`	Per-tick query time and expansion budget
`nav3d_setQueryThreaded <0\|1>`	Background-thread scheduling
`nav3d_setBuildBudget <chunksPerTick>`	Streaming build submit budget
`nav3d_validateVolume <entityId>`	SVO invariant self-check

Volume readiness: poll IsVolumeReady(), or listen for NavigationVolumeNotificationBus::OnNavigationVolumeReady.

SVO health check

nav3d_validateVolume <volumeEntityId> checks structural invariants (layers / parent-child / Morton order / leaf refs) and optional border-link symmetry. Run it first when build or pathfinding looks wrong. Programmatic variant in Programmatic API.

Runtime tuning (Settings Registry)

Key prefix: /O3DE/Gems/Navigation3D/Runtime/ (defaults in the Gem’s Registry/navigation3d.setreg).

Key	Default	Console override	Purpose
`QueryBudgetMs`	`0.5`	`nav3d_setQueryBudget`	Per-tick query time (ms)
`QueryBudgetExpansions`	`2000`	same	Per-tick expansion cap
`QueryWorkerBatchExpansions`	`16384`	—	Background worker batch expansions
`QueryThreaded`	`false`	`nav3d_setQueryThreaded`	Background-thread scheduling
`BuildChunksPerTick`	`4`	`nav3d_setBuildBudget`	Streaming build chunks per tick
`ChunkSize`	`128.0`	—	Default chunk size
`LeafVoxelSize`	`0.5`	—	Default leaf voxel edge
`VelocityObstacleEnabled`	`true`	—	Global VO switch

Tips:

Multi-agent hitching → enable QueryThreaded, or lower QueryBudgetMs (smoother, slower completion).
Streaming build frame spikes → lower BuildChunksPerTick.
Resolution vs memory → tune LeafVoxelSize.

Troubleshooting

Symptom	Likely cause	What to try
Query `NoVolume`	Volume not ready / unresolved	`IsVolumeReady()`; set `VolumeEntity`; `nav3d_dumpStats`
`StartOccupied` / `GoalOccupied`	Endpoint in solid voxels	Snap with `FindNearestFreePosition`; ensure a radius tier covers the agent
`Unreachable`	Disconnected or blocked by no-fly	`nav3d_debugDraw 2`; check border links
Path through walls / poor fit	Geometry not collected or voxels too coarse	Confirm provider coverage; reduce `LeafVoxelSize`
Fixed-wing falls back to straight line	Turn / climb constraints too tight	Relax `MinTurnRadius` / `MaxClimbAngle`
AutoBuild does nothing	Baked asset assigned	Clear baked asset or rebake
Bake produces nothing	AP not running / wrong path	Confirm AP, `.svonav` exists, geometry provider present
Follow does nothing	Desired velocity never applied	Read `GetDesiredVelocity` each frame into your motion layer
Climb finds no path	Slope filter too strict / surface not ready	Tune `MinSlopeDegrees` / `MaxSlopeDegrees`; `IsSurfaceReady()`

CI gates (developer-oriented)

Gems/Navigation3D/Scripts/ci/ contains bake-determinism compare and benchmark threshold scripts. Not needed for day-to-day use; useful when shipping or changing core algorithms.

Next steps

HTN integration — planner-driven flight
Programmatic API — reproduce pathfinding in unit tests