game-ai Checked

--- Chase state: returns Patrol when the player escapes sight range ---

class Chase extends State:

func update(agent, dt) -> State:

if not agent.can_see(agent.target):

return Patrol.new() # transition by returning next state

agent.move_toward(agent.target.position, dt)

return null # null = stay in this state

--- Driver: call once per frame ---

func tick(dt):

var next = current.update(self, dt)

if next != null:

current.exit(self); next.enter(self); current = next

Keep transition logic *inside* states (or in a table), never as a growing pile
of `if` flags. One state owns one behavior; that is what keeps an FSM readable.

### 2. Behavior tree tick (composite nodes return a status)

A node's tick() returns SUCCESS, FAILURE, or RUNNING (still working this frame).

enum Status { SUCCESS, FAILURE, RUNNING }

Sequence: run children in order; stop at the first non-SUCCESS (logical AND).

func sequence_tick(children, agent, dt) -> int:

for child in children:

var s = child.tick(agent, dt)

if s != Status.SUCCESS:

return s # FAILURE or RUNNING short-circuits the sequence

return Status.SUCCESS

Selector: try children until one succeeds or is RUNNING (logical OR / fallback).

func selector_tick(children, agent, dt) -> int:

for child in children:

var s = child.tick(agent, dt)

if s != Status.FAILURE:

return s # SUCCESS or RUNNING stops the search

return Status.FAILURE

A guard AI reads top-down: `Selector[ Sequence[CanSeePlayer?, Chase], Patrol ]`
— chase if visible, otherwise patrol. See `references/behavior-trees.md` for
leaf nodes, decorators (Inverter, Cooldown), and a blackboard.

### 3. Steering: seek and arrive (smooth, frame-rate independent)

Seek: accelerate toward a target at full speed. Steering = desired - current.

func seek(pos, vel, target, max_speed, max_force) -> Vector2:

var desired = (target - pos).normalized() * max_speed

return (desired - vel).limit_length(max_force) # a force, not a teleport

Arrive: like seek, but ramp speed down inside slow_radius so it stops cleanly.

func arrive(pos, vel, target, max_speed, max_force, slow_radius) -> Vector2:

var offset = target - pos

var dist = offset.length()

if dist < 0.001: return -vel # already there: kill drift

var ramped = max_speed * min(dist / slow_radius, 1.0)

var desired = offset / dist * ramped

return (desired - vel).limit_length(max_force)

Per frame: vel += steering * dt; pos += vel * dt (always scale by dt)

### 4. A* heuristic must not overestimate (or paths stop being shortest)

Match the heuristic to the movement. An ADMISSIBLE heuristic (never larger

than the true remaining cost) keeps A* optimal.

def heuristic(a, b):

dx, dy = abs(a.x - b.x), abs(a.y - b.y)

return dx + dy # Manhattan: 4-direction grids (no diagonals)

return (dx + dy) + (1.414 - 2) * min(dx, dy) # octile: 8-direction grids

f(n) = g(n) + h(n): g = cost from start, h = heuristic to goal.

Overestimating h is faster but no longer guarantees the shortest path.

The full A* loop (priority queue, `came_from` reconstruction, grid + waypoint
graphs) is in `references/pathfinding.md`.

## Pitfalls

- **Pathfinding every frame** tanks the frame rate. Recompute on a timer or only
  when the target moves to a new tile; follow the cached waypoints in between.
- **Steering straight to the goal** instead of to the next waypoint makes agents
  hug walls and corners. Follow the path; advance the waypoint when within radius.
- **Inadmissible A\* heuristic** (e.g. Euclidean distance scaled up, or Manhattan
  on a diagonal grid) returns fast but *non-shortest* paths. Pick the heuristic
  that matches your allowed moves.
- **Behavior tree leaves that never return RUNNING** for multi-frame actions
  (walking, playing an animation) cause the tree to restart the action every
  tick. Return RUNNING until the action completes.
- **FSM transition spaghetti**: scattering `if state == ...` checks everywhere
  recreates the mess an FSM exists to prevent. Keep transitions in the state.
- **No line-of-sight or stuck check** → agents grind into walls forever. Add a
  timeout that forces a repath or a state change.

## References

- `references/pathfinding.md` — complete A* (priority queue, reconstruction),
  grid vs waypoint graphs, when to defer to an engine navmesh.
- `references/behavior-trees.md` — node taxonomy, leaf/decorator implementations,
  blackboard, and FSM-vs-BT selection.

## Related skills

- `unity-navmesh`, `unreal-behavior-trees` — concrete engine AI/navigation APIs.
- `physics-tuning` — movement, collision response, and agent radius.
- `procedural-gen` — generating the graph/level the AI navigates.
- `tower-defense`, `fps-shooter` — genres that compose this skill.