Skip to main content
skill CX Codex

3d-wood-lighting-scorecard — Claude Code skill for wood lighting

3d-wood-lighting-scorecard sets up lighting, procedural wood grain and volumetric shafts in Three.js, then scores the render against a rubric and iterates until each item hits target.

MIT ★ 7,995 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add MengTo/Skills --skill 3d-wood-lighting-scorecard -a claude-code
Open on GitHub

What 3d-wood-lighting-scorecard does

Builds a carved-wood scene in a dark room: one warm key through a window, procedural pores and fibres from a shared 1024×1024 noise field, soft shadows, light shafts and dust. Renders into a HalfFloatType MSAA buffer, ACES tone-mapping once at the end. Then runs references/scorecard.mjs, a headless script that measures shadow contact, shimmer, black-point lift and clip on the final frame, scores each item and iterates until target is met.

Verified on Three.js r169 (unpkg), WebGL2, GLSL patches MeshPhysicalMaterial.onBeforeCompile. Without Puppeteer or a way to capture frames headlessly, the scorecard will not run. Wood reads flat when fill raises the shadows — the skill keeps envMapIntensity under 0.45, the key at 2.0, and fades volumetric rays by height so they do not lift the black point above 7. Extracted from Kibori, a scroll-driven WebGL woodworking page.

What it helps with

  • set up procedural wood with pores and fibres from one noise field
  • build light shafts and dust without lifting the black point above 7
  • score a Three.js render against a rubric and iterate to target
  • remove shimmer on fine relief at grazing angles with fwidth
  • balance key, shadow and ambient so grain remains visible

Example prompts for the agent

  • Build a carved wood scene with window light following 3d-wood-lighting-scorecard
  • Run the render through the scorecard and get lighting to 8
  • Add volumetric shafts and dust, keeping the black point under 7

How to install 3d-wood-lighting-scorecard

1Skills CLI (Vercel)

npx skills add MengTo/Skills --skill 3d-wood-lighting-scorecard -a claude-code

2Manually: put the files in place

~/.claude/skills/3d-wood-lighting-scorecard/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/3d-wood-lighting-scorecard/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about 3d-wood-lighting-scorecard

How to install 3d-wood-lighting-scorecard in Claude Code?

Run npx skills add MengTo/Skills --skill 3d-wood-lighting-scorecard -a claude-code. The skill will land in ~/.claude/skills/3d-wood-lighting-scorecard/SKILL.md.

What does 3d-wood-lighting-scorecard do?

Sets up lighting, procedural textures and shadows for carved wood in Three.js, then measures contact, shimmer and brightness via a headless script and iterates until the score hits target.

What does the scorecard need to run?

The headless script references/scorecard.mjs needs Puppeteer or another way to run WebGL without a window and capture a frame. Without that, scoring will not work.

Source text

SKILL.md · MIT
---
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.

© MengTo · MIT · MengTo/Skills

Similar skills

All skills for Game dev and 3D: Unity, Unreal, Godot, Blender →

From the same set178

The whole set →
3d-cloth-material The 3d-cloth-material skill guides Claude Code in building woven, folded fabric materials for Three.js. Use it for cloth with visible seams, hems, sheen, or light transmission. CX Codex +1 ★ 7,995repo stars 3d-underwater-god-rays 3d-underwater-god-rays adds volumetric sun shafts under water in Three.js: one drifting wave field marched along every view ray, so the beams converge on the sun. CX Codex +1 ★ 7,995repo stars 3d-metal-material 3d-metal-material builds realistic PBR metals in Three.js using conductor physics, measured F0 linear values, dark HDR studio setups with PMREM, and layered roughness noise. CX Codex +1 ★ 7,995repo stars 3d-wood-material 3d-wood-material is a Claude Code skill that builds a procedural timber material for Three.js, with growth rings, pores, medullary rays, checks and tool marks from one noise field, without image textures. CX Codex +1 ★ 7,995repo stars html-demo The html-demo skill generates live, step-by-step UI simulations in pure HTML and React instead of video recordings. It keeps text crisp at any display scaling and supports step jumping. CX Codex +1 ★ 7,995repo stars illustration-vintage-emblem illustration-vintage-emblem creates hand-authored SVG badges with a vintage screen-print look. Use it for emblems, posters, stickers, release cards, 404 pages, and team artwork. CX Codex +1 ★ 7,995repo stars illustration-teal-spot illustration-teal-spot draws one hero object as a 480x360 SVG card in teal on white. Built for empty states, onboarding steps and blog headers. CX Codex +1 ★ 7,995repo stars illustration-outlined-cartoon illustration-outlined-cartoon generates hand-crafted cartoon SVG spot illustrations with warm dark ink outlines. It helps create friendly characters and mascots for onboarding, error pages, or feature cards. CX Codex +1 ★ 7,995repo stars

Project sponsors

Companies that keep this analytics open