Skip to content

gamedev-skills/awesome-gamedev-agent-skills / skills/godot/godot-3d-essentials

godot-3d-essentials

Verified

Godot 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

  1. 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.
  2. One current Camera3D per viewport. Set current = true on the one you want. Godot's convention is -Z forward, +Y up.
  3. 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.
  4. Configure the Environment: background (sky or colour), ambient source, tonemapper, then post effects. Pick the tonemapper before tuning light energy or glow.
  5. Materials: StandardMaterial3D on MeshInstance3D.material_override (all surfaces) or set_surface_override_material(i, mat); ShaderMaterial for custom looks.
  6. Block out with GridMap and a MeshLibrary.
  7. Verify before you finish (paths are relative to this skill's folder):
    • If godot-nodes-scenes is installed, run python3 ../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 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 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 layers do not overlap the camera's cull_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/rotation are 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 MeshLibrary assigned, or the item id is not in it.

References

  • Read references/scene-and-environment.md for 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.gd is 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.

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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall