3d Wood Lighting Scorecard

---
name: 3d-wood-lighting-scorecard
description: Light carved wood in a dark room in three.js, with procedural grain and pores, one warm key through a window, soft shadows that touch, light shafts, background rays and dust, then score the render out of 10 on an anchored rubric with a runnable headless scorecard and iterate until each item reaches the target. Use for oiled timber, kumiko, joinery and workshop scenes; wood that reads flat, plastic or washed out; volumetrics that lift the blacks; "score this out of 10"; or "get the lighting to 8".
---

# 3D Wood Lighting Scorecard

Wood only looks like wood under one directional key raking across a dark room, so the grain, the shadow seam and the light shafts are lit by the same window, tone-mapped once at the end, and each is measured on the finished frame instead of judged by mood.

Verified stack: Three.js r169 (unpkg), WebGL2, GLSL patched into `MeshPhysicalMaterial.onBeforeCompile`, a half-float MSAA target and a hand-written ACES pass. The demo is `demo.html`; the numbers are `references/`.

Boundaries. This is the lighting-and-material layer for one lit interior. For sun shafts that must be cut by real trees and rooflines use `3d-sky-rays` (screen-space occlusion); here the shafts are authored planes. For scanned or painted PBR maps, texel budgets and delivery use `3d-high-resolution-textures`; here the wood is procedural from one shared 1024 noise field. For a bright rim on dark metal use `3d-specular-rim-glow`; for glass use the studio-box ladder, not this. For the scoring habit alone use `workflow-score-to-target`; this skill supplies the wood rubric and the machine that measures it.

Extracted from Kibori (木彫), a scroll-driven WebGL woodworking page: its `woodMat`, `buildEnvironment`, key rig, shaft planes, dust and final pass are ported, with the window moved to where the shafts need it.

## Build order

1. Renderer: `NoToneMapping`, `LinearSRGBColorSpace`, `HalfFloatType` target with `samples: 4`, `autoClear = false`. Draw everything, additive shafts and dust included, into that target. Tone-map once in a last full-screen pass.
2. One window. Put the emissive paper, the key light's direction, the shaft planes, and the window card in the PMREM environment on the same line. Nothing else.
3. Key `DirectionalLight` 0xfff2df, intensity 2.0, 4096 shadow map (2048 under 820 px), `normalBias` 0.0045 (0.0085 at 2048), `bias` -0.00025, `shadowMap.autoUpdate = false` for a static room. Let a real wall with a real opening cast: the pool of light on the bench is then the window's shape.
4. Fill 0xaec7df 0.60-0.76 from the camera side, rim 0xffdeb4 0.72 from behind, hemisphere 0xb5c5d7 / 0x35281c 0.19. These only keep the shaded flank alive; they are not the look.
5. Wood: `MeshPhysicalMaterial` `ior 1.43`, `specularIntensity 0.72`, roughness `clamp(base * W.rough, 0.35, 1)`, procedural albedo/roughness/bump from one periodic noise field baked once (1024x1024 RGBA8, 64 cells, three octaves, mipmapped, repeat).
6. Shafts, then dust, then the last pass, then run `references/scorecard.mjs`.

## Rules, each with the failure it prevents

**Grain vanishes under flat light.** A hemisphere or environment that is bright enough to see the room fills every pore and the board reads as painted. Keep the key at 2.0 and the ambient terms low; measured here, turning the studio reflections off raised the total score by 0.14 because they lifted the shadows. Per-material `envMapIntensity` 0.25 for the bench, 0.45 for the carved board, 0.40 default.

**`envMapIntensity` does nothing and tuning "works" on paper.** With three r163+ the material value is only read when `material.envMap` is set; `scene.environment` alone ignores it. Set `mat.envMap = env` on every wood material, and toggle a layer through the intensity, not by nulling the map (that recompiles).

**The sheen mirrors a window that is not there.** Kibori hung its environment window at front-left; a scene whose window is behind-left reflects a light that does not exist. Place the environment window pane group where the real window is (here `(-2.3, 4.3, -3.2)`, scale 0.5, 12 panes 1.24x1.38 at radiance 3.8/3.55/3.05). Tilt the board so the mirror direction lands a little off the window (0.27 rad here; at exactly the mirror angle the whole board turns milky).

**Volumetrics wash the blacks and the grain.** Additive planes add light to everything behind them, including the top of the timber they cross. Fade each shaft by world height (`smoothstep(0.02, 0.34, y)`), keep the gain at 0.13 (Kibori 0.12) and the brightness above the reference strip under 35 levels, and read the black point: `p1` must stay under 7. Before the height fade, gain 0.14 laid a milky haze across the plaque and the grain went with it.

**A hard wedge where a shaft plane cuts a solid.** The plane intersects the bench or the post and draws a bright line. Kibori kept planes behind the benches; the height fade above does it without moving them. Also `clamp` before `pow`: `pow(1.0 - across, 2.2)` with a hair-negative edge coordinate is NaN and NaN through additive blending is a black wedge.

**God rays clip.** If the renderer tone-maps, or the shaft pass is added after ACES, the beams either double-map or hit 1.0 flat. Sum them in linear HDR, then run ACES once (`a=2.51 b=0.03 c=2.43 d=0.59 e=0.14`). The window paper is `toneMapped:false` linear (1.15, 0.86, 0.52); at (3.9, 3.35, 2.55) it clipped to white paper.

**Additive alpha.** `AdditiveBlending` adds alpha too. On an opaque canvas it is invisible; if the scene is ever drawn into an alpha-composited layer, use `CustomBlending` with `blendSrc One, blendDst One, blendSrcAlpha Zero, blendDstAlpha One`.

**Shadow acne on the bench, or a gap under the plaque.** Acne comes from a small negative `bias` alone; use `normalBias` scaled to the map (0.0045 at 4096, 0.0085 at 2048). A gap between object and shadow (peter-panning) is `normalBias` too high. The scorecard reads it as `contactGap`. Add a baked contact pool under each object (radial alpha 0.78, r = 0.30..1.0 smoothstep, y 0.0012); the shadow map alone leaves the seam light.

**A single-band texture shimmers at grazing angles.** Fine bands (pores at 96/88 cycles per metre, fibres 230, rays 13/115) must fade with `fwidth` of their own coordinate, and the bump must give up before the colour does (`1 - smoothstep(0.05, 0.18, vesselPx)`), or `dFdx(h)` beats into moire. The scorecard's `shimmer` is a half-pixel view shift; 1.1 here, 3+ is aliasing.

**A carved relief turns to noise.** Grooves under 12 px per period alias in the bump and sparkle against a bright environment. The seigaiha carving here uses 0.15 m cells and two rings per circle (about 16 px at 1440 wide); at 0.062 m it was noise at 1x and fine at 2x. Size carving to the pixel budget, not the model.

**Bricks in the grain.** Medullary-ray flecks (`rays`) on a flat-sawn top face read as a tiled grid. Kibori's 0.8 default is for quartersawn faces; on the plaque it is 0, on others 0.15.

**Banding in the dark wall.** 8-bit steps in a vignetted gradient. A +-0.0015 hash dither (`(hash - 0.5) * 0.003`) after the sRGB encode removes it; the scorecard counts runs of 6+ identical pixels (`flatRun` 0.019).

**The metric moves when the camera does.** Freeze the sway and time (`KiboriScore.freeze(true)`), render and read the canvas in the same task (no `preserveDrawingBuffer`), capture at a fixed size and DPR, and use headless Chromium; the in-app pane backgrounds itself and shares the GPU.

## Constants

| Item | Value |
|---|---|
| Camera | 34 deg vertical, (0.60, 1.25, 2.55) looking at (0.05, 0.50, -0.30); wider FOV below aspect 1 |
| Light direction | (0.40, -0.75, 0.45) normalised, window centre (-0.60, 1.40, -1.0), opening 1.5 x 1.5 |
| Target | HalfFloat, MSAA 4, DPR cap 2 |
| Key / fill / rim / hemi | 2.0 / 0.60 / 0.72 / 0.19 (Kibori fill 0.76) |
| Shafts | 5 planes 0.44-0.52 wide, length 2.75, gain 0.13, foot fade 0.22 (Kibori 0.30), fbm 3 octaves |
| Wall rays | 10 planes, 0.20-0.90 wide, length 2.2, gain 0.08 |
| Dust | 1900 points, size `17 / depth` px clamped 3.4-46, `1 - smoothstep` bokeh, gated to within ~0.33 m of a beam axis |
| Field | 1024^2 RGBA8, 64 periodic cells (`n`, `f`, second `n`), mipmapped; 16 px for the "low" toggle |
| Last pass | unsharp 0.10, vignette `0.42 + 0.58 v`, ACES, sRGB, dither 0.003 |

## Cost (measured, headless Chromium on Apple Silicon, Metal)

Full pipeline, one frame plus a 1 px readback: 7.4-7.9 ms at 1440x900 x1, 16.5 ms at 2880x1800 (DPR 2), 7.2 ms at 390x844 DPR 2. The shaft and wall-ray planes are the dearest layer (a 3-octave fbm per additive pixel: about 1 ms at x1, 5 ms at x2); the shadow map is free after the first frame because it is static; grain, env, key and dust are each about 0.2-0.7 ms. The cheap lever is the fbm octave count on the shafts (or drawing them at half resolution), not fewer planes. Do not conclude from one toggle: at 2x the noise between runs is about 1 ms.

## Scoring loop

1. Serve the page, `npm i playwright-core`, run `node references/scorecard.mjs` (`--url`, `--size 1440x900`, `--dpr 1`, `--target 8`, `--no-ablate`, `--sync`). It captures headless, freezes time, scores the eight items in `references/rubric.md`, ablates each layer and writes JSON; exit code 1 if any item is short.
2. Score the baseline before changing anything (all layers off: 3.7 here) and keep the file. The ablation is the check on the metrics: a layer whose removal raises the total is either measured wrongly or not earning its cost.
3. Fix the lowest item's cheapest sub-metric first, re-run at the same size and DPR, and keep only what the picture confirms. Look at a 2x crop after every metric-driven change; three of this demo's "improvements" raised a number and made the board look worse (full-board clearcoat, anisotropy 0.3, per-pixel tone gain 2.4) and were reverted.
4. For a score that means "looks right", hand the captures and the rubric to a fresh judge that has not seen the numbers, and take the lower of the two.
5. Report honestly. Demo, 1440x900 x1: 8.8 average; grain 8.1, key/fill 10, shadows 9.6, shafts 8.0, rays 8.8, tone 9.8, texture 9.7, specular 6.5 (short of 8: the sheen is broad, not a distinct highlight, and the fixes that added one damaged the grain). At DPR 2 the specular item is 7.4 and shafts 7.3 (dust specks finer than the measuring window).

## Accessibility and lifecycle

- `prefers-reduced-motion`: a designed still (time fixed at 5.2, no sway, no dust drift), rendered on demand; the layer switches and the score still work.
- Pause on `document.hidden` and when the canvas leaves the viewport; `dt` clamped to 1/30 s, and the first frame after a pause has `dt = 0`.
- Size from a `ResizeObserver`; DPR capped at 2; target and dust point size follow it.
- Layer switches are real checkboxes with visible focus; the score is an `aria-live` region.
- Below 820 px the panel moves under the canvas and a score chip sits on it.

## Verify

- The metrics block in `demo.html` equals `references/metrics.js` (`node scorecard.mjs --sync`).
- 1440x900 and 390x844, console clean, reduced motion shows a composed frame, tab order reaches every switch.
- A scorecard JSON with baseline, all-on, ablation and cost exists and matches the claims above.