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.

referencesfsm-perception-steering.md

≈1.7k tokens on demand. Your agent reads this file only when SKILL.md points to it.

FSM, perception and steering patterns

Contents:

  1. State machine with queued transitions and shared exits
  2. Sight and hearing sensor
  3. Priority-truncated steering

Snippets are Godot 4.7 GDScript; the structure ports directly to C# or any engine.

1. State machine with queued transitions and shared exits

The machine owns change_state(), so the first state's enter() runs like every other. A transition requested during enter()/exit()/update() is queued and applied once, after the current call returns. Shared exits (death, stun) live in one place instead of in every state.

# state_machine.gd
class_name StateMachine extends RefCounted

var agent
var current: AIState
var _queued: AIState
var _time_in_state := 0.0

func _init(owner_agent, first: AIState) -> void:
    agent = owner_agent
    request(first)
    _apply_queued()

func request(next: AIState) -> void:
    _queued = next                      # last request in one tick wins

func tick(dt: float) -> void:
    _time_in_state += dt
    var shared := _shared_exit()        # checked before the state, so no state can forget it
    if shared != null and (current == null or shared.get_script() != current.get_script()):
        request(shared)
    elif current != null:
        current.update(self, dt)
    _apply_queued()

func time_in_state() -> float:
    return _time_in_state

func _shared_exit() -> AIState:
    if agent.health <= 0:
        return DeadState.new()
    return null

func _apply_queued() -> void:
    while _queued != null:              # enter() may queue again; apply in order, never recurse
        var next := _queued
        _queued = null
        if current != null:
            current.exit(self)
        current = next
        _time_in_state = 0.0
        current.enter(self)
# ai_state.gd: base class. States call machine.request(), never assign machine.current.
class_name AIState extends RefCounted
func enter(_machine: StateMachine) -> void: pass
func update(_machine: StateMachine, _dt: float) -> void: pass
func exit(_machine: StateMachine) -> void: pass
# chase_state.gd: hysteresis on distance plus a minimum time in state.
class_name ChaseState extends AIState
const GIVE_UP_DISTANCE := 14.0          # chase starts at 10 (see PatrolState); leave at 14
const MIN_TIME := 0.4

func update(machine: StateMachine, _dt: float) -> void:
    var bb: Dictionary = machine.agent.blackboard
    if machine.time_in_state() < MIN_TIME:
        return
    if not bb.can_see and machine.agent.global_position.distance_to(bb.last_known_pos) < 1.0:
        machine.request(SearchState.new())
    elif machine.agent.global_position.distance_to(bb.last_known_pos) > GIVE_UP_DISTANCE:
        machine.request(PatrolState.new())

PatrolState, SearchState and DeadState follow the same shape. Each script holds one class_name, so put each in its own file.

2. Sight and hearing sensor

One sensor per agent, ticked on a timer, writes facts the decision layer reads. The order is cheap to expensive, and only targets that pass the cone test pay for raycasts.

# sensor_3d.gd: attach under the agent; set eye, target and blackboard from the agent.
extends Node3D

@export var sight_range := 20.0
@export var half_angle_deg := 55.0
@export var tick_interval := 0.15           # about 7 Hz; stagger start times across agents
@export_flags_3d_physics var sight_mask := 1
var eye: Node3D
var target: Node3D
var blackboard: Dictionary
var _timer := randf() * 0.15                # random phase so agents don't all raycast together
var _exclude: Array[RID] = []

func _ready() -> void:
    if get_parent() is CollisionObject3D:
        _exclude.append(get_parent().get_rid())  # don't let the ray hit our own body

func _physics_process(dt: float) -> void:
    _timer -= dt
    if _timer > 0.0:
        return
    _timer = tick_interval
    var seen := _can_see(target)
    blackboard.can_see = seen
    if seen:
        blackboard.last_known_pos = target.global_position

func _can_see(t: Node3D) -> bool:
    if t == null:
        return false
    var to := t.global_position - eye.global_position
    if to.length_squared() > sight_range * sight_range:
        return false                         # 1. distance, no sqrt
    var fwd := -eye.global_basis.z
    if fwd.dot(to.normalized()) < cos(deg_to_rad(half_angle_deg)):
        return false                         # 2. view cone
    var space := get_world_3d().direct_space_state
    for offset in [Vector3(0, 1.6, 0), Vector3(0, 1.0, 0)]:   # 3. head, then chest
        var q := PhysicsRayQueryParameters3D.create(
            eye.global_position, t.global_position + offset, sight_mask, _exclude)
        var hit := space.intersect_ray(q)
        if hit.is_empty() or hit.collider == t:
            return true
    return false

# Hearing: gameplay posts sounds; agents never poll for them.
func hear(at: Vector3, loudness_radius: float) -> void:
    if eye.global_position.distance_squared_to(at) <= loudness_radius * loudness_radius:
        blackboard.heard_at = at

Post noises through a group call, for example get_tree().call_group(&"ai_sensors", &"hear", pos, 12.0) for a gunshot and a smaller radius for footsteps. Add an awareness value that rises while can_see holds (faster when close) and acts only past a threshold, so the first sighting is not an instant hit.

3. Priority-truncated steering

Blending all behaviors with weights lets opposing forces cancel. Priority truncation spends a fixed force budget in order: avoidance first, then separation, then path following.

# steering.gd: returns a force; the caller integrates vel += force * dt, pos += vel * dt.
func steer(pos: Vector2, vel: Vector2, wants: Array[Vector2], max_force: float) -> Vector2:
    var total := Vector2.ZERO
    var budget := max_force
    for want in wants:                      # ordered by priority, highest first
        if budget <= 0.0:
            break
        var f := want.limit_length(budget)
        total += f
        budget -= f.length()
    return total

func arrive(pos: Vector2, vel: Vector2, target: Vector2, max_speed: float, slow_radius: float) -> Vector2:
    var offset := target - pos
    var dist := offset.length()
    if dist < 0.001:
        return -vel
    var speed := max_speed * minf(dist / slow_radius, 1.0)
    return offset / dist * speed - vel

Call it as steer(pos, vel, [avoid, separate, arrive_to_waypoint], max_force). Separation reads only neighbors from a spatial hash (cells about the neighbor radius, often 2× the agent radius).

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