MaterialSystem creates and updates Three.js materials from a MaterialConfig, and handles texture loading, caching and disposal. Six material types are available.

Standard

The default PBR material (MeshStandardMaterial). Supports the roughness/metalness workflow, emission and all standard texture maps.

Property	Range	Default
color	hex	'#3B82F6'
roughness	0-1	0.5
metalness	0-1	0.1
emissive	hex	'#000000'
emissiveIntensity	0-3	0
opacity	0-1	1
flatShading	—	false
envMapIntensity	0-3	1

Physical (Glass)

MeshPhysicalMaterial extends Standard with transmission, clearcoat, sheen and iridescence.

Property	Range	Default
transmission	0-1	0
ior	1-2.5	1.5
thickness	0-10	0.5
clearcoat	0-1	0
clearcoatRoughness	0-1	0
sheen	0-1	0
sheenColor	hex	'#ffffff'
sheenRoughness	0-1	0.5
iridescence	0-1	0
iridescenceIOR	1-2.5	1.5
iridescenceThicknessMin / Max	—	100 / 400
specularIntensity	0-1	1
specularColor	hex	'#ffffff'

When transmission is greater than 0, transparent is set to true automatically.

Lambert and Phong

Lambert (MeshLambertMaterial) is a non-physically-based material using Lambertian reflectance. It is cheaper to render and supports color, emissive, opacity and the color and alpha maps only.

Phong (MeshPhongMaterial) uses the classic Blinn-Phong shading model with specular highlights, and also supports normal and bump maps.

Phong Property	Range	Default
phongSpecular	hex	'#ffffff'
shininess	0-1000	30

Toon and Wireframe

Toon (MeshToonMaterial) is a cel-shading material with discrete shading steps. toonSteps accepts 2, 3 or 5, defaulting to 3. A DataTexture gradient map is built by buildToonGradient() using NearestFilter, which is what produces hard transitions between bands rather than a smooth ramp.

Wireframe uses MeshStandardMaterial with wireframe: true, and supports roughness and metalness for specular response on the wire lines.

Common Properties

Property	Default	Description
transparent	false	Enables alpha blending
depthWrite	true	Whether to write to the depth buffer. Disable for transparent objects to prevent z-fighting
side	'double'	Which face sides to render — front, back or double
wireframe	false	Overlay wireframe on any material type

Material Switching

When the user switches material type, only color, opacity and transparent are preserved. Everything else resets to DEFAULT_MATERIAL_CONFIG:

handleMaterial({
  ...DEFAULT_MATERIAL_CONFIG,
  type,
  color: prev.color,
  opacity: prev.opacity,
  transparent: prev.transparent
});

All PBR-specific, Phong-specific and Toon-specific properties are lost when switching away from those types. Switching to compare looks is therefore destructive.

Texture Cache

MaterialSystem keeps a module-level Map<string, THREE.Texture> keyed by URL, so the same texture is not loaded twice across objects. The cache must be cleared manually via disposeTextureByUrl() when a texture is removed.