> For the complete documentation index, see [llms.txt](https://docs.allout.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.allout.game/core-engine-concepts/movement-agents-npcs.md).

# Movement Agents/NPCs

### Movement Agents

`Movement_Agent` is a movement helper component used for steering and pathfinding.

Most commonly, you use it to:

* Request a path toward a target (`set_path_target`)
* Constrain an entity to walkable space (lock to a `Navmesh`)
* Move through simple collider geometry
* Drive trigger checks for traps, teleporters, pickup zones, and similar gameplay

{% hint style="info" %}
This page covers movement and pathfinding. For building/querying navmeshes and collider trigger details, see [Navmesh & Collision](/core-engine-concepts/navmesh-and-collision.md).
{% endhint %}

### Movement\_Agent API reference

```go
Movement_Agent :: class : Component {
    Set_Path_Target_Result :: struct {
        success:        bool;
        next_point:     v2;
        move_direction: v2;
    }

    // Request a path toward target at a given speed.
    set_path_target :: method(target: v2, speed: float) -> Set_Path_Target_Result;

    // Constrain this agent to a navmesh (snap to it every frame).
    // Pass null to clear.
    set_navmesh_to_lock_to :: method(navmesh: Navmesh);

    // Common tuning/state
    movement_speed:   float;
    friction:         float;
    velocity:         v2;
    input_this_frame: v2;
}
```

### CSL movement physics and triggers

Movement\_Agent entities have a CSL physics path for simple ballistic movement and/or trigger detection.

Rigidbody collision: the agent's enabled non-trigger colliders block against enabled non-trigger world colliders, taking `category_bits` / `mask_bits` filtering into account. Movement stops at the first hit and slides along the hit surface.

Trigger overlap detection: if a collider has `is_trigger == true`, it can report when another collider enters, stays inside, or exits its bounds through callbacks.

{% hint style="info" %}
Movement\_Agent has velocity/friction fields but you do not have to use them. For a stationary trap, teleporter, pickup zone, or similar trigger volume, add a Movement\_Agent and a trigger collider to the entity and assign trigger callbacks.
{% endhint %}

### Pathfinding (set a target)

Call `set_path_target` every frame (or whenever your target changes).

```go
follow_target :: proc(agent: Movement_Agent, target_pos: v2) {
    result := agent.set_path_target(target_pos, agent.movement_speed);

    if result.success {
        // result.next_point: next waypoint
        // result.move_direction: normalized move direction (useful for facing/anim)
    }
}
```

{% hint style="info" %}
`set_path_target` is processed asynchronously with other agents. The returned result is the latest completed pathfind data, so the first frame you set a new target may not return `success == true`.
{% endhint %}

### Lock movement to a navmesh (stay on walkable space)

If an entity should never leave walkable space, lock it to a navmesh:

```go
agent.set_navmesh_to_lock_to(navmesh);
```

Call it with `null` to clear.

### Creating Moving NPCs

This is a minimal “follow the player” NPC using a movement agent:

```go
Follower_NPC :: class : Component {
    agent: Movement_Agent @ao_serialize;
    target: Entity @ao_serialize;

    ao_update :: method(dt: float) {
        if !#alive(target) return;

        result := agent.set_path_target(target.world_position, agent.movement_speed);
        if result.success {
            // Optional: face direction / set animation flags
            // dir := result.move_direction;
        }
    }
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.allout.game/core-engine-concepts/movement-agents-npcs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.