godot-3d-materials

Files (16)

• SKILL.md
• decal_placer_expert.gd · scripts/
• depth_precision_fix.gd · scripts/
• instance_uniform_batching.gdshader · scripts/
• material_batcher.gd · scripts/
• material_fx.gd · scripts/
• organic_material.gd · scripts/
• pbr_material_builder.gd · scripts/
• pbr_orm_packer.gd · scripts/
• shader_state_manager.gd · scripts/
• subsurface_scattering_setup.gd · scripts/
• transparency_sorting_fix.gd · scripts/
• triplanar_world.gdshader · scripts/
• triplanar_world_projection.gdshader · scripts/
• vertex_wind_sway.gdshader · scripts/
• triplanar_smooth.gdshader · shaders/

SKILL.md (first lines)

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

---

## Godot 4.7: Materials

- **AreaLight3D** pairs with emissive materials for physically correct rectangular emitters.
- `Texture2D.get_format()` unified on base class for portable compressed textures.

## Available Scripts

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

### [material_fx.gd](scripts/material_fx.gd)
Runtime material property animation for damage effects, dissolve, and texture swapping. Use for dynamic material state changes.

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

### PBR Texture Setup

```gdscript
# Create physically-based material
var mat := StandardMaterial3D.new()

# Albedo (base color)
mat.albedo_texture = load("res://textures/wood_albedo.png")
mat.albedo_color = Color.WHITE  # Tint multiplier

# Normal map (surface detail)
mat.normal_enabled = true  # CRITICAL: Must enable first
mat.normal_texture = load("res://textures/wood_normal.png")
mat.normal_scale = 1.0  # Bump strength

# ORM Texture (R=Occlusion, G=Roughness, B=Metallic)
mat.orm_texture = load("res://textures/wood_orm.png")

# Alternative: Separate textures (less efficient)
# mat.roughness_texture = load("res://textures/wood_roughness.png")
# mat.metallic_texture = load("res://textures/wood_metallic.png")
# mat.ao_texture = load("res://textures/wood_ao.png")

# Apply to mesh
$MeshInstance3D.material_override = mat
```

---

## Metallic vs Roughness

### Metal Workflow

```gdscript
# Pure metal (steel, gold, copper)
mat.metallic = 1.0
mat.roughness = 0.2  # Polished metal
mat.albedo_color = Color(0.8, 0.8, 0.8)  # Metal tint

# Rough metal (iron, aluminum)
mat.metallic = 1.0
mat.roughness = 0.7
```

### Dielectric Workflow

From bgrenat/godot-game-dev-studio, LGPL-3.0.

More from bgrenat/godot-game-dev-studio