사용 방법
- 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
- 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
- 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill game-ai시작 전 확인
- 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
- 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.
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_at to 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.
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.
- Godot 4.7
AStarGrid2D: defaultdiagonal_modeisDIAGONAL_MODE_ALWAYS,update()clears
point data, and jumping_enabled disables 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).