Split every agent into layers that pass one small value to the next: perceive (facts on a
Blackboard) → decide (an intent such as "go to X", "attack Y") → path (waypoints) →
steer (a velocity) → animate. Most "dumb AI" bugs are a layer doing another layer's job:
a state that raycasts, a pathfinder called every frame, steering that ignores the path.
Not this skill: BT and utility runtimes go to ai-behavior-trees-utility-ai; UnrealBehaviorTree, EQS and StateTree go to unreal-behavior-trees; Unity NavMeshSurface andNavMeshAgent go to unity-navmesh. Movement and collision feel go to physics-tuning.
| Situation | Default |
|---|---|
| 2-6 states, transitions obvious (door, turret, simple guard) | FSM |
| Several states share exits (stunned, dead, alerted from anywhere) | Hierarchical FSM: a parent state owns the shared exits |
| Many prioritized, interruptible behaviors, reused across enemy types | Behavior tree, built with ai-behavior-trees-utility-ai |
| Graded trade-offs (which target, heal or attack, needs) | Utility scoring, same skill; usually inside a BT branch |
| Multi-step plans with preconditions the designers want to emerge | GOAP; only if a BT cannot express it, because plans are hard to debug |
Common shipping mix: an FSM for the top mode (Idle, Combat, Dead) with a BT inside Combat.
Start with the FSM; promote a state to a BT when its transitions stop fitting on one screen.
AStarGrid2D,a tile grid), and how enemies find the player today. Extend what exists.
target, last_known_pos,can_see, heard_at to a Blackboard on a timer (5-10 Hz). Decisions read those facts; they
never raycast.
scattered if state == ... checks.
cache the path, and follow the next waypoint with steering.
h = 0)cost. Any mismatch means the heuristic or step costs are wrong.
transitions per second for one agent means missing hysteresis.
progress toward its waypoint in 2 s.
Then watch it with the path, current state and sight cone drawn on screen.
FSM
enter() never runs when the agent assigns current = Patrol.new()without calling it. Route the first state through the same change_state() as every other.
enter()/exit() re-enters the machine and runs exits twice.Queue the next state and apply it after update() returns.
at the boundary. Use separate enter and exit thresholds (chase at 10, give up at 14) and a
minimum time in state of about 0.3-0.5 s.
Perception
cos(half_angle)`), then one raycast. Only survivors pay for the ray; stagger rays across frames.
a gap at the waist. Cast to two or three points (head, chest) and accept any hit.
reading the player's live position after sight is lost. Delay the first reaction by roughly
0.2-0.5 s, or fill an awareness meter faster at close range, so players can react.
Steering
freezes at the wall. Use priority truncation: apply avoidance first and spend the remaining
force budget on lower behaviors.
speed * dt) makes agents overshoot andorbit the point. Advance when within max(radius, speed * dt).
neighbor radius.
path and feed its desired velocity into your steering (Godot: NavigationAgent2D/3Dvelocity and velocity_computed when avoidance is on; Unity: see unity-navmesh).
Pathfinding
√2; if diagonals cost 1 use Chebyshev; terrain weights below 1 break every grid heuristic.
neighbors are open. Godot AStarGrid2D defaults to DIAGONAL_MODE_ALWAYS, which cuts
corners; set DIAGONAL_MODE_ONLY_IF_NO_OBSTACLES (or NEVER for 4-way with Manhattan).
AStarGrid2D.update() clears every solid point and weight. Call it after settingregion/cell_size/offset, then mark walls. jumping_enabled ignores weight scales.
reject cross-region requests, or cap node expansions per search.
0.25-0.5 s, staggered, with a per-frame budget of searches. Many agents to one goal: one flow
field (Dijkstra from the goal) instead of A* per agent.
failed repaths, change state (give up, teleport off-screen, or pick a new goal).
references/pathfinding.md: read when writing A* or a grid adapter by hand, choosing aheuristic, or deciding between hand-rolled A*, AStarGrid2D and an engine navmesh.
references/fsm-perception-steering.md: read when implementing a hierarchical FSM, asight/hearing sensor or priority-truncated steering.
ai-behavior-trees-utility-ai: BT and utility runtimes once the model is chosen.unity-navmesh, unreal-behavior-trees: engine navigation and AI assets.physics-tuning: agent radius, movement and collision response.procedural-gen: the level graph the AI navigates.Last verified: 2026-11-11.
AStarGrid2D: default diagonal_mode is DIAGONAL_MODE_ALWAYS, update() clearspoint data, and jumping_enabled disables weight scaling
(https://docs.godotengine.org/en/4.7/classes/class_astargrid2d.html).
NavigationAgent2D: avoidance_enabled, velocity, velocity_computed(https://docs.godotengine.org/en/4.7/classes/class_navigationagent2d.html).