Index of every page on this site: llms.txt
All skills
Run it yourself

Designs engine-neutral enemy and NPC AI: picks FSM, behavior tree, utility or GOAP, and builds perception, steering and A* pathfinding. Use for patrol and chase, "find a path to the player", agents stuck on corners or AI that sees through walls. Not for BT or utility code (`ai-behavior-trees-utility-ai`), Unreal AI (`unreal-behavior-trees`) or Unity NavMesh (`unity-navmesh`).

Use this Skill: https://skilld.dev/gh/gamedev-skills/awesome-gamedev-agent-skills/game-ai

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈97 tokens for metadata: the name and description. ≈1.9k when used: this file. ≈3.6k more on demand in 2 files.

Description uses 4.9% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈388 characters, or 4.9%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Game AI architecture

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.

When to use

  • Choose a decision model, or fix one that has grown into flag soup.
  • Build or debug an FSM, perception, steering, A* on a grid or graph, or a flow field.
  • Diagnose agents that get stuck, oscillate, react unfairly fast or see through walls.

Not this skill: BT and utility runtimes go to ai-behavior-trees-utility-ai; Unreal BehaviorTree, EQS and StateTree go to unreal-behavior-trees; Unity NavMeshSurface and NavMeshAgent go to unity-navmesh. Movement and collision feel go to physics-tuning.

Pick the decision model

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.

Workflow

  1. Read the project first. Engine, existing AI code, navigation (navmesh, AStarGrid2D, a tile grid), and how enemies find the player today. Extend what exists.
  2. Write perception once. One sensor per agent writes target, last_known_pos, can_see, heard_at to a Blackboard on a timer (5-10 Hz). Decisions read those facts; they never raycast.
  3. Pick the model from the table and keep transitions inside states (or a table), not in scattered if state == ... checks.
  4. Path on the coarsest graph that works (waypoints or a nav grid beats a dense pixel grid), cache the path, and follow the next waypoint with steering.
  5. Add stuck and fairness guards (see Gotchas) before tuning numbers.
  6. Verify with runnable checks, not just by watching:
    • A* admissibility: on 50 random grids, the path cost from A* equals Dijkstra's (h = 0) cost. Any mismatch means the heuristic or step costs are wrong.
    • State flicker: log transitions with timestamps during a scripted run; more than about 2 transitions per second for one agent means missing hysteresis.
    • Stuck: run agents through the level headless and fail if any makes less than 0.5 units of progress toward its waypoint in 2 s. Then watch it with the path, current state and sight cone drawn on screen.

Gotchas

FSM

  • The initial state's 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.
  • Changing state from inside enter()/exit() re-enters the machine and runs exits twice. Queue the next state and apply it after update() returns.
  • Threshold flicker. Chase at 10 m and give up at 10 m, and the agent toggles every frame 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

  • Check cheap to expensive: squared distance, then the view cone (dot(forward, dir) > cos(half_angle)), then one raycast. Only survivors pay for the ray; stagger rays across frames.
  • One ray to the target's origin fails behind low cover (origin at the feet) or passes through a gap at the waist. Cast to two or three points (head, chest) and accept any hit.
  • Omniscient AI feels like cheating. Chase the last-known position, then search, instead of 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

  • Weighted sums cancel. Seek plus avoid pointing opposite ways sums to zero and the agent freezes at the wall. Use priority truncation: apply avoidance first and spend the remaining force budget on lower behaviors.
  • Waypoint radius smaller than one tick of travel (speed * dt) makes agents overshoot and orbit the point. Advance when within max(radius, speed * dt).
  • Separation over every pair is O(n²); bucket agents in a spatial hash with cells about the neighbor radius.
  • Steering and an engine nav agent both moving the body jitter. Let the agent compute the path and feed its desired velocity into your steering (Godot: NavigationAgent2D/3D velocity and velocity_computed when avoidance is on; Unity: see unity-navmesh).

Pathfinding

  • Inadmissible heuristic returns fast but longer paths: octile assumes diagonal steps cost √2; if diagonals cost 1 use Chebyshev; terrain weights below 1 break every grid heuristic.
  • Diagonal corner cutting through wall corners: only allow a diagonal when both orthogonal 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).
  • Godot AStarGrid2D.update() clears every solid point and weight. Call it after setting region/cell_size/offset, then mark walls. jumping_enabled ignores weight scales.
  • Unreachable goal floods the whole map. Label connected regions with a flood fill once and reject cross-region requests, or cap node expansions per search.
  • Repathing every frame. Repath when the target moves more than a cell (or 1-2 m), or every 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.
  • Stuck forever. If progress toward the next waypoint stalls for about 2 s, repath; after two failed repaths, change state (give up, teleport off-screen, or pick a new goal).

References

  • references/pathfinding.md: read when writing A* or a grid adapter by hand, choosing a heuristic, or deciding between hand-rolled A*, AStarGrid2D and an engine navmesh.
  • references/fsm-perception-steering.md: read when implementing a hierarchical FSM, a sight/hearing sensor or priority-truncated steering.

Related skills

  • 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.

Version notes

Last verified: 2026-11-11.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts8d3 checks · Risk SAFE
  • Gen Agent Trust Hub9d

    This skill provides architectural guidance and code snippets for game AI development, including Finite State Machines, perception systems, and pathfinding. No security risks were identified.

  • Socket8d

    No alerts

  • Snyk9d

    Risk: LOW · No issues

Signed by skilld at c6ca6c4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated last week

README badge

README badge for gamedev-skills/awesome-gamedev-agent-skills/game-ai