Bug Reporting for Games With AI Companions

AI companions are the NPCs players form attachments to, which means a companion that gets stuck on a doorway, runs into a wall, or stands uselessly during a fight is a memorable and immersion breaking bug. The player sees a friend acting like an idiot, but the cause is a behavior state machine in the wrong node or a navmesh query that quietly failed. By the time they reload, the companion has reset and the broken state is gone. This post covers the behavior and pathing state to capture so a companion report carries what the AI was actually thinking, instead of a clip of it walking into a corner.

Companion bugs are behavior state bugs

A companion's actions come from a behavior tree or state machine that selects what to do based on the world: follow the player, fight an enemy, take cover, wait. When a companion misbehaves, it is almost always sitting in the wrong node, following the player when it should fight, or stuck in a transition that never completes. The visible symptom, doing nothing or doing the wrong thing, tells you nothing about which node it is in or why it chose that node. The state machine value at the moment of the bug is the single most useful thing you can capture.

Compounding this, companions react to inputs the player cannot see: aggro from an off screen enemy, an order issued seconds ago, a condition like low health that flipped a branch. A companion that suddenly stops following may have entered combat with something the player never noticed. Capturing the current state, the last transition, and the trigger that caused it turns inexplicable behavior into a readable decision trail. You stop guessing what the AI meant to do and start reading what it actually decided and why.

Capture the behavior and target state

The core payload is the companion's brain at report time. Record the current behavior tree node or state machine value, the last transition and what triggered it, the companion's current target if any, and the last order the player or game issued. Include the companion's key blackboard values, things like perceived threat, health, and whether it believes it can reach the player. This is the difference between a report that says the companion froze and one that says the companion is stuck in the move to cover state with no valid cover target, which is an actual bug you can chase.

Capture a short history of recent state transitions rather than just the current node, because companions often get wedged by a rapid oscillation between two states rather than sitting in one. A companion flipping every frame between follow and attack will look frozen while actually thrashing, and only a transition log reveals it. A handful of recent transitions with their triggers is cheap to record and turns this whole class of oscillation bug from invisible into obvious the moment you read the report.

Pathing and navmesh failures

The other huge category is movement: a companion that runs into a wall, fails to follow through a door, or teleports to catch up. These are navmesh and pathfinding bugs. Capture the companion's current position and the player's position, the path the companion was following as a list of waypoints, the goal it was trying to reach, and the result of the last path query, succeeded, failed, or partial. A failed query that left the companion with no path, or a path that ends short of an off mesh link like a door, explains the stuck companion precisely and points you at the exact navmesh gap.

Teleport and warp behaviors deserve special attention because they are often band aids that hide the real bug. Many companion systems teleport an ally that falls too far behind, which masks a pathing failure as a jarring pop. Capturing why a warp fired, the distance that triggered it and whether a path was available, tells you whether the teleport is doing its job or papering over a navmesh hole the companion should have walked through. The position pair plus the path query result lets you reconstruct the geometry the companion could not navigate.

Combat and coordination bugs

In combat, companions must coordinate with the player and each other, and this is where their AI looks dumbest when it breaks. A companion that ignores the enemy attacking the player, focuses a dead target, or blocks a doorway during a fight is failing at target selection or positioning. Capture the companion's chosen combat target, the list of enemies it perceives, its current combat sub state such as attacking or repositioning, and its line of sight to its target. These reveal whether it picked a bad target, could not see a valid one, or got wedged trying to position, each a distinct fix.

Coordination bugs between multiple companions add another layer, since allies must share space and avoid each other's lines of fire. Two companions trying to occupy the same cover slot, or one blocking another's shot, are positioning conflicts that only make sense when you can see what each ally believed about the other. Capturing the squad's claimed positions and targets together lets you spot these conflicts, which are otherwise nearly impossible to reproduce because they depend on the exact arrangement of several agents at one instant.

Setting it up with Bugnet

Bugnet's in-game report button lets a player flag a misbehaving companion the moment it happens, and you attach the AI state as custom fields: the behavior node, last transition and trigger, current target, last order, key blackboard values, both positions, the path query result, and the combat sub state. The player writes my companion is stuck on the door, and the brain state that explains it ships with the report. Occurrence grouping then folds every report of the same stuck state into one counted issue, so a recurring pathing gap stands out from a one time fluke.

Because the behavior node and path result are fields, you can filter the dashboard to every report where the companion was stuck in move to cover with a failed path query, which is the exact cohort sharing one navmesh bug. That filtered view, paired with the captured positions, often points straight at a single doorway or seam in your level, so you can fix the geometry once and clear a whole cluster of reports rather than chasing each stuck companion individually.

Make companions reliable

Companion reliability is built from the accumulation of these captured cases. Each report that pins a companion to a specific bad state at a specific location becomes a test scene: spawn the companion there, issue the order, and assert it does the right thing. Over time these scenes form a suite that protects against the regressions a behavior tree edit can easily cause. A companion AI is too interactive to verify entirely by hand, so the captured field cases become the backbone of your verification, grounded in the situations that actually tripped players up.

The payoff is a companion players trust rather than babysit. When you can read the exact node a companion got stuck in and the exact navmesh seam it could not cross, you fix causes instead of adding more teleport band aids. The result is an ally that follows reliably, fights sensibly, and stays out of doorways, which is what makes a companion feel like a real character rather than a liability. Treat the behavior and pathing payload as the foundation of companion QA and the friend players remember will be remembered for the right reasons.

A companion's brain is a state machine. Capture the node, the trigger, and the path query and a stuck ally becomes a traceable case.