移动代理/NPC

使用 Movement_Agent 结合寻路和导航网格限制来移动实体。

移动代理

移动代理 是一个用于转向和寻路的移动辅助组件。

最常见的用途是：

• 请求一条指向目标的路径（set_path_target)
• 将实体限制在可行走空间中（锁定到一个 导航网格)
• 穿过简单的碰撞体几何体

本页介绍移动和寻路。有关构建/查询导航网格以及碰撞体触发器细节，请参阅 导航网格与碰撞.

Movement_Agent API 参考

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

    // 请求一条以给定速度朝向目标的路径。
    set_path_target :: method(target: v2, speed: float) -> Set_Path_Target_Result;

    // 将此代理限制到一个导航网格上（每帧将其吸附到导航网格）。
    // 传入 null 以清除。
    set_navmesh_to_lock_to :: method(navmesh: Navmesh);

    // 常见调优/状态
    movement_speed:   float;
    agent_radius:     float;
    friction:         float;
    velocity:         v2;
    input_this_frame: v2;
}

CSL 移动物理与触发器

Movement_Agent 实体具有一条用于简单抛体运动的 CSL 物理路径。

碰撞：该代理启用的非触发器碰撞体会与启用的非触发器世界碰撞体发生阻挡，并将 category_bits / mask_bits 过滤规则纳入考虑。移动会在首次碰撞处停止，并沿碰撞表面滑动。

触发器回调属于碰撞体本身，不需要一个 移动代理.

寻路（设置目标）

调用 set_path_target 只要实体应继续移动，就每帧调用一次。单次调用并不是持久的移动指令。

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：下一个路径点
        // result.move_direction：归一化的移动方向（用于朝向/动画很有用）
    }
}

set_path_target 会与其他代理异步处理。返回的结果是最近完成的寻路数据，因此在你设置新目标的第一帧，可能不会返回 success == true.

将移动锁定到导航网格（停留在可行走空间上）

如果实体永远不应离开可行走空间，请将其锁定到导航网格：

agent.set_navmesh_to_lock_to(navmesh);

将其调用为 null 以清除。

创建移动中的 NPC

这是一个使用移动代理实现的最简“跟随玩家”NPC：

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 {
            // 可选：朝向方向 / 设置动画标志
            // dir := result.move_direction;
        }
    }
}