3d Cloth Material

---
name: 3d-cloth-material
description: Build convincing woven cloth in Three.js, with a thread-level weave normal map, sheen and anisotropic highlights, folds that never stretch the texture, hems with thickness, stitches, seams, frayed edges, fold occlusion, dye and wear variation, and light passing through thin fabric. Use for linen, silk, wool, canvas, curtains, banners, cloaks, tablecloths, tapestries or any 3D drape that currently looks like a plastic sheet, a stretched texture, or a flat coloured plane.
---

# 3D Cloth Material

**Mechanism:** hang the cloth as rows whose *tangent angle* is the fold signal, so arc length equals the rest coordinate `s` and the weave never stretches. Then let a thread-level weave, sheen, hem thickness and light through the gaps do the reading of "fabric".

Nearest neighbours: `3d-high-resolution-textures` chooses texel density, mipmaps and delivery for any material; use it for the budget and stay here for what makes *cloth* different (weave interlacement, folds, sheen, hems). `3d-wood-material`, `3d-paper-material` and `3d-metal-material` cover their own surfaces; this skill owns woven and sewn fabric only. It is not a cloth *simulation*: for a character's flowing cape or a flag that collides, simulate (Verlet or Blender cloth) and bake, then keep the material rules below.

Extracted from KIBORI 木彫, a dark WebGL workshop where a roll of indigo canvas (the dōgu-maki) lies under a warm key light and had to survive a macro close-up. Ported from there: the weave bake, the stitch shader, half-circle hem turn-under, wear on thread tops, the sheen constants. Newly built for this skill (Kibori has one indigo canvas, not three fabrics): the tangent-angle fold curve, satin and twill interlacements, silk/wool/linen tables, tabs on the rod, raw-edge fray, fold AO, backlit transmission, wind. `demo.html` is the reference.

Demo: Three.js r169 · WebGL · GLSL (`MeshPhysicalMaterial` + `onBeforeCompile`), vanilla JavaScript, no post chain.

## The rules, each with the failure it prevents

1. **Integrate folds from an angle, not a height.** `α(s) = a·(sinθ + 0.16 sin(2θ+0.8)) + …`, then `x += ds·cos α`, `z += ds·sin α`. Failure: a height field `z = A·sin(kx)` gives arc length 1 + slope², so the weave swims and stretches 30–80% on every fold. With the angle form `uv = (s, v)` in metres is exact. Keep `|α| < 1.45` rad; past that it clamps into flat plateaus and folds become tubes with black seams.
2. **Uv is material metres, never re-fitted per frame.** Do not recompute uv from the moving surface. Failure: weave shimmers and crawls in wind. Set `texture.repeat = 1/(threads × pitch)` so one texel tile is `NT` threads; linen 1.6 mm, silk 0.7 mm, wool 2.6 mm pitch.
3. **Bake interlacement, not noise.** Each thread has its own width (0.80–0.97), tone and a slub (Gaussian thickening up to 0.34). Warp height blends over/under across cell borders by `0.5·smoothstep(0.05, 0.5, |t|)`. Plain = `(A+B)&1`, twill 2/1 = `(A+B)%3 < 2`, 5-harness satin = `(2A+B)%5 != 0` warp-over. `NT` must be a multiple of the repeat (32, 24, 40) or the tile shows a seam. Failure: a tiled noise normal map reads as stucco or leather.
4. **Spun yarn gets a twist.** Add `0.22·twist·sin(2π(5·along + 1.3·across))` to each thread height (twist 0.10–0.14 for linen and wool, 0 for silk). Failure: linen looks like wire mesh.
5. **Two dyes, per-thread tone.** Colour `mix(warpDye, weftDye, weftOnTop·shot)`; silk uses shot 1.0 (madder red warp, gold weft), the rest 0. Tone `mix(0.86, 1.14, threadTone)`, cavity `mix(0.5, 1, smoothstep(0.05, 0.85, height))`, blotch + warp-direction streaks `1 + var·((blot−0.5)·0.62 + (streak−0.5)·0.22)`. Failure: one flat albedo on a woven map looks printed.
6. **Sheen is the fabric, and it must be small.** `sheen 0.5–1.0`, `sheenRoughness 0.28 (silk) – 0.82 (wool)`, and `sheenColor = dye lightened × 0.62`. Failure: near-white `sheenColor` blows out to a milky rim under a warm key. Never set `sheen` to exactly 0 at runtime (0.0001); crossing zero recompiles the program and hitches 200+ ms.
7. **Silk gets anisotropy, wool gets fuzz.** Silk `anisotropy 0.85, roughness 0.36`; linen `0.90` rough with sheen 0.55; wool `0.96` rough with sheen 1.0. Keep `anisotropy` above 0 at creation (0.0001) so the define never flips.
8. **Fold occlusion is not optional.** Cast and receive the key's shadow map (`normalBias 0.012`, `bias −0.0004`, `DoubleSide` shadows) and add a vertex AO from the fold depth `0.62 + 0.38·smoothstep(−0.075, 0.035, zFold)` on indirect light. Failure: without both, valleys light up like the crests and the folds look painted.
9. **Edges have thickness.** Turn every free edge under on a half circle, `P = edge + out·r·sinφ − N·r(1−cosφ)`, `φ ∈ [0, 0.94π]`, `r` = 1.1 mm silk, 2.2 mm linen, 4.6 mm wool. Return the bottom hem up the back at `2r + 0.2 mm` with flipped normals. Failure: a zero-thickness cut edge is the loudest tell for CG cloth in a close-up.
10. **Stitch in the shader, in cloth metres.** Thread arches between holes (`4·x(1−x)` over 74% of the pitch), the needle groove and pucker feed the normal by finite difference, faded by `fwidth`. Hem 3 cm up, sides 2.2 cm in, seam `±7 mm` with a proud ridge that puckers every 4 pitches. Failure: geometry stitches z-fight and alias; texture-painted ones do not follow the folds.
11. **Raw edge: draw out the weft.** Beyond the cut, discard fragments except the warp threads (`|fract(u/pitch)−0.5| < 0.36`), each with a random length `F·(0.3+0.7·hash)`. Failure: an alpha fringe texture has no thread structure.
12. **Thin cloth passes light.** `emissive += trans · lightColour · dye·(1.7,1.2,0.85) · pow(max(0, −N·L), 1.15) · gap · thin` with `gap = mix(1, 0.42, height)` so threads block and gaps pass. Silk 1.05, linen 0.6, wool 0.06. Failure: without it a lit window behind a curtain does nothing.
13. **Wear where cloth is touched.** `wear = clamp(aWear·(0.25+height) + (fbm−0.5)·0.3, 0, 1)` → mix dye toward a pale colour by `wear·threadTop`. Hems +0.4, crests +0.3. Failure: uniform dye reads brand new.

## Constants

| | linen | silk | wool |
|---|---|---|---|
| weave / NT / pitch | plain / 32 / 1.6 mm | 5-harness satin / 40 / 0.7 mm | twill / 24 / 2.6 mm |
| normal strength S · normalScale | 2.6 · 1.15 | 1.5 · 0.6 | 2.9 · 1.45 |
| roughness · sheen · sheenR | 0.90 · 0.55 · 0.55 | 0.36 · 0.5 · 0.28 | 0.96 · 1.0 · 0.82 |
| fold λ · amax · wind gain | 0.34 m · 0.98 · 1.0 | 0.40 · 1.02 · 1.9 | 0.32 · 0.86 · 0.55 |
| edge | raw fray 3 cm | hem 3.5 cm | hem 5 cm |

Cloth 2.0 × 1.95 m, grid 160 × 120 (≈ 21k verts, 45k tris). Key SpotLight 0xffd0a0 × 3.0, angle 0.44, decay 0; cool fill 1.0; window back light 0.2–1.8; environment intensity 0.42; ACES, exposure 1.0.

## Gotchas, symptom first

- **Weave crawls or shimmers when it moves** → uv was rebuilt from arc length or scrolled; keep it as the rest metres.
- **Horizontal moire stripes at wide view** → bump/crease term uses `dFdx` of a high-frequency noise; keep crease octaves below 17 cycles/m and scale by 0.016. Mipmaps + 16× anisotropy handle the weave itself.
- **Folds are flat panels with black slits** → `|α|` clamped. Lower `amax` so `a·env·1.28 < 1.45`, do not add more darkness.
- **Everything glows orange when backlit** → transmission colour multiplied by a warm light *and* a warm dye. Tint by `(1.7,1.2,0.85)`, not `(2.1,1.35,0.72)`.
- **envMapIntensity does nothing** → in r163+ it only applies with `material.envMap`; with `scene.environment` use `scene.environmentIntensity`.
- **`onBeforeCompile` shader is shared between two meshes with different uniforms** → set `customProgramCacheKey`, and put uniforms on the material, not the mesh.
- **Winding wrong on a hem strip (lit inside-out)** → pick each strip's index order from the sign of its first triangle normal against the attribute normal, once, after the first update.
- **Turn-under leaves a dark gap** → the return strip must sit at `2r + 0.2 mm`, not `r`.
- **Shadow acne on a double-sided sheet** → `normalBias`, not a bigger `bias`; a large bias detaches the fold shadows.

## Lifecycle

`prefers-reduced-motion`: render one designed still at `t = 7.3` (gust mid-swell), stop the loop, keep every control live and re-render on change. Pause on `document.hidden`; reset `last` on resume. Clamp `dt` to 1/30 s, cap DPR at 2 and step it down by 0.25 when a 60-frame average exceeds 26 ms. Size from a `ResizeObserver`. Expose no per-frame allocation in the cloth loop: reuse typed arrays and update `position`/`normal` only.

## Cost (measured, headless Chrome for Testing, Apple GPU, 1440×900 at DPR 2)

- Cloth CPU (folds + normals + hems + tabs + fringe): 3.7–4.9 ms at 160×120. Halving the row count (190 → 120) bought −40%, and no fold was lost, because folds vary slowly down the drop.
- Whole frame: 10–11 ms wide, 15 ms macro. The macro's extra 4 ms is the fragment shader (weave + stitch + fbm) over the whole screen, not geometry.
- Boot: 0.8 s to first frame including three 512² weave bakes. Fabric switch 25 ms. Layer toggles 14 ms.
- Not the bottleneck: triangle count, the 2048 shadow map, tabs, fringe (520 strands).

## Score against the rubric (0 = flat coloured plane, 5 = convincing at arm's length, 10 = photographic macro)

Weave structure 7 · Sheen and dye 6.5 · Fold shape and drape 6 (a hanging curtain, not free cloth with self-contact) · Edges, stitches, seams 7.5 · Light transmission 6 · Wear 5.5 · Motion 5.5 (wind is analytic, no collision) · Performance 8. Overall 6.5. What would lift it: real self-collision folds (simulate and bake), fibre halo geometry on wool, a second normal scale for creases.