Godot 3D World Building

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_size doesn'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.

Available Scripts

MANDATORY: Read the appropriate script before implementing the corresponding pattern. Do NOT Load lighting/sky/fog scripts or deep Environment tutorials here — route to godot-3d-lighting.

collision_gen.gd

Automatic collision shape generation from meshes. Use when importing models without collision or for procedural geometry.

gridmap_runtime_builder.gd

Sole streaming / runtime GridMap entry — batch tile placement, chunk-style rebuilds, and auto-navigation baking. Prefer this over ad-hoc WorldStreamer stubs.

csg_bake_tool.gd

EditorScript to bake CSG geometry to static meshes with proper materials and collision. Use when finalizing level prototypes.

safe_csg_baking.gd

Expert technique for safe CSG baking. Awaits the end of the frame before extracting baked meshes to avoid empty data.

lod_manager.gd

Level-of-detail switching based on camera distance. Manages mesh swapping and visibility for large outdoor scenes.

occlusion_setup.gd

OccluderInstance3D configuration for manual occlusion culling. Use for indoor levels with many rooms.

grid_map_logic_manager.gd

Proxy-tile pattern: replace invisible MeshLibrary markers with spawn/trigger scenes at _ready, then clear proxy cells.

world_streamer.gd

ResourceLoader.load_threaded_request queue — stutter-free chunk instantiation after background load completes.

Golden Path (GridMap / CSG / Occlusion)

1. MeshLibrary — Source scene: MeshInstance3D + StaticBody3D/CollisionShape3D → Convert To MeshLibrary → verify get_item_shapes().
2. GridMap — Set cell_size once, place cells, bake NavigationRegion3D. Runtime rebuilds: MANDATORY gridmap_runtime_builder.gd.
3. CSG greybox — Prototype with CSGCombiner3D → MANDATORY safe_csg_baking.gd / csg_bake_tool.gd → delete live CSG.
4. Occlusion / LOD — Indoor rooms: occlusion_setup.gd. Distance swaps: lod_manager.gd.
5. Sky / fog / WorldEnvironment — Out of scope; use peer godot-3d-lighting (keep only a DirectionalLight3D present if volumetric fog is enabled elsewhere).

GridMap Fundamentals

Setup (compact)

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

Cell API: set_cell_item(pos, index[, orientation]), get_cell_item, INVALID_CELL_ITEM, local_to_map / map_to_local. For batch/runtime placement and nav bake, load gridmap_runtime_builder.gd — do not paste a custom chunk streamer.

Collision verification

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 Bake Order

1. Finish boolean edits under CSGCombiner3D.
2. await get_tree().process_frame (WHY: CSG dirty flags settle one frame late).
3. Bake to MeshInstance3D + collision via scripts above; remove CSG from exported scenes.
4. Never animate CSG at runtime.

Brush types (Box/Cylinder/Sphere/Polygon) are editor greybox tools only — not shipping geometry.

Streaming Decision

Expert Techniques

Spatially Partitioning MultiMeshes

Partition dense props into regional MultiMeshInstance3D nodes so frustum/occlusion can cull whole clusters (single MultiMesh AABB draws everything).

GridMap Logic Proxies

Use invisible proxy tile IDs for spawns/triggers; at _ready, get_used_cells_by_item, instantiate logic scenes, clear proxy cells. Keep logic off the GridMap itself.