Bug Reporting for Games With Enemy AI Pathfinding

Enemy pathfinding produces some of the most visible and immersion-breaking bugs in a game: an enemy that freezes mid-charge, one that jitters back and forth at a corner, one that teleports across the level, or one that walks calmly into a wall. Players notice these instantly and report them, but a video only tells you the symptom. The cause lives in the navigation state, the path the agent was following, the navmesh under its feet, and the target it was chasing. Without that state you are reverse-engineering complex AI from a few frames of footage. This post covers the AI state worth capturing and how it turns navigation mysteries into reproducible cases.

Pathfinding failures and what they look like

The common failure modes each point at a different layer. A stuck agent that has no path usually means the planner could not connect its position to its target, often because one of them is off the navmesh or on an isolated island. An agent that jitters at a corner is typically fighting between path following and local avoidance, recomputing a slightly different path each frame. A teleport means the agent left the navmesh and a recovery routine snapped it to the nearest valid polygon, sometimes far away. Each symptom maps to a layer, but only if you captured which layer was active.

Because these systems are layered, the symptom can be misleading. An enemy walking into a wall might have a perfect path that it is not following because a state machine put it in an attack mode that overrides movement. So the report needs more than the path, it needs the agent's high-level state too: is it patrolling, chasing, attacking, fleeing, or stunned. Capturing both the navigation state and the behavior state lets you tell apart a navmesh problem from a behavior tree problem, which are fixed in completely different places.

Capture the path and the navmesh position

The most useful navigation snapshot includes the agent's world position, the navmesh polygon it currently occupies, its current path as a list of waypoints, and the index of the waypoint it is heading toward. A null or empty path with a valid target tells you the planner failed. A path that exists but points away from the target tells you the target moved after planning and a replan did not fire. The polygon the agent stands on tells you whether it is even on the navmesh, which is the first thing to check when an agent freezes or teleports.

Capture the target as well, whether it is the player, a position, or another entity, and the target's position at report time. Many pathfinding bugs are really target bugs: the agent is chasing a stale position, or the target went somewhere unreachable and the agent gave up in a confusing way. If your navmesh has off-mesh links like ladders or jumps, record whether the agent was traversing one, since those are frequent failure points where an agent can fall off the mesh entirely. The path, the polygon, and the target together describe the navigation problem precisely.

Dynamic obstacles and timing

Navigation rarely happens on a static mesh. Doors open and close, other agents block corridors, and physics objects roll into paths. Many pathfinding bugs are interactions between an agent and a dynamic obstacle that only existed for a moment. An agent freezes because an avoidance system thinks it is trapped between two other agents that have since moved on. Capturing the nearby dynamic obstacles or at least the local agent density at report time helps reconstruct a jam that has already cleared by the time you watch the clip.

Timing matters because pathfinding is often budgeted across frames. To avoid spikes, many games only let a few agents replan per frame, queuing the rest. An agent can appear stuck simply because its replan request sat in a queue behind others during a crowded moment. Capturing how long since the agent last replanned, and whether a replan is pending, reveals these scheduling artifacts. A bug that looks like broken pathfinding is sometimes just a starved replan budget, and you only see that if you captured the timing alongside the path state.

Make navigation reproducible

Pathfinding is more reproducible than it feels if you capture inputs and control the clock. Given the navmesh, the agent position, and the target, your planner should return the same path, so a captured scenario can be replayed by placing an agent at the recorded position with the recorded target on the same navmesh. The hard part is reproducing the dynamic context. A debug build that can spawn an agent at a saved position and target, on the player's loaded level, lets you watch the planner produce the same null path or the same bad route the player saw.

Build navigation debug visualization early: draw the navmesh, the agent's path, its target line, its avoidance radius, and color agents by their behavior state. Most navigation bugs become obvious the instant you can see the path and the mesh together. An island lights up, a gap in an off-mesh link is visible, a path that clips a wall is plain. Pair this with the captured state and you go from a confusing clip to a clear diagnosis fast. When you fix a navigation bug, save the scenario as a test that asserts the planner returns a valid path for that position and target.

Setting it up with Bugnet

Bugnet's in-game report button captures device and platform context automatically, and you extend it with custom fields for the agent's position, navmesh polygon, current path summary, target, behavior state, and time since last replan. Because the button snapshots game state when the player reports a frozen enemy, you receive the agent's exact navigation state at that instant rather than a description of a clip. That snapshot is enough to recreate the scenario on your build, spawn the agent at the same spot with the same target, and watch the path fail the same way.

Occurrence grouping shows you which navigation failures are systemic versus one-off. If a particular corridor or off-mesh link traps agents repeatedly, Bugnet folds those reports into one issue with a count so you fix the location, not the symptom. Filter by behavior state to separate navmesh bugs from behavior tree bugs, filter by level to find problem geometry, and keep every captured path in one dashboard. A genre full of seemingly random AI glitches becomes a prioritized list of specific navmesh patches and behavior transitions that you can actually repair.

Build the safety net

Navigation bugs love to come back, because a level tweak can reintroduce a gap or an island that you fixed months ago. So when you capture and fix a pathfinding bug, turn the scenario into a regression test: the agent position, the target, the navmesh, and an assertion about the expected path. Run a connectivity sweep over your navmesh in continuous integration to catch islands and gaps before they ship. Over time these tests become a map of every navigation failure your levels have ever produced, and they guard against the silent regressions that plague hand-edited navmeshes.

The mindset is to treat each agent as a system whose behavior is a function of its navmesh, its position, its target, and its state, all of which you can capture and replay. Once you instrument reports to grab that state, build navigation visualization, and grow a test corpus, the frozen and teleporting enemies that used to feel like gremlins become ordinary, fixable bugs. Your AI looks smarter to players not because it is, but because you finally have the information to stop it from doing the obviously dumb thing in front of them.

Pathfinding bugs are navmesh, path, and behavior state bugs. Capture all three with the report and the frozen enemy stops being a mystery.