---

name: 3d-metal-material description: Build hyperrealistic PBR metal in Three.js: steel, brass, gold, copper and iron as true conductors (metalness 1, measured F0 tint, no albedo) with roughness-varied finishes (polished, brushed anisotropic, aged with patina and worn edges) lit by a dark HDR studio of real bright window cards prefiltered with PMREM. Use when metal looks like grey plastic, a dull blur, or a black hole; when blades, tools, rings, ingots, hardware or product metal need reflections with edges and structure; or when a finish needs scratches, streaks, fingerprints and bevels that catch light.

3D Metal Material

Mechanism: a conductor has no colour of its own, so it looks like metal only when a dark environment holds a few very bright, hard-edged things to reflect, and the surface then bends those reflections with roughness that varies across it. Remove the bright cards and the same steel goes flat grey; remove the roughness variation and it goes CG-clean.

Boundary. This skill is the material and the environment it reads. Reach for 3d-specular-rim-glow when the job is one bright edge catch and halo on a product, 3d-high-resolution-textures when you ship authored PBR texture sets and need texel density and mip budgets, 3d-ultra-realistic-water for water. Siblings 3d-wood-material, 3d-cloth-material and 3d-paper-material cover the non-metal surfaces that usually sit next to metal; use them for the bench, handle or wrapping. The demo has a bench and a chisel handle only as staging.

Verified stack of the demo: Three.js r169 (three@0.169.0), WebGL 2, GLSL patched into MeshStandardMaterial/MeshPhysicalMaterial with onBeforeCompile, PMREMGenerator, a HalfFloat MSAA target and a hand-written ACES pass. No post-processing library.

Build order

Do these in order; each one fixes a named failure the previous step cannot.

1. Conductor, not painted. metalness: 1, color = the metal's F0 (linear reflectance at normal incidence), nothing else in color. A bright base colour turns lit faces into white paint, and metalness < 1 lets a diffuse term leak in as plastic.

2. A dark room with bright cards. Build the environment as a real Scene of MeshBasicMaterial planes with toneMapped:false and HDR radiance above 1, on a near-black background, then PMREMGenerator.fromScene. A bright uniform sky makes every reflection the same mean tone, and raising envMapIntensity only lifts that mean. A canvas equirect capped at display white cannot make a window brighter than the paper. Cards used in the demo:

   | card | size, position | linear radiance | | --- | --- | --- | | window, 4 x 3 panes | 1.08 x 1.20 panes on 1.30 x 1.47 pitch, at (-5, 4.2, 4.8) | 3.8, 3.55, 3.05 | | cool side card | 3.0 x 5.4 at (6, 1.6, 2) | 0.52, 0.68, 0.90 | | warm back card | 2.0 x 4.6 at (2.5, 2.2, -5.5) | 1.50, 1.22, 0.88 | | top card | 7.5 x 2.2 at (0, 6, 0) | 0.52, 0.55, 0.60 | | floor bounce | 9 x 9 at (0, -4, 0) | 0.18, 0.12, 0.07 | | background | | 0.045, 0.050, 0.060 |

3. Aim a card at the object. The eye sees the reflection of whatever lies along the mirror direction. The hero plate is turned to the bisector of eye and window (yaw -0.38, pitch -0.36 rad). Left face-on to a dark region, the same polished steel reads black.

4. Vary the roughness. Roughness is the finish, not the constant. Layer low-frequency smears (fingerprints), two angles of micro-scratches, and a fine grain into roughnessFactor, and fade each below its pixel footprint with fw = max(length(dFdx(p)), length(dFdy(p))). Uniform roughness is what makes metal look rendered.

5. Give it a bevel. Use a chamfered box (round the arrises 1 to 3 mm at object scale, 3 to 5 segments). A sharp 90 degree edge has no normals between faces, so it catches no highlight. Above 6 to 19 percent of the smallest side it reads as soap.

6. Ground it in darkness. Contact shadow blobs and a shadow-casting key light on a dark bench. Metal on a bright ground reflects the ground and loses contrast.

7. Tone map last. Render into a HalfFloat target, add the bloom, then ACES and the sRGB encode by hand. Keep renderer.toneMapping = NoToneMapping while rendering to the target.

Constants

F0 goes in color as linear values (Color.setRGB(r,g,b, LinearSRGBColorSpace)), so you do not lose the tint to an sRGB round trip.

| metal | F0 linear | aged surface tint (uPatCol) | | --- | --- | --- | | steel | 0.56, 0.57, 0.58 | rust 0.16, 0.055, 0.02 | | brass | 0.89, 0.72, 0.36 | dark tarnish 0.09, 0.055, 0.02 | | gold | 1.00, 0.71, 0.29 | dirty wear 0.13, 0.085, 0.03 | | copper | 0.95, 0.64, 0.54 | verdigris 0.10, 0.34, 0.27 |

| finish | base roughness | envMapIntensity | extra | | --- | --- | --- | --- | | polished | 0.09 (0.045 to 0.6 after variation) | 1.0 | smear +0.11, scratch +0.24, grain +-0.025 | | brushed | 0.26 (0.10 to 0.75) | 0.72 | MeshPhysicalMaterial.anisotropy 0.85, streaks 520 and 1500 cycles per unit along the grain | | aged | 0.36 (0.10 to 0.95) | 0.85 | patina lowers metalness to 0.28, raises roughness +0.42, bump 0.9 |

Intensities fall as roughness rises because a rough finish spreads the same window over more of the surface and clips it. Kibori's own steel is envMapIntensity 0.94, roughness 0.16 to 0.5, F0 0xc9ced2; its baked floor room for a polished blade uses 3.0 (the map is dim, so the gain is high).

Bloom: threshold 5.0 in linear, clamp 1.0, gain 0.22, quarter resolution. Lower thresholds turn one hot lamp glint into an orange halo above the object.

Symptom-first gotchas

• Metal looks like grey plastic, and envMapIntensity changes nothing. On r163+ material.envMapIntensity is ignored when the environment comes only from scene.environment. Set material.envMap = envTexture too, and re-bind it whenever the environment is rebuilt. Sweep it to an extreme and diff if you doubt it.
• Reflection shows a soft cloud, no window bars. PMREM fromScene renders a 256 px cube and its sigma blurs. Kibori's 0.06 unit mullions and sigma 0.025 vanished. Widen the gaps to 0.22 units and use sigma 0.006.
• Window reflection is a flat white block. ACES rolls linear 1.0 to about 204, so a window at 3.8 times F0 clips. Cut envMapIntensity for rougher finishes (table above) and let the panes read as luminous with bars, not as a paper rectangle. Measure >250 percent on the object's own mask, not on the frame.
• Polished blade reflects a black nothing. A face that looks up at a dark ceiling has nothing to show. Aim it at a card, or bake a floor room (Kibori's blade room: near black above 0.07 to 0.12, warm boards, five soft sun patches with kumiko bars, 1024 x 512 equirect, about 424 ms once) and give only that object the map.
• Rough metal goes flat and dark, not satin. Metal needs the roughness spread; a constant 0.4 with no variation is a matte grey. Add the layered terms above.
• Detail shimmers or disappears at distance. Every high-frequency term needs a footprint fade (smoothstep(0.15..0.8, fw * frequency)), or it aliases to noise. The macro shot only resolves the 0.4 mm grain because the camera is close.
• Anisotropy does nothing. It needs MeshPhysicalMaterial and UVs; streak your roughness along the same axis as anisotropyRotation, or the highlight stretches across the streaks.
• Aged patina looks like camouflage. One big fbm blob field. Multiply a large region mask, a fine fbm at about 70 cycles per unit and a dust term, and wear it off the bevels (edgeK from the object-space normal: 1 - max(|n.x|, |n.y|, |n.z|)). Drop metalness inside the patina or it stays mirror.
• A custom shader program is shared between finishes. Set customProgramCacheKey per finish, or onBeforeCompile for the second finish is never used.
• GLSL inside a JS template with a // comment. In a one-line string it comments out the rest of the shader and the mesh silently draws nothing. Use /* */.

Lifecycle and cost

• Reduced motion: no orbit, light parked at -0.3 (the window lands across the plate), one still render on every control change. Controls stay live.
• Pause on document.hidden; reset the time base on resume; clamp dt to 1/30 s; cap DPR at 2; size from a ResizeObserver.
• Measured on an Apple GPU through ANGLE Metal, 1440 x 900, 4x MSAA HalfFloat target: 1.1 ms per frame polished, 2.9 ms brushed, 3.1 ms aged at DPR 1; 9.4 and 13.0 ms at DPR 2. 13 shader programs and 9 textures alive after cycling all three finishes. The expensive part is the fragment noise on a full-screen-sized plate, not the environment. The cheap lever is DPR; the thing that does not matter is bloom at quarter resolution. Boot is about 1.4 s cold, of which the floor-room bake is 0.42 s.
• Contrast, not brightness, separates real from grey: the same plate measured mean luminance 174 under the studio and 169 under a flat grey room, but standard deviation 76 against 23.

Provenance

Extracted from KIBORI 木彫, a scroll-driven three.js woodworking film where a chisel blade, saw plate and plane iron had to hold up at macro range in a dark workshop. Ported unchanged: steelMat (forge, polish lines, lamination), buildEnvironment (with the two window changes above), chamferBox, the blade-room bake and its envMapIntensity 3.0, the crowned blade normals, the ACES pass. New in this skill: the finish layers, the metal library, the environment switch.

Self-score

Anchors: 0 flat colour, 3 PBR with a stock environment, 5 structured reflections but uniform roughness, 7 finish variation and bevels, 9 macro-legible with contact, 10 indistinguishable from a photograph.

| axis | score | evidence | | --- | --- | --- | | reflections have structure | 8 | window bars, cool and warm cards visible on plate, ball and ring | | surface texture at macro | 7 | scratches, grain and streaks resolve; no normal-mapped pitting on polished | | edge and bevel highlights | 7 | chamfer arrises catch a continuous line | | contact and darkness | 7 | shadow map plus blobs; no true AO | | tone and no blown highlights | 7 | window clips on flat plate at some angles | | overall | 7 | an honest 7; a photograph would still win on micro-pitting and dust |