Index of every page on this site: llms.txt
All skills
gamedev-skills avatar

/godot-3d-essentials

@c6ca6c4
Run it yourself

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`).

Use this Skill: https://skilld.dev/gh/gamedev-skills/awesome-gamedev-agent-skills/godot-3d-essentials

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈106 tokens for metadata: the name and description. ≈1.9k when used: this file. ≈1.2k more on demand in 1 file.

Description uses 5.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈425 characters, or 5.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts8d3 checks · Risk SAFE
  • Gen Agent Trust Hub9d

    This skill is a security-conscious utility that provides diagnostic tools and configuration guidelines for Godot 4.7 3D scenes. It uses a headless GDScript to verify scene visibility and lighting without performing any network or privileged operations.

  • Socket8d

    No alerts

  • Snyk9d

    Risk: LOW · No issues

Signed by skilld at c6ca6c4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated last week

README badge

README badge for gamedev-skills/awesome-gamedev-agent-skills/godot-3d-essentials