MTL material fidelity: specular, alpha maps, Pr/Pm — #1575 items 1, 2 (scalars) and 3

[obiot]

Items 1 and 3 of #1575. The MTL parser recognised around twenty properties and consumed five, so an authored highlight was read and thrown away and an alpha map was rejected outright — while both destinations already existed in the engine.

Specular — Ks + Ns

The lit mesh path was half-Lambert diffuse plus an ambient floor, so every material read as chalk whatever the .mtl said. It now carries a Blinn-Phong term, exposed as mesh.specular / mesh.shininess.

Two decisions worth calling out, because both are places the obvious implementation is wrong:

• Gated on the exponent, not the colour. Ns of 0 is the format's "no highlight", and exporters routinely write a bright Ks beside it. Reading the colour alone would put a full-strength highlight on every matte material in the wild.
• Masked by the unwrapped Lambert term. Half-Lambert deliberately lifts the shadowed side; reusing it for specular would light a highlight on a surface facing away from the light.

The eye position the half-vector needs is derived from the view matrix as -Rᵀ·t rather than plumbed from the camera, so it stays correct for any caller that sets a view directly.

Per-texel opacity — map_d

alphaCutoff could only threshold uniformly across a material; map_d cuts to the shape of a leaf, a fence, a perforation. It rides mesh.alphaMap, is fetched automatically by the MTL loader alongside map_Kd, and multiplies alpha before the cutout — the other order cuts nothing out, because a fragment that survived the test keeps its alpha whatever the map says.

Both backends sample unconditionally and weight by a flag rather than branching. One backend branching and the other not is exactly how the emissive early-return diverged in #1572, and weighting also keeps the WGSL sample in uniform control flow.

WebGPU needed the second texture: group 1 for the mesh family grows from two bindings to four, and MeshUniforms from 176 to 208 bytes (specular = rgb + exponent, eye = camera world position). A mesh with no map binds its own diffuse texture as filler — no extra unit, no extra upload — and the bind-group cache is keyed on the alpha record object, so one diffuse shared by two meshes with different masks cannot hand the second mesh the first's cut-outs.

Widening the layout does not break the documented custom-WGSL mesh contract from #1564: a module may declare a subset of its layout's bindings, so an existing custom mesh shader declaring only texture+sampler still validates.

glTF metallic/roughness → the same terms

The loader read baseColorTexture, baseColorFactor and the sampler wrap, and stopped — it never touched metallicFactor or roughnessFactor, though every glTF asset carries them. They now map onto the terms this PR adds: roughness → exponent through the usual GGX bridge, metallic → tint between the dielectric F0 and the base colour.

This is an approximation onto a stylized shading model, not a PBR implementation, and it is deliberately inert by default: the glTF default roughness of 1 lands on exactly 0, so a material that declares nothing shades exactly as before.

It changes no existing example. Every glTF asset in this repo — platformer-diorama.glb (44 materials), character.glb, forest.glb — is authored fully rough, so nothing in the gallery moves a pixel. This unblocks assets users bring in from Blender; it does not improve what ships.

Also folded in

• packages/examples/LICENSE.md had the multiMaterialMesh attribution cut mid-sentence by the Water Overworld paragraph (pre-existing).
• The Mesh: bind per-material textures at draw for multi-material models #1573 unit-exhaustion spec cleared the shared session renderer's unit assignments without emitting GPU_TEXTURE_CACHE_RESET, leaving every batcher's boundTextures claiming units the cache no longer considered assigned — the next getUnit could hand one to a texture that never got bound.

Example

The Per-material Textures example is reworked into a Camera3d scene showing every piece at once: the crate for #1573, a chrome ball for the highlight (smooth because its normals are generated — #1572), and a perforated panel for the cutout. Textures regenerated at 256×256 with antiAlias on; at 64×64 they were magnified into blocks. Verified rendering identically on WebGL and WebGPU.

Verification

• +31 tests, adversarial where the trap is silent: a bright Ks with Ns 0, an Ns with no Ks, the sample-before-cutout ordering pinned across all four shader sources, the specular/emissive uniform offsets, one diffuse with two masks, and the glTF defaults. That last one caught a real bug: a malformed roughnessFactor made the exponent NaN, failed the > 0 test, and fell into the mirror-smooth branch — turning a broken file into chrome.
• A performance regression caught and fixed: the four new uniforms were set unconditionally per draw while every other uniform in that method is change-guarded, which timed out a fuzz spec. All four are guarded now.
• WGSL validated on a real device — both tiers plus all four derived instanced variants, zero compilation messages. The in-tree validation spec skips without a device, so this was done out of band.
• Full suite 232 files / 5772 passed, eslint 0 errors, biome clean, build clean, examples tsc clean.

Not in scope

#1575 items 2 (Pr/Pm as a real PBR model) and 4 (Ka/illum) remain open, as does #1574 (normal maps) — which will reuse the second-texture plumbing this PR introduces.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QVjYzf76AEU3wJk766JAQi

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.