3d-metal-material

name: 3d-metal-materialdescription: 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.

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.