SKILL.md
$2a
Material
Use Case
Lighting
MeshBasicMaterial
Unlit, flat colors, wireframes
No
MeshLambertMaterial
Matte surfaces, performance
Yes (diffuse only)
MeshPhongMaterial
Shiny surfaces, specular highlights
Yes
MeshStandardMaterial
PBR, realistic materials
Yes (PBR)
MeshPhysicalMaterial
Advanced PBR, clearcoat, transmission
Yes (PBR+)
MeshToonMaterial
Cel-shaded, cartoon look
Yes (toon)
MeshNormalMaterial
Debug normals
No
MeshDepthMaterial
Depth visualization
No
ShaderMaterial
Custom GLSL shaders
Custom
RawShaderMaterial
Full shader control
Custom
MeshBasicMaterial
No lighting calculations. Fast, always visible.
const material = new THREE.MeshBasicMaterial({
color: 0xff0000,
transparent: true,
opacity: 0.5,
side: THREE.DoubleSide, // FrontSide, BackSide, DoubleSide
wireframe: false,
map: texture, // Color/diffuse texture
alphaMap: alphaTexture, // Transparency texture
envMap: envTexture, // Reflection texture
reflectivity: 1, // Env map intensity
fog: true, // Affected by scene fog
});MeshLambertMaterial
Diffuse-only lighting. Fast, no specular highlights.
const material = new THREE.MeshLambertMaterial({
color: 0x00ff00,
emissive: 0x111111, // Self-illumination color
emissiveIntensity: 1,
map: texture,
emissiveMap: emissiveTexture,
envMap: envTexture,
reflectivity: 0.5,
});MeshPhongMaterial
Specular highlights. Good for shiny, plastic-like surfaces.
const material = new THREE.MeshPhongMaterial({
color: 0x0000ff,
specular: 0xffffff, // Highlight color
shininess: 100, // Highlight sharpness (0-1000)
emissive: 0x000000,
flatShading: false, // Flat vs smooth shading
map: texture,
specularMap: specTexture, // Per-pixel shininess
normalMap: normalTexture,
normalScale: new THREE.Vector2(1, 1),
bumpMap: bumpTexture,
bumpScale: 1,
displacementMap: dispTexture,
displacementScale: 1,
});MeshStandardMaterial (PBR)
Physically-based rendering. Recommended for realistic results.
const material = new THREE.MeshStandardMaterial({
color: 0xffffff,
roughness: 0.5, // 0 = mirror, 1 = diffuse
metalness: 0.0, // 0 = dielectric, 1 = metal
// Textures
map: colorTexture, // Albedo/base color
roughnessMap: roughTexture, // Per-pixel roughness
metalnessMap: metalTexture, // Per-pixel metalness
normalMap: normalTexture, // Surface detail
normalScale: new THREE.Vector2(1, 1),
aoMap: aoTexture, // Ambient occlusion (uses uv2!)
aoMapIntensity: 1,
displacementMap: dispTexture, // Vertex displacement
displacementScale: 0.1,
displacementBias: 0,
// Emissive
emissive: 0x000000,
emissiveIntensity: 1,
emissiveMap: emissiveTexture,
// Environment
envMap: envTexture,
envMapIntensity: 1,
// Other
flatShading: false,
wireframe: false,
fog: true,
});
// Note: aoMap requires second UV channel
geometry.setAttribute("uv2", geometry.attributes.uv);MeshPhysicalMaterial (Advanced PBR)
Extends MeshStandardMaterial with advanced features.
const material = new THREE.MeshPhysicalMaterial({
// All MeshStandardMaterial properties plus:
// Clearcoat (car paint, lacquer)
clearcoat: 1.0, // 0-1 clearcoat layer strength
clearcoatRoughness: 0.1,
clearcoatMap: ccTexture,
clearcoatRoughnessMap: ccrTexture,
clearcoatNormalMap: ccnTexture,
clearcoatNormalScale: new THREE.Vector2(1, 1),
// Transmission (glass, water)
transmission: 1.0, // 0 = opaque, 1 = fully transparent
transmissionMap: transTexture,
thickness: 0.5, // Volume thickness for refraction
thicknessMap: thickTexture,
attenuationDistance: 1, // Absorption distance
attenuationColor: new THREE.Color(0xffffff),
// Refraction
ior: 1.5, // Index of refraction (1-2.333)
// Sheen (fabric, velvet)
sheen: 1.0,
sheenRoughness: 0.5,
sheenColor: new THREE.Color(0xffffff),
sheenColorMap: sheenTexture,
sheenRoughnessMap: sheenRoughTexture,
// Iridescence (soap bubbles, oil slicks)
iridescence: 1.0,
iridescenceIOR: 1.3,
iridescenceThicknessRange: [100, 400],
iridescenceMap: iridTexture,
iridescenceThicknessMap: iridThickTexture,
// Anisotropy (brushed metal)
anisotropy: 1.0,
anisotropyRotation: 0,
anisotropyMap: anisoTexture,
// Specular
specularIntensity: 1,
specularColor: new THREE.Color(0xffffff),
specularIntensityMap: specIntTexture,
specularColorMap: specColorTexture,
});Glass Material Example
const glass = new THREE.MeshPhysicalMaterial({
color: 0xffffff,
metalness: 0,
roughness: 0,
transmission: 1,
thickness: 0.5,
ior: 1.5,
envMapIntensity: 1,
});Car Paint Example
const carPaint = new THREE.MeshPhysicalMaterial({
color: 0xff0000,
metalness: 0.9,
roughness: 0.5,
clearcoat: 1,
clearcoatRoughness: 0.1,
});MeshToonMaterial
Cel-shaded cartoon look.
const material = new THREE.MeshToonMaterial({
color: 0x00ff00,
gradientMap: gradientTexture, // Optional: custom shading gradient
});
// Create step gradient texture
const colors = new Uint8Array([0, 128, 255]);
const gradientMap = new THREE.DataTexture(colors, 3, 1, THREE.RedFormat);
gradientMap.minFilter = THREE.NearestFilter;
gradientMap.magFilter = THREE.NearestFilter;
gradientMap.needsUpdate = true;MeshNormalMaterial
Visualize surface normals. Useful for debugging.
const material = new THREE.MeshNormalMaterial({
flatShading: false,
wireframe: false,
});MeshDepthMaterial
Render depth values. Used for shadow maps, DOF effects.
const material = new THREE.MeshDepthMaterial({
depthPacking: THREE.RGBADepthPacking,
});PointsMaterial
For point clouds.
const material = new THREE.PointsMaterial({
color: 0xffffff,
size: 0.1,
sizeAttenuation: true, // Scale with distance
map: pointTexture,
alphaMap: alphaTexture,
transparent: true,
alphaTest: 0.5, // Discard pixels below threshold
vertexColors: true, // Use per-vertex colors
});
const points = new THREE.Points(geometry, material);LineBasicMaterial & LineDashedMaterial
// Solid lines
const lineMaterial = new THREE.LineBasicMaterial({
color: 0xffffff,
linewidth: 1, // Note: >1 only works on some systems
linecap: "round",
linejoin: "round",
});
// Dashed lines
const dashedMaterial = new THREE.LineDashedMaterial({
color: 0xffffff,
dashSize: 0.5,
gapSize: 0.25,
scale: 1,
});
// Required for dashed lines
const line = new THREE.Line(geometry, dashedMaterial);
line.computeLineDistances();ShaderMaterial
Custom GLSL shaders with Three.js uniforms.
const material = new THREE.ShaderMaterial({
uniforms: {
time: { value: 0 },
color: { value: new THREE.Color(0xff0000) },
texture1: { value: texture },
},
vertexShader: `
varying vec2 vUv;
uniform float time;
void main() {
vUv = uv;
vec3 pos = position;
pos.z += sin(pos.x * 10.0 + time) * 0.1;
gl_Position = projectionMatrix * modelViewMatrix * vec4(pos, 1.0);
}
`,
fragmentShader: `
varying vec2 vUv;
uniform vec3 color;
uniform sampler2D texture1;
void main() {
// Use texture2D() for GLSL 1.0, texture() for GLSL 3.0 (glslVersion: THREE.GLSL3)
vec4 texColor = texture2D(texture1, vUv);
gl_FragColor = vec4(color * texColor.rgb, 1.0);
}
`,
transparent: true,
side: THREE.DoubleSide,
});
// Update uniform in animation loop
material.uniforms.time.value = clock.getElapsedTime();Built-in Uniforms (auto-provided)
// Vertex shader
uniform mat4 modelMatrix; // Object to world
uniform mat4 modelViewMatrix; // Object to camera
uniform mat4 projectionMatrix; // Camera projection
uniform mat4 viewMatrix; // World to camera
uniform mat3 normalMatrix; // For transforming normals
uniform vec3 cameraPosition; // Camera world position
// Attributes
attribute vec3 position;
attribute vec3 normal;
attribute vec2 uv;RawShaderMaterial
Full control - no built-in uniforms/attributes.
const material = new THREE.RawShaderMaterial({
uniforms: {
projectionMatrix: { value: camera.projectionMatrix },
modelViewMatrix: { value: new THREE.Matrix4() },
},
vertexShader: `
precision highp float;
attribute vec3 position;
uniform mat4 projectionMatrix;
uniform mat4 modelViewMatrix;
void main() {
gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
}
`,
fragmentShader: `
precision highp float;
void main() {
gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0);
}
`,
});Common Material Properties
All materials share these base properties:
// Visibility
material.visible = true;
material.transparent = false;
material.opacity = 1.0;
material.alphaTest = 0; // Discard pixels with alpha < value
// Rendering
material.side = THREE.FrontSide; // FrontSide, BackSide, DoubleSide
material.depthTest = true;
material.depthWrite = true;
material.colorWrite = true;
// Blending
material.blending = THREE.NormalBlending;
// NormalBlending, AdditiveBlending, SubtractiveBlending, MultiplyBlending, CustomBlending
// Stencil
material.stencilWrite = false;
material.stencilFunc = THREE.AlwaysStencilFunc;
material.stencilRef = 0;
material.stencilMask = 0xff;
// Polygon offset (z-fighting fix)
material.polygonOffset = false;
material.polygonOffsetFactor = 0;
material.polygonOffsetUnits = 0;
// Misc
material.dithering = false;
material.toneMapped = true;Multiple Materials
// Assign different materials to geometry groups
const geometry = new THREE.BoxGeometry(1, 1, 1);
const materials = [
new THREE.MeshBasicMaterial({ color: 0xff0000 }), // right
new THREE.MeshBasicMaterial({ color: 0x00ff00 }), // left
new THREE.MeshBasicMaterial({ color: 0x0000ff }), // top
new THREE.MeshBasicMaterial({ color: 0xffff00 }), // bottom
new THREE.MeshBasicMaterial({ color: 0xff00ff }), // front
new THREE.MeshBasicMaterial({ color: 0x00ffff }), // back
];
const mesh = new THREE.Mesh(geometry, materials);
// Custom groups
geometry.clearGroups();
geometry.addGroup(0, 6, 0); // start, count, materialIndex
geometry.addGroup(6, 6, 1);Environment Maps
// Load cube texture
const cubeLoader = new THREE.CubeTextureLoader();
const envMap = cubeLoader.load([
"px.jpg",
"nx.jpg", // positive/negative X
"py.jpg",
"ny.jpg", // positive/negative Y
"pz.jpg",
"nz.jpg", // positive/negative Z
]);
// Apply to material
material.envMap = envMap;
material.envMapIntensity = 1;
// Or set as scene environment (affects all PBR materials)
scene.environment = envMap;
// HDR environment (recommended)
import { RGBELoader } from "three/examples/jsm/loaders/RGBELoader.js";
const rgbeLoader = new RGBELoader();
rgbeLoader.load("environment.hdr", (texture) => {
texture.mapping = THREE.EquirectangularReflectionMapping;
scene.environment = texture;
scene.background = texture;
});Material Cloning and Modification
// Clone material
const clone = material.clone();
clone.color.set(0x00ff00);
// Modify at runtime
material.color.set(0xff0000);
material.needsUpdate = true; // Only needed for some changes
// When needsUpdate is required:
// - Changing flat shading
// - Changing texture
// - Changing transparent
// - Custom shader code changesPerformance Tips
- Reuse materials: Same material = batched draw calls
- Avoid transparent when possible: Transparent materials require sorting
- Use alphaTest instead of transparency: When applicable, faster
- Choose simpler materials: Basic > Lambert > Phong > Standard > Physical
- Limit active lights: Each light adds shader complexity
// Material pooling
const materialCache = new Map();
function getMaterial(color) {
const key = color.toString(16);
if (!materialCache.has(key)) {
materialCache.set(key, new THREE.MeshStandardMaterial({ color }));
}
return materialCache.get(key);
}
// Dispose when done
material.dispose();See Also
threejs-textures- Texture loading and configuration
threejs-shaders- Custom shader development
threejs-lighting- Light interaction with materials