Verwendung
- Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
- Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
- Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill godot-3d-essentialsVor dem Start
- Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
- Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.
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.