@netforge/engine 0.0.0-stage → 0.1.0

package/dist/runtime/styles/handdrawn/index.js

@@ -0,0 +1,94 @@
+/**
+ * HAND-DRAWN: the world as an ink-and-watercolour illustration.
+ *
+ * The library's 3D models are painted, not swapped for flat cards: every
+ * lit surface is repainted in watercolour washes from one pigment box
+ * (paint.ts), pen lines are drawn from the depth of the scene with a
+ * wandering, pressure-varied line that is redrawn eight times a second
+ * (ink.ts), the frame is printed on paper, effects are painted flecks,
+ * blots and brush rings (vfx.ts), and template ground is a painted field
+ * or a ruled yard (ground.ts). A game opts in with `game({ style:
+ * "handdrawn" })`; nothing in the game changes.
+ */
+import { Vector2, Vector4 } from "three/webgpu";
+import { uniform } from "three/tsl";
+import { paintField, paintGlow, paintPaving } from "./ground.js";
+import { inkDisplay, inkScene } from "./ink.js";
+import { handdrawnLook } from "./looks.js";
+import { paintNode, PaintWatcher } from "./paint.js";
+import { noiseTexture, paperTexture, seeded } from "./textures.js";
+import { decalLook, particleLook, ringLook } from "./vfx.js";
+/** Lines, hatching and wash borders are redrawn this many times a second (the boil). */
+export const BOIL_FPS = 8;
+/** Seconds between scans for newly loaded materials. */
+const SCAN_EVERY = 0.25;
+/** Metres one painted ground tile covers, and one paved floor tile (four slabs). */
+const GROUND_TILE = 14;
+const FLOOR_TILE = 8;
+export const handdrawnKit = {
+    id: "handdrawn",
+    needsPost: true,
+    bloom: true,
+    look: (preset) => handdrawnLook(preset),
+    attach({ renderer, scene, preset }) {
+        const noise = noiseTexture();
+        const boil = uniform(new Vector2(0, 0));
+        const dpr = uniform(1);
+        const first = handdrawnLook(preset);
+        const paint = { boil, dpr, noise, snap: uniform(0.62), hatch: uniform(1), exposure: uniform(first.paint), values: uniform(new Vector4(...first.values)), glow: uniform(first.glow) };
+        const ink = { boil, dpr, noise, paperTex: paperTexture(), lineWidth: uniform(1.9), lineStrength: uniform(0.92), wobble: uniform(1.1), paper: uniform(1) };
+        const watcher = new PaintWatcher(scene, () => paintNode(paint));
+        const rnd = seeded(97);
+        let tick = -1;
+        let lastScan = -Infinity;
+        const surfaces = new Map();
+        return {
+            post: {
+                scene: (input) => inkScene(input, ink),
+                display: (color, input) => inkDisplay(color, input, ink),
+            },
+            frame(seconds) {
+                const t = Math.floor(seconds * BOIL_FPS);
+                if (t !== tick) {
+                    tick = t;
+                    boil.value.set(rnd(), rnd());
+                }
+                dpr.value = renderer.getPixelRatio();
+                if (seconds - lastScan >= SCAN_EVERY || seconds < lastScan) {
+                    lastScan = seconds;
+                    watcher.scan();
+                }
+            },
+            setPreset(p) {
+                const l = handdrawnLook(p);
+                paint.exposure.value = l.paint;
+                paint.values.value.set(...l.values);
+                paint.glow.value = l.glow;
+            },
+            particles: particleLook(noise),
+            decals: decalLook(noise),
+            rings: ringLook(noise),
+            surface(kind) {
+                if (kind !== "ground" && kind !== "floor" && kind !== "glow")
+                    return null;
+                let t = surfaces.get(kind);
+                if (t === undefined) {
+                    t = kind === "ground" ? paintField() : kind === "floor" ? paintPaving() : paintGlow();
+                    surfaces.set(kind, t);
+                }
+                if (!t)
+                    return null;
+                if (kind === "glow")
+                    return t;
+                const c = t.clone();
+                // Metres one tile covers: the pen marks then print at about one screen pixel at the templates' camera distance.
+                c.userData = { tile: kind === "ground" ? GROUND_TILE : FLOOR_TILE };
+                return c;
+            },
+            dispose() {
+                for (const t of surfaces.values())
+                    t?.dispose();
+            },
+        };
+    },
+};

package/dist/runtime/styles/handdrawn/ink.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The hand-drawn post stages.
+ *
+ *  scene (HDR): the painted frame is read through a slow wobble, so wash
+ *    borders are never ruler-straight, and pigment pools a little darker
+ *    where one wash meets another (the wet edge of real watercolour).
+ *  display (sRGB): pen lines from the depth buffer (silhouettes heavy,
+ *    creases light) with varying pressure, small breaks and their own
+ *    wobble, redrawn a few times a second; then the frame is printed on
+ *    paper: tooth, fibres, granulation in the darker washes.
+ */
+import type { Node, Texture, UniformNode, Vector2 } from "three/webgpu";
+import type { StylePostInput } from "../kit.js";
+export interface InkUniforms {
+    readonly boil: UniformNode<"vec2", Vector2>;
+    readonly dpr: UniformNode<"float", number>;
+    /** Pen width in CSS px. */
+    readonly lineWidth: UniformNode<"float", number>;
+    /** 0..1 line opacity. */
+    readonly lineStrength: UniformNode<"float", number>;
+    /** Wobble of the washes, CSS px. */
+    readonly wobble: UniformNode<"float", number>;
+    /** 0..1 how much the paper shows. */
+    readonly paper: UniformNode<"float", number>;
+    readonly noise: Texture;
+    readonly paperTex: Texture;
+}
+/** HDR stage: wobbled read of the painted frame, darker wet edges. */
+export declare function inkScene(input: StylePostInput, u: InkUniforms): Node<"vec4">;
+/** Display stage: pen lines and paper over the graded, tone-mapped frame. */
+export declare function inkDisplay(color: Node<"vec4">, input: StylePostInput, u: InkUniforms): Node<"vec4">;

package/dist/runtime/styles/handdrawn/ink.js

@@ -0,0 +1,68 @@
+import { abs, float, luminance, max, mix, perspectiveDepthToViewZ, pow, screenUV, smoothstep, texture, vec2, vec3, vec4 } from "three/tsl";
+import { PIGMENTS } from "./palette.js";
+const hexVec = (hex) => vec3(((hex >> 16) & 255) / 255, ((hex >> 8) & 255) / 255, (hex & 255) / 255);
+/** HDR stage: wobbled read of the painted frame, darker wet edges. */
+export function inkScene(input, u) {
+    const px = input.texel;
+    // CSS pixel coordinates of this fragment.
+    const css = screenUV.div(px).div(u.dpr);
+    const n = texture(u.noise, css.div(170).add(u.boil.mul(0.37))).rg.sub(0.5).mul(2);
+    const uv = screenUV.add(n.mul(u.wobble).mul(u.dpr).mul(px));
+    const c = input.color.sample(uv);
+    // Wet edge: how much the colour changes across a few pixels.
+    const r = px.mul(u.dpr).mul(1.6);
+    const l = luminance(c.rgb);
+    const lx = luminance(input.color.sample(uv.add(vec2(r.x, 0))).rgb);
+    const ly = luminance(input.color.sample(uv.add(vec2(0, r.y))).rgb);
+    const lx2 = luminance(input.color.sample(uv.sub(vec2(r.x, 0))).rgb);
+    const ly2 = luminance(input.color.sample(uv.sub(vec2(0, r.y))).rgb);
+    const grad = abs(lx.sub(l)).add(abs(ly.sub(l))).add(abs(lx2.sub(l))).add(abs(ly2.sub(l))).div(max(l, float(0.06)));
+    // The darker side of a border collects pigment.
+    const darker = smoothstep(0, 0.02, l.mul(4).sub(lx).sub(ly).sub(lx2).sub(ly2).negate());
+    const pool = smoothstep(0.12, 0.6, grad).mul(darker).mul(0.18);
+    return vec4(c.rgb.mul(float(1).sub(pool)), c.a);
+}
+/** Display stage: pen lines and paper over the graded, tone-mapped frame. */
+export function inkDisplay(color, input, u) {
+    const px = input.texel;
+    const css = screenUV.div(px).div(u.dpr);
+    // The pen wanders on its own (lines sit a little off the washes, as when inked by hand).
+    const nw = texture(u.noise, css.div(90).add(u.boil)).rg.sub(0.5).mul(2);
+    const uv = screenUV.add(nw.mul(1.1).mul(u.dpr).mul(px));
+    // Pressure: thicker and thinner along a stroke, with an occasional lift.
+    const press = texture(u.noise, css.div(55).add(u.boil.yx)).g;
+    const width = u.lineWidth.mul(press.mul(0.8).add(0.6));
+    const lift = smoothstep(0.1, 0.24, press);
+    const o = px.mul(u.dpr).mul(width);
+    const dist = (p) => perspectiveDepthToViewZ(input.depth.sample(p).x, input.near, input.far).negate();
+    const dc = dist(uv);
+    const d1 = dist(uv.add(vec2(o.x, 0)));
+    const d2 = dist(uv.sub(vec2(o.x, 0)));
+    const d3 = dist(uv.add(vec2(0, o.y)));
+    const d4 = dist(uv.sub(vec2(0, o.y)));
+    // Silhouettes: a neighbour much further away (the line sits on the near side).
+    const far = max(max(d1.sub(dc), d2.sub(dc)), max(d3.sub(dc), d4.sub(dc)));
+    const sil = smoothstep(0.006, 0.02, far.div(dc));
+    // Creases: the surface bends (1/z is flat across a plane, so its Laplacian finds folds).
+    const wc = float(1).div(dc);
+    const lap = abs(float(1).div(d1).add(float(1).div(d2)).add(float(1).div(d3)).add(float(1).div(d4)).sub(wc.mul(4))).div(wc);
+    const crease = smoothstep(0.0035, 0.012, lap).mul(0.55);
+    // Colour edges: where one painted thing meets another at the same depth (a crowd shoulder to shoulder).
+    const lumAt = (p) => luminance(input.color.sample(p).rgb);
+    const l0 = lumAt(uv);
+    const lx = abs(lumAt(uv.add(vec2(o.x, 0))).sub(lumAt(uv.sub(vec2(o.x, 0)))));
+    const ly = abs(lumAt(uv.add(vec2(0, o.y))).sub(lumAt(uv.sub(vec2(0, o.y)))));
+    const edge = smoothstep(0.55, 1.1, max(lx, ly).div(max(l0, float(0.04)))).mul(0.6);
+    const line = max(max(sil, crease), edge).mul(lift).mul(u.lineStrength);
+    const ink = hexVec(PIGMENTS.ink);
+    let col = mix(color.rgb, ink, line);
+    // Paper: tooth and fibres everywhere, granulation where the wash is dark, a slow tone across the sheet.
+    const pp = texture(u.paperTex, css.div(512));
+    const sheet = texture(u.paperTex, css.div(2048)).g;
+    const lum = luminance(col);
+    const tooth = pow(pp.r, float(1.4));
+    const gran = mix(float(1), pp.b.mul(0.22).add(0.78), float(1).sub(lum).mul(0.9));
+    const paper = mix(float(1), tooth.mul(gran).mul(sheet.mul(0.06).add(0.97)), u.paper);
+    col = col.mul(paper);
+    return vec4(col, color.a);
+}

package/dist/runtime/styles/handdrawn/looks.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The look presets as an illustrator would paint them. Light is soft and
+ * coloured (the washes keep its hue), fog is the paper showing through,
+ * tone mapping is neutral so pigments print as mixed, and bloom is a
+ * whisper (watercolour does not glow; only lanterns and fire get a halo).
+ * `paint` is the light level the washes are cut at for that preset.
+ */
+import type { Look, LookPreset } from "../../render/presets.js";
+export interface HanddrawnLook extends Look {
+    /** Multiplier on the light level before the washes are cut. */
+    readonly paint: number;
+    /** Paint value of each wash: deep shadow, shadow, mid, light. */
+    readonly values: readonly [number, number, number, number];
+    /** Paint value where the light is hot (lanterns, fire). */
+    readonly glow: number;
+}
+export declare const HANDDRAWN_LOOKS: Record<LookPreset, HanddrawnLook>;
+export declare function handdrawnLook(preset: LookPreset): HanddrawnLook;

package/dist/runtime/styles/handdrawn/looks.js

@@ -0,0 +1,42 @@
+const neutralGrade = {
+    exposure: 1,
+    contrast: 1,
+    saturation: 1,
+    shadowTint: [1, 1, 1],
+    highlightTint: [1, 1, 1],
+    toneMapping: "neutral",
+};
+export const HANDDRAWN_LOOKS = {
+    // A nocturne: an indigo wash over the sheet, the moon cool on the tops of things, lanterns left as warm paper.
+    night: {
+        paint: 0.9,
+        values: [0.34, 0.52, 0.74, 0.94], glow: 1.3,
+        lighting: { sky: 0x8ea4e6, ground: 0x3e3c5c, hemi: 1.7, sun: 0xc4d2ff, sunIntensity: 1.6, sunDir: [-0.45, 0.85, 0.3], ambient: 0.35, ambientColor: 0x8090c8, shadowStrength: 0.55 },
+        atmosphere: { fog: 0x2e3450, skyTop: 0x1c2036, mode: "linear", near: 40, far: 120, density: 0.01, heightFog: 0, heightFogTop: 0 },
+        grade: { ...neutralGrade, saturation: 0.96, vignette: 0.34, bloomStrength: 0.28, bloomRadius: 0.35, bloomThreshold: 0.92 },
+    },
+    dusk: {
+        paint: 1,
+        values: [0.32, 0.5, 0.74, 0.95], glow: 1.2,
+        lighting: { sky: 0xffcfae, ground: 0x5a4658, hemi: 1.5, sun: 0xffb27a, sunIntensity: 2.2, sunDir: [0.7, 0.45, 0.35], ambient: 0.25, ambientColor: 0xffe0c8, shadowStrength: 0.6 },
+        atmosphere: { fog: 0x8a6a74, skyTop: 0x3a3050, mode: "linear", near: 40, far: 130, density: 0.008, heightFog: 0, heightFogTop: 0 },
+        grade: { ...neutralGrade, vignette: 0.3, bloomStrength: 0.22, bloomRadius: 0.35, bloomThreshold: 0.92 },
+    },
+    day: {
+        paint: 1,
+        values: [0.4, 0.6, 0.84, 1], glow: 1.12,
+        lighting: { sky: 0xe4ecf6, ground: 0x8a7a5a, hemi: 1.6, sun: 0xfff2dc, sunIntensity: 2.5, sunDir: [0.4, 0.9, 0.25], ambient: 0.25, ambientColor: 0xffffff, shadowStrength: 0.5 },
+        atmosphere: { fog: 0xece3cc, skyTop: 0xd8dde0, mode: "linear", near: 50, far: 170, density: 0.006, heightFog: 0, heightFogTop: 0 },
+        grade: { ...neutralGrade, vignette: 0.22, bloomStrength: 0.12, bloomRadius: 0.3, bloomThreshold: 0.96 },
+    },
+    studio: {
+        paint: 1,
+        values: [0.42, 0.62, 0.86, 1], glow: 1.1,
+        lighting: { sky: 0xffffff, ground: 0x6a6258, hemi: 1.6, sun: 0xffffff, sunIntensity: 2.2, sunDir: [0.5, 1, 0.6], ambient: 0.3, ambientColor: 0xffffff, shadowStrength: 0.45 },
+        atmosphere: { fog: 0xece3cc, skyTop: 0xe6dcc4, mode: "linear", near: 60, far: 200, density: 0.005, heightFog: 0, heightFogTop: 0 },
+        grade: { ...neutralGrade, vignette: 0.18, bloomStrength: 0.1, bloomRadius: 0.3, bloomThreshold: 0.96 },
+    },
+};
+export function handdrawnLook(preset) {
+    return HANDDRAWN_LOOKS[preset] ?? HANDDRAWN_LOOKS.studio;
+}

package/dist/runtime/styles/handdrawn/paint.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Watercolour painting for lit materials. Every lit surface keeps its own
+ * geometry, maps, skinning and vertex animation; only its final colour is
+ * repainted (the material's `outputNode`):
+ *
+ *  - its colour is pulled toward the nearest pigment in the palette, so a
+ *    pack of toy-bright models reads as one painter's box;
+ *  - the light it receives is split into a few washes (deep shadow,
+ *    shadow, mid, light, glow) with ragged, slightly wet borders, keeping
+ *    the light's hue (moonlight blue, lantern amber);
+ *  - shadows go cool, and the deepest are hatched with pen strokes that
+ *    are redrawn a few times a second.
+ *
+ * Light is read as the ratio of the lit colour to the albedo, so every
+ * light the scene has (sun, sky, lanterns, emissive glow) is honoured
+ * without touching the lighting code.
+ */
+import type { Material, Node, Object3D, Texture, UniformNode, Vector2, Vector4 } from "three/webgpu";
+export interface PaintUniforms {
+    /** Random offset re-rolled a few times a second (the boil). */
+    readonly boil: UniformNode<"vec2", Vector2>;
+    /** Render pixels per CSS pixel. */
+    readonly dpr: UniformNode<"float", number>;
+    /** 0..1 pull toward the palette. */
+    readonly snap: UniformNode<"float", number>;
+    /** Strength of the shadow hatching, 0..1. */
+    readonly hatch: UniformNode<"float", number>;
+    /** Light level multiplier before the washes are cut (per look preset). */
+    readonly exposure: UniformNode<"float", number>;
+    /** Paint value of each wash: deep shadow, shadow, mid, light (the glow is `glow`). */
+    readonly values: UniformNode<"vec4", Vector4>;
+    readonly glow: UniformNode<"float", number>;
+    readonly noise: Texture;
+}
+/** The repainted output for a lit material (assign to `material.outputNode`). */
+export declare function paintNode(u: PaintUniforms): Node<"vec4">;
+type PaintableMaterial = Material & {
+    outputNode?: Node | null;
+    metalness?: number;
+    roughness?: number;
+    flatShading?: boolean;
+};
+/** Lit materials get painted; unlit ones (flames, glows, outlines, effects) keep their colour. */
+export declare function paintable(m: Material): m is PaintableMaterial;
+/**
+ * Finds lit materials as they arrive in the scene (models load late) and
+ * paints each once. A scan walks the scene graph (a few hundred nodes; the
+ * crowds are one node per type), so it runs every few frames, not every one.
+ */
+export declare class PaintWatcher {
+    private readonly root;
+    private readonly make;
+    private readonly done;
+    painted: number;
+    constructor(root: Object3D, make: () => Node<"vec4">);
+    private paint;
+    scan(): void;
+}
+export {};

package/dist/runtime/styles/handdrawn/paint.js

@@ -0,0 +1,129 @@
+import { abs, diffuseColor, dot, exp, float, Fn, fract, luminance, max, min, mix, output, screenCoordinate, smoothstep, sqrt, texture, vec3, vec4, } from "three/tsl";
+import { HANDDRAWN_PALETTE, linearRgb, PIGMENTS } from "./palette.js";
+const PIGMENT_LINEAR = HANDDRAWN_PALETTE.map(linearRgb);
+/**
+ * The palette's pull on a linear colour: a soft blend of the pigments
+ * nearest to it (compared gamma-encoded with eye weights). Soft, not a hard
+ * nearest pick, so a gradient in a texture stays a gradient instead of
+ * breaking into patches.
+ */
+const pigmentOf = Fn(([c]) => {
+    const g = sqrt(max(c, vec3(0)));
+    const sum = vec3(0).toVar();
+    const wsum = float(1e-6).toVar();
+    for (const p of PIGMENT_LINEAR) {
+        const pg = vec3(Math.sqrt(p[0]), Math.sqrt(p[1]), Math.sqrt(p[2]));
+        const d = g.sub(pg);
+        const w = exp(dot(d.mul(d), vec3(0.3, 0.59, 0.11)).mul(-260));
+        sum.addAssign(vec3(p[0], p[1], p[2]).mul(w));
+        wsum.addAssign(w);
+    }
+    return sum.div(wsum);
+});
+/** A pen stroke field: 1 on lines `spacing` CSS px apart along `u`, about 1 px wide. */
+function strokes(u, spacing) {
+    const d = abs(fract(u).sub(0.5)).mul(spacing);
+    return float(1).sub(smoothstep(0.35, 1.15, d));
+}
+/** The repainted output for a lit material (assign to `material.outputNode`). */
+export function paintNode(u) {
+    const albedo = diffuseColor.rgb;
+    const lit = output.rgb;
+    const pig = pigmentOf(albedo);
+    const snapped = mix(albedo, pig, u.snap);
+    // A wash is never solid black: very dark albedos (night stone, dark walls) are lifted toward a grey wash, and the
+    // hatching and the pen carry their darkness instead, as an illustrator would draw a dark rock.
+    const darkness = float(1).sub(smoothstep(0.015, 0.12, luminance(snapped)));
+    const paint = mix(snapped, snapped.mul(0.4).add(vec3(...linearRgb(PIGMENTS.slate)).mul(0.6)), darkness.mul(0.65));
+    // Light received, per channel; its luminance picks the wash and its hue tints it.
+    const ratio = lit.div(max(albedo, vec3(0.045)));
+    const level = luminance(ratio).mul(u.exposure);
+    const hue = min(ratio.div(max(luminance(ratio), float(1e-3))), vec3(2.2));
+    // Screen position in CSS pixels, and the noise that makes wash borders ragged.
+    const sc = screenCoordinate.xy.div(u.dpr);
+    const n = texture(u.noise, sc.div(150).add(u.boil)).r;
+    const nf = texture(u.noise, sc.div(37).add(u.boil.yx)).b;
+    const lv = level.mul(n.mul(0.22).add(0.89));
+    // Washes: deep shadow, shadow, mid, light, glow (each preset sets their values).
+    const v = u.values;
+    const s1 = smoothstep(0.1, 0.16, lv);
+    const s2 = smoothstep(0.3, 0.38, lv);
+    const s3 = smoothstep(0.62, 0.74, lv);
+    const s4 = smoothstep(1.45, 1.8, lv);
+    const value = v.x.add(v.y.sub(v.x).mul(s1)).add(v.z.sub(v.y).mul(s2)).add(v.w.sub(v.z).mul(s3)).add(u.glow.sub(v.w).mul(s4));
+    // Shadows go cool, light keeps its hue.
+    const cool = mix(vec3(0.8, 0.86, 1.1), vec3(1, 1, 1), s2);
+    let col = paint.mul(value).mul(mix(vec3(1, 1, 1), hue, 0.6)).mul(cool);
+    // Hatching: the shadow wash gets one direction, the deep shadow a cross.
+    const jitter = nf.mul(0.5);
+    const h1 = strokes(sc.x.mul(0.62).add(sc.y).div(7).add(jitter).add(u.boil.x.mul(3)), 7);
+    const h2 = strokes(sc.x.sub(sc.y.mul(0.62)).div(7.5).add(jitter).add(u.boil.y.mul(3)), 7.5);
+    const dash = smoothstep(0.26, 0.4, texture(u.noise, sc.div(19).add(u.boil)).g);
+    const shade = float(1).sub(s2);
+    const deep = max(float(1).sub(s1), darkness.mul(0.8));
+    // Light single hatching in the shadow wash, a firmer cross only in the deep shadow (a lit field never turns to cloth).
+    const hatch = max(h1.mul(shade).mul(0.45), max(h1, h2).mul(deep).mul(0.9)).mul(dash).mul(u.hatch);
+    const ink = vec3(...linearRgb(PIGMENTS.sepia));
+    col = mix(col, col.mul(0.3).add(ink.mul(0.3)), hatch);
+    return vec4(col, output.a);
+}
+const LIT_TYPES = new Set([
+    "MeshStandardMaterial",
+    "MeshStandardNodeMaterial",
+    "MeshPhysicalMaterial",
+    "MeshPhysicalNodeMaterial",
+    "MeshLambertMaterial",
+    "MeshLambertNodeMaterial",
+    "MeshPhongMaterial",
+    "MeshPhongNodeMaterial",
+    "MeshToonMaterial",
+    "MeshToonNodeMaterial",
+]);
+/** Lit materials get painted; unlit ones (flames, glows, outlines, effects) keep their colour. */
+export function paintable(m) {
+    const pm = m;
+    return LIT_TYPES.has(m.type) && (pm.outputNode === undefined || pm.outputNode === null);
+}
+/**
+ * Finds lit materials as they arrive in the scene (models load late) and
+ * paints each once. A scan walks the scene graph (a few hundred nodes; the
+ * crowds are one node per type), so it runs every few frames, not every one.
+ */
+export class PaintWatcher {
+    root;
+    make;
+    done = new WeakSet();
+    painted = 0;
+    constructor(root, make) {
+        this.root = root;
+        this.make = make;
+    }
+    paint(m) {
+        if (this.done.has(m))
+            return;
+        this.done.add(m);
+        if (!paintable(m))
+            return;
+        // Paint is matte: no metal, no gloss (watercolour has no specular).
+        if (m.metalness !== undefined)
+            m.metalness = 0;
+        if (m.roughness !== undefined)
+            m.roughness = 1;
+        m.outputNode = this.make();
+        m.needsUpdate = true;
+        this.painted++;
+    }
+    scan() {
+        this.root.traverse((o) => {
+            const mesh = o;
+            if (!mesh.isMesh)
+                return;
+            const mat = mesh.material;
+            if (Array.isArray(mat))
+                for (const m of mat)
+                    this.paint(m);
+            else if (mat)
+                this.paint(mat);
+        });
+    }
+}

package/dist/runtime/styles/handdrawn/palette.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The hand-drawn palette: a watercolour box of pigments. Every surface the
+ * style paints is pulled toward its nearest pigment, which is what makes
+ * models from different packs read as one illustrator's work. The asset
+ * library's handdrawn manifest carries the same list (its `palette`), so
+ * generated art is locked to it too.
+ */
+/** Pigments as sRGB hex, light to dark within each family. */
+export declare const PIGMENTS: {
+    readonly paper: 15985366;
+    readonly naples: 15521178;
+    readonly ochre: 14263624;
+    readonly sienna: 12088378;
+    readonly umber: 7227955;
+    readonly sepia: 3811872;
+    readonly peach: 15450015;
+    readonly vermilion: 14047804;
+    readonly crimson: 11023690;
+    readonly rose: 14192538;
+    readonly violet: 8146814;
+    readonly indigo: 3882859;
+    readonly ultramarine: 4941480;
+    readonly cerulean: 7579339;
+    readonly teal: 4097923;
+    readonly viridian: 4159062;
+    readonly sap: 7771455;
+    readonly leaf: 11125372;
+    readonly olive: 9078344;
+    readonly slate: 9213344;
+    readonly paynes: 4147800;
+    readonly stone: 11971221;
+    readonly ink: 2365972;
+    readonly white: 16513006;
+};
+export type Pigment = keyof typeof PIGMENTS;
+/** The palette in a fixed order (the manifest's `palette`). */
+export declare const HANDDRAWN_PALETTE: readonly number[];
+/** "#rrggbb" strings, for manifests and docs. */
+export declare const HANDDRAWN_PALETTE_HEX: readonly string[];
+/** sRGB 0..255 channel to linear 0..1. */
+export declare function srgbToLinear(c: number): number;
+/** A hex colour as linear rgb. */
+export declare function linearRgb(hex: number): [number, number, number];
+/**
+ * The pigment nearest to a colour (sRGB hex), measured in a perceptual-ish
+ * space (gamma-encoded, weighted toward green like the eye). Pure, so the
+ * shader's choice can be checked in node.
+ */
+export declare function nearestPigment(hex: number): number;

package/dist/runtime/styles/handdrawn/palette.js

@@ -0,0 +1,70 @@
+/**
+ * The hand-drawn palette: a watercolour box of pigments. Every surface the
+ * style paints is pulled toward its nearest pigment, which is what makes
+ * models from different packs read as one illustrator's work. The asset
+ * library's handdrawn manifest carries the same list (its `palette`), so
+ * generated art is locked to it too.
+ */
+/** Pigments as sRGB hex, light to dark within each family. */
+export const PIGMENTS = {
+    paper: 0xf3ead6,
+    naples: 0xecd59a,
+    ochre: 0xd9a548,
+    sienna: 0xb8743a,
+    umber: 0x6e4a33,
+    sepia: 0x3a2a20,
+    peach: 0xebbf9f,
+    vermilion: 0xd65a3c,
+    crimson: 0xa8354a,
+    rose: 0xd88f9a,
+    violet: 0x7c4f7e,
+    indigo: 0x3b3f6b,
+    ultramarine: 0x4b66a8,
+    cerulean: 0x73a6cb,
+    teal: 0x3e8783,
+    viridian: 0x3f7656,
+    sap: 0x76953f,
+    leaf: 0xa9c27c,
+    olive: 0x8a8648,
+    slate: 0x8c95a0,
+    paynes: 0x3f4a58,
+    stone: 0xb6aa95,
+    ink: 0x241a14,
+    white: 0xfbf7ee,
+};
+/** The palette in a fixed order (the manifest's `palette`). */
+export const HANDDRAWN_PALETTE = Object.values(PIGMENTS);
+/** "#rrggbb" strings, for manifests and docs. */
+export const HANDDRAWN_PALETTE_HEX = HANDDRAWN_PALETTE.map((c) => `#${c.toString(16).padStart(6, "0")}`);
+/** sRGB 0..255 channel to linear 0..1. */
+export function srgbToLinear(c) {
+    const v = c / 255;
+    return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+}
+/** A hex colour as linear rgb. */
+export function linearRgb(hex) {
+    return [srgbToLinear((hex >> 16) & 255), srgbToLinear((hex >> 8) & 255), srgbToLinear(hex & 255)];
+}
+/**
+ * The pigment nearest to a colour (sRGB hex), measured in a perceptual-ish
+ * space (gamma-encoded, weighted toward green like the eye). Pure, so the
+ * shader's choice can be checked in node.
+ */
+export function nearestPigment(hex) {
+    const r = (hex >> 16) & 255;
+    const g = (hex >> 8) & 255;
+    const b = hex & 255;
+    let best = HANDDRAWN_PALETTE[0] ?? 0;
+    let bd = Infinity;
+    for (const p of HANDDRAWN_PALETTE) {
+        const dr = r - ((p >> 16) & 255);
+        const dg = g - ((p >> 8) & 255);
+        const db = b - (p & 255);
+        const d = 0.3 * dr * dr + 0.59 * dg * dg + 0.11 * db * db;
+        if (d < bd) {
+            bd = d;
+            best = p;
+        }
+    }
+    return best;
+}

package/dist/runtime/styles/handdrawn/textures.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Procedural textures for the hand-drawn style, generated in JS (no DOM,
+ * no files, deterministic from a seed): a tileable noise field the line
+ * wobble, wet edges and hatching read, and a sheet of paper with grain and
+ * fibres the whole frame is printed on. Original work, so no licence
+ * question.
+ */
+import { DataTexture } from "three/webgpu";
+/** A small seeded generator (mulberry32). */
+export declare function seeded(seed: number): () => number;
+/** Tileable value noise on a `size` grid with `cells` lattice cells per side, fractal over `octaves`. Values 0..1. */
+export declare function tileNoise(size: number, cells: number, octaves: number, rnd: () => number): Float32Array;
+/**
+ * Noise for the style's shaders, 256 px and tileable: R low (wobble, wet
+ * edges), G mid (line pressure and breaks), B fine (stroke jitter), A white.
+ */
+export declare function noiseData(seed?: number, size?: number): Uint8Array;
+/**
+ * Cold-pressed paper, 512 px and tileable: R is the surface (1 = the top of
+ * the tooth, lower = valleys and fibres), G a slower mottle for the sheet's
+ * tone, B the tooth alone (where pigment granulates).
+ */
+export declare function paperData(seed?: number, size?: number): Uint8Array;
+/** The shared noise texture (built once per page). */
+export declare function noiseTexture(): DataTexture;
+/** The shared paper texture (built once per page). */
+export declare function paperTexture(): DataTexture;