导航网格与碰撞

导航网格定义了寻路和移动约束的可行走空间。

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

• 将生成的物品贴合到可到达的地面上

• 将玩家/NPC限制在可行走区域内

碰撞体也可以在编辑器中用于雕刻导航网格。

组件（快速概览）

• 导航网格：你查询和重建的烘焙导航网格

• Navmesh_Loop：定义可行走边界（和洞）的多边形环

• 碰撞体: Box_Collider, Circle_Collider, Edge_Collider, Polygon_Collider

用于移动/寻路（Movement_Agent）见 移动代理/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;

    rebuild_immediately :: method() -> bool;
    mark_for_rebuild    :: method();
}

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

1. 创建一个实体并添加一个 导航网格 组件。

2. 创建带有子实体的 Navmesh_Loop 组件以定义可行走多边形。

3. 对于每个 Navmesh_Loop:

   • 添加点以定义环形形状

   • 切换 翻转内外（Flip Inside Outside） 以使其成为一个洞/障碍，而不是可行走的空间

4. 在检查器中使用导航网格调试选项来可视化三角形。

默认情况下， 一个 Navmesh_Loop 定义一个可行走区域。翻转它以在现有导航网格中“打孔”（不可行走的孤立区域）。

碰撞体和导航网格环

碰撞体也可以通过碰撞体检查器选项贡献环（例如“制作导航网格环”/“翻转导航网格环”）。

重要注意事项：

• 一个 导航网格 确实 不会 仅因为碰撞体在运行时发生变化而自动重建。

• 如果你修改了碰撞体几何并依赖于碰撞体驱动的环，请手动重建导航网格（见下文）。

• 如果你想要一个完全忽略碰撞体的导航网格，请使用导航网格检查器选项来忽略碰撞体。

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

使用 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 用于在同一区域重复查询（战利品生成器、波次生成等）。它可以显著加快投射速度。

重建导航网格（当几何体发生变化时）

使用下列之一：

• mark_for_rebuild()：将重建延迟到下一帧开始（便于批处理）

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

navmesh->mark_for_rebuild();

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

如果你有一个将多个子导航网格“缝合”在一起的父导航网格，更改子导航网格并不会自动重建父级。编辑后在父级上调用 mark_for_rebuild() / rebuild_immediately() 。

碰撞（当前 CSL 支持）

碰撞体以组件形式存在（Box_Collider, Circle_Collider, Edge_Collider, Polygon_Collider），但碰撞进入/退出的脚本回调尚未在 CSL 中实现 尚未在 CSL 中实现.

伪碰撞行为（触发器、拾取、“命中”）

在 CSL 中暴露碰撞回调之前，标准做法是：

• 使用以下方法查询附近组件 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;
}

优先在服务端执行对游戏性有影响的操作（伤害、拾取、计分）。将仅本地的检查用于视觉反馈。

触发体积（进入 / 停留 / 退出）

要模拟触发区域，请保留上帧内部的列表并将其与当前帧的结果做差异比较。

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) {
                    // on_enter
                    Notifier.notify(p, "进入区域！");
                }
                else {
                    // on_stay
                }
            }
        }

        for id: last_inside {
            if !contains_id(current_inside, id) {
                // on_exit（你可能需要自己的 id->player 查找）
            }
        }

        last_inside = current_inside;
    }
}

这是“尽力而为”的碰撞逻辑。如果某些东西在更新之间被传送/取消生成，除非你处理清理，否则你可能无法获得干净的“退出”。

拾取（范围内最近）

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) {
                // 应用一次命中，开始冷却等。
            }
        }
    }
}