godot-3d-world-building

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 0c0182b848c3 · 22 Oct 2026Report an issue or request a re-scan

• Publisherthedivergentai GitHub userOwner of the repository this skill is read from
• Source folderthedivergentai/gd-agentic-skills/skills/godot-3d-world-buildingThe exact folder we audited
• LicenceLGPL-3.0As the repository states it
• Commit pinned for this verdict0c0182b848c3A new audit runs when the source changes
• Repository statusNot archivedLast push 5 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Expert patterns for 3D level design using GridMap with MeshLibrary, CSG constructive solid geometry, occlusion, and runtime GridMap builders. Use when building 3D levels, modular tilesets, or BSP-style geometry. For…

---
name: godot-3d-world-building
description: "Expert patterns for 3D level design using GridMap with MeshLibrary, CSG constructive solid geometry, occlusion, and runtime GridMap builders. Use when building 3D levels, modular tilesets, or BSP-style geometry. For sky/fog/Environment recipes, route to godot-3d-lighting. Trigger keywords: GridMap, MeshLibrary, set_cell_item, get_cell_item, map_to_local, local_to_map, CSGCombiner3D, CSGBox3D, CSGSphere3D, CSGPolygon3D, OccluderInstance3D, bake CSG."
---

# 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](scripts/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](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-3d-lighting/SKILL.md).

### [collision_gen.gd](scripts/collision_gen.gd)
Automatic collision shape generation from meshes. Use when importing models without collision or for procedural geometry.

### [gridmap_runtime_builder.gd](scripts/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](scripts/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](scripts/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](scripts/lod_manager.gd)
Level-of-detail switching based on camera distance. Manages mesh swapping and visibility for large outdoor scenes.

### [occlusion_setup.gd](scripts/occlusion_setup.gd)
OccluderInstance3D configuration for manual occlusion culling. Use for indoor levels with many rooms.

### [grid_map_logic_manager.gd](scripts/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](scripts/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](scripts/gridmap_runtime_builder.gd).
3. **CSG greybox** — Prototype with CSGCombiner3D → **MANDATORY** [safe_csg_baking.gd](scripts/safe_csg_baking.gd) / [csg_bake_tool.gd](scripts/csg_bake_tool.gd) → delete live CSG.
4. **Occlusion / LOD** — Indoor rooms: [occlusion_setup.gd](scripts/occlusion_setup.gd). Distance swaps: [lod_manager.gd](scripts/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)

```gdscript
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](scripts/gridmap_runtime_builder.gd) — do not paste a custom chunk streamer.

### Collision verification

```gdscript
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

| Need | Action |
|------|--------|
| Runtime GridMap tiles / chunk rebuild + nav bake

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/thedivergentai/gd-agentic-skills
git -C gd-agentic-skills checkout 0c0182b848c3

Works in

1. 2026-10-22
   ✓SAFE B 89 / 100

   first audit · source 0c0182b848c3

Questions about godot-3d-world-building

• github.com/thedivergentai/gd-agentic-skills/tree/main/skills/god — the audited source at commit 0c0182b848c3 and every finding aboveObserved · 22 Oct 2026

Spotted something wrong? Report a correction · Methodology