unreal-navigation-ai

Unreal 5.8 Navigation and AI

Build and debug Unreal navigation and AI

---
name: unreal-navigation-ai
description: Operational Unreal Engine 5.8 guidance for Recast NavMesh generation and agent settings, static/dynamic/invoker/world-partition navigation, areas, modifiers, links, path following, Behavior Trees and Blackboards, StateTree, AI Perception, EQS, Smart Objects, RVO and Detour Crowd avoidance, multiplayer authority, performance, and AI debugging. Use when designing, implementing, optimizing, testing, or diagnosing Unreal navigation and gameplay AI.
---

# Unreal 5.8 Navigation and AI

Separate path data, movement execution, sensing, decision logic, spatial queries, interaction reservation, and local avoidance. Route only the current subsystem's details into context.

## Select systems before building

- Use **NavMesh** for pathfinding over traversable collision. It does not decide goals or execute animations.
- Use **Behavior Tree + Blackboard** for event-driven, priority-ordered reactive decisions with observable aborts.
- Use **StateTree** for explicit hierarchical modes, transitions, sequences, and shared task data.
- Use a small component/enum/timer for trivial behavior; a graph asset is not mandatory.
- Use **AI Perception** for sensed stimuli and memory. Perception is evidence, not omniscient authoritative truth.
- Use **EQS** to generate, filter, and score environmental candidates. Do not run it continuously for facts a direct query already knows.
- Use **Smart Objects** to find and reserve interaction slots. The interactor executes the behavior and must release the claim.
- Use **RVO** or **Detour Crowd**, exclusively, for local avoidance. They complement pathfinding; they do not replace world paths.

Read [system-selector-architecture.md](references/system-selector-architecture.md) first when choosing between these systems.

## Route by task

| Need | Load |
|---|---|
| Choose systems, ownership, update model | [system-selector-architecture.md](references/system-selector-architecture.md) |
| Build NavMesh and tune agents/tiles/resolution | [navmesh-generation-agents.md](references/navmesh-generation-agents.md) |
| Choose static/dynamic/invoker/World Partition navigation | [dynamic-navigation-world-partition.md](references/dynamic-navigation-world-partition.md) |
| Tune MoveTo, areas, filters, modifiers, links, failure recovery | [movement-paths-links.md](references/movement-paths-links.md) |
| Build Behavior Trees, Blackboards, decorators, services, tasks | [behavior-trees.md](references/behavior-trees.md) |
| Build StateTree states, tasks, data, and transitions | [statetree.md](references/statetree.md) |
| Configure AI Perception and EQS | [perception-eqs.md](references/perception-eqs.md) |
| Build reservable interactions and crowd avoidance | [smart-objects-crowds.md](references/smart-objects-crowds.md) |
| Debug, profile, network, and run test gates | [debugging-performance.md](references/debugging-performance.md) |
| Apply common behavior patterns | [patterns.md](references/patterns.md) |
| Verify claims and maturity | [sources.md](references/sources.md) |

## Execute in this order

1. State agent shapes, locomotion abilities, decision latency, maximum population, world/streaming model, network authority, and target hardware.
2. Establish correct collision and supported-agent settings; build the simplest static NavMesh that proves paths.
3. Choose navigation generation mode from actual world changes. Do not default to fully Dynamic.
4. Prove movement, arrival, path failure, off-mesh traversal, interruption, and recovery before decision graphs.
5. Choose one primary decision architecture and define its data contract.
6. Add Perception as event-fed observations; define forgetting and last-known-state semantics.
7. Add EQS only for candidate selection that needs scoring/filtering.
8. Add Smart Objects and crowd avoidance only after single-agent behavior is reliable.
9. Make authoritative AI decisions on the server in networked games; replicate observable gameplay results.
10. Debug selected agents and profile worst-case populations in a cooked target build.

## Hard rules

- NavMesh green coverage does not prove an agent can move: controller, movement component, supported-agent selection, projection, path following, collision, links, and runtime availability must agree.
- Agent radius, height, slope, and step settings are gameplay contracts. Do not shrink them merely to force paths through invalid geometry.
- Do not make NavMesh fully Dynamic when static data, Dynamic Modifiers Only, streamed chunks, or invokers satisfy the requirement.
- World Partition NavMesh is explicitly **Experimental** in UE 5.8.
- Behavior Tree tasks must finish exactly once and clean up latent work when aborted. Use observer aborts deliberately.
- StateTree Tasks on active states run concurrently; the first completing task can trigger completion. Do not model an intended sequence as parallel tasks.
- Current UE 5.8 EQS documentation still describes the system as experimental. Bound query size/frequency and keep a fallback.
- AI Perception expiration is not the same as forgetting unless the project setting and state logic support it.
- Smart Objects contain opportunity/reservation data, not execution logic. Release claims on success, failure, abort, death, unload, or invalidation.
- RVO and Detour Crowd are independent alternatives and should not both control one agent.
- AI does not need to tick every decision every frame. Prefer events, observed data changes, bounded service intervals, and staggered work.

## Answer contract

Return:

1. **Selected systems and assumptions**.
2. **Authority and data ownership** — server/client, controller/pawn, Blackboard/StateTree/context.
3. **Navigation contract** — agents, generation mode, areas/links, movement and failure behavior.
4. **Exact actions and parameter effects**.
5. **Cancellation, unload, death, and invalidation recovery**.
6. **Performance/scaling consequences**.
7. **Verification** — visible debug evidence and target-build pass criteria.

Do not invent universal NavMesh cell sizes, perception ranges, service intervals, or crowd limits. Derive them from agent geometry, level metrics, reaction design, population, and profiling.

Separate path data, movement execution, sensing, decision logic, spatial queries, interaction reservation, and local avoidance. Route only the current subsystem's details into context.

## Select systems before building

- Use **NavMesh** for pathfinding over traversable collision. It does not decide goals or execute animations.
- Use **Behavior Tree + Blackboard** for event-driven, priority-ordered reactive decisions with observable aborts.
- Use **StateTree** for explicit hierarchical modes, transitions, sequences, and shared task data.
- Use a small component/enum/timer for trivial behavior; a graph asset is not mandatory.
- Use **AI Perception** for sensed stimuli and memory. Perception is evidence, not omniscient authoritative truth.
- Use **EQS** to generate, filter, and score environmental candidates. Do not run it continuously for facts a direct query already knows.
- Use **Smart Objects** to find and reserve interaction slots. The interactor executes the behavior and must release the claim.
- Use **RVO** or **Detour Crowd**, exclusively, for local avoidance. They complement pathfinding; they do not replace world paths.

Read [system-selector-architecture.md](/unreal/unreal-navigation-ai/system-selector-architecture/) first when choosing between these systems.

## Route by task

| Need | Load |
|---|---|
| Choose systems, ownership, update model | [system-selector-architecture.md](/unreal/unreal-navigation-ai/system-selector-architecture/) |
| Build NavMesh and tune agents/tiles/resolution | [navmesh-generation-agents.md](/unreal/unreal-navigation-ai/navmesh-generation-agents/) |
| Choose static/dynamic/invoker/World Partition navigation | [dynamic-navigation-world-partition.md](/unreal/unreal-navigation-ai/dynamic-navigation-world-partition/) |
| Tune MoveTo, areas, filters, modifiers, links, failure recovery | [movement-paths-links.md](/unreal/unreal-navigation-ai/movement-paths-links/) |
| Build Behavior Trees, Blackboards, decorators, services, tasks | [behavior-trees.md](/unreal/unreal-navigation-ai/behavior-trees/) |
| Build StateTree states, tasks, data, and transitions | [statetree.md](/unreal/unreal-navigation-ai/statetree/) |
| Configure AI Perception and EQS | [perception-eqs.md](/unreal/unreal-navigation-ai/perception-eqs/) |
| Build reservable interactions and crowd avoidance | [smart-objects-crowds.md](/unreal/unreal-navigation-ai/smart-objects-crowds/) |
| Debug, profile, network, and run test gates | [debugging-performance.md](/unreal/unreal-navigation-ai/debugging-performance/) |
| Apply common behavior patterns | [patterns.md](/unreal/unreal-navigation-ai/patterns/) |
| Verify claims and maturity | [sources.md](/unreal/unreal-navigation-ai/sources/) |

## Execute in this order

1. State agent shapes, locomotion abilities, decision latency, maximum population, world/streaming model, network authority, and target hardware.
2. Establish correct collision and supported-agent settings; build the simplest static NavMesh that proves paths.
3. Choose navigation generation mode from actual world changes. Do not default to fully Dynamic.
4. Prove movement, arrival, path failure, off-mesh traversal, interruption, and recovery before decision graphs.
5. Choose one primary decision architecture and define its data contract.
6. Add Perception as event-fed observations; define forgetting and last-known-state semantics.
7. Add EQS only for candidate selection that needs scoring/filtering.
8. Add Smart Objects and crowd avoidance only after single-agent behavior is reliable.
9. Make authoritative AI decisions on the server in networked games; replicate observable gameplay results.
10. Debug selected agents and profile worst-case populations in a cooked target build.

## Hard rules

- NavMesh green coverage does not prove an agent can move: controller, movement component, supported-agent selection, projection, path following, collision, links, and runtime availability must agree.
- Agent radius, height, slope, and step settings are gameplay contracts. Do not shrink them merely to force paths through invalid geometry.
- Do not make NavMesh fully Dynamic when static data, Dynamic Modifiers Only, streamed chunks, or invokers satisfy the requirement.
- World Partition NavMesh is explicitly **Experimental** in UE 5.8.
- Behavior Tree tasks must finish exactly once and clean up latent work when aborted. Use observer aborts deliberately.
- StateTree Tasks on active states run concurrently; the first completing task can trigger completion. Do not model an intended sequence as parallel tasks.
- Current UE 5.8 EQS documentation still describes the system as experimental. Bound query size/frequency and keep a fallback.
- AI Perception expiration is not the same as forgetting unless the project setting and state logic support it.
- Smart Objects contain opportunity/reservation data, not execution logic. Release claims on success, failure, abort, death, unload, or invalidation.
- RVO and Detour Crowd are independent alternatives and should not both control one agent.
- AI does not need to tick every decision every frame. Prefer events, observed data changes, bounded service intervals, and staggered work.

## Answer contract

Return:

1. **Selected systems and assumptions**.
2. **Authority and data ownership** — server/client, controller/pawn, Blackboard/StateTree/context.
3. **Navigation contract** — agents, generation mode, areas/links, movement and failure behavior.
4. **Exact actions and parameter effects**.
5. **Cancellation, unload, death, and invalidation recovery**.
6. **Performance/scaling consequences**.
7. **Verification** — visible debug evidence and target-build pass criteria.

Do not invent universal NavMesh cell sizes, perception ranges, service intervals, or crowd limits. Derive them from agent geometry, level metrics, reaction design, population, and profiling.

unreal 5.8 navigation and ai operational unreal engine 5.8 guidance for recast navmesh generation and agent settings, static/dynamic/invoker/world-partition navigation, areas, modifiers, links, path following, behavior trees and blackboards, statetree, ai perception, eqs, smart objects, rvo and detour crowd avoidance, multiplayer authority, performance, and ai debugging. use when designing, implementing, optimizing, testing, or diagnosing unreal navigation and gameplay ai. behavior trees and blackboards behavior trees and blackboards execution model ue behavior trees are event-driven. search/execution proceeds left-to-right and top-down; left branches represent higher priority. blackboard observers and decorators can trigger reevaluation and abort running work. asset/data contract - blackboard keys are typed working memory: target actor, last-known location, state flags, timestamps, current smart object handle wrapper, or requested action. - use a blackboard parent only for genuinely shared keys. - keep durable/shared game truth in the owning gameplay system, not only in a blackboard. - name keys semantically and distinguish observation (seenactor) from conclusion (combattarget). node responsibilities - composite: controls branch traversal. - decorator: gates execution and optionally observes changes/aborts branches. - task: performs one bounded action and reports success/failure/in-progress. - service: periodically updates data while its branch is active. observer aborts - self: abort the decorated running branch when its condition fails. - lower priority: abort branches to the right when this higher-priority condition becomes valid. - both: applies both behaviors. use the smallest abort scope that expresses intent. broad aborts create churn and can repeatedly cancel expensive actions. task contract 1. validate controller, pawn, keys, and required subsystem. 2. start the bounded action. 3. if latent, retain only the handles/state required for completion and return in progress. 4. complete exactly once with success or failure. 5. on abort, cancel delegates/timers/moves/abilities/claims and release resources. 6. prevent stale callbacks from finishing a newer task instance. prefer native tasks/services in measured hot paths; epic notes blueprint versions are less performant. services set an interval and random deviation from reaction needs and population budget. do not use a service as disguised per-frame tick. prefer perception/blackboard events for facts that already publish changes. common architecture text selector combat (target valid) [abort lower priority] sequence: choose position -> move -> execute action investigate (lastknownlocation set) sequence: move -> search -> clear patrol sequence: choose point -> move -> wait keep sensing outside the tree where possible; the tree reacts to well-defined working memory. debug acceptance - live behavior tree shows the expected active branch; - blackboard values change at the responsible event; - aborts cancel latent work and release claims; - every task result is handled; - no high-priority condition causes search/restart oscillation; - worst-case agent count stays inside the ai frame budget. debugging, performance, networking, and testing debugging, performance, networking, and testing diagnose in order 1. authority/lifetime — correct server/controller/pawn, possessed and initialized. 2. nav data — bounds, collision, agent/navdata selection, generation mode, loaded tile. 3. path request — valid projected start/goal, filter, partial-path policy, result. 4. path following/movement — movement mode, speed, collision, root motion, avoidance, link. 5. observation/data — perception stimulus, blackboard/statetree values and age. 6. decision — active bt branch/statetree path and transition/abort cause. 7. action cleanup — move, task, ability, montage, timer, delegate, claim. 8. budget — number/frequency/cost of agents, queries, traces, rebuilds, and replication. gameplay debugger during play, press apostrophe (') while looking at an ai to select/debug it. - numpad 0: navmesh. - numpad 1: general ai/controller/path following. - numpad 2: behavior tree and blackboard. - numpad 3: eqs when available in the current configuration. - numpad 4: perception. use show navigation true/false for runtime navmesh visualization. statetree uses its asset debugger and trace-backed instance timeline. performance capture record: - active/sleeping ai count and distance bands; - game-thread time by controller, bt/statetree task/service/evaluator; - path requests and path time percentile; - dynamic tile rebuild count/time and dirty causes; - perception listeners/sources/stimuli and sight trace load; - eqs queries, candidates/tests, duration, and failures; - smart object searches/claims/contention; - crowd neighbor/sample cost; - replication bandwidth and character movement corrections. use unreal insights and before/after captures on target hardware. stagger periodic work and apply significance/distance-based update policies only when behavior quality remains acceptable. network rules - server owns ai decisions, authoritative navigation, smart object reservation, and gameplay effects. - clients receive replicated pawns/state and render presentation. - test dedicated server, late join, relevancy loss/regain, dormancy, possession, server travel, and packet impairment. - a client debug overlay may not contain server-only internal data unless the gameplay debugger category replicates it. required failure tests - unreachable/invalid destination and partial path; - runtime obstacle and navmesh rebuild latency; - agent knocked off mesh or movement mode changes; - target dies/unloads/becomes irrelevant; - task/state abort during moveto, montage, ability, or smart object use; - claim contention and invalidation; - perception gain/loss/expiration and late stimulus; - eqs returns none or result becomes invalid; - streamed cell/navdata unload; - crowd congestion above configured maximum. acceptance requires bounded recovery—no per-frame retry loops, leaked claims/delegates, zombie moves, or silent permanent stalls. dynamic navigation, invokers, and world partition dynamic navigation, invokers, and world partition generation mode selector | mode | use when | constraint | |---|---|---| | static | navigable collision does not change at runtime | build/cook data; cheapest runtime | | dynamic modifiers only | base surface is static; runtime obstacles/areas modify it | cannot create arbitrary new navigable surface absent from base data | | dynamic | runtime geometry changes require tile regeneration | highest runtime generation cost | | dynamic + navigation invokers | very large/procedural world needs local generation around seeds | readiness radius, generation latency, and removal policy become gameplay constraints | prefer the least dynamic mode that represents real changes. runtime modifier pattern - use navmodifiervolume or navmodifiercomponent with an area class to change cost or mark navareanull. - for moving obstacles that should block rather than become walking surface, mark them as dynamic obstacles/appropriate modifiers so only affected data is dirtied. - batch or debounce frequent changes; continuous transform noise can cause rebuild thrash. navigation invokers 1. enable generate navigation only around navigation invokers in navigation system settings. 2. use dynamic runtime generation. 3. keep a navmeshboundsvolume covering the possible generation domain. 4. add navigationinvokercomponent or register an invoker. 5. set generation radius from movement speed × worst tile-ready latency + path/look-ahead margin. 6. set removal radius larger than generation radius to prevent boundary churn. 7. test fast motion, teleport, multiple invokers, invokers far from seeds, and no-invoker cleanup. do not allow an agent to request a route beyond generated navigation without a waiting, partial-route, or fallback policy. world partition navmesh world partitioned navigation mesh is experimental in ue 5.8. it splits navmesh into chunk actors that stream with world partition and supports static, dynamic modifiers only, and dynamic modes. key rules: - enable is world partitioned navmesh on the recastnavmesh; - enable fixed tile pool size for streaming and size the pool for the maximum loaded navigation bubble plus editor visualization needs; - disable automatic editor navigation updates for very large maps and require a deliberate final build; - understand base navmesh data layers: base navigation includes navigation-relevant objects outside data layers, editor data layers, and configured base navmesh data layers; - dynamic tile generation is limited to loaded space; - build static wp navigation with worldpartitionnavigationdatabuilder through the world partition builder commandlet. acceptance - clean commandlet build from source control; - correct chunks load/unload with cells; - no route crosses unloaded/missing collision; - pool exhaustion and rapid traversal have explicit behavior; - runtime data layer state produces expected base/dynamic navigation; - server paths and replicated movement remain correct; - experimental dependency and fallback are recorded for shipping review. movement, paths, areas, filters, and links movement, paths, areas, filters, and links move request contract define for every move: - actor target versus location target; - pathfinding required and partial paths allowed/forbidden; - destination projection policy and failure if projection fails; - acceptance radius and whether agent/goal radii contribute; - strafing/focus/rotation ownership; - timeout or stuck policy; - response to target movement, new priority, damage, death, unload, or possession change; - completion result handling: success, blocked, off-path, invalid, aborted. an acceptance radius is design tolerance, not a patch for bad reachability. verify actual interaction range and animation alignment. areas and filters nav areas assign traversal cost or exclusion to polygons. - high cost means “avoid if a cheaper path exists,” not “forbidden.” - use navareanull for impassable space. - use query filters to vary cost/permissions by agent or decision without rebuilding world geometry. - keep area costs positive, bounded, named semantically, and tested against path length tradeoffs. use modifiers for mud, danger, crouch zones, doors, temporary hazards, or preferred lanes only when the cost model represents gameplay intent. nav links use navlinkproxy to connect disconnected navmesh regions such as drops, jumps, ladders, doors, lifts, or teleport transitions. - simple links express a connection and direction. - smart links allow runtime/custom traversal handling. - link endpoints must touch/project to compatible navigation. - direction, agent support, area/cost, enable state, capacity, and traversal behavior must agree. for custom traversal: 1. pause/hand off normal path following at the smart link. 2. execute the movement/animation/gameplay action with authority and cancellation. 3. validate landing/exit position and collision. 4. resume/finish path following exactly once. 5. recover on interruption, link disable, moving endpoint, or streamed destination loss. stuck recovery ladder 1. confirm a valid path and correct navdata/agent. 2. confirm movement mode, collision, root motion, speed/acceleration, and controller ownership. 3. repath when the target or relevant navigation changed. 4. use a bounded retry with backoff or alternate candidate. 5. abort to a higher-level decision; do not loop moveto every frame. 6. teleport only when the design explicitly permits it and destination collision/navigation is ready. verification draw the path, areas, links, and agent corridor; log request/result identifiers and timing. test successful, unreachable, partial, invalid, aborted, moving-target, link, and streamed-boundary cases. navmesh generation and agents navmesh generation and agents basic setup 1. place a navmeshboundsvolume over intended traversable space. 2. press p to visualize generated navigation. 3. configure supported agents from real capsule/body dimensions and traversal abilities. 4. confirm the pawn uses an aicontroller and a movement/path-following-compatible movement component. 5. project representative starts/goals and run actual path/movement tests. navmesh is generated from collision, not visible triangles alone. inspect collision channels, can ever affect navigation, mobility, modifier components/volumes, and runtime generation. agent settings - agent radius: clearance from obstacles; too small permits paths the body cannot traverse. - agent height: vertical clearance requirement. - agent max slope: steepest navigable surface. - agent max step height: largest vertical step represented as traversable. keep character movement step/slope/capsule constraints compatible. multiple materially different agent shapes may require separate supported-agent/navdata configurations; validate which navdata each controller selects. tile and voxel settings - smaller cell size/cell height: more accurate geometry, slower generation, higher data cost. - larger cells: faster/smaller, but narrow paths and steps can disappear. - larger tile size uu: fewer heavier rebuild units. - smaller tiles: more localized rebuilds but more border/management overhead. - min region area: discards small isolated regions. - max simplification error: trades polygon fidelity for simpler data. epic recommends making cells as large as possible while preserving required paths and using roughly 32–128 cells per tile side for dynamic rebuild performance. treat this as a measured range, not a copied value. multiple resolutions ue 5.8 supports low/default/high tile resolutions in one navmesh through nav modifier components/areas. - use low resolution in open areas for faster generation/lower memory. - use default/high resolution only where narrow geometry needs it. - make resolution cell sizes multiples and keep tile size uu divisible by each cell size. - visualize tile resolutions and build-time heat maps on the recastnavmesh actor. validation grid test every agent at: - narrowest intended doorway/corridor; - lowest overhead clearance; - steepest intended slope and largest intended step; - moving platform/link endpoints; - material/collision transitions and landscape edits; - navmesh bounds edge and streamed-cell boundary; - exact and slightly invalid start/goal positions. never approve settings only because the green overlay exists. record successful path query, movement completion, arrival distance, and body collision. common navigation and ai patterns common navigation and ai patterns patrol -> investigate -> combat - perception event stores current stimulus and last-known location/time. - behavior tree priorities or statetree transitions own mode selection. - patrol follows authored points/spline goals through navmesh, not direct spline locomotion through obstacles. - investigate moves to last-known location, performs a bounded search, then clears/ages state. - combat chooses an action/position; interruption aborts lower-priority movement cleanly. ranged cover selection 1. generate a bounded candidate set around the querier/target. 2. filter unreachable, exposed, occupied, too-close/far, or invalid-team candidates. 3. score path cost, line of sight, distance band, spacing, and tactical direction. 4. choose best or controlled random top percentile. 5. reserve the position if multiple agents compete. 6. revalidate on arrival and use a cooldown before re-querying. eqs finds a candidate; it does not own the combat state, path lifecycle, or reservation by itself. door/ladder/jump - nav link expresses connectivity and direction. - link traversal task owns door claim/open, alignment, animation/root motion, collision changes, and resume. - abort closes/releases/restores state safely. - the destination cell and landing navigation must be loaded before traversal. smart object activity - query a bounded set at a modest interval/event. - claim before committing movement. - move to the slot transform with appropriate filter. - use returned behavior definition to execute the interactor-owned behavior. - release in one cleanup path shared by success/failure/abort/death. large-world agents - server keeps only design-required agents fully simulated. - streaming and ai significance/lifetime policies agree. - static/streamed navmesh is preferred; use dynamic/invoker generation only where world changes require it. - world partition navmesh remains experimental and needs a fallback/shipping review. - durable world state survives actor unload; controllers/tasks/claims do not assume cells remain loaded. crowd through a choke point - use one avoidance system. - spread destinations and approach slots. - keep agent radius/corridor valid; do not shrink navmesh agent settings below bodies. - add lanes, queue smart objects, token/capacity control, or encounter scheduling when geometry cannot support simultaneous flow. - stress above expected population and record deadlocks, arrival time, and cpu. acceptance for any behavior - correct under success, failure, abort, unload, and death; - explainable in debugger from observation through action; - no authoritative client-only decisions; - deterministic where design requires it and varied where repetition should be hidden; - meets reaction-quality and frame budgets at worst population on target hardware. ai perception and eqs ai perception and eqs ai perception setup place aiperceptioncomponent on the authoritative ai owner, commonly the aicontroller. add only required sense configs and select a dominant sense when location resolution needs it. sight - sight radius: range at which an unseen target can begin perception. - lose sight radius: hysteresis range for losing an already seen target; keep it at least as large as sight radius. - peripheral vision half angle degrees: angle from the forward vector, not total cone width. - auto success range from last seen location: retains sight within a local region; use only if it matches the fiction. - affiliation is fully defined through team interfaces/c++; blueprint-only projects commonly detect neutrals and filter through tags/team logic. hearing configure range/affiliation and emit explicit report noise event data with location, loudness, instigator, and tag as required. audio playback alone is not automatically a gameplay hearing stimulus. memory max age controls stimulus aging; 0 means it never expires. to actually forget stale actors through the perception system, enable project settings > engine > ai system > forget stale actors. keep last-known position/time and “currently sensed” as distinct state. use aiperceptionstimulisourcecomponent or registration apis for designated sources. unregister runtime sources when their lifetime ends. perception event pattern 1. receive ontargetperceptionupdated/appropriate batched event. 2. validate actor and stimulus sense/success. 3. update observation data and timestamp. 4. let decision logic choose whether the actor becomes a threat/target. 5. on loss/expiration, preserve or clear last-known state according to design. 6. rate-limit expensive follow-up queries across populations. eqs boundary eqs generates candidate actors/locations, then tests filter and score them relative to contexts. use it for “best valid option,” not for direct known facts. workflow: 1. define the smallest candidate generator/domain. 2. supply explicit contexts: querier, target, squad, objective, custom location. 3. apply hard invalidity as filters. 4. score surviving candidates with named, normalized design criteria. 5. select a deliberate run mode: best, random from top 5%, random from top 25%, or all matching. 6. handle no-result and stale-result cases. 7. cache/reuse only while inputs remain valid. current ue 5.8 documentation still calls eqs experimental. bound candidate count, trace/path tests, query frequency, and simultaneous agents. use an eqstestingpawn for editor visualization, but clear its query template while editing expensive queries to avoid continuous heavy updates. debugging - gameplay debugger: apostrophe, perception on numpad 4; eqs category when executing. - eqs testing pawn: blue failed/filtered candidates; green-to-red scored desirability. - record query template, owner, contexts, named parameters, run mode, candidate counts, duration, result, and failure reason. perception/eqs do not replicate internal truth automatically. run authoritative decisions on the server and replicate resulting gameplay state. smart objects and crowd avoidance smart objects and crowd avoidance smart object boundary smart objects describe spatial interaction opportunities and reserve slots. they do not contain the execution logic; each interactor implements the returned behavior definition. core pieces: - smartobject subsystem and spatial database; - smartobject component on the world actor; - smart object definition asset shared across instances; - slots with transforms, filters/tags, and behavior definitions; - optional persistent collection influencing runtime-instance lifetime. claim lifecycle text find matching objects -> choose result -> claim slot -> validate handle -> navigate to slot -> use/occupy -> execute behavior -> release rules: - search with bounded area, activity tags, user tags, behavior class, and other filters. - a search result is not a reservation; always validate the returned claim handle. - revalidate slot/location and object state before/after approach. - release on success, failure, abort, death, possession change, timeout, and task/state exit. - handle onslotinvalidateddelegate; the object may disable/unload/destroy while claimed or occupied. - keep durable gameplay outcome outside the transient claim. a persistent collection keeps included smart object runtime instances in the simulation even if source actors stream out. that is a lifetime decision, not permission to execute interaction against unloaded visuals/collision. rvo versus detour crowd | system | use | constraint | |---|---|---| | rvo | charactermovement-local velocity avoidance, including without navmesh | character only, less configurable, can push agents outside navmesh | | detour crowd | path-corridor-aware crowd avoidance for pawns | fixed max agents/max agent radius and crowd manager tuning | epic states the two systems work independently and should be used exclusively. do not enable both for one agent. crowd tuning start without avoidance and prove paths. then add one system and test: - maximum simultaneous agents and radius support; - consideration radius/neighbors and wall samples; - corridor width, opposing flows, doors, corners, merges, and destinations; - separation/collision resolution and movement-component interaction; - agents leaving navmesh, deadlocks, oscillation, and arrival congestion; - cpu cost at worst population. crowd avoidance cannot solve a level whose doorway is narrower than the throughput the encounter requires. fix geometry, lane design, destination distribution, or scheduling when appropriate. smart object + crowd pattern reserve before entering a congested approach, expose one slot per true simultaneous user, move to a reachable slot transform, queue outside the interaction corridor, and release immediately on cancellation. do not let every waiting agent continuously re-query every object. ue 5.8 primary sources ue 5.8 primary sources checked against epic's unreal engine 5.8 documentation on 2026-07-19. navigation - navigation system - basic navigation - navigation mesh settings - navigation mesh resolutions - modifying the navigation mesh - optimizing navmesh generation - navigation invokers - world partitioned navigation mesh decisions and queries - behavior tree overview - behavior tree user guide - behavior tree decorators - behavior tree services - statetree overview - statetree debugger - ai perception - environment query system - eqs testing pawn interaction, crowds, and diagnosis - smart objects overview - avoidance with the navigation system - crowd manager settings - ai debugging - gameplay debugger maturity notes - core recast navmesh, behavior trees, statetree, ai perception, smart objects, and avoidance workflows have current 5.8 documentation. - world partitioned navigation mesh is explicitly experimental. - the current eqs testing pawn guide still refers to the experimental nature of eqs; keep eqs bounded and validated. - do not infer that all ai systems replicate or run on clients. authoritative gameplay ai remains a project/network architecture decision. prefer the 5.8 page, installed engine source, console help, and working sample behavior over remembered earlier-version defaults. statetree statetree execution model statetree combines hierarchical state-machine transitions with tree-based state selection. - selection evaluates enter conditions from the target/root path toward a selectable leaf. - the selected leaf and all parent states on its active path become active. - tasks on all active states start and run concurrently. - the first completing task can trigger completion-based transition evaluation. - transitions are the only way to change the selected state. do not place sequential actions as sibling tasks in one state. use child states and next transitions for ordered steps. data roles - parameters: configured per asset/instance inputs. - context/external data: required owner, actor, subsystem, or component data supplied by the schema/runtime. - evaluators: expose/update data used by states, tasks, conditions, and transitions. - tasks: perform bounded work while their state is active. - conditions: gate state entry or transitions. choose the correct schema for the owner, such as an actor/component-oriented schema. fail early when required external data is absent. authoring workflow 1. define top-level modes with mutually understandable ownership: idle, patrol, alert, combat, disabled. 2. put shared always-active responsibilities on parent states only when concurrency is intended. 3. decompose ordered behavior into child states and success/failure/next transitions. 4. make transition priority and destination explicit. 5. expose typed data once and bind deliberately; avoid long invisible binding chains. 6. define enter/exit/cancel cleanup for moves, delegates, abilities, animation, and smart object claims. 7. use linked/subtrees only when their interface is stable and reuse is real. common failure patterns - sequence completes instantly/wrong action wins: sibling tasks ran concurrently and one finished first. - no state selected: enter conditions reject every path or required context is missing. - transition loop: a condition remains true on entry and immediately selects again. - stale data: evaluator/binding lifetime differs from the assumed update moment. - action survives state exit: task failed to cancel latent work or release resources. debugging use the statetree debugger (window > debugger in the asset editor), instance selection, traces, state/task breakpoints, and recorded transitions. the debugger can consume trace analyzer data from editor, client, and dedicated server processes. acceptance requires the active state path, task lifetimes, data values, transition cause, and cleanup to match the authored contract under interruption and failure. system selector and architecture system selector and architecture layer the problem text world collision -> navmesh/path graph -> path following/movement stimuli/events -> perception/memory -> decision architecture world candidates -> eqs/direct query -> chosen goal interaction opportunities -> smart object claim -> interactor behavior nearby moving agents -> rvo or detour crowd -> local velocity adjustment a bug belongs to one layer until evidence shows otherwise. do not “fix ai” by changing several layers together. decision selector | need | default | |---|---| | one or two simple modes | component/enum/timers/events | | reactive priorities, conditions, abort-to-higher-priority behavior | behavior tree + blackboard | | explicit hierarchical state, transitions, sequences, shared task data | statetree | | large data-oriented crowds | evaluate mass/statetree architecture separately; ordinary actor ai may not scale | behavior tree and statetree can coexist at a system boundary, but do not duplicate the same state machine in both. assign one owner and exchange compact state/events. query selector - direct known actor/location: use the known reference or subsystem lookup. - reachable random point: navigation query. - “best cover/attack/resource point” from multiple constraints: eqs. - reusable reservable activity: smart object query/claim. - long-range route: navmesh pathfinding. - short-range agent avoidance: rvo or detour crowd. authority model in networked games: - run authoritative ai controller, decisions, path requests, smart object claims, damage, and gameplay state on the server; - replicate the pawn and observable gameplay state/animation inputs as designed; - keep client-only cosmetic prediction/presentation non-authoritative; - do not replicate entire blackboards or internal decision graphs by default. route replication details to $unreal-replication. data ownership - controller owns decision/path-following concerns tied to possession. - pawn/character owns body, movement component, collision, animation-facing state. - blackboard holds behavior tree working memory, not universal game truth. - statetree context/external data supplies required owner/world data; parameters configure instances. - subsystems/game state own durable shared facts. - perception stores observations; gameplay systems decide what those observations mean. update policy prefer event-driven updates for target acquired/lost, damage, state changes, path completion, smart object invalidation, and blackboard changes. use bounded timers/services for genuinely periodic sensing or scoring. stagger expensive work across agents and treat reaction delay as a design variable, not merely a performance defect.

Behavior Trees and Blackboards

# Behavior Trees and Blackboards

## Execution model

UE Behavior Trees are event-driven. Search/execution proceeds left-to-right and top-down; left branches represent higher priority. Blackboard observers and decorators can trigger reevaluation and abort running work.

## Asset/data contract

- Blackboard keys are typed working memory: target actor, last-known location, state flags, timestamps, current Smart Object handle wrapper, or requested action.
- Use a Blackboard parent only for genuinely shared keys.
- Keep durable/shared game truth in the owning gameplay system, not only in a Blackboard.
- Name keys semantically and distinguish observation (`SeenActor`) from conclusion (`CombatTarget`).

## Node responsibilities

- **Composite**: controls branch traversal.
- **Decorator**: gates execution and optionally observes changes/aborts branches.
- **Task**: performs one bounded action and reports success/failure/in-progress.
- **Service**: periodically updates data while its branch is active.

## Observer aborts

- `Self`: abort the decorated running branch when its condition fails.
- `Lower Priority`: abort branches to the right when this higher-priority condition becomes valid.
- `Both`: applies both behaviors.

Use the smallest abort scope that expresses intent. Broad aborts create churn and can repeatedly cancel expensive actions.

## Task contract

1. Validate controller, pawn, keys, and required subsystem.
2. Start the bounded action.
3. If latent, retain only the handles/state required for completion and return In Progress.
4. Complete exactly once with success or failure.
5. On abort, cancel delegates/timers/moves/abilities/claims and release resources.
6. Prevent stale callbacks from finishing a newer task instance.

Prefer native Tasks/Services in measured hot paths; Epic notes Blueprint versions are less performant.

## Services

Set an interval and random deviation from reaction needs and population budget. Do not use a service as disguised per-frame Tick. Prefer Perception/Blackboard events for facts that already publish changes.

## Common architecture

```text
Selector
  Combat (Target valid) [abort lower priority]
    Sequence: choose position -> move -> execute action
  Investigate (LastKnownLocation set)
    Sequence: move -> search -> clear
  Patrol
    Sequence: choose point -> move -> wait
```

Keep sensing outside the tree where possible; the tree reacts to well-defined working memory.

## Debug acceptance

- live Behavior Tree shows the expected active branch;
- Blackboard values change at the responsible event;
- aborts cancel latent work and release claims;
- every task result is handled;
- no high-priority condition causes search/restart oscillation;
- worst-case agent count stays inside the AI frame budget.

# Debugging, performance, networking, and testing

## Diagnose in order

1. **Authority/lifetime** — correct server/controller/pawn, possessed and initialized.
2. **Nav data** — bounds, collision, agent/NavData selection, generation mode, loaded tile.
3. **Path request** — valid projected start/goal, filter, partial-path policy, result.
4. **Path following/movement** — movement mode, speed, collision, root motion, avoidance, link.
5. **Observation/data** — Perception stimulus, Blackboard/StateTree values and age.
6. **Decision** — active BT branch/StateTree path and transition/abort cause.
7. **Action cleanup** — move, task, ability, montage, timer, delegate, claim.
8. **Budget** — number/frequency/cost of agents, queries, traces, rebuilds, and replication.

## Gameplay Debugger

During play, press apostrophe (`'`) while looking at an AI to select/debug it.

- Numpad `0`: NavMesh.
- Numpad `1`: general AI/controller/path following.
- Numpad `2`: Behavior Tree and Blackboard.
- Numpad `3`: EQS when available in the current configuration.
- Numpad `4`: Perception.

Use `show Navigation true/false` for runtime NavMesh visualization. StateTree uses its asset Debugger and trace-backed instance timeline.

## Performance capture

Record:

- active/sleeping AI count and distance bands;
- game-thread time by controller, BT/StateTree task/service/evaluator;
- path requests and path time percentile;
- dynamic tile rebuild count/time and dirty causes;
- Perception listeners/sources/stimuli and sight trace load;
- EQS queries, candidates/tests, duration, and failures;
- Smart Object searches/claims/contention;
- crowd neighbor/sample cost;
- replication bandwidth and Character Movement corrections.

Use Unreal Insights and before/after captures on target hardware. Stagger periodic work and apply significance/distance-based update policies only when behavior quality remains acceptable.

## Network rules

- Server owns AI decisions, authoritative navigation, Smart Object reservation, and gameplay effects.
- Clients receive replicated Pawns/state and render presentation.
- Test dedicated server, late join, relevancy loss/regain, dormancy, possession, server travel, and packet impairment.
- A client debug overlay may not contain server-only internal data unless the Gameplay Debugger category replicates it.

## Required failure tests

- unreachable/invalid destination and partial path;
- runtime obstacle and NavMesh rebuild latency;
- agent knocked off mesh or movement mode changes;
- target dies/unloads/becomes irrelevant;
- task/state abort during MoveTo, montage, ability, or Smart Object use;
- claim contention and invalidation;
- Perception gain/loss/expiration and late stimulus;
- EQS returns none or result becomes invalid;
- streamed cell/NavData unload;
- crowd congestion above configured maximum.

Acceptance requires bounded recovery—no per-frame retry loops, leaked claims/delegates, zombie moves, or silent permanent stalls.

# Dynamic navigation, invokers, and World Partition

## Generation mode selector

| Mode | Use when | Constraint |
|---|---|---|
| Static | Navigable collision does not change at runtime | Build/cook data; cheapest runtime |
| Dynamic Modifiers Only | Base surface is static; runtime obstacles/areas modify it | Cannot create arbitrary new navigable surface absent from base data |
| Dynamic | Runtime geometry changes require tile regeneration | Highest runtime generation cost |
| Dynamic + Navigation Invokers | Very large/procedural world needs local generation around seeds | Readiness radius, generation latency, and removal policy become gameplay constraints |

Prefer the least dynamic mode that represents real changes.

## Runtime modifier pattern

- Use `NavModifierVolume` or `NavModifierComponent` with an Area Class to change cost or mark `NavArea_Null`.
- For moving obstacles that should block rather than become walking surface, mark them as Dynamic Obstacles/appropriate modifiers so only affected data is dirtied.
- Batch or debounce frequent changes; continuous transform noise can cause rebuild thrash.

## Navigation Invokers

1. Enable `Generate Navigation Only Around Navigation Invokers` in Navigation System settings.
2. Use Dynamic runtime generation.
3. Keep a NavMeshBoundsVolume covering the possible generation domain.
4. Add `NavigationInvokerComponent` or register an invoker.
5. Set generation radius from movement speed × worst tile-ready latency + path/look-ahead margin.
6. Set removal radius larger than generation radius to prevent boundary churn.
7. Test fast motion, teleport, multiple invokers, invokers far from seeds, and no-invoker cleanup.

Do not allow an agent to request a route beyond generated navigation without a waiting, partial-route, or fallback policy.

## World Partition NavMesh

World Partitioned Navigation Mesh is **Experimental** in UE 5.8. It splits NavMesh into chunk Actors that stream with World Partition and supports Static, Dynamic Modifiers Only, and Dynamic modes.

Key rules:

- enable `Is World Partitioned Navmesh` on the RecastNavMesh;
- enable Fixed Tile Pool Size for streaming and size the pool for the maximum loaded navigation bubble plus editor visualization needs;
- disable automatic editor navigation updates for very large maps and require a deliberate final build;
- understand Base NavMesh Data Layers: base navigation includes navigation-relevant objects outside Data Layers, Editor Data Layers, and configured Base NavMesh Data Layers;
- Dynamic tile generation is limited to loaded space;
- build static WP navigation with `WorldPartitionNavigationDataBuilder` through the World Partition Builder Commandlet.

## Acceptance

- clean commandlet build from source control;
- correct chunks load/unload with cells;
- no route crosses unloaded/missing collision;
- pool exhaustion and rapid traversal have explicit behavior;
- Runtime Data Layer state produces expected base/dynamic navigation;
- server paths and replicated movement remain correct;
- Experimental dependency and fallback are recorded for shipping review.

# Movement, paths, areas, filters, and links

## Move request contract

Define for every move:

- actor target versus location target;
- pathfinding required and partial paths allowed/forbidden;
- destination projection policy and failure if projection fails;
- acceptance radius and whether agent/goal radii contribute;
- strafing/focus/rotation ownership;
- timeout or stuck policy;
- response to target movement, new priority, damage, death, unload, or possession change;
- completion result handling: success, blocked, off-path, invalid, aborted.

An acceptance radius is design tolerance, not a patch for bad reachability. Verify actual interaction range and animation alignment.

## Areas and filters

Nav Areas assign traversal cost or exclusion to polygons.

- High cost means “avoid if a cheaper path exists,” not “forbidden.”
- Use `NavArea_Null` for impassable space.
- Use query filters to vary cost/permissions by agent or decision without rebuilding world geometry.
- Keep area costs positive, bounded, named semantically, and tested against path length tradeoffs.

Use modifiers for mud, danger, crouch zones, doors, temporary hazards, or preferred lanes only when the cost model represents gameplay intent.

## Nav Links

Use `NavLinkProxy` to connect disconnected NavMesh regions such as drops, jumps, ladders, doors, lifts, or teleport transitions.

- Simple links express a connection and direction.
- Smart links allow runtime/custom traversal handling.
- Link endpoints must touch/project to compatible navigation.
- Direction, agent support, area/cost, enable state, capacity, and traversal behavior must agree.

For custom traversal:

1. Pause/hand off normal path following at the smart link.
2. Execute the movement/animation/gameplay action with authority and cancellation.
3. Validate landing/exit position and collision.
4. Resume/finish path following exactly once.
5. Recover on interruption, link disable, moving endpoint, or streamed destination loss.

## Stuck recovery ladder

1. Confirm a valid path and correct NavData/agent.
2. Confirm movement mode, collision, root motion, speed/acceleration, and controller ownership.
3. Repath when the target or relevant navigation changed.
4. Use a bounded retry with backoff or alternate candidate.
5. Abort to a higher-level decision; do not loop MoveTo every frame.
6. Teleport only when the design explicitly permits it and destination collision/navigation is ready.

## Verification

Draw the path, areas, links, and agent corridor; log request/result identifiers and timing. Test successful, unreachable, partial, invalid, aborted, moving-target, link, and streamed-boundary cases.

NavMesh generation and agents

# NavMesh generation and agents

## Basic setup

1. Place a `NavMeshBoundsVolume` over intended traversable space.
2. Press `P` to visualize generated navigation.
3. Configure Supported Agents from real capsule/body dimensions and traversal abilities.
4. Confirm the Pawn uses an AIController and a movement/path-following-compatible movement component.
5. Project representative starts/goals and run actual path/movement tests.

NavMesh is generated from collision, not visible triangles alone. Inspect collision channels, `Can Ever Affect Navigation`, mobility, modifier components/volumes, and runtime generation.

## Agent settings

- `Agent Radius`: clearance from obstacles; too small permits paths the body cannot traverse.
- `Agent Height`: vertical clearance requirement.
- `Agent Max Slope`: steepest navigable surface.
- `Agent Max Step Height`: largest vertical step represented as traversable.

Keep Character Movement step/slope/capsule constraints compatible. Multiple materially different agent shapes may require separate supported-agent/NavData configurations; validate which NavData each controller selects.

## Tile and voxel settings

- Smaller `Cell Size`/`Cell Height`: more accurate geometry, slower generation, higher data cost.
- Larger cells: faster/smaller, but narrow paths and steps can disappear.
- Larger `Tile Size UU`: fewer heavier rebuild units.
- Smaller tiles: more localized rebuilds but more border/management overhead.
- `Min Region Area`: discards small isolated regions.
- `Max Simplification Error`: trades polygon fidelity for simpler data.

Epic recommends making cells as large as possible while preserving required paths and using roughly 32–128 cells per tile side for dynamic rebuild performance. Treat this as a measured range, not a copied value.

## Multiple resolutions

UE 5.8 supports low/default/high tile resolutions in one NavMesh through Nav Modifier components/areas.

- Use low resolution in open areas for faster generation/lower memory.
- Use default/high resolution only where narrow geometry needs it.
- Make resolution Cell Sizes multiples and keep `Tile Size UU` divisible by each Cell Size.
- Visualize tile resolutions and build-time heat maps on the RecastNavMesh actor.

## Validation grid

Test every agent at:

- narrowest intended doorway/corridor;
- lowest overhead clearance;
- steepest intended slope and largest intended step;
- moving platform/link endpoints;
- material/collision transitions and Landscape edits;
- NavMesh bounds edge and streamed-cell boundary;
- exact and slightly invalid start/goal positions.

Never approve settings only because the green overlay exists. Record successful path query, movement completion, arrival distance, and body collision.

Common navigation and AI patterns

# Common navigation and AI patterns

## Patrol -> investigate -> combat

- Perception event stores current stimulus and last-known location/time.
- Behavior Tree priorities or StateTree transitions own mode selection.
- Patrol follows authored points/spline goals through NavMesh, not direct spline locomotion through obstacles.
- Investigate moves to last-known location, performs a bounded search, then clears/ages state.
- Combat chooses an action/position; interruption aborts lower-priority movement cleanly.

## Ranged cover selection

1. Generate a bounded candidate set around the querier/target.
2. Filter unreachable, exposed, occupied, too-close/far, or invalid-team candidates.
3. Score path cost, line of sight, distance band, spacing, and tactical direction.
4. Choose best or controlled random top percentile.
5. Reserve the position if multiple agents compete.
6. Revalidate on arrival and use a cooldown before re-querying.

EQS finds a candidate; it does not own the combat state, path lifecycle, or reservation by itself.

## Door/ladder/jump

- Nav Link expresses connectivity and direction.
- Link traversal task owns door claim/open, alignment, animation/root motion, collision changes, and resume.
- Abort closes/releases/restores state safely.
- The destination cell and landing navigation must be loaded before traversal.

## Smart Object activity

- Query a bounded set at a modest interval/event.
- Claim before committing movement.
- Move to the Slot transform with appropriate filter.
- Use returned Behavior Definition to execute the interactor-owned behavior.
- Release in one cleanup path shared by success/failure/abort/death.

## Large-world agents

- Server keeps only design-required agents fully simulated.
- Streaming and AI significance/lifetime policies agree.
- Static/streamed NavMesh is preferred; use dynamic/invoker generation only where world changes require it.
- World Partition NavMesh remains Experimental and needs a fallback/shipping review.
- Durable world state survives actor unload; controllers/tasks/claims do not assume cells remain loaded.

## Crowd through a choke point

- Use one avoidance system.
- Spread destinations and approach slots.
- Keep agent radius/corridor valid; do not shrink NavMesh agent settings below bodies.
- Add lanes, queue Smart Objects, token/capacity control, or encounter scheduling when geometry cannot support simultaneous flow.
- Stress above expected population and record deadlocks, arrival time, and CPU.

## Acceptance for any behavior

- correct under success, failure, abort, unload, and death;
- explainable in debugger from observation through action;
- no authoritative client-only decisions;
- deterministic where design requires it and varied where repetition should be hidden;
- meets reaction-quality and frame budgets at worst population on target hardware.

AI Perception and EQS

# AI Perception and EQS

## AI Perception setup

Place `AIPerceptionComponent` on the authoritative AI owner, commonly the AIController. Add only required sense configs and select a Dominant Sense when location resolution needs it.

### Sight

- `Sight Radius`: range at which an unseen target can begin perception.
- `Lose Sight Radius`: hysteresis range for losing an already seen target; keep it at least as large as Sight Radius.
- `Peripheral Vision Half Angle Degrees`: angle from the forward vector, not total cone width.
- `Auto Success Range from Last Seen Location`: retains sight within a local region; use only if it matches the fiction.
- Affiliation is fully defined through team interfaces/C++; Blueprint-only projects commonly detect neutrals and filter through tags/team logic.

### Hearing

Configure range/affiliation and emit explicit `Report Noise Event` data with location, loudness, instigator, and tag as required. Audio playback alone is not automatically a gameplay hearing stimulus.

### Memory

`Max Age` controls stimulus aging; `0` means it never expires. To actually forget stale actors through the Perception system, enable `Project Settings > Engine > AI System > Forget Stale Actors`. Keep last-known position/time and “currently sensed” as distinct state.

Use `AIPerceptionStimuliSourceComponent` or registration APIs for designated sources. Unregister runtime sources when their lifetime ends.

## Perception event pattern

1. Receive `OnTargetPerceptionUpdated`/appropriate batched event.
2. Validate actor and stimulus sense/success.
3. Update observation data and timestamp.
4. Let decision logic choose whether the actor becomes a threat/target.
5. On loss/expiration, preserve or clear last-known state according to design.
6. Rate-limit expensive follow-up queries across populations.

## EQS boundary

EQS generates candidate Actors/locations, then Tests filter and score them relative to Contexts. Use it for “best valid option,” not for direct known facts.

Workflow:

1. Define the smallest candidate Generator/domain.
2. Supply explicit Contexts: querier, target, squad, objective, custom location.
3. Apply hard invalidity as filters.
4. Score surviving candidates with named, normalized design criteria.
5. Select a deliberate run mode: best, random from top 5%, random from top 25%, or all matching.
6. Handle no-result and stale-result cases.
7. Cache/reuse only while inputs remain valid.

Current UE 5.8 documentation still calls EQS experimental. Bound candidate count, trace/path tests, query frequency, and simultaneous agents. Use an `EQSTestingPawn` for editor visualization, but clear its Query Template while editing expensive queries to avoid continuous heavy updates.

## Debugging

- Gameplay Debugger: apostrophe, Perception on Numpad `4`; EQS category when executing.
- EQS Testing Pawn: blue failed/filtered candidates; green-to-red scored desirability.
- Record query template, owner, contexts, named parameters, run mode, candidate counts, duration, result, and failure reason.

Perception/EQS do not replicate internal truth automatically. Run authoritative decisions on the server and replicate resulting gameplay state.

Smart Objects and crowd avoidance

# Smart Objects and crowd avoidance

## Smart Object boundary

Smart Objects describe spatial interaction opportunities and reserve Slots. They do **not** contain the execution logic; each interactor implements the returned Behavior Definition.

Core pieces:

- SmartObject subsystem and spatial database;
- SmartObject component on the world actor;
- Smart Object Definition asset shared across instances;
- Slots with transforms, filters/tags, and behavior definitions;
- optional Persistent Collection influencing runtime-instance lifetime.

## Claim lifecycle

```text
Find matching objects -> choose result -> claim slot -> validate handle
-> navigate to slot -> use/occupy -> execute behavior -> release
```

Rules:

- Search with bounded area, activity tags, user tags, behavior class, and other filters.
- A search result is not a reservation; always validate the returned Claim Handle.
- Revalidate slot/location and object state before/after approach.
- Release on success, failure, abort, death, possession change, timeout, and task/state exit.
- Handle `OnSlotInvalidatedDelegate`; the object may disable/unload/destroy while claimed or occupied.
- Keep durable gameplay outcome outside the transient claim.

A Persistent Collection keeps included Smart Object runtime instances in the simulation even if source actors stream out. That is a lifetime decision, not permission to execute interaction against unloaded visuals/collision.

## RVO versus Detour Crowd

| System | Use | Constraint |
|---|---|---|
| RVO | CharacterMovement-local velocity avoidance, including without NavMesh | Character only, less configurable, can push agents outside NavMesh |
| Detour Crowd | path-corridor-aware crowd avoidance for Pawns | fixed Max Agents/Max Agent Radius and Crowd Manager tuning |

Epic states the two systems work independently and should be used exclusively. Do not enable both for one agent.

## Crowd tuning

Start without avoidance and prove paths. Then add one system and test:

- maximum simultaneous agents and radius support;
- consideration radius/neighbors and wall samples;
- corridor width, opposing flows, doors, corners, merges, and destinations;
- separation/collision resolution and movement-component interaction;
- agents leaving NavMesh, deadlocks, oscillation, and arrival congestion;
- CPU cost at worst population.

Crowd avoidance cannot solve a level whose doorway is narrower than the throughput the encounter requires. Fix geometry, lane design, destination distribution, or scheduling when appropriate.

## Smart Object + crowd pattern

Reserve before entering a congested approach, expose one Slot per true simultaneous user, move to a reachable slot transform, queue outside the interaction corridor, and release immediately on cancellation. Do not let every waiting agent continuously re-query every object.

UE 5.8 primary sources

# UE 5.8 primary sources

Checked against Epic's Unreal Engine 5.8 documentation on 2026-07-19.

## Navigation

- [Navigation System](https://dev.epicgames.com/documentation/en-us/unreal-engine/navigation-system-in-unreal-engine)
- [Basic Navigation](https://dev.epicgames.com/documentation/unreal-engine/basic-navigation-in-unreal-engine?lang=en-US)
- [Navigation Mesh Settings](https://dev.epicgames.com/documentation/unreal-engine/navigation-mesh-settings-in-the-unreal-engine-project-settings?lang=en-US)
- [Navigation Mesh Resolutions](https://dev.epicgames.com/documentation/unreal-engine/navigation-mesh-resolutions-user-guide?lang=en-US)
- [Modifying the Navigation Mesh](https://dev.epicgames.com/documentation/unreal-engine/overview-of-how-to-modify-the-navigation-mesh-in-unreal-engine?lang=en-US)
- [Optimizing NavMesh Generation](https://dev.epicgames.com/documentation/unreal-engine/optimizing-navigation-mesh-generation-speed-in-unreal-engine)
- [Navigation Invokers](https://dev.epicgames.com/documentation/unreal-engine/using-navigation-invokers-in-unreal-engine?lang=en-US)
- [World Partitioned Navigation Mesh](https://dev.epicgames.com/documentation/unreal-engine/world-partitioned-navigation-mesh?lang=en-US)

## Decisions and queries

- [Behavior Tree Overview](https://dev.epicgames.com/documentation/unreal-engine/behavior-tree-in-unreal-engine---overview?lang=en-US)
- [Behavior Tree User Guide](https://dev.epicgames.com/documentation/unreal-engine/behavior-tree-in-unreal-engine---user-guide)
- [Behavior Tree Decorators](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-behavior-tree-node-reference-decorators)
- [Behavior Tree Services](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-behavior-tree-node-reference-services)
- [StateTree Overview](https://dev.epicgames.com/documentation/unreal-engine/overview-of-state-tree-in-unreal-engine?lang=en-US)
- [StateTree Debugger](https://dev.epicgames.com/documentation/unreal-engine/statetree-debugger-quick-start-guide)
- [AI Perception](https://dev.epicgames.com/documentation/unreal-engine/ai-perception-in-unreal-engine?lang=en-US)
- [Environment Query System](https://dev.epicgames.com/documentation/en-us/unreal-engine/environment-query-system-in-unreal-engine)
- [EQS Testing Pawn](https://dev.epicgames.com/documentation/en-us/unreal-engine/environment-query-testing-pawn-in-unreal-engine)

## Interaction, crowds, and diagnosis

- [Smart Objects Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/smart-objects-in-unreal-engine---overview)
- [Avoidance with the Navigation System](https://dev.epicgames.com/documentation/unreal-engine/using-avoidance-with-the-navigation-system-in-unreal-engine)
- [Crowd Manager Settings](https://dev.epicgames.com/documentation/en-us/unreal-engine/crowd-manager-settings-in-the-the-unreal-engine-project-settings)
- [AI Debugging](https://dev.epicgames.com/documentation/unreal-engine/ai-debugging-in-unreal-engine?lang=en-US)
- [Gameplay Debugger](https://dev.epicgames.com/documentation/unreal-engine/using-the-gameplay-debugger-in-unreal-engine)

## Maturity notes

- Core Recast NavMesh, Behavior Trees, StateTree, AI Perception, Smart Objects, and avoidance workflows have current 5.8 documentation.
- World Partitioned Navigation Mesh is explicitly Experimental.
- The current EQS Testing Pawn guide still refers to the experimental nature of EQS; keep EQS bounded and validated.
- Do not infer that all AI systems replicate or run on clients. Authoritative gameplay AI remains a project/network architecture decision.

Prefer the 5.8 page, installed engine source, console help, and working sample behavior over remembered earlier-version defaults.

StateTree

# StateTree

## Execution model

StateTree combines hierarchical state-machine transitions with tree-based state selection.

- Selection evaluates Enter Conditions from the target/root path toward a selectable leaf.
- The selected leaf and all parent states on its active path become active.
- Tasks on all active states start and run concurrently.
- The first completing Task can trigger completion-based transition evaluation.
- Transitions are the only way to change the selected state.

Do not place sequential actions as sibling Tasks in one state. Use child states and `Next` transitions for ordered steps.

## Data roles

- **Parameters**: configured per asset/instance inputs.
- **Context/External Data**: required owner, actor, subsystem, or component data supplied by the schema/runtime.
- **Evaluators**: expose/update data used by states, tasks, conditions, and transitions.
- **Tasks**: perform bounded work while their state is active.
- **Conditions**: gate state entry or transitions.

Choose the correct schema for the owner, such as an Actor/Component-oriented schema. Fail early when required external data is absent.

## Authoring workflow

1. Define top-level modes with mutually understandable ownership: Idle, Patrol, Alert, Combat, Disabled.
2. Put shared always-active responsibilities on parent states only when concurrency is intended.
3. Decompose ordered behavior into child states and success/failure/`Next` transitions.
4. Make transition priority and destination explicit.
5. Expose typed data once and bind deliberately; avoid long invisible binding chains.
6. Define enter/exit/cancel cleanup for moves, delegates, abilities, animation, and Smart Object claims.
7. Use linked/subtrees only when their interface is stable and reuse is real.

## Common failure patterns

- **Sequence completes instantly/wrong action wins**: sibling tasks ran concurrently and one finished first.
- **No state selected**: Enter Conditions reject every path or required context is missing.
- **Transition loop**: a condition remains true on entry and immediately selects again.
- **Stale data**: evaluator/binding lifetime differs from the assumed update moment.
- **Action survives state exit**: task failed to cancel latent work or release resources.

## Debugging

Use the StateTree Debugger (`Window > Debugger` in the asset editor), instance selection, traces, state/task breakpoints, and recorded transitions. The debugger can consume Trace Analyzer data from Editor, Client, and Dedicated Server processes.

Acceptance requires the active state path, task lifetimes, data values, transition cause, and cleanup to match the authored contract under interruption and failure.

System selector and architecture

# System selector and architecture

## Layer the problem

```text
World collision -> NavMesh/path graph -> Path following/movement
Stimuli/events -> Perception/memory -> Decision architecture
World candidates -> EQS/direct query -> chosen goal
Interaction opportunities -> Smart Object claim -> interactor behavior
Nearby moving agents -> RVO or Detour Crowd -> local velocity adjustment
```

A bug belongs to one layer until evidence shows otherwise. Do not “fix AI” by changing several layers together.

## Decision selector

| Need | Default |
|---|---|
| One or two simple modes | component/enum/timers/events |
| Reactive priorities, conditions, abort-to-higher-priority behavior | Behavior Tree + Blackboard |
| Explicit hierarchical state, transitions, sequences, shared task data | StateTree |
| Large data-oriented crowds | Evaluate Mass/StateTree architecture separately; ordinary Actor AI may not scale |

Behavior Tree and StateTree can coexist at a system boundary, but do not duplicate the same state machine in both. Assign one owner and exchange compact state/events.

## Query selector

- Direct known actor/location: use the known reference or subsystem lookup.
- Reachable random point: navigation query.
- “Best cover/attack/resource point” from multiple constraints: EQS.
- Reusable reservable activity: Smart Object query/claim.
- Long-range route: NavMesh pathfinding.
- Short-range agent avoidance: RVO or Detour Crowd.

## Authority model

In networked games:

- run authoritative AI controller, decisions, path requests, Smart Object claims, damage, and gameplay state on the server;
- replicate the Pawn and observable gameplay state/animation inputs as designed;
- keep client-only cosmetic prediction/presentation non-authoritative;
- do not replicate entire Blackboards or internal decision graphs by default.

Route replication details to `$unreal-replication`.

## Data ownership

- Controller owns decision/path-following concerns tied to possession.
- Pawn/Character owns body, movement component, collision, animation-facing state.
- Blackboard holds Behavior Tree working memory, not universal game truth.
- StateTree context/external data supplies required owner/world data; Parameters configure instances.
- Subsystems/game state own durable shared facts.
- Perception stores observations; gameplay systems decide what those observations mean.

## Update policy

Prefer event-driven updates for target acquired/lost, damage, state changes, path completion, Smart Object invalidation, and Blackboard changes. Use bounded timers/services for genuinely periodic sensing or scoring. Stagger expensive work across agents and treat reaction delay as a design variable, not merely a performance defect.