Unity NPC debugging
Explains surprising Unity NPC behavior by tracing perception, memory, decisions and movement separately. Finds stale facts or competing controllers before replacing the whole decision system.
unity-npc-ai-debugging
Agents using this skill
When is it useful?
Use it when enemies oscillate, navigate poorly or appear to know things their sensors never observed.
What does it help you do?
- Traces perception, memory, decisions, execution and navigation separately.
- Checks stale targets, oscillating scores and competing movement writers.
- Profiles representative crowds and verifies the original failure after correction.
Try asking this
A Unity guard alternates between chasing and returning to patrol every second. Record what it sees, remembers and scores at each switch, then inspect movement ownership and target validity. Correct the demonstrated cause and rerun the same route with several guards to verify stable behavior and acceptable update cost.
Detailed documentation
Read the skill’s original instructions, examples and checks in their authored language.
Show less
NPC AI Debugging and Tuning
Reproduce before changing behavior
Record scene, Unity/package versions, NPC configuration, initial state, actor count, player actions and random seed when controllable. Write the expected decision and the actual decision at a specific point in the scenario. Separate a behavior-design disagreement from an implementation defect.
Collect a compact trace of sensed facts, remembered facts and age, current state/action, transition reason, candidate scores, cooldowns, path status, motor ownership and interruptions. Prefer on-demand bounded traces over logging every NPC every frame.
Diagnose by layer
- Perception: verify sensor origin, range/FOV, layer/trigger filters, occluders and whether information was sensed or shared.
- Memory: check timestamp/expiry, stale targets, pooled actor identity and whether last-known positions are updated without perception.
- Decisions: inspect guards, normalized utility values, ties, invalid candidates, priority and fallback. Look for oscillation and unreachable exit conditions.
- Execution: check cancellation, action completion, reservations, cooldown/reset semantics and competing movement writers.
- Navigation: inspect baked surfaces, agent type, destination projection, pending/partial/invalid paths, link traversal and retry rate.
- Runtime budget: profile representative crowds and separate sensing, decisions, pathfinding, animation and rendering. Compare fixed scenarios before/after and inspect worst-frame spikes as well as averages.
Verify the correction
Add focused behavior checks when the environment permits: lost target, unreachable destination, interruption, death/pooling, zero valid choices and repeated transitions. Control randomness and clock inputs for reproduction without claiming the whole Unity simulation is deterministic.
Tune one behavior parameter against an explicit player outcome at a time. Preserve reaction limits, readable attack signals and difficulty rules rather than masking bugs with omniscience or inflated stats. Report what changed, why the trace supports it, what ran and what needs playtesting or target hardware.
References: project-version Unity Profiler, installed AI Navigation/Behavior documentation and the game's own acceptance scenarios. Do not start remote inference, paid training or broad architecture replacement as a debugging shortcut.
Included files 1
SKILL.md