Godot 3D Essentials (4.x)
Assemble a working 3D scene: transforms, camera, lights, environment/post, materials, and
GridMap blockouts. Targets Godot 4.7.
When to use
- Use when starting or fixing a 3D scene: positioning a
Camera3D, adding lights, setting
up a WorldEnvironment (sky, ambient, tonemap, glow/SSAO), assigning materials, or
building levels with GridMap.
When not to use: writing spatial shaders → godot-shaders; 3D physics bodies and
raycasts → godot-physics; character animation blending → godot-animation; full FPS
template → the fps-shooter genre skill.
Core workflow
- Everything 3D is a
Node3D with a Transform3D (position, rotation basis, scale).
Move with global_position, rotate with rotate_y(angle) or look_at(target).
- Add a
Camera3D. Mark it current (or call make_current()); set fov, near,
far. Parent it to a rig/pivot for orbit or follow cameras.
- Light the scene. A
DirectionalLight3D is the sun; OmniLight3D/SpotLight3D are
local; AreaLight3D (4.7+) is a rectangular panel light that costs more than omni/spot.
Enable shadows per light. Without lights and ambient, surfaces render black.
- Add a
WorldEnvironment with an Environment resource: background (sky/color),
ambient light, tonemap, and post (glow, SSAO, fog, adjustments).
- Give meshes materials (
StandardMaterial3D or a ShaderMaterial) on
MeshInstance3D.
- Block out levels with
GridMap, which places MeshLibrary items on a 3D grid
(the 3D analog of a tilemap).
Patterns
1. A follow camera (third-person, smoothed)
extends Camera3D
@export var target: Node3D
@export var offset := Vector3(0, 4, 8)
@export var smooth := 6.0
func _physics_process(delta: float) -> void:
if target == null:
return
var desired := target.global_position + offset
global_position = global_position.lerp(desired, smooth * delta) # smooth follow
look_at(target.global_position, Vector3.UP) # face the target
2. Sun + environment in code
func _ready() -> void:
var sun := DirectionalLight3D.new()
sun.rotation_degrees = Vector3(-45, -30, 0)
sun.shadow_enabled = true
add_child(sun)
var we := WorldEnvironment.new()
var env := Environment.new()
env.background_mode = Environment.BG_SKY
env.sky = Sky.new()
env.sky.sky_material = ProceduralSkyMaterial.new()
env.ambient_light_source = Environment.AMBIENT_SOURCE_SKY
env.tonemap_mode = Environment.TONE_MAPPER_FILMIC
env.glow_enabled = true
we.environment = env
add_child(we)
3. Assign a StandardMaterial3D from code
func tint_mesh(mesh: MeshInstance3D, color: Color) -> void:
var mat := StandardMaterial3D.new()
mat.albedo_color = color
mat.metallic = 0.0
mat.roughness = 0.6
mat.emission_enabled = true
mat.emission = color * 0.3
mesh.material_override = mat # overrides the mesh's surface materials
4. Place tiles into a GridMap
@onready var grid: GridMap = $GridMap # cell_size + mesh_library set in the editor
func build_floor(width: int, depth: int, item_id: int) -> void:
for x in width:
for z in depth:
# set_cell_item(Vector3i cell, int item, orientation = 0)
grid.set_cell_item(Vector3i(x, 0, z), item_id)
Pitfalls
- Scene renders black → no lights and no ambient. Add a
DirectionalLight3D and/or a
WorldEnvironment with ambient/sky. New scenes have neither by default.
- No camera / wrong camera. If nothing shows, no
Camera3D is current. Set
current = true or make_current(); only one camera renders per viewport.
- Confusing local vs global transforms.
position/rotation are relative to the
parent; global_position/global_transform are world space. Mixing them under a rotated
parent gives surprising results. look_at uses global coordinates.
- Scaling physics/lights. Non-uniform
scale on a Node3D distorts child collisions
and lights; prefer scaling the mesh asset or using uniform scale.
look_at does nothing and prints an error → the target equals the node's position, the
up vector is parallel to the look direction (e.g. looking straight down with
Vector3.UP), or the node is not in the tree yet. Keep an offset, pass a different up, or
use look_at_from_position() before the node enters the tree.
- GridMap with no
MeshLibrary places nothing. Create a MeshLibrary (from scenes)
and assign it; set_cell_item(cell, -1) clears a cell.
- HDR/glow too strong → check
tonemap_mode and glow thresholds; raw emissive values
bloom hard under filmic tonemapping.
References
- For Transform3D math, camera projection modes, light/shadow params, the full
Environment/post-processing options,
MeshLibrary creation, and ReflectionProbe/
LightmapGI lighting, read references/scene-and-environment.md.
Related skills
godot-physics — 3D bodies, areas, and raycasts.
godot-shaders — spatial shaders for custom 3D surfaces.
godot-animation — AnimationTree for 3D characters.
camera-systems — third-person orbit / first-person look rigs, framing, and collision.
performance-optimization — keep 3D scenes within frame budget (draw calls, lights, LOD).
fps-shooter — composes 3D movement, input, and AI into a game.
1---2name: godot-3d-essentials3description: >4 Set up a Godot 4.7 3D scene: Node3D transforms, Camera3D, lighting5 (DirectionalLight3D/OmniLight3D), WorldEnvironment for sky/ambient/tonemap/post,6 MeshInstance3D materials, and GridMap for tile-based 3D levels. Use when building7 a 3D scene in a Godot project, placing cameras/lights, configuring environment and8 post-processing, or working with Node3D/.tscn 3D content and GridMap.9metadata:10 source: https://skillmd.com/skills/junmystery/godot-3d-essentials11---1213# Godot 3D Essentials (4.x)1415Assemble a working 3D scene: transforms, camera, lights, environment/post, materials, and16`GridMap` blockouts. Targets **Godot 4.7**.1718## When to use1920- Use when starting or fixing a 3D scene: positioning a `Camera3D`, adding lights, setting21 up a `WorldEnvironment` (sky, ambient, tonemap, glow/SSAO), assigning materials, or22 building levels with `GridMap`.2324**When *not* to use:** writing spatial shaders → `godot-shaders`; 3D physics bodies and25raycasts → `godot-physics`; character animation blending → `godot-animation`; full FPS26template → the `fps-shooter` genre skill.2728## Core workflow29301. **Everything 3D is a `Node3D`** with a `Transform3D` (position, rotation basis, scale).31 Move with `global_position`, rotate with `rotate_y(angle)` or `look_at(target)`.322. **Add a `Camera3D`.** Mark it `current` (or call `make_current()`); set `fov`, `near`,33 `far`. Parent it to a rig/pivot for orbit or follow cameras.343. **Light the scene.** A `DirectionalLight3D` is the sun; `OmniLight3D`/`SpotLight3D` are35 local; `AreaLight3D` (4.7+) is a rectangular panel light that costs more than omni/spot.36 Enable shadows per light. Without lights and ambient, surfaces render black.374. **Add a `WorldEnvironment`** with an `Environment` resource: background (sky/color),38 ambient light, tonemap, and post (glow, SSAO, fog, adjustments).395. **Give meshes materials** (`StandardMaterial3D` or a `ShaderMaterial`) on40 `MeshInstance3D`.416. **Block out levels with `GridMap`**, which places `MeshLibrary` items on a 3D grid42 (the 3D analog of a tilemap).4344## Patterns4546### 1. A follow camera (third-person, smoothed)4748```gdscript49extends Camera3D5051@export var target: Node3D52@export var offset := Vector3(0, 4, 8)53@export var smooth := 6.05455func _physics_process(delta: float) -> void:56 if target == null:57 return58 var desired := target.global_position + offset59 global_position = global_position.lerp(desired, smooth * delta) # smooth follow60 look_at(target.global_position, Vector3.UP) # face the target61```6263### 2. Sun + environment in code6465```gdscript66func _ready() -> void:67 var sun := DirectionalLight3D.new()68 sun.rotation_degrees = Vector3(-45, -30, 0)69 sun.shadow_enabled = true70 add_child(sun)7172 var we := WorldEnvironment.new()73 var env := Environment.new()74 env.background_mode = Environment.BG_SKY75 env.sky = Sky.new()76 env.sky.sky_material = ProceduralSkyMaterial.new()77 env.ambient_light_source = Environment.AMBIENT_SOURCE_SKY78 env.tonemap_mode = Environment.TONE_MAPPER_FILMIC79 env.glow_enabled = true80 we.environment = env81 add_child(we)82```8384### 3. Assign a StandardMaterial3D from code8586```gdscript87func tint_mesh(mesh: MeshInstance3D, color: Color) -> void:88 var mat := StandardMaterial3D.new()89 mat.albedo_color = color90 mat.metallic = 0.091 mat.roughness = 0.692 mat.emission_enabled = true93 mat.emission = color * 0.394 mesh.material_override = mat # overrides the mesh's surface materials95```9697### 4. Place tiles into a GridMap9899```gdscript100@onready var grid: GridMap = $GridMap # cell_size + mesh_library set in the editor101102func build_floor(width: int, depth: int, item_id: int) -> void:103 for x in width:104 for z in depth:105 # set_cell_item(Vector3i cell, int item, orientation = 0)106 grid.set_cell_item(Vector3i(x, 0, z), item_id)107```108109## Pitfalls110111- **Scene renders black** → no lights and no ambient. Add a `DirectionalLight3D` and/or a112 `WorldEnvironment` with ambient/sky. New scenes have neither by default.113- **No camera / wrong camera.** If nothing shows, no `Camera3D` is `current`. Set114 `current = true` or `make_current()`; only one camera renders per viewport.115- **Confusing local vs global transforms.** `position`/`rotation` are relative to the116 parent; `global_position`/`global_transform` are world space. Mixing them under a rotated117 parent gives surprising results. `look_at` uses global coordinates.118- **Scaling physics/lights.** Non-uniform `scale` on a `Node3D` distorts child collisions119 and lights; prefer scaling the mesh asset or using uniform scale.120- **`look_at` does nothing and prints an error** → the target equals the node's position, the121 `up` vector is parallel to the look direction (e.g. looking straight down with122 `Vector3.UP`), or the node is not in the tree yet. Keep an offset, pass a different `up`, or123 use `look_at_from_position()` before the node enters the tree.124- **GridMap with no `MeshLibrary`** places nothing. Create a `MeshLibrary` (from scenes)125 and assign it; `set_cell_item(cell, -1)` clears a cell.126- **HDR/glow too strong** → check `tonemap_mode` and glow thresholds; raw emissive values127 bloom hard under filmic tonemapping.128129## References130131- For Transform3D math, camera projection modes, light/shadow params, the full132 Environment/post-processing options, `MeshLibrary` creation, and `ReflectionProbe`/133 `LightmapGI` lighting, read `references/scene-and-environment.md`.134135## Related skills136137- `godot-physics` — 3D bodies, areas, and raycasts.138- `godot-shaders` — spatial shaders for custom 3D surfaces.139- `godot-animation` — `AnimationTree` for 3D characters.140- `camera-systems` — third-person orbit / first-person look rigs, framing, and collision.141- `performance-optimization` — keep 3D scenes within frame budget (draw calls, lights, LOD).142- `fps-shooter` — composes 3D movement, input, and AI into a game.