导航网格与碰撞

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

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

• 将生成的物品吸附到可到达的地面上

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

碰撞体也可用于在编辑器中雕刻 navmesh。

组件（快速概览）

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

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

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

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

Navmesh API 参考

Navmesh :: class : Component {
    // 将一个点投影到此 navmesh 上。
    // 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();
}

编辑器设置（构建 navmesh）

1. 创建一个实体并添加一个 Navmesh 组件。

2. 创建子实体并添加 Navmesh_Loop 组件来定义可行走多边形。

3. 对于每个 Navmesh_Loop:

   • 添加点以定义环的形状

   • 切换 Flip Inside Outside 将其变为洞/障碍，而不是可行走空间

4. 使用检查器中的 navmesh 调试选项来可视化三角形。

默认情况下， Navmesh_Loop 定义一个可行走区域。将其翻转可在现有 navmesh 中“打洞”（不可行走岛屿）。

碰撞体与 navmesh 环

碰撞体也可以通过碰撞体检查器选项提供环（例如 “Make Navmesh Loop” / “Flip Navmesh Loop”）。

重要注意事项：

• 一个 Navmesh 不会 不 仅仅因为运行时某个碰撞体发生变化就自动重建。

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

• 如果你想要一个完全忽略碰撞体的 navmesh，请在 navmesh 检查器中使用忽略碰撞体的选项。

在 navmesh 上生成（吸附到可到达地面）

使用 try_find_closest_point_on_navmesh 将期望位置投影到 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 用于同一区域的重复查询（战利品生成器、波次生成等）。它可以显著加快投影速度。

重建 navmesh（当几何发生变化时）

使用以下之一：

• mark_for_rebuild()：将重建延迟到下一帧开始时进行（最适合批处理）

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

navmesh->mark_for_rebuild();

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

如果你有一个父级 navmesh 将多个子 navmesh “缝合” 在一起，那么修改子 navmesh 不会自动重建父级。编辑后请在 mark_for_rebuild() / rebuild_immediately() 父级上调用。

碰撞（当前 CSL 支持）

碰撞体作为组件存在（Box_Collider, Circle_Collider, Edge_Collider, Polygon_Collider），但碰撞进入/退出脚本回调 尚未在 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) {
                // 仅施加一次命中，开始冷却等。
            }
        }
    }
}