导航网格与碰撞

导航网格定义了用于寻路和移动限制的可行走空间。

导航网格定义了 可行走区域 在你的世界中。可用于：

• 将生成的物品吸附到可到达的地面上
• 将玩家/NPC锁定在可行走区域内

在编辑器中，碰撞体也可用于切割导航网格。

组件（快速概览）

• 导航网格：你查询并重建的烘焙导航网格
• 导航网格环：定义可行走边界（以及洞）的多边形环
• 碰撞体: 盒体碰撞体, 圆形碰撞体, 边缘碰撞体, 多边形碰撞体

用于移动/寻路（移动代理）请参见 移动代理/NPC.

导航网格 API 参考

Navmesh :: class : Component {
    // 将一个点投射到此导航网格上。
    // triangle_hint 是一个加速提示，可供附近查询复用。
    try_find_closest_point_on_navmesh :: method(
        to_point: v2,
        result: ref v2,
        triangle_hint: ref s64
    ) -> bool;

    // 沿着导航网格进行射线投射。返回终点以及查询是否成功。
    try_raycast :: method(position: v2, direction: v2) -> v2, bool;

    // 为正常的导航网格更新排队重建。
    mark_for_rebuild :: method();

    // 当同一帧查询需要新的几何体时，立即重建。
    rebuild_immediately :: method() -> bool;

    // 仅包含此实体及其后代上的碰撞体。
    child_colliders_only: bool;

    // 检测输入变化并自动重建。
    enable_automatic_rebuilds: bool;
}

编辑器设置（构建导航网格）

1. 创建一个实体并添加一个 导航网格 组件。
2. 创建带有 导航网格环 组件的子实体，以定义可行走多边形。
3. 对于每个 导航网格环:

   • 添加点以定义环的形状
   • 按逆时针顺序排列外边界点
   • 切换 翻转内外侧 将其变为洞/障碍，而不是可行走空间
4. 在检查器中使用导航网格调试选项来可视化这些三角形。

默认情况下， 导航网格环 定义一个可行走区域。将其翻转可在现有导航网格中“打洞”（形成不可行走岛屿）。

环的绕行方向决定每条边哪一侧被视为内部。逆时针是可行走外边界的正常绕行方向。顺时针会反转该结果。请使用 翻转内外侧 有意用于洞，而不是依赖意外反转的点顺序。

碰撞体与导航网格环

碰撞体也可通过碰撞体检查器选项提供环（例如“创建导航网格环”/“翻转导航网格环”）。

重要注意事项：

• 启用 自动重建时，导航网格会检测环、碰撞体、瓦片地图和子导航网格输入变化，并排队重建。
• 开启 仅子级碰撞体 以忽略场景中其他无关的碰撞体。
• 在禁用自动重建时，调用 mark_for_rebuild() 在更改输入后。
• 调用 rebuild_immediately() 仅在需要变更后几何体的同一帧查询之前。

在导航网格上生成（限制到可到达地面）

使用 try_find_closest_point_on_navmesh 将期望位置投射到导航网格上最近的有效点：

spawn_on_navmesh :: proc(navmesh: Navmesh, desired_position: v2) -> Entity {
    spawn_pos: v2;
    triangle_hint: s64; // 0 = 尚未设置

    if navmesh.try_find_closest_point_on_navmesh(desired_position, ref spawn_pos, ref triangle_hint) {
        e := Scene.create_entity();
        e.set_local_position(spawn_pos);
        return e;
    }

    return null;
}

重复使用 triangle_hint 用于在同一区域进行重复查询（战利品生成器、波次生成等）。它可以显著加快投射。

立即重建导航网格

大多数几何变化都会被自动捕获。仅在你需要强制时序时使用：

• rebuild_immediately()：立即重建（仅在必须在同一帧查询更新后的网格时使用）

ok := navmesh.rebuild_immediately();
if !ok {
    log_info("导航网格重建失败", {});
}

父级导航网格会在子级导航网格之后刷新，因此拼接后的父级网格会自动获取子网格输入变化。

穿过导航网格进行射线投射

try_raycast 沿着 方向 到达导航网格边界。第二个返回值报告查询是否成功。

endpoint, ok := navmesh.try_raycast(start, direction);
if ok {
    // endpoint 位于导航网格边界上。
}

碰撞体触发器

一个带有 is_trigger == true 的碰撞体可以在另一个碰撞体进入、停留在内部或离开时进行报告。触发器回调适用于静止和移动的碰撞体；一个 移动代理 并非必需。

请谨慎使用碰撞体。 只将它们添加到关键玩法表面：地图边界、玩家必须落到的平台、关键障碍物以及有意设置的触发器体积。 不要 将碰撞体添加到装饰性实体（树木、灌木、背景道具等）上。场景中的大多数实体都不应带有碰撞体。

Trigger_Listener :: class : Component {
    ao_start :: method() {
        trigger_collider := entity.get_component(Circle_Collider);
        trigger_collider.is_trigger = true;

        trigger_collider.on_trigger_start = proc(self: Collider, other: Collider) {
            log("重叠开始: %", {other.entity.get_name()});
        };

        trigger_collider.on_trigger_stay = proc(self: Collider, other: Collider) {
            log("重叠持续: %", {other.entity.get_name()});
        };

        trigger_collider.on_trigger_end = proc(self: Collider, other: Collider) {
            log("重叠结束: %", {other.entity.get_name()});
        };
    }
}

接近检查和自定义命中逻辑

对于使用范围查询而非碰撞体回调的触发区域、拾取物、投射物检测或其他自定义命中逻辑，请使用：

• Scene.get_all_components_in_range / Scene.get_closest_component_in_range
• 简单距离检查（in_range）来判断“在内部”、“已拾取”、“命中”等。

场景查询辅助函数

Scene :: struct {
    get_all_components_in_range :: proc(position: v2, range: float, results: ref [..]$T);
    get_closest_component_in_range :: proc(position: v2, range: float, $T: typeid) -> T, bool;
}

在正常的共享游戏流程中处理伤害、拾取和计分。不要用 Game.is_server().

触发体积（进入 / 停留 / 离开）

要模拟触发区域，保留上一帧处于内部的对象列表，并将其与当前帧的结果进行差异比较。

contains_id :: proc(list: []u64, id: u64) -> bool {
    for x: list if x == id return true;
    return false;
}

Trigger_Zone :: class : Component {
    radius: float @ao_serialize;
    last_inside: [..]u64;

    ao_update :: method(dt: float) {
        center := entity.world_position;

        players: [..]Player;
        Scene.get_all_components_in_range(center, radius, ref players);

        current_inside: [..]u64;

        for p: players {
            if in_range(p.entity.world_position, center, radius) {
                current_inside.append(p.entity.id);

                if !contains_id(last_inside, p.entity.id) {
                    // 进入时
                    Notifier.notify(p, "已进入区域！");
                }
                else {
                    // 停留时
                }
            }
        }

        for id: last_inside {
            if !contains_id(current_inside, id) {
                // 离开时（你可能需要自行进行 id.player 查找）
            }
        }

        last_inside.clear();
        for id: current_inside {
            last_inside.append(id);
        }
    }
}

当你不想添加碰撞体触发体积时，这种手动触发模式仍然很有用。如果某物体在更新之间被传送/销毁，除非你处理清理逻辑，否则可能无法得到干净的“离开”事件。

拾取物（范围内最近）

try_pickup_near_player :: proc(player: Player) {
    pos := player.entity.world_position;

    pickup, ok := Scene.get_closest_component_in_range(pos, 1.5, Pickup);
    if ok && pickup != null {
        if in_range(pickup.entity.world_position, pos, 1.5) {
            pickup.claim(player); // 你自己的逻辑（授予 + 销毁）
        }
    }
}

快速移动“命中”（简单子步进）

如果你移动很快（冲刺、投射物），只检查最终位置时可能会错过较窄的目标。一个简单的解决方法是子步进：在上一个位置和新位置之间采样几个点，并运行相同的范围查询。

hit_check_move :: proc(last_pos: v2, new_pos: v2) {
    steps := 4;
    for i := 1; i <= steps; i += 1 {
        t := (i.(float)) / (steps.(float));
        p := lerp(last_pos, new_pos, t);

        enemies: [..]Enemy;
        Scene.get_all_components_in_range(p, 1.0, ref enemies);
        for e: enemies {
            if in_range(e.entity.world_position, p, 1.0) {
                // 仅应用一次命中，开始冷却等。
            }
        }
    }
}