在 Godot 中搭建 3D…

适用于 Godot 3D 关卡设计、模块化图块、CSG 原型转静态网格、遮挡剔除、LOD 以及运行时/流式 GridMap 构建。

适用场景

解决思路

1. 不要忘记烘焙 GridMap 导航：GridMap 不会自动生成导航网格；使用 EditorPlugin 或手动 NavigationRegion3D。
2. 不要把 CSG 用作最终游戏几何：CSG 只用于原型，最终应转换为静态网格以提升性能（编辑器中使用「Bake CSG Mesh」）。
3. 不要在放置 tile 后修改 GridMap 的 cell_size：修改 cell_size 不会更新已有 tile，会导致错位；应在开始时只设置一次。
4. 不要发布未验证碰撞的 MeshLibrary item：转换前调用 mesh_library.get_item_shapes(tile_index)（或检查源场景中的 StaticBody3D + CollisionShape3D）；空 shapes 会生成只有视觉的几何，玩家会掉下去。
5. 不要在 CSGCombiner 帧未稳定时烘焙 CSG：只在 await get_tree().process_frame 后提取网格（见 safe_csg_baking.gd）；在重算中途烘焙会得到空或陈旧的 ArrayMesh 数据。顺序：完成布尔编辑 → 等一帧 → 烘焙 → 删除 CSG → 添加碰撞。
6. 不要在游戏运行时动画 CSG 节点：在另一个 CSG 内移动 CSG 节点会强制 CPU 重算布尔几何，造成显著性能下降。
7. 不要在 GridMap 中放置通用逻辑节点：GridMap 只对网格、导航和碰撞高度优化；用代理 tile + 脚本处理 spawn/trigger。
8. 不要在 CSG 中使用非流形网格：自定义 CSGMesh3D 资产必须是流形的（封闭、无自相交）；非流形网格会破坏 CSG 算法。
9. 实现对应模式前必须读取合适脚本；不要在此加载 lighting/sky/fog 或深入 Environment 教程，应路由到 godot-3d-lighting。
10. collision_gen.gd：从网格自动生成碰撞形状；用于导入无碰撞模型或程序化几何。
11. gridmap_runtime_builder.gd：唯一流式/运行时 GridMap 入口；用于批量放置 tile、chunk 风格重建和自动导航烘焙。优先用它，而不是临时 WorldStreamer stub。
12. csg_bake_tool.gd：EditorScript，用于把 CSG 几何烘焙为带正确材质和碰撞的静态网格；在最终定稿关卡原型时使用。
13. safe_csg_baking.gd：安全 CSG 烘焙技术；提取烘焙网格前等待帧结束，避免空数据。
14. lod_manager.gd：基于相机距离的 LOD 切换；管理网格切换和可见性，用于大型户外场景。
15. occlusion_setup.gd：手动遮挡剔除的 OccluderInstance3D 配置；用于有很多房间的室内关卡。
16. grid_map_logic_manager.gd：代理 tile 模式；在 _ready 时用 spawn/trigger 场景替换不可见 MeshLibrary 标记，然后清除代理 cell。
17. world_streamer.gd：ResourceLoader.load_threaded_request 队列；后台加载完成后无卡顿实例化 chunk。
18. MeshLibrary 流程：源场景使用 MeshInstance3D + StaticBody3D/CollisionShape3D → Convert To MeshLibrary → 验证 get_item_shapes()。
19. GridMap 流程：设置 cell_size 一次，放置 cell，烘焙 NavigationRegion3D。运行时重建必须用 gridmap_runtime_builder.gd。
20. CSG 灰盒流程：用 CSGCombiner3D 原型 → 必须用 safe_csg_baking.gd / csg_bake_tool.gd → 删除实时 CSG。
21. 遮挡/LOD 流程：室内房间用 occlusion_setup.gd；距离切换用 lod_manager.gd。
22. Sky/fog/WorldEnvironment 超出本技能范围；使用对等 godot-3d-lighting（如果别处启用体积雾，只保留 DirectionalLight3D）。
23. GridMap 初始化：extends GridMap；在 _ready 中 mesh_library = load("res://tilesets/dungeon_library.tres")；cell_size = Vector3(2, 2, 2)；cell_size 只设置一次，且不要在有 tile 后设置。
24. GridMap Cell API：使用 set_cell_item(pos, index[, orientation])、get_cell_item、INVALID_CELL_ITEM、local_to_map / map_to_local。批处理/运行时放置和 nav bake 时加载 gridmap_runtime_builder.gd，不要粘贴自定义 chunk streamer。
25. GridMap 碰撞验证：调用 var shapes := mesh_library.get_item_shapes(tile_index)；如果 shapes.is_empty()，用 push_error 报错并修复 MeshLibrary 源场景。
26. CSG 烘焙顺序 1：在 CSGCombiner3D 下完成所有布尔编辑。
27. CSG 烘焙顺序 2：await get_tree().process_frame；原因是 CSG dirty flags 会晚一帧稳定。
28. CSG 烘焙顺序 3：通过上述脚本烘焙为 MeshInstance3D + 碰撞；从导出场景中移除 CSG。
29. CSG 烘焙顺序 4：绝不在运行时动画 CSG。
30. CSG 笔刷类型（Box/Cylinder/Sphere/Polygon）只是编辑器灰盒工具，不作为发布几何。
31. 流式决策：需要运行时 GridMap tiles / chunk 重建 + nav bake 时，必须用 gridmap_runtime_builder.gd。
32. 流式决策：需要大型开放世界场景流式加载时，转到 godot-genre-open-world。
33. 流式决策：不要重新引入临时 WorldStreamer 内联 stub 或不完整的 load-from-file TODO。
34. MultiMesh 空间分区：把密集道具分到区域性的 MultiMeshInstance3D 节点，使视锥/遮挡能剔除整个簇（单个 MultiMesh 的 AABB 会绘制全部）。
35. GridMap 逻辑代理：用不可见代理 tile ID 表示 spawn/trigger；在 _ready 中 get_used_cells_by_item，实例化逻辑场景，然后清除代理 cell；逻辑不要放在 GridMap 本身上。
36. 室内映射：城市规模假室内可用窗口平面上的 spatial shader；转到 godot-shaders-basics，不要在此粘贴完整 shader 配方。
37. 边界情况：没有碰撞时，get_item_shapes 为空 → 修复 MeshLibrary 源场景。
38. 边界情况：CSG z-fight 时，在烘焙前给减法笔刷设置极小偏移。
39. 按需查阅深层配方：GridMap/CSG bake walkthrough 看 gridmap-and-csg.md；chunk streaming/procgen rooms 看 streaming-and-procgen.md；proxy spawn tiles 看 grid_map_logic_manager.gd；threaded chunk load 看 world_streamer.gd。
40. 渐进式披露：只在研究具体 API 时打开官方文档链接；路由到对等技能时加载 Related Skills，不要预加载整个文档网络。

适用边界 · 注意事项

• 不适用于天空、雾、WorldEnvironment、照明和氛围制作；这些应走 godot-3d-lighting。
• 大型开放世界场景流式加载不应只靠本技能；应转到 godot-genre-open-world。
• 不要用 CSG 作为最终发布几何或运行时动画对象；CSG 只适合编辑器灰盒原型。