How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill godot-3d-essentialsBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
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,mobile
or gl_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 `Camera3D` per viewport. Set
current = 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 DirectionalLight3D and a WorldEnvironment to the main scene, or set rendering/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)
or set_surface_override_material(i, mat); ShaderMaterial for custom looks.
- Block out with `GridMap` and a
MeshLibrary. - 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 every ERROR.
- 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 no Sky, or a mesh is hidden by the camera's cull_mask, behind the camera or past far.
- 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.tscn writes shots/f00000000.png and up, which you can open and inspect. This draws with the Compatibility renderer, so judge Forward+ looks by asking the user for a screenshot.
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 materials3. 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 cellGotchas
- 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 WorldEnvironment in the scene.
- Meshes are black → nothing lights them. With no
Environment, Forward+ and Mobile still
add flat ambient from rendering/environment/defaults/default_clear_color, but Compatibility adds none, so the same scene is dim grey on desktop and black on web. An Environment with ambient Disabled or 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.
Keep current on one camera, or call make_current() after the scene loads.
- A mesh is missing → its
layersdo not overlap the camera'scull_mask, it is past
far, or an imported mesh has flipped normals (try cull_mode = CULL_DISABLED to 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 with Vector3.UP), or the node is not in the tree yet; use look_at_from_position() before add_child().
- Local vs global mix-ups →
position/rotationare parent-relative;look_at()and
global_position are 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 lower glow_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 a MeshLibrary, 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.