gamedev-skills/awesome-gamedev-agent-skills / skills/disciplines/game-ai
game-ai
VerifiedDesigns 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`).
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
- Read the project first. Engine, existing AI code, navigation (navmesh,
AStarGrid2D, a tile grid), and how enemies find the player today. Extend what exists. - Write perception once. One sensor per agent writes
target,last_known_pos,can_see,heard_atto a Blackboard on a timer (5-10 Hz). Decisions read those facts; they never raycast. - Pick the model from the table and keep transitions inside states (or a table), not in
scattered
if state == ...checks. - 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.
- Add stuck and fairness guards (see Gotchas) before tuning numbers.
- 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.
- A* admissibility: on 50 random grids, the path cost from A* equals Dijkstra's (
Gotchas
FSM
- The initial state's
enter()never runs when the agent assignscurrent = Patrol.new()without calling it. Route the first state through the samechange_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 afterupdate()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 withinmax(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/3Dvelocityandvelocity_computedwhen avoidance is on; Unity: seeunity-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
AStarGrid2Ddefaults toDIAGONAL_MODE_ALWAYS, which cuts corners; setDIAGONAL_MODE_ONLY_IF_NO_OBSTACLES(orNEVERfor 4-way with Manhattan). - Godot
AStarGrid2D.update()clears every solid point and weight. Call it after settingregion/cell_size/offset, then mark walls.jumping_enabledignores 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*,AStarGrid2Dand 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.
- Godot 4.7
AStarGrid2D: defaultdiagonal_modeisDIAGONAL_MODE_ALWAYS,update()clears point data, andjumping_enableddisables weight scaling (https://docs.godotengine.org/en/4.7/classes/class_astargrid2d.html). - Godot 4.7
NavigationAgent2D:avoidance_enabled,velocity,velocity_computed(https://docs.godotengine.org/en/4.7/classes/class_navigationagent2d.html).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |