threejs-syntax-materials

Quick Reference

Material Type Decision Tree

Base Material Properties (All Materials)

Base Material Methods

Critical Warnings

NEVER set opacity < 1 without transparent: true -- the opacity value is silently ignored. ALWAYS pair them together.

NEVER use MeshPhysicalMaterial when MeshStandardMaterial suffices -- Physical compiles a significantly larger shader. ONLY use it when you need clearcoat, transmission, sheen, iridescence, or anisotropy.

NEVER set SRGBColorSpace on normal maps, roughness maps, metalness maps, or any data texture -- this corrupts the data and causes incorrect lighting. ONLY set SRGBColorSpace on diffuse/color/emissive textures.

NEVER forget to call material.dispose() and texture.dispose() when removing objects -- GPU memory leaks accumulate and crash the application.

NEVER set linewidth > 1 on LineBasicMaterial -- it is silently ignored on most platforms due to WebGL limitations. ALWAYS use Line2 + LineMaterial from three/addons/lines/ for thick lines.

ALWAYS set material.needsUpdate = true after changing properties that affect shader compilation (e.g., toggling flatShading, changing side, adding/removing texture maps at runtime).

ALWAYS set wrapS and wrapT to RepeatWrapping when using texture.repeat values other than (1, 1) -- the default ClampToEdgeWrapping does NOT tile textures.

MeshStandardMaterial (PBR)

The recommended material for most 3D scenes. Uses physically-based metalness/roughness workflow.

import { MeshStandardMaterial, TextureLoader, SRGBColorSpace, RepeatWrapping } from 'three';

const loader = new TextureLoader();
const material = new MeshStandardMaterial({
  color: 0xffffff,
  roughness: 0.7,           // 0 = mirror, 1 = fully rough
  metalness: 0.0,           // 0 = dielectric, 1 = metal
  map: null,                // Diffuse/albedo texture
  roughnessMap: null,       // Per-pixel roughness
  metalnessMap: null,       // Per-pixel metalness
  normalMap: null,          // Surface normal perturbation
  normalScale: new Vector2(1, 1),
  aoMap: null,              // Ambient occlusion (requires uv2)
  aoMapIntensity: 1.0,
  emissive: 0x000000,       // Emissive color
  emissiveMap: null,        // Emissive texture
  emissiveIntensity: 1.0,
  envMap: null,             // Environment reflection map
  envMapIntensity: 1.0,
  bumpMap: null,            // Grayscale height map
  bumpScale: 1.0,
  displacementMap: null,    // Vertex displacement map
  displacementScale: 1.0,
  displacementBias: 0.0,
  alphaMap: null,           // Per-pixel transparency
  lightMap: null,           // Baked lighting (requires uv2)
  lightMapIntensity: 1.0,
  flatShading: false,
  wireframe: false,
  fog: true
});

MeshPhysicalMaterial (Advanced PBR)

Extends MeshStandardMaterial with ALL its properties, plus:

Texture System

Color Space Rules (Critical)

Rule: Diffuse/emissive/color textures = SRGBColorSpace. ALL data textures = NoColorSpace. Getting this wrong causes washed-out or over-saturated rendering.

Texture Loaders

Wrapping Modes

Filter Modes

Texture Properties

flipY Rules

• flipY = true (default): Correct for loaded image textures (PNG, JPG)
• flipY = false: ALWAYS use for WebGLRenderTarget textures, DataTexture, and framebuffer textures

Material Disposal

// ALWAYS dispose materials and textures when removing objects
function disposeMesh(mesh) {
  if (mesh.material) {
    // Dispose all texture maps
    for (const key of Object.keys(mesh.material)) {
      const value = mesh.material[key];
      if (value && value.isTexture) {
        value.dispose();
      }
    }
    mesh.material.dispose();
  }
  if (mesh.geometry) {
    mesh.geometry.dispose();
  }
}

needsUpdate Flag

ALWAYS set material.needsUpdate = true after changing these at runtime:

• Toggling flatShading
• Changing side (FrontSide/BackSide/DoubleSide)
• Adding or removing a texture map (e.g., setting map from null to a texture)
• Changing transparent or alphaTest
• Toggling wireframe
• Any property that changes the compiled shader variant

NEVER set needsUpdate = true every frame -- it forces expensive shader recompilation. ONLY set it once after the property change.

For textures: set texture.needsUpdate = true after modifying texture.image data to trigger GPU re-upload.

Toon Material Special Rule

When using MeshToonMaterial, ALWAYS set gradientMap.minFilter = NearestFilter and gradientMap.magFilter = NearestFilter. Linear filtering blurs the discrete shading steps into smooth gradients, defeating the toon effect.

Reference Links

• references/methods.md -- All material types with constructor signatures and key properties
• references/examples.md -- Complete working examples (PBR, textures, multi-material)
• references/anti-patterns.md -- What NOT to do, with explanations

Official Sources

• https://threejs.org/docs/#api/en/materials/Material
• https://threejs.org/docs/#api/en/materials/MeshStandardMaterial
• https://threejs.org/docs/#api/en/materials/MeshPhysicalMaterial
• https://threejs.org/docs/#api/en/textures/Texture