/3d-essentials

name: 3d-essentials
description: Use when working with 3D-specific systems — materials, lighting, shadows, environment, global illumination, fog, LOD, occlusion culling, and decals in Godot 4.3+

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):

| Axis | Direction | Color | |------|-----------|--------| | X | Right | Red | | Y | Up | Green | | Z | Out of screen (+Z toward viewer) | Blue |

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

Essential 3D Nodes

| Node | Purpose | |--------------------|-------------------------------------------------| | `Node3D` | Base transform node — position, rotation, scale | | `MeshInstance3D` | Displays a mesh with a material | | `Camera3D` | Required to render 3D — perspective or orthogonal | | `DirectionalLight3D` | Sun/moon — parallel rays, cheapest light | | `OmniLight3D` | Point light — emits in all directions | | `SpotLight3D` | Cone light — flashlights, spotlights | | `WorldEnvironment` | Sky, fog, tonemap, post-processing | | `Decal` | Projected texture onto surfaces | | `GPUParticles3D` | GPU-driven particle effects | | `CSGBox3D` etc. | Constructive Solid Geometry — prototyping | | `GridMap` | 3D tile-based level building |

> **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](references/godot-4.7-additions.md)

Minimal 3D Scene

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

---

2. Materials

StandardMaterial3D vs ShaderMaterial

| Material | Use For | Notes | |----------------------|---------------------------------------------|--------------------------------| | `StandardMaterial3D` | Most 3D objects — PBR workflow | No code; Inspector-driven | | `ORMMaterial3D` | Same as Standard but with packed ORM texture | Occlusion+Roughness+Metallic in one texture | | `ShaderMaterial` | Custom effects — toon, water, dissolve | Requires spatial shader code |

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](references/materials-and-lighting-recipes.md#transparency-modes) 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](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

| Light | Shape | Shadows | Cost | Max Visible | |---------------------|---------------|---------|---------|----------------------| | `DirectionalLight3D` | Parallel rays | PSSM | Cheapest | 8 (Forward+) | | `OmniLight3D` | Sphere | Cube/Dual Paraboloid | Medium | 512 clustered* | | `SpotLight3D` | Cone | Single texture | Cheap | 512 clustered* | | `AreaLight3D` (4.7+) | Rectangle | PCSS soft | Most expensive | — |

*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](references/materials-and-lighting-recipes.md#light-properties) 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](references/materials-and-lighting-recipes.md#arealight3d-godot-47) for the full property table and the GDScript + C# setup recipe