godot-3d-world-building

3D 世界构建

关于使用 GridMap、烘焙 CSG 和遮挡进行关卡设计的专家指导，不涉及灯光／氛围创作。

绝对不要做

• 绝对不要忘记烘焙 GridMap 导航——GridMap 不会自动生成导航网格。使用 EditorPlugin 或手动创建 NavigationRegion3D。
• 绝对不要将 CSG 用于最终游戏几何体——CSG 用于原型制作。为提升性能，应将其转换为静态网格（在编辑器中使用 “Bake CSG Mesh”）。
• 绝对不要在放置图块后缩放 GridMap 单元格大小——更改 cell_size 不会更新已有图块，导致错位。请在开始时设置一次。
• 绝对不要在未验证碰撞的情况下发布 MeshLibrary 项目——转换前，调用 mesh_library.get_item_shapes(tile_index)（或检查源场景中的 StaticBody3D + CollisionShape3D）；如果形状列表为空，生成的几何体就只有视觉效果，玩家会直接穿过。
• 绝对不要在组合器完成当前帧计算前烘焙 CSG——仅在 await get_tree().process_frame 之后提取网格（参见 safe_csg_baking.gd）；在重新计算过程中烘焙会得到空的或过时的 ArrayMesh 数据。顺序：完成布尔编辑 → 等待一帧 → 烘焙 → 删除 CSG → 添加碰撞。
• 绝对不要在游戏过程中为 CSG 节点添加动画——在另一个 CSG 节点内移动 CSG 节点会迫使 CPU 重新计算布尔几何体，导致性能显著下降。
• 绝对不要在 GridMap 中放置通用逻辑节点——GridMap 仅针对网格、导航和碰撞进行了高度优化。应使用代理图块 + 脚本来处理生成／触发器。
• 绝对不要在 CSG 中使用非流形网格——自定义 CSGMesh3D 资源必须是流形的（封闭且无自相交）。非流形网格会破坏 CSG 算法。

---

可用脚本

必须遵守：实现对应模式前，请先阅读相应脚本。 不要加载灯光／天空／雾效脚本或深入讲解 Environment 的教程——请转至 godot-3d-lighting。

collision_gen.gd

从网格自动生成碰撞形状。适用于导入没有碰撞的模型或程序化几何体。

gridmap_runtime_builder.gd

流式加载／运行时 GridMap 的唯一入口——批量放置图块、以区块方式重建并自动烘焙导航。请优先使用此脚本，而不是临时编写的 WorldStreamer 桩代码。

csg_bake_tool.gd

用于将 CSG 几何体烘焙为包含适当材质和碰撞的静态网格的 EditorScript。用于完成关卡原型。

safe_csg_baking.gd

安全烘焙 CSG 的专家技巧。在提取烘焙后的网格前等待当前帧结束，以避免数据为空。

lod_manager.gd

根据摄像机距离切换细节层级。管理大型户外场景的网格替换和可见性。

occlusion_setup.gd

用于手动遮挡剔除的 OccluderInstance3D 配置。适用于房间众多的室内关卡。

grid_map_logic_manager.gd

代理图块模式：在 _ready 时，将不可见的 MeshLibrary 标记替换为生成／触发场景，然后清除代理单元格。

world_streamer.gd

ResourceLoader.load_threaded_request 队列——后台加载完成后无卡顿地实例化区块。

Golden Path（GridMap / CSG / 遮挡）

1. MeshLibrary — 源场景：MeshInstance3D + StaticBody3D/CollisionShape3D → 转换为 MeshLibrary → 验证 get_item_shapes()。
2. GridMap — 只设置一次 cell_size，放置单元格，烘焙 NavigationRegion3D。运行时重建：必须使用 gridmap_runtime_builder.gd。
3. CSG 灰盒 — 使用 CSGCombiner3D 制作原型 → 必须使用 safe_csg_baking.gd / csg_bake_tool.gd → 删除实时 CSG。
4. 遮挡 / LOD — 室内房间：occlusion_setup.gd。距离切换：lod_manager.gd。
5. 天空 / 雾 / WorldEnvironment — 不在此范围内；请使用同领域的 godot-3d-lighting（如果其他位置启用了体积雾，则仅保留一个 DirectionalLight3D）。

---

GridMap 基础知识

设置（精简）

extends GridMap

func _ready() -> void:
    mesh_library = load("res://tilesets/dungeon_library.tres")
    cell_size = Vector3(2, 2, 2)  # Set once; never after tiles exist

单元格 API：set_cell_item(pos, index[, orientation])、get_cell_item、INVALID_CELL_ITEM、local_to_map / map_to_local。对于批量 / 运行时放置和导航烘焙，请加载 gridmap_runtime_builder.gd — 不要粘贴自定义区块流送器。

碰撞验证

var shapes := mesh_library.get_item_shapes(tile_index)
if shapes.is_empty():
    push_error("Tile %d has no collision — fix MeshLibrary source scene" % tile_index)

---

CSG 烘焙顺序

1. 在 CSGCombiner3D 下完成布尔编辑。
2. await get_tree().process_frame（原因：CSG 脏标记会晚一帧稳定）。
3. 使用上述脚本烘焙为 MeshInstance3D + 碰撞体；从导出的场景中移除 CSG。
4. 绝不要在运行时为 CSG 制作动画。

画刷类型（Box/Cylinder/Sphere/Polygon）仅用于编辑器中的灰盒制作 — 不可用于最终几何体。

---

流送方案选择

需求	操作
运行时 GridMap 瓦片 / 区块重建 + 导航烘焙	必须使用 gridmap_runtime_builder.gd
大型开放世界场景流送	同领域的 godot-genre-open-world
临时内联 WorldStreamer 占位实现	删除 — 不要重新引入不完整的从文件加载 TODO

---

专家技巧

对 MultiMesh 进行空间分区

将密集道具划分到区域性的 MultiMeshInstance3D 节点中，以便视锥体 / 遮挡剔除可移除整个簇（单个 MultiMesh AABB 会绘制所有内容）。

GridMap 逻辑代理

使用不可见的代理瓦片 ID 表示生成点 / 触发器；在 _ready 中调用 get_used_cells_by_item，实例化逻辑场景，然后清除代理单元格。不要将逻辑直接放在 GridMap 上。

内部映射

对于城市规模的假内部场景，在窗户平面上使用空间着色器 — 同领域的 godot-shaders-basics。不要在此处粘贴完整的着色器方案。

边缘情况

• 无碰撞：get_item_shapes 为空 → 修复 MeshLibrary 源。
• CSG 深度冲突：烘焙前，在减法画刷上添加微小偏移。

深入方案（按需查看）

主题	参考资料 / 脚本
GridMap / CSG 烘焙演练	gridmap-and-csg.md
区块流送 / 程序化生成房间	streaming-and-procgen.md
代理生成瓦片	grid_map_logic_manager.gd
线程化区块加载	world_streamer.gd

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接；在路由到同领域技能时加载相关技能 — 不要预加载整个技能网络。

官方文档

• 使用 GridMaps — MeshLibrary 工作流、单元格放置，以及 GridMap 适合用作模块化关卡工具的情形。
• MeshLibrary — GridMap 在运行时实例化的项目网格、名称和碰撞形状。
• CSG 工具 — 使用 CSGCombiner3D/基本体进行布尔原型设计，以及烘焙为网格的衔接流程。
• 环境与后期处理 — WorldEnvironment、Sky、ProceduralSkyMaterial/PanoramaSkyMaterial 和雾效模式。
• 体积雾与雾效体积 — 散射设置、密度/反照率，以及可见体积雾为何需要灯光。
• 遮挡剔除 — 室内房间中 OccluderInstance3D 的放置方式及 CPU 开销权衡。
• 网格细节层次（LOD） — 导入器自动生成 LOD 与大型室外关卡手动切换网格的比较。
• 可见性范围 — LOD 管理器使用的 GeometryInstance3D 距离淡入淡出/滞回。
• 碰撞形状（3D） — MeshLibrary 项目和烘焙后的 CSG 的凸体/三角网格/基本体选择。
• 导航简介（3D） — 烘焙 NavigationRegion3D；GridMap 不会自动生成导航区域。
• 后台加载 — 使用 ResourceLoader 进行线程化区块流式加载，避免卡顿峰值。
• 使用 MultiMesh — 密集道具的实例化，以及空间分区的 MultiMesh 如何恢复剔除效果。

相关技能

前置要求

• godot-project-foundations — 在转换为 MeshLibrary 和设置 WorldEnvironment 之前，先掌握场景树、资源和导入基础。
• godot-physics-3d — StaticBody3D/CollisionShape3D 模式必须放入 MeshLibrary 源场景，否则玩家会穿过地块。
• godot-gdscript-mastery — 烘焙和运行时构建器中使用的类型化 GridMap/CSG 脚本、信号，以及 await/process_frame 模式。

补充

• godot-3d-lighting — DirectionalLight3D 和体积雾散射的 GI；将环境与实际灯光设置配合使用。
• godot-3d-materials — 在灰盒阶段之后，为瓦片和烘焙后的 CSG 网格使用 StandardMaterial3D/ORM。
• godot-navigation-pathfinding — 在单元格编辑后，从 GridMap 几何体烘焙并更新 NavigationMesh。
• godot-shaders-basics — 使用 interior-mapping 等空间技巧，在城市规模场景中伪造建筑内部。
• godot-camera-systems — 摄像机距离决定可见范围、LOD 切换和区块加载半径。
• godot-scene-management — 通过场景打包和多线程加载队列，实现无卡顿的世界流式加载。
• godot-performance-optimization — 大型关卡的绘制调用预算、遮挡策略和 MultiMesh 分区。

下游 / 使用方

• godot-procedural-generation — 将单元格写入 GridMap、以此作为放置后端的地牢 / 地形生成器。
• godot-genre-open-world — 基于这些世界构建基础功能实现区块流式加载、浮动原点和 HLOD。
• godot-genre-sandbox — 可复用 GridMap/CSG 烘焙流程的玩家驱动建造和可编辑体素 / 网格世界。

主模块

• godot-master — 用于跨技能发现的库路由器和镜像模块入口。