Testing and Debugging AI
Test AI in layers so that a missing path is not mistaken for a behavior-selection problem.
Recommended test sequence
- Geometry: create a simple floor with collision and verify navmesh visualization.
- Route: use Navmesh Path Test with two nearby endpoints, then introduce an obstacle.
- Movement: request one destination on AI Navigation. Check its movement mode and controller settings.
- Selection: add an AI Agent with a simple idle behavior. Add target-dependent behaviors after sensor detections work.
- Queries: test EQS or tactical destinations separately, then connect them to a navigation state.
- Coordination: add claims, squads, and distance-based update budgets after the single-agent case works.
Editor previews versus runtime tests
| Tool | What it verifies |
|---|---|
| Behavior Score Preview | Consideration curves, utility, weight scaling, and commit/cooldown effects for simulated inputs. |
| Archetype Perception & Peek | Authored behavior grouping, consideration summaries, and perception tuning. |
| EQS Query Preview | Query scoring in a synthetic layout with approximate navigation tests. |
| Navmesh Path Test | Routes on generated scene navigation data while simulating. |
| AI EQS Query Test / AI Tactical Query Test | Query results and optional cover claims in the actual simulating scene. |
The EQS editor's use scene simulation checkbox is currently disabled. Use a scene test component for collision, line-of-sight, and navmesh validation.
Useful CVars
Open Panels > CVars to edit these values. Most visualizations need a simulating scene. See CVars for console and command-line alternatives.
| CVar | Use |
|---|---|
AI.Navmesh.Visualize | Navmesh index: 0 = first, -1 = off. |
AI.Navmesh.ShowBuildStats | Inspect sector build progress and load. |
AI.Navmesh.VisualizeBlockers | Show blockers and obstacle carve volumes. |
AI.Navmesh.VisualizeLinks | Show off-mesh links. |
AI.Agents.ShowScores | Behavior scores and consideration breakdowns. |
AI.Agents.ShowHistory | Behavior switch history. |
AI.Agents.ShowPerception | Perceived target records. |
AI.Agents.DebugFilter | Only display agents whose object names contain this text. |
AI.EQS.VisualizeQueries | Set to 1 to inspect query candidates/results. |
AI.EQS.VisualizeScores | Show the winning candidate's per-test scores. |
AI.EQS.Stats | Query statistics. |
AI.Tactical.VisualizeCover | Generated/authored cover and claims. |
AI.Tactical.VisualizeQueries | Tactical query results. |
AI.Tactical.ShowStats | Tactical statistics. |
AI.SmartObjects.ShowDebug | Interaction slots and claims. |
AI.Squad.ShowDebug | Squad membership, tokens, targets, and intent. |
AI.VoxelGrid.Visualize | Voxel navigation grid. |
Common problems
| Symptom | Check |
|---|---|
| Empty navmesh overlay | A navmesh configuration must exist and something must request sectors. Check floor collision, layer, ground type, sector bounds, and simulation state. |
| Narrow doorway missing | Agent radius rounds up to whole cells. Check clearance, height, slope, and step height. |
| Path test works but character stays still | Check destination calls, navigation state, ApplySteering in DirectTransform mode, and controller/animation setup in the other modes. |
| Agent never chooses combat | Check sensor categories/markers, team filtering, target confidence, zero-valued considerations, cooldown, and behavior locks. |
| Behavior switches repeatedly | Inspect history; tune commit bonus, curve floors, cooldown, and completion signals. |
| EQS reports area not ready | Allow generation to finish or prebuild the region. Retry rather than treating it as an unreachable destination. |
| EQS reports no result | Inspect context names, candidate radius, filters, cover generation, and claims. |
| Agent walks to the origin | Check query success and the exact vector-entry name before starting navigation. |
| Cover is missing on low props | A prop below step height may not form a navmesh boundary. Add an authored cover point or strip. |
| Smart object is found but cannot be used | Check claim ownership, slot position, use range, and the navigation result. |
| Slow response at distance | Check the LOD center and decision-rate budgets before assuming logic failed. |
Changes to geometry, settings, or asset dependencies can require a new simulation run. Keep an explicit failure or retry branch in state machines so a query or path failure does not leave the agent waiting indefinitely.