Godot 3D Essentials

3D Essentials in Godot 4.3+

All examples target Godot 4.3+ with no deprecated APIs. GDScript is shown first, then C#.

Related skills: player-controller for CharacterBody3D movement, physics-system for 3D collision shapes and raycasting, camera-system for Camera3D follow and transitions, shader-basics for spatial shaders and post-processing, godot-optimization for 3D performance tuning, animation-system for AnimationTree and 3D animation blending.

1. 3D Coordinate System & Core Nodes

Coordinate System

Godot uses a right-handed coordinate system with metric units (1 unit = 1 meter):

Cameras and lights point along -Z by default. When a character "faces forward," they look along -Z.

Essential 3D Nodes

Godot 4.7+: GridMap exposes its internal octants for spatial queries (cell_octant_size, get_used_octants(), get_octants_in_bounds() and friends) so you can scope work to a region instead of walking every cell. CSGShape3D gains autosmooth / smoothing_angle for automatic face smoothing. Full method table and semantics: references/godot-4.7-additions.md

Minimal 3D Scene

World (Node3D)
├── Camera3D
├── DirectionalLight3D
├── WorldEnvironment
├── MeshInstance3D (floor)
└── MeshInstance3D (player model)

2. Materials

StandardMaterial3D vs ShaderMaterial

Key StandardMaterial3D Properties

The PBR core: albedo_color / albedo_texture (base color), metallic (0 dielectric → 1 metal), roughness (0 mirror → 1 matte), normal_map (surface detail), ao_texture (ambient occlusion). Add emission + emission_energy_multiplier for self-illumination, heightmap_texture for parallax, rim / clearcoat for material flair.

Transparency Modes

Prefer Alpha Scissor (fast, shadowed cutouts) or Alpha Hash (dithered — hair) over plain Alpha (slow, no shadows); Depth Pre-Pass suits mostly-opaque meshes with transparent edges.

See references/materials-and-lighting-recipes.md for the comparison table.

Setting Materials from Code & Material Instancing

Create a StandardMaterial3D at runtime, assign to mesh.material_override, and drive emissive flashes via Tween. Use .duplicate() to make per-instance copies so changing one mesh's material doesn't affect others.

See references/materials-and-lighting-recipes.md for the full GDScript and C# recipes (basic material setup, emissive flash, per-instance duplicate, dynamic OmniLight3D explosion).

3. Lighting

Light Types Comparison

*Forward+ shares 512 clustered element slots among omni lights, spot lights, decals, and reflection probes.

Light Properties

Key knobs: light_color, light_energy (HDR — values >1 are valid), shadow_enabled (big perf hit), directional_shadow_mode, directional_shadow_max_distance (lower = sharper shadows).

See references/materials-and-lighting-recipes.md for the properties table and the GDScript + C# sun setup snippet.

AreaLight3D (Godot 4.7+)

AreaLight3D emits light from a rectangle along the node's -Z — neon tubes, screens, softbox panels — with PCSS soft shadows driven by light_size. Key properties: area_size = Vector2(1, 1) (meters), area_range = 5.0, area_attenuation = 1.0 (2.0 = physically accurate inverse square), area_normalize_energy = true (resizing keeps total output stable), optional area_texture for textured emission (Forward+/Mobile only). Mobile support is limited and Compatibility cannot cast area-light shadows; in Forward+, a single visible area light adds clustered-lighting cost to all rendered objects — reserve for cinematics or high-end targets.

See references/materials-and-lighting-recipes.md for the full property table and the GDScript + C# setup recipe.

Dynamic Point Light

Spawn an OmniLight3D at runtime, drive its energy with a tween, queue-free on completion. Common for explosions, muzzle flashes, magic effects.

See references/materials-and-lighting-recipes.md for the full GDScript and C# recipe.

Shadow Configuration & Bake Modes

Prefer shadow_normal_bias over shadow_bias against acne; keep directional_shadow_max_distance at the minimum needed (50–100 m typical). Bake modes: Disabled (fully real-time, default), Static (fully baked, no runtime cost), Dynamic (indirect baked, direct real-time).

See references/materials-and-lighting-recipes.md for the shadow-tuning table and the bake-modes table.

4. Environment & Post-Processing

Configure global rendering — sky background, tonemapping, glow, SSR, SSAO/SSIL/SDFGI, depth-of-field — through a WorldEnvironment node holding an Environment resource. Pick a tonemap (Linear, Reinhard, Filmic, ACES, or AgX) on the Environment resource. Forward+ enables SSAO, SSIL, SSR, and SDFGI; mobile/compatibility renderers omit these.

See references/environment-and-post.md for the full setup recipes (sky options, tonemap modes, all post-processing effects, the 4.6+ glow-before-tonemapping pipeline change, AgX tonemap_white / tonemap_contrast controls, and the 4.6+ SSR quality upgrade).

Godot 4.7+: display/window/hdr/request_hdr_output (default false, promoted to a basic project setting) requests HDR display output for the main window and editor where supported, auto-switching between HDR and SDR as screens or system settings change; it forces Viewport.use_hdr_2d on for the main viewport (other SubViewports must enable it themselves). Read only at startup — toggle Window.hdr_output_requested at runtime.

⚠️ Changed in Godot 4.7: The rendering/reflections/sky_reflections/roughness_layers default changed from 7 to 8, altering sky-reflection roughness mip distribution for projects that left it at the default. Set it back to 7 to keep the 4.6 output. See the 4.7 migration guide.

5. Global Illumination

Five GI options trade quality for cost: none (ambient only) → ReflectionProbe (localized) → LightmapGI (best quality, baked) → VoxelGI (small/medium dynamic) → SDFGI (large open-world). VoxelGI/SDFGI/LightmapGI require Forward+. The 4.5+ subsections below (Specular Occlusion, Bent Normal Maps) stay inline because they apply across GI methods.

See references/global-illumination.md for the methods comparison table, ReflectionProbe scene + code recipe, LightmapGI bake workflow, and SDFGI configuration.

Specular Occlusion from Ambient Light (Godot 4.5+)

Godot 4.5+ automatically computes specular occlusion from the ambient light probe when LightmapGI, VoxelGI, or SDFGI is active. Prevents unrealistically bright speculars in areas that receive little indirect light (under eaves, inside crevices, in corners). No API change — re-bake after upgrading to see the improvement on metallic / low-roughness surfaces. ReflectionProbe alone does not provide specular occlusion.