1---2name: game-ai-behaviour-and-navigation3description: Use when designing, implementing, profiling, or reviewing non-player-agent behaviour, navigation, perception, decision systems, crowds, reservations, behaviour trees, state trees, utility logic, encounter AI, or AI validation in a game; load an engine skill for concrete APIs.4---56# Game AI Behaviour and Navigation78Build deterministic, debuggable and budgeted runtime agents whose decisions, movement, perception and interaction remain legible under worst-case gameplay conditions.910## Prerequisites1112Load `world-class-engineering`, `gameplay-systems-engineering`, `level-world-and-content-production`, the selected engine skill, performance/testing skills, and the game's accessibility, difficulty and narrative contracts.1314<!-- dual-compat-start -->15## Use When1617- Defining agent goals, states, decisions, behaviour trees/state machines/utility systems, blackboards, perception, navigation, avoidance, crowds or Smart-Object-style reservations.18- Debugging stuck, oscillating, unfair, expensive, nondeterministic or unreadable NPC behaviour.19- Specifying AI architecture, data contracts, budgets, telemetry, authoring tools and validation scenarios.2021## Do Not Use When2223- The task is generative AI, model training or an online LLM feature.24- The task is animation rigging; use `blender-game-asset-production` and animation systems.25- The requested API is engine-specific but engine/version is unknown; freeze a versioned spike first.2627## Required Inputs2829| Input | Required | Missing-input response |30|---|---:|---|31| Agent fantasy, capabilities, fairness/readability rules and difficulty envelope | yes | Stop architecture and return gameplay decisions required. |32| World topology, traversal types, collision, interactions and animation contract | yes | Limit work to an abstract state model. |33| Pinned engine/version and feature maturity policy | yes for implementation | Mark APIs and performance `not assessed`. |34| Simultaneous-agent envelope, frame/memory/network budgets and target hardware | yes | Block scale claims and crowd architecture. |35| Determinism, save/load, replay, authority and multiplayer constraints | conditional | Flag state ownership and reproduction gaps. |3637## Workflow38391. Define each agent archetype by player-observable goals, verbs, senses, knowledge limits, reaction windows, failure modes and fairness contract.402. Separate sensing, memory/world state, decision, action execution, navigation, animation and feedback. Keep engine controllers/adapters outside reusable domain logic.413. Choose the simplest decision model that explains the behaviour: finite state for bounded modes, behaviour tree for reactive hierarchy, utility for competing scored choices, planner for expensive compositional goals, or hybrid with explicit boundaries.424. Give all shared state typed keys, ownership, defaults, lifetime and update/event policy. Prefer event-driven reevaluation; bound polling rates.435. Specify navigation agents, mesh generation/update, areas/costs/filters, links, path failure, partial paths, moving targets, avoidance, off-mesh traversal and recovery.446. Treat interactable locations as capacity-controlled resources: eligibility, reservation, timeout, cancellation, completion and orphan cleanup are explicit.457. Integrate animation and gameplay with named events and bounded waits. Define root-motion, turning, hit reaction, interruption and fallback contracts.468. Instrument decision transitions, perception changes, path requests/failures, stuck recovery, reservation lifecycle and per-archetype cost without shipping noisy debug output.479. Test single-agent correctness, adversarial geometry, simultaneous worst case, save/load, network authority, difficulty variants and target hardware. Retain seeds, scenario, build and trace.4810. Stop on unbounded search/polling, missing recovery, unstable experimental dependency, unfair information access, unreachable state or budget failure.4911. Load `references/behaviour-telemetry-and-tuning.md` before tuning behaviour. Retain50 the exact build, seed, configuration, scenario, state trace, path failures, and51 guardrail result for every experiment; never promote learned or probabilistic52 behaviour without a deterministic fallback and rollback path.5354## Outputs5556| Artefact | Acceptance condition |57|---|---|58| AI behaviour contract and state/key registry | States, transitions, ownership, defaults and failure recovery are deterministic. |59| Navigation/interaction contract | Agents, costs, links, reservations, invalidation and fallback are explicit. |60| Engine adapter and feature-status decision | Version, plugin/feature maturity, fallback and upgrade evidence are recorded. |61| AI verification and profiling report | Named scenarios prove correctness, legibility and worst-case cost. |6263## Evidence Produced6465| Category | Artifact | Format | Example |66|---|---|---|---|67| Correctness | Transition, perception, path, reservation, save/load and recovery traces. | Trace log with build, seed, scenario and state transitions | `docs/game-ai/navigation-traces.jsonl` |68| Performance | Per-agent and simultaneous worst-case CPU, memory and path-query evidence. | Profiling report with scenario, target hardware and measured costs | `docs/game-ai/navigation-profile.md` |69| UX quality | Reaction, telegraph, knowledge-boundary and difficulty playtests. | Playtest report with fairness/readability observations and findings | `docs/game-ai/fairness-playtests.md` |70| Release evidence | Engine/plugin version, feature status, known failure states and regression suite. | Release record with version identity, limitations and regression results | `docs/game-ai/release-evidence.md` |71<!-- dual-compat-end -->7273## Capability and Degraded Mode7475Changing navigation generation, runtime authority or experimental plugins requires implementation authority and rollback. Without the pinned engine and representative build, provide contracts and test scenarios only; mark API fit, feature stability and performance `not assessed`.7677## Decision Rules7879| Condition | Action |80|---|---|81| Behaviour can be expressed with a small explicit state machine | Do not introduce a planner or deep tree. |82| Agent reads information the player could not reasonably expose | Add a perception/memory path or label the intentional difficulty rule. |83| Decision checks run every frame without need | Convert to events, services at bounded intervals, or scheduled batches. |84| Path or interaction can fail | Specify timeout, retry/backoff, alternate goal and safe idle—not an infinite wait. |85| Engine feature is beta/experimental | Record status in the pinned release, isolate behind an adapter and define fallback. |8687## Quality Standards8889- Name behaviours by intent; keep tasks/actions small, reusable and independently testable.90- Do not mutate decision-node configuration at runtime; keep changing state in typed runtime data.91- AI difficulty changes decision quality, timing, resources or coordination explicitly—not hidden omniscience.92- Measure worst cases with actual agents, geometry, animation and target hardware.93- Record time and memory complexity, update frequency, worst-case path/search cost, and invariants for critical behaviours. Test a bounded degraded path before standardising a Kaizen change.9495## Anti-Patterns9697- Giant behaviour tree as a visual script. Fix: split domain decisions, reusable actions and engine adapters.98- Polling everything every frame. Fix: event-driven updates and budgeted schedules.99- Navigation success treated as guaranteed. Fix: handle invalid targets, partial paths, topology change and stuck recovery.100- Reservation without cancellation. Fix: define ownership, timeout and cleanup on death/unload/disconnect.101- Debugging by animation alone. Fix: capture state, reason, key changes, path status and timestamps.102- Tutorial agent counts treated as product budgets. Fix: measure project worst cases.103104## Read Next105106- The selected Unity/Unreal/Godot skill for concrete implementation.107- `level-world-and-content-production` for nav-ready spaces and encounter topology.108- `game-testing-polish` and performance skills for scenario and target-device evidence.109110## References111112- [AI architecture and runtime contract](references/ai-architecture-and-runtime-contract.md)113- [AI verification matrix](references/ai-verification-matrix.md)114- [Behaviour telemetry and tuning](references/behaviour-telemetry-and-tuning.md)115- [Game-development source register](../../../docs/game-dev-analysis/source-register.md)
peterbamuhigire