SKILL.md
3D World Building
Expert guidance for level design with GridMaps, CSG bake, and occlusion — not lighting/atmosphere authorship.
NEVER Do
- NEVER forget to bake GridMap navigation — GridMaps don't auto-generate navigation meshes. Use EditorPlugin or manual NavigationRegion3D.
- NEVER use CSG for final game geometry — CSG is for prototyping. Convert to static meshes for performance (use "Bake CSG Mesh" in editor).
- NEVER scale GridMap cell size after placing tiles — Changing
cell_sizedoesn't update existing tiles, causing misalignment. Set it once at the start. - NEVER ship a MeshLibrary item without verifying collision — Call
mesh_library.get_item_shapes(tile_index)(or inspect the source scene StaticBody3D + CollisionShape3D) before convert; empty shapes spawn visual-only geometry players fall through. - NEVER bake CSG before the combiner has a settled frame — Extract meshes only after
await get_tree().process_frame(see safe_csg_baking.gd); baking mid-recompute yields empty or stale ArrayMesh data. Order: finish boolean edits → wait one frame → bake → delete CSG → add collision. - NEVER animate CSG nodes during gameplay — Moving a CSG node within another forces the CPU to recalculate the boolean geometry, causing significant performance drops.
- NEVER place generic logic nodes in a GridMap — GridMap is highly optimized only for meshes, navigation, and collision. Use proxy tiles + scripts for spawns/triggers.
- NEVER use non-manifold meshes in CSG — Custom CSGMesh3D assets must be manifold (closed, no self-intersections). Non-manifold meshes break the CSG algorithm.