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`).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.8 KB |
| assets/check_3d_scene.gd | other | 4.5 KB |
| references/scene-and-environment.md | markdown | 4.8 KB |
assets/check_3d_scene.gd
View on GitHub# Headless check for the usual reasons a Godot 4.7 3D scene shows black or nothing.
# Needs no GPU, so it cannot judge colours: it checks the camera, lights, ambient light
# and mesh placement that decide whether anything can be seen at all.
#
# Run from the project folder (the scene after "--" defaults to the main scene):
# godot --headless --path . --script /abs/path/to/check_3d_scene.gd -- res://level.tscn
# Exit code 0 means no problems and 1 means problems were found (listed on stderr).
extends SceneTree
const DEFAULT_ENV_SETTING := "rendering/environment/defaults/default_environment"
func _initialize() -> void:
var args := OS.get_cmdline_user_args()
var path: String = args[0] if args.size() > 0 else ProjectSettings.get_setting(
"application/run/main_scene", "")
var packed := load(path) as PackedScene if path != "" else null
if packed == null:
push_error("cannot load scene '%s'; pass one after --" % path)
quit(1)
return
await process_frame # root is not inside the tree until the first frame
var scene := packed.instantiate()
root.add_child(scene)
await process_frame # let a Camera3D with current = false claim the viewport
var problems := PackedStringArray()
var cam := root.get_camera_3d()
if cam == null:
problems.append("no current Camera3D: add one, or set current = true on the one you want")
var lights := scene.find_children("*", "Light3D", true, false).filter(
func(l: Light3D) -> bool: return l.is_visible_in_tree() and l.light_energy > 0.0)
var env: Environment = null
var envs := scene.find_children("*", "WorldEnvironment", true, false)
if not envs.is_empty():
env = (envs[0] as WorldEnvironment).environment
if env == null and cam != null:
env = cam.environment
var default_env: String = ProjectSettings.get_setting(DEFAULT_ENV_SETTING, "")
if env == null and default_env != "":
env = load(default_env) as Environment
var has_ambient := ambient_present(env)
if lights.is_empty() and not has_ambient:
problems.append("nothing lights the meshes (no visible light, no ambient), so they render"
+ " black; the editor's preview sun and sky do not exist in the running game")
elif lights.is_empty():
print("note: no visible light; meshes get only flat ambient light")
if env != null and env.background_mode == Environment.BG_SKY and env.sky == null:
problems.append("Environment background is Sky but no Sky resource is set")
if cam != null:
for node in scene.find_children("*", "MeshInstance3D", true, false):
var mesh := node as MeshInstance3D
if not mesh.is_visible_in_tree():
continue
if mesh.mesh == null:
problems.append("%s has no mesh" % scene.get_path_to(mesh))
continue
var centre := mesh.global_transform * mesh.get_aabb().get_center()
if mesh.layers & cam.cull_mask == 0:
problems.append("%s is on visual layers the camera's cull_mask hides"
% scene.get_path_to(mesh))
elif cam.is_position_behind(centre):
problems.append("%s is behind the camera" % scene.get_path_to(mesh))
elif cam.global_position.distance_to(centre) > cam.far:
problems.append("%s is beyond the camera's far plane" % scene.get_path_to(mesh))
for problem in problems:
push_error(problem)
print("3D scene problems: %d (current camera: %s, visible lights: %d, ambient: %s)" % [
problems.size(), scene.get_path_to(cam) if cam else "none", lights.size(), has_ambient])
quit(1 if problems.size() > 0 else 0)
# Mirrors the 4.7 renderers: with no Environment, Forward+ and Mobile use the default clear
# colour as ambient light, and the Compatibility renderer adds none.
func ambient_present(env: Environment) -> bool:
var clear: Color = ProjectSettings.get_setting(
"rendering/environment/defaults/default_clear_color", Color(0.3, 0.3, 0.3))
if env == null:
var method: String = ProjectSettings.get_setting("rendering/renderer/rendering_method", "")
return method != "gl_compatibility" and clear.get_luminance() > 0.0
if env.ambient_light_source == Environment.AMBIENT_SOURCE_DISABLED:
return false
if env.ambient_light_source == Environment.AMBIENT_SOURCE_COLOR:
return env.ambient_light_color.get_luminance() * env.ambient_light_energy > 0.0
if env.ambient_light_source == Environment.AMBIENT_SOURCE_SKY:
return env.sky != null
match env.background_mode: # AMBIENT_SOURCE_BG: ambient follows the background
Environment.BG_CLEAR_COLOR:
return clear.get_luminance() > 0.0
Environment.BG_COLOR:
return env.background_color.get_luminance() > 0.0
Environment.BG_SKY:
return env.sky != null
return true # canvas, keep or camera-feed backgrounds: not judged here
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: 196k | 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: 196k | 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: 196k | Updated | Claude CodeCodex | Verified | Install |