Godot 3D Materials

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

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

material_fx.gd

MANDATORY for runtime FX. ensure_unique_override() / overlay flash / scissor dissolve — never tween shared .tres materials.

pbr_material_builder.gd

Runtime PBR material creation with ORM textures and triplanar mapping.

organic_material.gd

Subsurface scattering and rim lighting setup for organic surfaces (skin, leaves). Use for realistic character or vegetation materials.

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

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

High-performance GPU-driven foliage animation. Uses vertex world coordinates and vertex color weight painting to simulate wind without skeletons.

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

Configuring realistic organic materials. Covers Skin Mode, Transmittance, and depth scattering settings for Forward+ rendering.

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

Dynamic 3D decal system with cull masking and life-cycle management for impact effects.

transparency_sorting_fix.gd

Solving visual artifacts using Alpha Hash and Depth Prepass strategies.

shader_state_manager.gd

Clean pattern for toggling shader-based visual states (Frozen, Burned) on multiple entities.

depth_precision_fix.gd

Camera-side fix for Z-fighting and texture flickering in large-scale worlds.

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; 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 + subsurface_scattering_setup.gd (Forward+ only for real SSS).
5. Runtime flash/dissolve → MANDATORY material_fx.gd ensure_unique_override() first.
6. Shared-mesh tint/variant → instance_uniform_batching.gdshader; never unique .tres per instance.
7. Distant LOD simplify / Pixel Dither fade → material_batcher.gd setup_lod_materials().
8. Check Forward+ vs Mobile feature matrix before enabling SSS/clearcoat/anisotropy.

Forward+ vs Mobile (material features)

Transparency Modes

Decision Matrix

Alpha Scissor (Cutout)

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

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

# 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 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

# 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

# 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

# ✅ 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.albedo_color = Color(0.5, 0.5, 0.5)
        wall.material_override = mat
    # Each wall is separate draw call

Texture Atlasing

# Combine multiple materials into one texture atlas
# Then use UV offsets to select regions

# material_atlas.gd
extends StandardMaterial3D

func set_atlas_region(tile_x: int, tile_y: int, tiles_per_row: int) -> void:
    var tile_size := 1.0 / tiles_per_row
    uv1_offset = Vector3(tile_x * tile_size, tile_y * tile_size, 0)
    uv1_scale = Vector3(tile_size, tile_size, 1)

Edge Cases

Normal Maps Not Working

# Problem: Forgot to enable
mat.normal_enabled = true  # REQUIRED

# Problem: Wrong texture import settings
# In Import tab: Texture → Normal Map = true

Texture Seams on Models

# Problem: Mipmaps causing seams
# Solution: Disable mipmaps for tightly-packed UVs
# Import → Mipmaps → Generate = false

Material Looks Flat

# Problem: Missing normal map or roughness variation
# Solution: Add normal map + roughness texture

mat.normal_enabled = true
mat.normal_texture = load("res://normal.png")
mat.roughness_texture = load("res://roughness.png")

Expert Techniques & Optimizations

1. LOD Transitions using Pixel Dither

When utilizing Hierarchical Level of Detail (HLOD) or Visibility Ranges to fade objects out at a distance, standard alpha blending causes severe performance hits due to overlapping transparent bounds. Instead, configure the Distance Fade mode on your material to Pixel Dither. This provides a perceptually smooth fade while remaining entirely within the high-performance opaque pipeline.