--- name: godot-3d-materials description: "Expert patterns for Godot 3D PBR materials using StandardMaterial3D including albedo, metallic/roughness workflows, normal maps, ORM texture packing, transparency modes, and shader conversion. Use when creating realistic 3D surfaces, PBR workflows, or material optimization. Trigger keywords: StandardMaterial3D, BaseMaterial3D, albedo_texture, metallic, metallic_texture, roughness, roughness_texture, normal_texture, normal_enabled, orm_texture, transparency, alpha_scissor, alpha_hash, cull_mode, ShaderMaterial, shader parameters." ---

# 3D Materials

Expert guidance for PBR materials and StandardMaterial3D in Godot.

## NEVER Do

- **NEVER use separate metallic/roughness/AO textures** — Use ORM packing (1 RGB texture with Occlusion/Roughness/Metallic channels) to save texture slots and memory. - **NEVER forget to enable normal_enabled** — Normal maps don't work unless you set `normal_enabled = true`. Silent failure is common. - **NEVER use TRANSPARENCY_ALPHA for cutout materials** — Use TRANSPARENCY_ALPHA_SCISSOR or TRANSPARENCY_ALPHA_HASH instead. Full alpha blending is expensive and causes sorting issues. - **NEVER set metallic = 0.5** — Materials are either metallic (1.0) or dielectric (0.0). Values between are physically incorrect except for rust/dirt transitions. - **NEVER use emission without HDR** — Emission values > 1.0 only work with HDR rendering enabled in Project Settings. - **NEVER use transparent materials for large environmental surfaces** — Transparent objects cannot rely on the Z-buffer for early fragment rejection, resulting in massive overdraw. If only a tiny part of a mesh is transparent, split the mesh into two surfaces: one opaque, one transparent. - **NEVER create hundreds of slightly varied StandardMaterial3D resources if performance is dropping** — Godot minimizes GPU state changes by automatically reusing the underlying shader for materials that share the exact same configuration flags (checkboxes). Try to group your material configurations. - **NEVER attempt to fix Z-fighting strictly by moving objects further apart** — Floating-point precision degrades over distance. To fix flickering textures, increase your Camera3D's `Near` plane property and decrease the `Far` property to compress the precision range. - **NEVER use unique Material resources per MeshInstance3D** — This breaks draw call batching. Use 'Instance Uniforms' to vary parameters while keeping a single shared material. - **NEVER mutate a shared Material `.tres` / surface material at runtime** — Call `duplicate(true)` or enable **Local To Scene**, then assign the unique instance before tweaking parameters. **MANDATORY** use [`material_fx.gd`](scripts/material_fx.gd) `ensure_unique_override()` / overlay helpers for flash/dissolve. - **NEVER use Decals on dynamic moving actors without a Cull Mask** — Bullet holes should not stick to the player's face as they walk over them. Mask out character layers.

---

## Available Scripts

> **MANDATORY**: Read the appropriate script before implementing the corresponding pattern.

### Workflow router (MANDATORY / Do NOT Load) | Task | Load | Do NOT Load | |------|------|-------------| | StandardMaterial3D / ORM / transparency | `pbr_orm_packer.gd`, `transparency_sorting_fix.gd`, `material_batcher.gd`, `material_fx.gd` | `triplanar_world*.gdshader`, `vertex_wind_sway.gdshader` | | UV-less terrain / cliffs | `triplanar_world.gdshader` or `triplanar_world_projection.gdshader` + `pbr_material_builder.gd` | Wind sway unless foliage | | Foliage wind | `vertex_wind_sway.gdshader` | Triplanar unless rock/terrain also needed | | Runtime damage / dissolve | **MANDATORY** `material_fx.gd` | Editing shared imported materials | | Instance color/health / texture-array variants | **MANDATORY** `instance_uniform_batching.gdshader` | Per-mesh unique StandardMaterial3D copies; body texture-array samples | | HLOD / distant material simplify | `material_batcher.gd` (`setup_lod_materials`) | Alpha-blend distance fade (use Pixel Dither) | | Organic SSS / rim / clearcoat | `organic_material.gd`, `subsurface_scattering_setup.gd` | SSS recipes on Mobile/Compatibility |

> Pure StandardMaterial3D albedo/ORM/transparency work: **Do NOT Load** triplanar, wind, or texture-array shaders.

### [material_fx.gd](scripts/material_fx.gd) **MANDATORY** for runtime FX. `ensure_unique_override()` / overlay flash / scissor dissolve — never tween shared `.tres` materials.

### [pbr_material_builder.gd](scripts/pbr_material_builder.gd) Runtime PBR material creation with ORM textures and triplanar mapping.

### [organic_material.gd](scripts/organic_material.gd) Subsurface scattering and rim lighting setup for organic surfaces (skin, leaves). Use for realistic character or vegetation materials.

### [triplanar_world.gdshader](scripts/triplanar_world.gdshader) Triplanar projection shader for terrain without UV mapping. Blends textures based on surface normals. Use for cliffs, caves, or procedural terrain.

### [pbr_orm_packer.gd](scripts/pbr_orm_packer.gd) Expert PBR resource utility. Packs Ambient Occlusion, Roughness, and Metallic into a single ORM texture to optimize VRAM and draw calls.

### [vertex_wind_sway.gdshader](scripts/vertex_wind_sway.gdshader) High-performance GPU-driven foliage animation. Uses vertex world coordinates and vertex color weight painting to simulate wind without skeletons.

### [triplanar_world_projection.gdshader](scripts/triplanar_world_projection.gdshader) UV-less environment mapping. Projects textures along X/Y/Z axes for organic blending over complex rocks and terrain.

### [subsurface_scattering_setup.gd](scripts/subsurface_scattering_setup.gd) Configuring realistic organic materials. Covers Skin Mode, Transmittance, and depth scattering settings for Forward+ rendering.

### [instance_uniform_batching.gdshader](scripts/instance_uniform_batching.gdshader) Architecture pattern for high-speed batching. Allows 10,000 meshes to share one material while maintaining unique colors or health states via instance uniforms.

### [decal_placer_expert.gd](scripts/decal_placer_expert.gd) Dynamic 3D decal system with cull masking and life-cycle management for impact effects.

### [transparency_sorting_fix.gd](scripts/transparency_sorting_fix.gd) Solving visual artifacts using Alpha Hash and Depth Prepass strategies.

### [shader_state_manager.gd](scripts/shader_state_manager.gd) Clean pattern for toggling shader-based visual states (Frozen, Burned) on multiple entities.

### [depth_precision_fix.gd](scripts/depth_precision_fix.gd) Camera-side fix for Z-fighting and texture flickering in large-scale worlds.

### [material_batcher.gd](scripts/material_batcher.gd) Global override system to ensure environmental meshes draw in optimized, state-locked batches.

---

## StandardMaterial3D Checklist (script-first)

1. Pack AO/Roughness/Metallic → **MANDATORY** [`pbr_orm_packer.gd`](scripts/pbr_orm_packer.gd); set `orm_texture` (never three separate maps). 2. Enable `normal_enabled` before assigning `normal_texture` (silent no-op otherwise). 3. Pick transparency from the matrix below — not docs-default ALPHA for cutouts. 4. Organic skin/leaves → [`organic_material.gd`](scripts/organic_material.gd) + [`subsurface_scattering_setup.gd`](scripts/subsurface_scattering_setup.gd) (Forward+ only for real SSS). 5. Runtime flash/dissolve → **MANDATORY** [`material_fx.gd`](scripts/material_fx.gd) `ensure_unique_override()` first. 6. Shared-mesh tint/variant → [`instance_uniform_batching.gdshader`](scripts/instance_uniform_batching.gdshader); never unique `.tres` per instance. 7. Distant LOD simplify / Pixel Dither fade → [`material_batcher.gd`](scripts/material_batcher.gd) `setup_lod_materials()`. 8. Check Forward+ vs Mobile feature matrix before enabling SSS/clearcoat/anisotropy.

### Forward+ vs Mobile (material features)

| Feature | Forward+ | Mobile / Compatibility | WHY | |---------|----------|------------------------|-----| | Subsurface scattering / Skin Mode | Full | Limited / often unavailable | SSS needs Forward+ lighting path; fake with rim + transmittance bake on Mobile | | Clearcoat | Yes | Often stripped / approximate | Extra specular lobe cost; drop on distant LOD and Mobile | | Anisotropy | Yes | Prefer off | Flowmap + anisotropic BRDF burns mobile fragment budget | | Alpha Hash / Pixel Dither fade | Yes | Prefer Alpha Scissor or opaque dither | Hash noise + overdraw hurts tile GPUs | | Instance uniforms (batching) | Yes | Yes (prefer this) | Keeps one material; avoids unique-resource draw breaks |

---

## Transparency Modes

### Decision Matrix

| Mode | Use Case | Performance | Sorting Issues | |------|----------|-------------|---------------| | ALPHA_SCISSOR | Foliage, chain-link fence | Fast | No | | ALPHA_HASH | Dithered fade, LOD transitions | Fast | Noisy | | ALPHA | Glass, water, godot-particles | Slow | Yes (render order) |

### Alpha Scissor (Cutout)

```gdscript # For leaves, grass, fences mat.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA_SCISSOR mat.alpha_scissor_threshold = 0.5 # Pixels < 0.5 alpha = discarded mat.albedo_texture = load("res://leaf.png") # Must have alpha channel

# Enable backface culling for performance mat.cull_mode = BaseMaterial3D.CULL_BACK ```

### Alpha Hash (Dithered)

```gdscript # For smooth fade-outs without sorting issues mat.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA_HASH mat.alpha_hash_scale = 1.0 # Dither pattern scale

# Animate fade var tween := create_tween() tween.tween_property(mat, "albedo_color:a", 0.0, 1.0) ```

### Alpha Blend (Full Transparency)

```gdscript # For glass, water (expensive) mat.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA mat.blend_mode = BaseMaterial3D.BLEND_MODE_MIX

# Disable depth writing for correct blending mat.depth_draw_mode = BaseMaterial3D.DEPTH_DRAW_DISABLED mat.cull_mode = BaseMaterial3D.CULL_DISABLED # Show both sides ```

---

## Texture Channel Packing

**MANDATORY** [`pbr_orm_packer.gd`](scripts/pbr_orm_packer.gd) for R=AO / G=Roughness / B=Metallic. Do not inline packing recipes here. Custom channel remaps only when an imported atlas already disagrees with ORM layout.

---

## Shader Conversion

### When to Convert to ShaderMaterial

- Need custom effects (dissolve, vertex displacement) - StandardMaterial3D limitations hit - Shader optimizations (remove unused features)

### Conversion Workflow

```gdscript # 1. Create StandardMaterial3D with all settings var std_mat := StandardMaterial3D.new() std_mat.albedo_color = Color.RED std_mat.metallic = 1.0 std_mat.roughness = 0.2

# 2. Convert to ShaderMaterial var shader_mat := ShaderMaterial.new() shader_mat.shader = load("res://custom_shader.gdshader")

# 3. Transfer parameters manually shader_mat.set_shader_parameter("albedo", std_mat.albedo_color) shader_mat.set_shader_parameter("metallic", std_mat.metallic) shader_mat.set_shader_parameter("roughness", std_mat.roughness) ```

---

## Material Variants (Godot 4.0+)

### Efficient Material Reuse

```gdscript # Base material (shared) var base_red_metal := StandardMaterial3D.new() base_red_metal.albedo_color = Color.RED base_red_metal.metallic = 1.0

# Variant 1: Rough var rough_variant := base_red_metal.duplicate() rough_variant.roughness = 0.8

# Variant 2: Smooth var smooth_variant := base_red_metal.duplicate() smooth_variant.roughness = 0.1

# Note: Use resource_local_to_scene for per-instance tweaks ```

---

## Performance Optimization

### Material Batching

```gdscript # ✅ GOOD: Reuse materials across meshes const SHARED_STONE := preload("res://materials/stone.tres")

func _ready() -> void: for wall in get_tree().get_nodes_in_group("stone_walls"): wall.material_override = SHARED_STONE # All walls batched in single draw call

# ❌ BAD: Unique material per mesh func _ready() -> void: for wall in get_tree().get_nodes_in_group("stone_walls"): var mat := StandardMaterial3D.new() # New material! mat.

--- name: godot-3d-materials description: "Expert patterns for Godot 3D PBR materials using StandardMaterial3D including albedo, metallic/roughness workflows, normal maps, ORM texture packing, transparency modes, and shader conversion. Use when creating realistic 3D surfaces, PBR workflows, or material optimization. Trigger keywords: StandardMaterial3D, BaseMaterial3D, albedo_texture, metallic, metallic_texture, roughness, roughness_texture, normal_texture, normal_enabled, orm_texture, transparency, alpha_scissor, alpha_hash, cull_mode, ShaderMaterial, shader parameters." ---

# 3D Materials

Expert guidance for PBR materials and StandardMaterial3D in Godot.

## NEVER Do

- **NEVER use separate metallic/roughness/AO textures** — Use ORM packing (1 RGB texture with Occlusion/Roughness/Metallic channels) to save texture slots and memory. - **NEVER forget to enable normal_enabled** — Normal maps don't work unless you set `normal_enabled = true`. Silent failure is common. - **NEVER use TRANSPARENCY_ALPHA for cutout materials** — Use TRANSPARENCY_ALPHA_SCISSOR or TRANSPARENCY_ALPHA_HASH instead. Full alpha blending is expensive and causes sorting issues. - **NEVER set metallic = 0.5** — Materials are either metallic (1.0) or dielectric (0.0). Values between are physically incorrect except for rust/dirt transitions. - **NEVER use emission without HDR** — Emission values > 1.0 only work with HDR rendering enabled in Project Settings. - **NEVER use transparent materials for large environmental surfaces** — Transparent objects cannot rely on the Z-buffer for early fragment rejection, resulting in massive overdraw. If only a tiny part of a mesh is transparent, split the mesh into two surfaces: one opaque, one transparent. - **NEVER create hundreds of slightly varied StandardMaterial3D resources if performance is dropping** — Godot minimizes GPU state changes by automatically reusing the underlying shader for materials that share the exact same configuration flags (checkboxes). Try to group your material configurations. - **NEVER attempt to fix Z-fighting strictly by moving objects further apart** — Floating-point precision degrades over distance. To fix flickering textures, increase your Camera3D's `Near` plane property and decrease the `Far` property to compress the precision range. - **NEVER use unique Material resources per MeshInstance3D** — This breaks draw call batching. Use 'Instance Uniforms' to vary parameters while keeping a single shared material. - **NEVER mutate a shared Material `.tres` / surface material at runtime** — Call `duplicate(true)` or enable **Local To Scene**, then assign the unique instance before tweaking parameters. **MANDATORY** use [`material_fx.gd`](scripts/material_fx.gd) `ensure_unique_override()` / overlay helpers for flash/dissolve. - **NEVER use Decals on dynamic moving actors without a Cull Mask** — Bullet holes should not stick to the player's face as they walk over them. Mask out character layers.

---

## Available Scripts

> **MANDATORY**: Read the appropriate script before implementing the corresponding pattern.

### Workflow router (MANDATORY / Do NOT Load) | Task | Load | Do NOT Load | |------|------|-------------| | StandardMaterial3D / ORM / transparency | `pbr_orm_packer.gd`, `transparency_sorting_fix.gd`, `material_batcher.gd`, `material_fx.gd` | `triplanar_world*.gdshader`, `vertex_wind_sway.gdshader` | | UV-less terrain / cliffs | `triplanar_world.gdshader` or `triplanar_world_projection.gdshader` + `pbr_material_builder.gd` | Wind sway unless foliage | | Foliage wind | `vertex_wind_sway.gdshader` | Triplanar unless rock/terrain also needed | | Runtime damage / dissolve | **MANDATORY** `material_fx.gd` | Editing shared imported materials | | Instance color/health / texture-array variants | **MANDATORY** `instance_uniform_batching.gdshader` | Per-mesh unique StandardMaterial3D copies; body texture-array samples | | HLOD / distant material simplify | `material_batcher.gd` (`setup_lod_materials`) | Alpha-blend distance fade (use Pixel Dither) | | Organic SSS / rim / clearcoat | `organic_material.gd`, `subsurface_scattering_setup.gd` | SSS recipes on Mobile/Compatibility |

> Pure StandardMaterial3D albedo/ORM/transparency work: **Do NOT Load** triplanar, wind, or texture-array shaders.

### [material_fx.gd](scripts/material_fx.gd) **MANDATORY** for runtime FX. `ensure_unique_override()` / overlay flash / scissor dissolve — never tween shared `.tres` materials.

### [pbr_material_builder.gd](scripts/pbr_material_builder.gd) Runtime PBR material creation with ORM textures and triplanar mapping.

### [organic_material.gd](scripts/organic_material.gd) Subsurface scattering and rim lighting setup for organic surfaces (skin, leaves). Use for realistic character or vegetation materials.

### [triplanar_world.gdshader](scripts/triplanar_world.gdshader) Triplanar projection shader for terrain without UV mapping. Blends textures based on surface normals. Use for cliffs, caves, or procedural terrain.

### [pbr_orm_packer.gd](scripts/pbr_orm_packer.gd) Expert PBR resource utility. Packs Ambient Occlusion, Roughness, and Metallic into a single ORM texture to optimize VRAM and draw calls.

### [vertex_wind_sway.gdshader](scripts/vertex_wind_sway.gdshader) High-performance GPU-driven foliage animation. Uses vertex world coordinates and vertex color weight painting to simulate wind without skeletons.

### [triplanar_world_projection.gdshader](scripts/triplanar_world_projection.gdshader) UV-less environment mapping. Projects textures along X/Y/Z axes for organic blending over complex rocks and terrain.

### [subsurface_scattering_setup.gd](scripts/subsurface_scattering_setup.gd) Configuring realistic organic materials. Covers Skin Mode, Transmittance, and depth scattering settings for Forward+ rendering.

### [instance_uniform_batching.gdshader](scripts/instance_uniform_batching.gdshader) Architecture pattern for high-speed batching. Allows 10,000 meshes to share one material while maintaining unique colors or health states via instance uniforms.

### [decal_placer_expert.gd](scripts/decal_placer_expert.gd) Dynamic 3D decal system with cull masking and life-cycle management for impact effects.

### [transparency_sorting_fix.gd](scripts/transparency_sorting_fix.gd) Solving visual artifacts using Alpha Hash and Depth Prepass strategies.

### [shader_state_manager.gd](scripts/shader_state_manager.gd) Clean pattern for toggling shader-based visual states (Frozen, Burned) on multiple entities.

### [depth_precision_fix.gd](scripts/depth_precision_fix.gd) Camera-side fix for Z-fighting and texture flickering in large-scale worlds.

### [material_batcher.gd](scripts/material_batcher.gd) Global override system to ensure environmental meshes draw in optimized, state-locked batches.

---

## StandardMaterial3D Checklist (script-first)

1. Pack AO/Roughness/Metallic → **MANDATORY** [`pbr_orm_packer.gd`](scripts/pbr_orm_packer.gd); set `orm_texture` (never three separate maps). 2. Enable `normal_enabled` before assigning `normal_texture` (silent no-op otherwise). 3. Pick transparency from the matrix below — not docs-default ALPHA for cutouts. 4. Organic skin/leaves → [`organic_material.gd`](scripts/organic_material.gd) + [`subsurface_scattering_setup.gd`](scripts/subsurface_scattering_setup.gd) (Forward+ only for real SSS). 5. Runtime flash/dissolve → **MANDATORY** [`material_fx.gd`](scripts/material_fx.gd) `ensure_unique_override()` first. 6. Shared-mesh tint/variant → [`instance_uniform_batching.gdshader`](scripts/instance_uniform_batching.gdshader); never unique `.tres` per instance. 7. Distant LOD simplify / Pixel Dither fade → [`material_batcher.gd`](scripts/material_batcher.gd) `setup_lod_materials()`. 8. Check Forward+ vs Mobile feature matrix before enabling SSS/clearcoat/anisotropy.

### Forward+ vs Mobile (material features)

| Feature | Forward+ | Mobile / Compatibility | WHY | |---------|----------|------------------------|-----| | Subsurface scattering / Skin Mode | Full | Limited / often unavailable | SSS needs Forward+ lighting path; fake with rim + transmittance bake on Mobile | | Clearcoat | Yes | Often stripped / approximate | Extra specular lobe cost; drop on distant LOD and Mobile | | Anisotropy | Yes | Prefer off | Flowmap + anisotropic BRDF burns mobile fragment budget | | Alpha Hash / Pixel Dither fade | Yes | Prefer Alpha Scissor or opaque dither | Hash noise + overdraw hurts tile GPUs | | Instance uniforms (batching) | Yes | Yes (prefer this) | Keeps one material; avoids unique-resource draw breaks |

---

## Transparency Modes

### Decision Matrix

| Mode | Use Case | Performance | Sorting Issues | |------|----------|-------------|---------------| | ALPHA_SCISSOR | Foliage, chain-link fence | Fast | No | | ALPHA_HASH | Dithered fade, LOD transitions | Fast | Noisy | | ALPHA | Glass, water, godot-particles | Slow | Yes (render order) |

### Alpha Scissor (Cutout)

```gdscript # For leaves, grass, fences mat.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA_SCISSOR mat.alpha_scissor_threshold = 0.5 # Pixels < 0.5 alpha = discarded mat.albedo_texture = load("res://leaf.png") # Must have alpha channel

# Enable backface culling for performance mat.cull_mode = BaseMaterial3D.CULL_BACK ```

### Alpha Hash (Dithered)

```gdscript # For smooth fade-outs without sorting issues mat.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA_HASH mat.alpha_hash_scale = 1.0 # Dither pattern scale

# Animate fade var tween := create_tween() tween.tween_property(mat, "albedo_color:a", 0.0, 1.0) ```

### Alpha Blend (Full Transparency)

```gdscript # For glass, water (expensive) mat.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA mat.blend_mode = BaseMaterial3D.BLEND_MODE_MIX

# Disable depth writing for correct blending mat.depth_draw_mode = BaseMaterial3D.DEPTH_DRAW_DISABLED mat.cull_mode = BaseMaterial3D.CULL_DISABLED # Show both sides ```

---

## Texture Channel Packing

**MANDATORY** [`pbr_orm_packer.gd`](scripts/pbr_orm_packer.gd) for R=AO / G=Roughness / B=Metallic. Do not inline packing recipes here. Custom channel remaps only when an imported atlas already disagrees with ORM layout.

---

## Shader Conversion

### When to Convert to ShaderMaterial

- Need custom effects (dissolve, vertex displacement) - StandardMaterial3D limitations hit - Shader optimizations (remove unused features)

### Conversion Workflow

```gdscript # 1. Create StandardMaterial3D with all settings var std_mat := StandardMaterial3D.new() std_mat.albedo_color = Color.RED std_mat.metallic = 1.0 std_mat.roughness = 0.2

# 2. Convert to ShaderMaterial var shader_mat := ShaderMaterial.new() shader_mat.shader = load("res://custom_shader.gdshader")

# 3. Transfer parameters manually shader_mat.set_shader_parameter("albedo", std_mat.albedo_color) shader_mat.set_shader_parameter("metallic", std_mat.metallic) shader_mat.set_shader_parameter("roughness", std_mat.roughness) ```

---

## Material Variants (Godot 4.0+)

### Efficient Material Reuse

```gdscript # Base material (shared) var base_red_metal := StandardMaterial3D.new() base_red_metal.albedo_color = Color.RED base_red_metal.metallic = 1.0

# Variant 1: Rough var rough_variant := base_red_metal.duplicate() rough_variant.roughness = 0.8

# Variant 2: Smooth var smooth_variant := base_red_metal.duplicate() smooth_variant.roughness = 0.1

# Note: Use resource_local_to_scene for per-instance tweaks ```

---

## Performance Optimization

### Material Batching

```gdscript # ✅ GOOD: Reuse materials across meshes const SHARED_STONE := preload("res://materials/stone.tres")

func _ready() -> void: for wall in get_tree().get_nodes_in_group("stone_walls"): wall.material_override = SHARED_STONE # All walls batched in single draw call

# ❌ BAD: Unique material per mesh func _ready() -> void: for wall in get_tree().get_nodes_in_group("stone_walls"): var mat := StandardMaterial3D.new() # New material! mat.

--- name: godot-3d-materials description: "Expert patterns for Godot 3D PBR materials using StandardMaterial3D including albedo, metallic/roughness workflows, normal maps, ORM texture packing, transparency modes, and shader conversion. Use when creating realistic 3D surfaces, PBR workflows, or material optimization. Trigger keywords: StandardMaterial3D, BaseMaterial3D, albedo_texture, metallic, metallic_texture, roughness, roughness_texture, normal_texture, normal_enabled, orm_texture, transparency, alpha_scissor, alpha_hash, cull_mode, ShaderMaterial, shader parameters." ---

# 3D Materials

Expert guidance for PBR materials and StandardMaterial3D in Godot.

## NEVER Do

- **NEVER use separate metallic/roughness/AO textures** — Use ORM packing (1 RGB texture with Occlusion/Roughness/Metallic channels) to save texture slots and memory. - **NEVER forget to enable normal_enabled** — Normal maps don't work unless you set `normal_enabled = true`. Silent failure is common. - **NEVER use TRANSPARENCY_ALPHA for cutout materials** — Use TRANSPARENCY_ALPHA_SCISSOR or TRANSPARENCY_ALPHA_HASH instead. Full alpha blending is expensive and causes sorting issues. - **NEVER set metallic = 0.5** — Materials are either metallic (1.0) or dielectric (0.0). Values between are physically incorrect except for rust/dirt transitions. - **NEVER use emission without HDR** — Emission values > 1.0 only work with HDR rendering enabled in Project Settings. - **NEVER use transparent materials for large environmental surfaces** — Transparent objects cannot rely on the Z-buffer for early fragment rejection, resulting in massive overdraw. If only a tiny part of a mesh is transparent, split the mesh into two surfaces: one opaque, one transparent. - **NEVER create hundreds of slightly varied StandardMaterial3D resources if performance is dropping** — Godot minimizes GPU state changes by automatically reusing the underlying shader for materials that share the exact same configuration flags (checkboxes). Try to group your material configurations. - **NEVER attempt to fix Z-fighting strictly by moving objects further apart** — Floating-point precision degrades over distance. To fix flickering textures, increase your Camera3D's `Near` plane property and decrease the `Far` property to compress the precision range. - **NEVER use unique Material resources per MeshInstance3D** — This breaks draw call batching. Use 'Instance Uniforms' to vary parameters while keeping a single shared material. - **NEVER mutate a shared Material `.tres` / surface material at runtime** — Call `duplicate(true)` or enable **Local To Scene**, then assign the unique instance before tweaking parameters. **MANDATORY** use [`material_fx.gd`](scripts/material_fx.gd) `ensure_unique_override()` / overlay helpers for flash/dissolve. - **NEVER use Decals on dynamic moving actors without a Cull Mask** — Bullet holes should not stick to the player's face as they walk over them. Mask out character layers.

---

## Available Scripts

> **MANDATORY**: Read the appropriate script before implementing the corresponding pattern.

### Workflow router (MANDATORY / Do NOT Load) | Task | Load | Do NOT Load | |------|------|-------------| | StandardMaterial3D / ORM / transparency | `pbr_orm_packer.gd`, `transparency_sorting_fix.gd`, `material_batcher.gd`, `material_fx.gd` | `triplanar_world*.gdshader`, `vertex_wind_sway.gdshader` | | UV-less terrain / cliffs | `triplanar_world.gdshader` or `triplanar_world_projection.gdshader` + `pbr_material_builder.gd` | Wind sway unless foliage | | Foliage wind | `vertex_wind_sway.gdshader` | Triplanar unless rock/terrain also needed | | Runtime damage / dissolve | **MANDATORY** `material_fx.gd` | Editing shared imported materials | | Instance color/health / texture-array variants | **MANDATORY** `instance_uniform_batching.gdshader` | Per-mesh unique StandardMaterial3D copies; body texture-array samples | | HLOD / distant material simplify | `material_batcher.gd` (`setup_lod_materials`) | Alpha-blend distance fade (use Pixel Dither) | | Organic SSS / rim / clearcoat | `organic_material.gd`, `subsurface_scattering_setup.gd` | SSS recipes on Mobile/Compatibility |

> Pure StandardMaterial3D albedo/ORM/transparency work: **Do NOT Load** triplanar, wind, or texture-array shaders.

### [material_fx.gd](scripts/material_fx.gd) **MANDATORY** for runtime FX. `ensure_unique_override()` / overlay flash / scissor dissolve — never tween shared `.tres` materials.

### [pbr_material_builder.gd](scripts/pbr_material_builder.gd) Runtime PBR material creation with ORM textures and triplanar mapping.

### [organic_material.gd](scripts/organic_material.gd) Subsurface scattering and rim lighting setup for organic surfaces (skin, leaves). Use for realistic character or vegetation materials.

### [triplanar_world.gdshader](scripts/triplanar_world.gdshader) Triplanar projection shader for terrain without UV mapping. Blends textures based on surface normals. Use for cliffs, caves, or procedural terrain.

### [pbr_orm_packer.gd](scripts/pbr_orm_packer.gd) Expert PBR resource utility. Packs Ambient Occlusion, Roughness, and Metallic into a single ORM texture to optimize VRAM and draw calls.

### [vertex_wind_sway.gdshader](scripts/vertex_wind_sway.gdshader) High-performance GPU-driven foliage animation. Uses vertex world coordinates and vertex color weight painting to simulate wind without skeletons.

### [triplanar_world_projection.gdshader](scripts/triplanar_world_projection.gdshader) UV-less environment mapping. Projects textures along X/Y/Z axes for organic blending over complex rocks and terrain.

### [subsurface_scattering_setup.gd](scripts/subsurface_scattering_setup.gd) Configuring realistic organic materials. Covers Skin Mode, Transmittance, and depth scattering settings for Forward+ rendering.

### [instance_uniform_batching.gdshader](scripts/instance_uniform_batching.gdshader) Architecture pattern for high-speed batching. Allows 10,000 meshes to share one material while maintaining unique colors or health states via instance uniforms.

### [decal_placer_expert.gd](scripts/decal_placer_expert.gd) Dynamic 3D decal system with cull masking and life-cycle management for impact effects.

### [transparency_sorting_fix.gd](scripts/transparency_sorting_fix.gd) Solving visual artifacts using Alpha Hash and Depth Prepass strategies.

### [shader_state_manager.gd](scripts/shader_state_manager.gd) Clean pattern for toggling shader-based visual states (Frozen, Burned) on multiple entities.

### [depth_precision_fix.gd](scripts/depth_precision_fix.gd) Camera-side fix for Z-fighting and texture flickering in large-scale worlds.

### [material_batcher.gd](scripts/material_batcher.gd) Global override system to ensure environmental meshes draw in optimized, state-locked batches.

---

## StandardMaterial3D Checklist (script-first)

1. Pack AO/Roughness/Metallic → **MANDATORY** [`pbr_orm_packer.gd`](scripts/pbr_orm_packer.gd); set `orm_texture` (never three separate maps). 2. Enable `normal_enabled` before assigning `normal_texture` (silent no-op otherwise). 3. Pick transparency from the matrix below — not docs-default ALPHA for cutouts. 4. Organic skin/leaves → [`organic_material.gd`](scripts/organic_material.gd) + [`subsurface_scattering_setup.gd`](scripts/subsurface_scattering_setup.gd) (Forward+ only for real SSS). 5. Runtime flash/dissolve → **MANDATORY** [`material_fx.gd`](scripts/material_fx.gd) `ensure_unique_override()` first. 6. Shared-mesh tint/variant → [`instance_uniform_batching.gdshader`](scripts/instance_uniform_batching.gdshader); never unique `.tres` per instance. 7. Distant LOD simplify / Pixel Dither fade → [`material_batcher.gd`](scripts/material_batcher.gd) `setup_lod_materials()`. 8. Check Forward+ vs Mobile feature matrix before enabling SSS/clearcoat/anisotropy.

### Forward+ vs Mobile (material features)

| Feature | Forward+ | Mobile / Compatibility | WHY | |---------|----------|------------------------|-----| | Subsurface scattering / Skin Mode | Full | Limited / often unavailable | SSS needs Forward+ lighting path; fake with rim + transmittance bake on Mobile | | Clearcoat | Yes | Often stripped / approximate | Extra specular lobe cost; drop on distant LOD and Mobile | | Anisotropy | Yes | Prefer off | Flowmap + anisotropic BRDF burns mobile fragment budget | | Alpha Hash / Pixel Dither fade | Yes | Prefer Alpha Scissor or opaque dither | Hash noise + overdraw hurts tile GPUs | | Instance uniforms (batching) | Yes | Yes (prefer this) | Keeps one material; avoids unique-resource draw breaks |

---

## Transparency Modes

### Decision Matrix

| Mode | Use Case | Performance | Sorting Issues | |------|----------|-------------|---------------| | ALPHA_SCISSOR | Foliage, chain-link fence | Fast | No | | ALPHA_HASH | Dithered fade, LOD transitions | Fast | Noisy | | ALPHA | Glass, water, godot-particles | Slow | Yes (render order) |

### Alpha Scissor (Cutout)

```gdscript # For leaves, grass, fences mat.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA_SCISSOR mat.alpha_scissor_threshold = 0.5 # Pixels < 0.5 alpha = discarded mat.albedo_texture = load("res://leaf.png") # Must have alpha channel

# Enable backface culling for performance mat.cull_mode = BaseMaterial3D.CULL_BACK ```

### Alpha Hash (Dithered)

```gdscript # For smooth fade-outs without sorting issues mat.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA_HASH mat.alpha_hash_scale = 1.0 # Dither pattern scale

# Animate fade var tween := create_tween() tween.tween_property(mat, "albedo_color:a", 0.0, 1.0) ```

### Alpha Blend (Full Transparency)

```gdscript # For glass, water (expensive) mat.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA mat.blend_mode = BaseMaterial3D.BLEND_MODE_MIX

# Disable depth writing for correct blending mat.depth_draw_mode = BaseMaterial3D.DEPTH_DRAW_DISABLED mat.cull_mode = BaseMaterial3D.CULL_DISABLED # Show both sides ```

---

## Texture Channel Packing

**MANDATORY** [`pbr_orm_packer.gd`](scripts/pbr_orm_packer.gd) for R=AO / G=Roughness / B=Metallic. Do not inline packing recipes here. Custom channel remaps only when an imported atlas already disagrees with ORM layout.

---

## Shader Conversion

### When to Convert to ShaderMaterial

- Need custom effects (dissolve, vertex displacement) - StandardMaterial3D limitations hit - Shader optimizations (remove unused features)

### Conversion Workflow

```gdscript # 1. Create StandardMaterial3D with all settings var std_mat := StandardMaterial3D.new() std_mat.albedo_color = Color.RED std_mat.metallic = 1.0 std_mat.roughness = 0.2

# 2. Convert to ShaderMaterial var shader_mat := ShaderMaterial.new() shader_mat.shader = load("res://custom_shader.gdshader")

# 3. Transfer parameters manually shader_mat.set_shader_parameter("albedo", std_mat.albedo_color) shader_mat.set_shader_parameter("metallic", std_mat.metallic) shader_mat.set_shader_parameter("roughness", std_mat.roughness) ```

---

## Material Variants (Godot 4.0+)

### Efficient Material Reuse

```gdscript # Base material (shared) var base_red_metal := StandardMaterial3D.new() base_red_metal.albedo_color = Color.RED base_red_metal.metallic = 1.0

# Variant 1: Rough var rough_variant := base_red_metal.duplicate() rough_variant.roughness = 0.8

# Variant 2: Smooth var smooth_variant := base_red_metal.duplicate() smooth_variant.roughness = 0.1

# Note: Use resource_local_to_scene for per-instance tweaks ```

---

## Performance Optimization

### Material Batching

```gdscript # ✅ GOOD: Reuse materials across meshes const SHARED_STONE := preload("res://materials/stone.tres")

func _ready() -> void: for wall in get_tree().get_nodes_in_group("stone_walls"): wall.material_override = SHARED_STONE # All walls batched in single draw call

# ❌ BAD: Unique material per mesh func _ready() -> void: for wall in get_tree().get_nodes_in_group("stone_walls"): var mat := StandardMaterial3D.new() # New material! mat.

--- name: godot-3d-materials description: "Expert patterns for Godot 3D PBR materials using StandardMaterial3D including albedo, metallic/roughness workflows, normal maps, ORM texture packing, transparency modes, and shader conversion. Use when creating realistic 3D surfaces, PBR workflows, or material optimization. Trigger keywords: StandardMaterial3D, BaseMaterial3D, albedo_texture, metallic, metallic_texture, roughness, roughness_texture, normal_texture, normal_enabled, orm_texture, transparency, alpha_scissor, alpha_hash, cull_mode, ShaderMaterial, shader parameters." ---

# 3D Materials

Expert guidance for PBR materials and StandardMaterial3D in Godot.

## NEVER Do

- **NEVER use separate metallic/roughness/AO textures** — Use ORM packing (1 RGB texture with Occlusion/Roughness/Metallic channels) to save texture slots and memory. - **NEVER forget to enable normal_enabled** — Normal maps don't work unless you set `normal_enabled = true`. Silent failure is common. - **NEVER use TRANSPARENCY_ALPHA for cutout materials** — Use TRANSPARENCY_ALPHA_SCISSOR or TRANSPARENCY_ALPHA_HASH instead. Full alpha blending is expensive and causes sorting issues. - **NEVER set metallic = 0.5** — Materials are either metallic (1.0) or dielectric (0.0). Values between are physically incorrect except for rust/dirt transitions. - **NEVER use emission without HDR** — Emission values > 1.0 only work with HDR rendering enabled in Project Settings. - **NEVER use transparent materials for large environmental surfaces** — Transparent objects cannot rely on the Z-buffer for early fragment rejection, resulting in massive overdraw. If only a tiny part of a mesh is transparent, split the mesh into two surfaces: one opaque, one transparent. - **NEVER create hundreds of slightly varied StandardMaterial3D resources if performance is dropping** — Godot minimizes GPU state changes by automatically reusing the underlying shader for materials that share the exact same configuration flags (checkboxes). Try to group your material configurations. - **NEVER attempt to fix Z-fighting strictly by moving objects further apart** — Floating-point precision degrades over distance. To fix flickering textures, increase your Camera3D's `Near` plane property and decrease the `Far` property to compress the precision range. - **NEVER use unique Material resources per MeshInstance3D** — This breaks draw call batching. Use 'Instance Uniforms' to vary parameters while keeping a single shared material. - **NEVER mutate a shared Material `.tres` / surface material at runtime** — Call `duplicate(true)` or enable **Local To Scene**, then assign the unique instance before tweaking parameters. **MANDATORY** use [`material_fx.gd`](scripts/material_fx.gd) `ensure_unique_override()` / overlay helpers for flash/dissolve. - **NEVER use Decals on dynamic moving actors without a Cull Mask** — Bullet holes should not stick to the player's face as they walk over them. Mask out character layers.

---

## Available Scripts

> **MANDATORY**: Read the appropriate script before implementing the corresponding pattern.

### Workflow router (MANDATORY / Do NOT Load) | Task | Load | Do NOT Load | |------|------|-------------| | StandardMaterial3D / ORM / transparency | `pbr_orm_packer.gd`, `transparency_sorting_fix.gd`, `material_batcher.gd`, `material_fx.gd` | `triplanar_world*.gdshader`, `vertex_wind_sway.gdshader` | | UV-less terrain / cliffs | `triplanar_world.gdshader` or `triplanar_world_projection.gdshader` + `pbr_material_builder.gd` | Wind sway unless foliage | | Foliage wind | `vertex_wind_sway.gdshader` | Triplanar unless rock/terrain also needed | | Runtime damage / dissolve | **MANDATORY** `material_fx.gd` | Editing shared imported materials | | Instance color/health / texture-array variants | **MANDATORY** `instance_uniform_batching.gdshader` | Per-mesh unique StandardMaterial3D copies; body texture-array samples | | HLOD / distant material simplify | `material_batcher.gd` (`setup_lod_materials`) | Alpha-blend distance fade (use Pixel Dither) | | Organic SSS / rim / clearcoat | `organic_material.gd`, `subsurface_scattering_setup.gd` | SSS recipes on Mobile/Compatibility |

> Pure StandardMaterial3D albedo/ORM/transparency work: **Do NOT Load** triplanar, wind, or texture-array shaders.

### [material_fx.gd](scripts/material_fx.gd) **MANDATORY** for runtime FX. `ensure_unique_override()` / overlay flash / scissor dissolve — never tween shared `.tres` materials.

### [pbr_material_builder.gd](scripts/pbr_material_builder.gd) Runtime PBR material creation with ORM textures and triplanar mapping.

### [organic_material.gd](scripts/organic_material.gd) Subsurface scattering and rim lighting setup for organic surfaces (skin, leaves). Use for realistic character or vegetation materials.

### [triplanar_world.gdshader](scripts/triplanar_world.gdshader) Triplanar projection shader for terrain without UV mapping. Blends textures based on surface normals. Use for cliffs, caves, or procedural terrain.

### [pbr_orm_packer.gd](scripts/pbr_orm_packer.gd) Expert PBR resource utility. Packs Ambient Occlusion, Roughness, and Metallic into a single ORM texture to optimize VRAM and draw calls.

### [vertex_wind_sway.gdshader](scripts/vertex_wind_sway.gdshader) High-performance GPU-driven foliage animation. Uses vertex world coordinates and vertex color weight painting to simulate wind without skeletons.

### [triplanar_world_projection.gdshader](scripts/triplanar_world_projection.gdshader) UV-less environment mapping. Projects textures along X/Y/Z axes for organic blending over complex rocks and terrain.

### [subsurface_scattering_setup.gd](scripts/subsurface_scattering_setup.gd) Configuring realistic organic materials. Covers Skin Mode, Transmittance, and depth scattering settings for Forward+ rendering.

### [instance_uniform_batching.gdshader](scripts/instance_uniform_batching.gdshader) Architecture pattern for high-speed batching. Allows 10,000 meshes to share one material while maintaining unique colors or health states via instance uniforms.

### [decal_placer_expert.gd](scripts/decal_placer_expert.gd) Dynamic 3D decal system with cull masking and life-cycle management for impact effects.

### [transparency_sorting_fix.gd](scripts/transparency_sorting_fix.gd) Solving visual artifacts using Alpha Hash and Depth Prepass strategies.

### [shader_state_manager.gd](scripts/shader_state_manager.gd) Clean pattern for toggling shader-based visual states (Frozen, Burned) on multiple entities.

### [depth_precision_fix.gd](scripts/depth_precision_fix.gd) Camera-side fix for Z-fighting and texture flickering in large-scale worlds.

### [material_batcher.gd](scripts/material_batcher.gd) Global override system to ensure environmental meshes draw in optimized, state-locked batches.

---

## StandardMaterial3D Checklist (script-first)

1. Pack AO/Roughness/Metallic → **MANDATORY** [`pbr_orm_packer.gd`](scripts/pbr_orm_packer.gd); set `orm_texture` (never three separate maps). 2. Enable `normal_enabled` before assigning `normal_texture` (silent no-op otherwise). 3. Pick transparency from the matrix below — not docs-default ALPHA for cutouts. 4. Organic skin/leaves → [`organic_material.gd`](scripts/organic_material.gd) + [`subsurface_scattering_setup.gd`](scripts/subsurface_scattering_setup.gd) (Forward+ only for real SSS). 5. Runtime flash/dissolve → **MANDATORY** [`material_fx.gd`](scripts/material_fx.gd) `ensure_unique_override()` first. 6. Shared-mesh tint/variant → [`instance_uniform_batching.gdshader`](scripts/instance_uniform_batching.gdshader); never unique `.tres` per instance. 7. Distant LOD simplify / Pixel Dither fade → [`material_batcher.gd`](scripts/material_batcher.gd) `setup_lod_materials()`. 8. Check Forward+ vs Mobile feature matrix before enabling SSS/clearcoat/anisotropy.

### Forward+ vs Mobile (material features)

| Feature | Forward+ | Mobile / Compatibility | WHY | |---------|----------|------------------------|-----| | Subsurface scattering / Skin Mode | Full | Limited / often unavailable | SSS needs Forward+ lighting path; fake with rim + transmittance bake on Mobile | | Clearcoat | Yes | Often stripped / approximate | Extra specular lobe cost; drop on distant LOD and Mobile | | Anisotropy | Yes | Prefer off | Flowmap + anisotropic BRDF burns mobile fragment budget | | Alpha Hash / Pixel Dither fade | Yes | Prefer Alpha Scissor or opaque dither | Hash noise + overdraw hurts tile GPUs | | Instance uniforms (batching) | Yes | Yes (prefer this) | Keeps one material; avoids unique-resource draw breaks |

---

## Transparency Modes

### Decision Matrix

| Mode | Use Case | Performance | Sorting Issues | |------|----------|-------------|---------------| | ALPHA_SCISSOR | Foliage, chain-link fence | Fast | No | | ALPHA_HASH | Dithered fade, LOD transitions | Fast | Noisy | | ALPHA | Glass, water, godot-particles | Slow | Yes (render order) |

### Alpha Scissor (Cutout)

```gdscript # For leaves, grass, fences mat.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA_SCISSOR mat.alpha_scissor_threshold = 0.5 # Pixels < 0.5 alpha = discarded mat.albedo_texture = load("res://leaf.png") # Must have alpha channel

# Enable backface culling for performance mat.cull_mode = BaseMaterial3D.CULL_BACK ```

### Alpha Hash (Dithered)

```gdscript # For smooth fade-outs without sorting issues mat.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA_HASH mat.alpha_hash_scale = 1.0 # Dither pattern scale

# Animate fade var tween := create_tween() tween.tween_property(mat, "albedo_color:a", 0.0, 1.0) ```

### Alpha Blend (Full Transparency)

```gdscript # For glass, water (expensive) mat.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA mat.blend_mode = BaseMaterial3D.BLEND_MODE_MIX

# Disable depth writing for correct blending mat.depth_draw_mode = BaseMaterial3D.DEPTH_DRAW_DISABLED mat.cull_mode = BaseMaterial3D.CULL_DISABLED # Show both sides ```

---

## Texture Channel Packing

**MANDATORY** [`pbr_orm_packer.gd`](scripts/pbr_orm_packer.gd) for R=AO / G=Roughness / B=Metallic. Do not inline packing recipes here. Custom channel remaps only when an imported atlas already disagrees with ORM layout.

---

## Shader Conversion

### When to Convert to ShaderMaterial

- Need custom effects (dissolve, vertex displacement) - StandardMaterial3D limitations hit - Shader optimizations (remove unused features)

### Conversion Workflow

```gdscript # 1. Create StandardMaterial3D with all settings var std_mat := StandardMaterial3D.new() std_mat.albedo_color = Color.RED std_mat.metallic = 1.0 std_mat.roughness = 0.2

# 2. Convert to ShaderMaterial var shader_mat := ShaderMaterial.new() shader_mat.shader = load("res://custom_shader.gdshader")

# 3. Transfer parameters manually shader_mat.set_shader_parameter("albedo", std_mat.albedo_color) shader_mat.set_shader_parameter("metallic", std_mat.metallic) shader_mat.set_shader_parameter("roughness", std_mat.roughness) ```

---

## Material Variants (Godot 4.0+)

### Efficient Material Reuse

```gdscript # Base material (shared) var base_red_metal := StandardMaterial3D.new() base_red_metal.albedo_color = Color.RED base_red_metal.metallic = 1.0

# Variant 1: Rough var rough_variant := base_red_metal.duplicate() rough_variant.roughness = 0.8

# Variant 2: Smooth var smooth_variant := base_red_metal.duplicate() smooth_variant.roughness = 0.1

# Note: Use resource_local_to_scene for per-instance tweaks ```

---

## Performance Optimization

### Material Batching

```gdscript # ✅ GOOD: Reuse materials across meshes const SHARED_STONE := preload("res://materials/stone.tres")

func _ready() -> void: for wall in get_tree().get_nodes_in_group("stone_walls"): wall.material_override = SHARED_STONE # All walls batched in single draw call

# ❌ BAD: Unique material per mesh func _ready() -> void: for wall in get_tree().get_nodes_in_group("stone_walls"): var mat := StandardMaterial3D.new() # New material! mat.