导航网格与碰撞

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

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

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

• 将玩家/NPC锁定到可行走区域

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

组件（快速概览）

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

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

• 碰撞体: 盒状碰撞体, 圆形碰撞体, 边缘碰撞体, 多边形碰撞体

用于移动/路径寻找（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:

   • 添加点以定义环形形状

   • 切换 翻转内外侧 以使其成为孔/障碍，而不是可行走空间

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

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

碰撞体和导航网格环

碰撞体也可以通过碰撞体检视器选项贡献环（例如 “Make Navmesh Loop” / “Flip 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 := 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 支持）

碰撞体作为组件存在（盒状碰撞体, 圆形碰撞体, 边缘碰撞体, 多边形碰撞体），但碰撞进入/退出的脚本回调 尚未在 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) {
                // 应用一次命中，开始冷却等。
            }
        }
    }
}