gamedev-skills/awesome-gamedev-agent-skills / skills/godot/godot-3d-essentials
godot-3d-essentials
VerifiedGodot 4.7 3D scene setup: Camera3D, lights, WorldEnvironment (sky, ambient, tonemap, fog), StandardMaterial3D, GridMap and local vs global transforms, with a headless scene check. Use when a 3D scene renders black or washed out, a mesh is invisible, or a child rotates on the wrong axis. Not for spatial shaders (`godot-shaders`), bodies and raycasts (`godot-physics`) or camera feel (`camera-systems`).
Godot 3D Essentials (4.x)
Assemble a 3D scene that shows what it should in the running game: a current camera, real
lights, an environment, materials and GridMap blockouts. Targets Godot 4.7; read
config/features and rendering/renderer/rendering_method in project.godot first,
because Forward+, Mobile and Compatibility differ in what they draw.
Workflow
- Check the renderer (
rendering/renderer/rendering_method:forward_plus,mobileorgl_compatibility). Mobile and Compatibility (web, low-end) have no SDFGI, SSIL, screen-space reflections or volumetric fog, and Mobile also has no SSAO, so do not build the look on them for those targets. The reference has the renderer table. - One current
Camera3Dper viewport. Setcurrent = trueon the one you want. Godot's convention is -Z forward, +Y up. - Light the scene in the scene itself. The editor viewport's preview sun and preview
environment (toolbar toggles) do not exist at runtime. Add a
DirectionalLight3Dand aWorldEnvironmentto the main scene, or setrendering/environment/defaults/default_environment. - Configure the
Environment: background (sky or colour), ambient source, tonemapper, then post effects. Pick the tonemapper before tuning light energy or glow. - Materials:
StandardMaterial3DonMeshInstance3D.material_override(all surfaces) orset_surface_override_material(i, mat);ShaderMaterialfor custom looks. - Block out with
GridMapand aMeshLibrary. - Verify before you finish (paths are relative to this skill's folder):
- If
godot-nodes-scenesis installed, runpython3 ../godot-nodes-scenes/scripts/check_godot_project.py <project>and fix everyERROR. - Run
godot --headless --path <project> --script <this skill>/assets/check_3d_scene.gd -- res://level.tscn(no scene argument means the main scene). It needs no GPU and exits 1 when there is no current camera, nothing lights the meshes, a sky background has noSky, or a mesh is hidden by the camera'scull_mask, behind the camera or pastfar. - To see a frame without a GPU, render one in software with Movie Maker:
xvfb-run -a godot --path <project> --rendering-driver opengl3 --write-movie shots/f.png --quit-after 3 res://level.tscnwritesshots/f00000000.pngand up, which you can open and inspect. This draws with the Compatibility renderer, so judge Forward+ looks by asking the user for a screenshot.
- If
Patterns
1. Sun and environment from code
func _ready() -> void:
var sun := DirectionalLight3D.new()
sun.rotation_degrees = Vector3(-50, -30, 0) # pointing down: -X tilt
sun.shadow_enabled = true
add_child(sun)
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_AGX
var world_env := WorldEnvironment.new()
world_env.environment = env
add_child(world_env)
Only one WorldEnvironment applies per world: the first one keeps control and a later one
is ignored without a runtime message (the editor shows a node warning).
2. A material from code
func tint(mesh: MeshInstance3D, color: Color) -> void:
var mat := StandardMaterial3D.new()
mat.albedo_color = color
mat.roughness = 0.6
mesh.material_override = mat # wins over surface and mesh materials
3. Fill a GridMap from code
@onready var grid: GridMap = $GridMap # mesh_library and cell_size set on the node
func build_floor(width: int, depth: int, item_id: int) -> void:
for x in width:
for z in depth:
grid.set_cell_item(Vector3i(x, 0, z), item_id) # -1 clears a cell
Gotchas
- Fine in the editor, dark or flat in the game → the editor preview sun and environment
were doing the lighting. Put a light and a
WorldEnvironmentin the scene. - Meshes are black → nothing lights them. With no
Environment, Forward+ and Mobile still add flat ambient fromrendering/environment/defaults/default_clear_color, but Compatibility adds none, so the same scene is dim grey on desktop and black on web. AnEnvironmentwith ambientDisabledor a black colour background does the same. - Plain grey screen → no current camera, so you only see the clear colour; or the camera sits inside a mesh, whose back faces are culled.
- Wrong camera renders → a camera in an instanced sub-scene also has
current = true. Keepcurrenton one camera, or callmake_current()after the scene loads. - A mesh is missing → its
layersdo not overlap the camera'scull_mask, it is pastfar, or an imported mesh has flipped normals (trycull_mode = CULL_DISABLEDto test). look_at()errors and does nothing → the target equals the node's position, the up vector is parallel to the view direction (looking straight down withVector3.UP), or the node is not in the tree yet; uselook_at_from_position()beforeadd_child().- Local vs global mix-ups →
position/rotationare parent-relative;look_at()andglobal_positionare world space. - Non-uniform scale distorts collision and lights → scale the mesh resource or use uniform scale on bodies.
- Washed-out or blown highlights → the tonemapper is
Linear(no tonemapping) or glow thresholds are low; switch to AgX or Filmic and lowerglow_intensity. - GridMap places nothing → no
MeshLibraryassigned, or the item id is not in it.
References
- Read
references/scene-and-environment.mdfor Transform3D math, camera projection and picking, the light table (including AreaLight3D costs), every Environment option, material fields, building aMeshLibrary, and baked or real-time GI. assets/check_3d_scene.gdis the headless check used in step 7.
Related skills
camera-systems: orbit, follow and first-person camera feel.godot-physics: 3D bodies, CharacterBody3D, areas and raycasts.godot-shaders: spatial shaders.godot-animation: AnimationTree for 3D characters.performance-optimization: draw calls, lights, LOD and frame budget.fps-shooter: a full 3D game on top of these pieces.
Version notes
Last verified: 2026-11-11 against the Godot 4.7.2 class reference, renderer source and a 4.7.2 headless and Movie Maker run.
- Godot 4.7.2 (August 2026) is the current stable release; 4.8 is in beta.
AreaLight3Dand the dedicated MeshLibrary editor are new in 4.7.- The AgX tonemapper exists since 4.4.
- No-environment ambient: Forward+/Mobile fall back to the default clear colour
(
render_scene_data_rd.cpp); Compatibility has no fallback (rasterizer_scene_gles3.cpp). - Sources: Godot releases, Godot 4.7 release page, Environment and post-processing, render_scene_data_rd.cpp @ 4.7.2, rasterizer_scene_gles3.cpp @ 4.7.2.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |