@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/render/transform.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Transforms: position, rotation and scale, with an optional parent, cached as a 3×4 world
+ * matrix. The renderer copies that matrix straight into the instance buffer
+ * (`frame.sprite(material, transform)` / `frame.mesh(mesh, material, transform)`).
+ *
+ * Conventions:
+ * - The world matrix is **3×4, row-major**: 12 floats `[r0 | tx, r1 | ty, r2 | tz]`, so
+ *   `world = (dot(row0, p), dot(row1, p), dot(row2, p))` with `p = (x, y, z, 1)`. The fourth
+ *   row of an affine matrix is always `(0, 0, 0, 1)` and is not stored.
+ * - The local matrix is `T · R · S` (scale, then rotate, then translate); a child's world
+ *   matrix is `parent.world · local`.
+ * - Rotation is a unit quaternion `(x, y, z, w)`. The 2D case is a rotation about +Z:
+ *   `rotation = a` (radians) gives the same matrix as `DrawParams.rotation`, clockwise on
+ *   screen when y points down. A pure Z rotation is built from `Math.cos/sin(a)` directly, so
+ *   it matches the `DrawParams` path exactly.
+ * - 2D: keep `z = 0`, rotate about Z only, and `scale.z = 1`.
+ *
+ * Setters mark the transform dirty; `world` recomputes lazily, at most once per change (or
+ * per parent change). Nothing allocates after construction.
+ */
+/** Floats in a 3×4 world matrix. */
+export declare const MATRIX3X4_FLOATS = 12;
+/**
+ * Write the 3×4 row-major matrix of a 2D draw (`DrawParams` x, y, w, h, rotation) at
+ * `out[o..o+12)`. This is the instance matrix `frame.sprite(material, params)` builds: the
+ * built-in quad spans -0.5..0.5, so `w, h` are its size. No allocation.
+ */
+export declare function writeMatrix2d(out: Float32Array, o: number, x: number, y: number, w: number, h: number, rotation: number): void;
+/**
+ * `out = a · b` for 3×4 affine matrices (implicit last row `0 0 0 1`). `out` may alias
+ * neither input. No allocation.
+ */
+export declare function multiplyMatrix3x4(out: Float32Array, a: ArrayLike<number>, b: ArrayLike<number>): void;
+/** Read-only view of a vector a transform owns. */
+export interface ReadonlyVec3 {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+export interface ReadonlyQuat extends ReadonlyVec3 {
+    readonly w: number;
+}
+export declare class Transform {
+    private readonly _position;
+    private readonly _rotation;
+    private readonly _scale;
+    /** Angle about Z when the rotation was set as one (exact cos/sin path), else NaN. */
+    private angleZ;
+    private _parent;
+    private readonly local;
+    private readonly _world;
+    private localDirty;
+    private worldDirty;
+    /** Bumps whenever `world` is recomputed; children compare it to their cached value. */
+    private worldVersion;
+    private parentVersion;
+    /** Setter calls on this transform (ws/audio-4); `changed` adds the ancestors'. */
+    private _changed;
+    constructor(opts?: {
+        x?: number;
+        y?: number;
+        z?: number;
+        rotation?: number;
+        scaleX?: number;
+        scaleY?: number;
+        scaleZ?: number;
+        parent?: Transform | null;
+    });
+    get position(): ReadonlyVec3;
+    /**
+     * A monotonic counter bumped by every setter on this transform or an ancestor (ws/audio-4),
+     * so a reader can skip `world` when nothing moved (`Voice.follow` does). It does not say
+     * whether `world` is stale; the dirty flags still do that.
+     */
+    get changed(): number;
+    get quaternion(): ReadonlyQuat;
+    get scale(): ReadonlyVec3;
+    setPosition(x: number, y: number, z?: number): this;
+    /**
+     * Set the local scale. One argument scales all three axes (`setScale(2)` is `2, 2, 2`, so a
+     * 3D node keeps its shape; a flat 2D quad has no depth, so it draws the same). Two arguments
+     * are the 2D form: `z` stays 1. Three set each axis.
+     */
+    setScale(s: number): this;
+    setScale(x: number, y: number, z?: number): this;
+    /**
+     * The 2D rotation: radians about +Z (clockwise on screen with y down, like
+     * `DrawParams.rotation`). Reading it after `setQuaternion` returns the quaternion's angle
+     * about Z, which is only meaningful for a pure Z rotation.
+     */
+    get rotation(): number;
+    set rotation(radians: number);
+    /** Set a 3D rotation as a quaternion (normalised here). */
+    setQuaternion(x: number, y: number, z: number, w: number): this;
+    /** Rotation from an axis (need not be unit length) and an angle in radians. */
+    setAxisAngle(ax: number, ay: number, az: number, radians: number): this;
+    /**
+     * Set the local matrix from a 3×4 row-major matrix at `m[o..o+12)` (an animation socket, a
+     * node world matrix). The 12 floats are copied as they are, so `world` is exact; `position`,
+     * `quaternion` and `scale` are decomposed from it (translation column, column lengths, the
+     * rotation of the normalised columns; a mirrored matrix carries the sign on `scale.z`), so a
+     * later setter rebuilds the nearest `T · R · S`. No allocation.
+     */
+    setMatrix(m: ArrayLike<number>, o?: number): this;
+    get parent(): Transform | null;
+    set parent(p: Transform | null);
+    /** Local matrix (3×4 row-major), recomputed if a setter ran since the last read. */
+    get localMatrix(): Float32Array;
+    /**
+     * World matrix (3×4 row-major): the parent's world times the local matrix. Cached; it
+     * recomputes only after a setter on this transform or a change anywhere up the chain.
+     */
+    get world(): Float32Array;
+    private updateLocal;
+}

package/dist/render/transform.js

@@ -0,0 +1,318 @@
+/**
+ * Transforms: position, rotation and scale, with an optional parent, cached as a 3×4 world
+ * matrix. The renderer copies that matrix straight into the instance buffer
+ * (`frame.sprite(material, transform)` / `frame.mesh(mesh, material, transform)`).
+ *
+ * Conventions:
+ * - The world matrix is **3×4, row-major**: 12 floats `[r0 | tx, r1 | ty, r2 | tz]`, so
+ *   `world = (dot(row0, p), dot(row1, p), dot(row2, p))` with `p = (x, y, z, 1)`. The fourth
+ *   row of an affine matrix is always `(0, 0, 0, 1)` and is not stored.
+ * - The local matrix is `T · R · S` (scale, then rotate, then translate); a child's world
+ *   matrix is `parent.world · local`.
+ * - Rotation is a unit quaternion `(x, y, z, w)`. The 2D case is a rotation about +Z:
+ *   `rotation = a` (radians) gives the same matrix as `DrawParams.rotation`, clockwise on
+ *   screen when y points down. A pure Z rotation is built from `Math.cos/sin(a)` directly, so
+ *   it matches the `DrawParams` path exactly.
+ * - 2D: keep `z = 0`, rotate about Z only, and `scale.z = 1`.
+ *
+ * Setters mark the transform dirty; `world` recomputes lazily, at most once per change (or
+ * per parent change). Nothing allocates after construction.
+ */
+/** Floats in a 3×4 world matrix. */
+export const MATRIX3X4_FLOATS = 12;
+/**
+ * Write the 3×4 row-major matrix of a 2D draw (`DrawParams` x, y, w, h, rotation) at
+ * `out[o..o+12)`. This is the instance matrix `frame.sprite(material, params)` builds: the
+ * built-in quad spans -0.5..0.5, so `w, h` are its size. No allocation.
+ */
+export function writeMatrix2d(out, o, x, y, w, h, rotation) {
+    const c = rotation === 0 ? 1 : Math.cos(rotation);
+    const s = rotation === 0 ? 0 : Math.sin(rotation);
+    out[o] = c * w;
+    out[o + 1] = -s * h;
+    out[o + 2] = 0;
+    out[o + 3] = x;
+    out[o + 4] = s * w;
+    out[o + 5] = c * h;
+    out[o + 6] = 0;
+    out[o + 7] = y;
+    out[o + 8] = 0;
+    out[o + 9] = 0;
+    out[o + 10] = 1;
+    out[o + 11] = 0;
+}
+/**
+ * `out = a · b` for 3×4 affine matrices (implicit last row `0 0 0 1`). `out` may alias
+ * neither input. No allocation.
+ */
+export function multiplyMatrix3x4(out, a, b) {
+    for (let r = 0; r < 3; r++) {
+        const a0 = a[r * 4];
+        const a1 = a[r * 4 + 1];
+        const a2 = a[r * 4 + 2];
+        const a3 = a[r * 4 + 3];
+        out[r * 4] = a0 * b[0] + a1 * b[4] + a2 * b[8];
+        out[r * 4 + 1] = a0 * b[1] + a1 * b[5] + a2 * b[9];
+        out[r * 4 + 2] = a0 * b[2] + a1 * b[6] + a2 * b[10];
+        out[r * 4 + 3] = a0 * b[3] + a1 * b[7] + a2 * b[11] + a3;
+    }
+}
+export class Transform {
+    _position = { x: 0, y: 0, z: 0 };
+    _rotation = { x: 0, y: 0, z: 0, w: 1 };
+    _scale = { x: 1, y: 1, z: 1 };
+    /** Angle about Z when the rotation was set as one (exact cos/sin path), else NaN. */
+    angleZ = 0;
+    _parent = null;
+    local = new Float32Array(MATRIX3X4_FLOATS);
+    _world = new Float32Array(MATRIX3X4_FLOATS);
+    localDirty = true;
+    worldDirty = true;
+    /** Bumps whenever `world` is recomputed; children compare it to their cached value. */
+    worldVersion = 0;
+    parentVersion = -1;
+    /** Setter calls on this transform (ws/audio-4); `changed` adds the ancestors'. */
+    _changed = 0;
+    constructor(opts) {
+        if (opts) {
+            this.setPosition(opts.x ?? 0, opts.y ?? 0, opts.z ?? 0);
+            if (opts.rotation)
+                this.rotation = opts.rotation;
+            this.setScale(opts.scaleX ?? 1, opts.scaleY ?? 1, opts.scaleZ ?? 1);
+            if (opts.parent)
+                this.parent = opts.parent;
+        }
+    }
+    get position() {
+        return this._position;
+    }
+    /**
+     * A monotonic counter bumped by every setter on this transform or an ancestor (ws/audio-4),
+     * so a reader can skip `world` when nothing moved (`Voice.follow` does). It does not say
+     * whether `world` is stale; the dirty flags still do that.
+     */
+    get changed() {
+        return this._changed + (this._parent ? this._parent.changed : 0);
+    }
+    get quaternion() {
+        return this._rotation;
+    }
+    get scale() {
+        return this._scale;
+    }
+    setPosition(x, y, z = 0) {
+        const p = this._position;
+        p.x = x;
+        p.y = y;
+        p.z = z;
+        this._changed++;
+        this.localDirty = true;
+        return this;
+    }
+    setScale(x, y, z) {
+        const s = this._scale;
+        s.x = x;
+        s.y = y ?? x;
+        s.z = z ?? (y === undefined ? x : 1);
+        this._changed++;
+        this.localDirty = true;
+        return this;
+    }
+    /**
+     * The 2D rotation: radians about +Z (clockwise on screen with y down, like
+     * `DrawParams.rotation`). Reading it after `setQuaternion` returns the quaternion's angle
+     * about Z, which is only meaningful for a pure Z rotation.
+     */
+    get rotation() {
+        if (!Number.isNaN(this.angleZ))
+            return this.angleZ;
+        const q = this._rotation;
+        return 2 * Math.atan2(q.z, q.w);
+    }
+    set rotation(radians) {
+        this.angleZ = radians;
+        const q = this._rotation;
+        q.x = 0;
+        q.y = 0;
+        q.z = Math.sin(radians / 2);
+        q.w = Math.cos(radians / 2);
+        this._changed++;
+        this.localDirty = true;
+    }
+    /** Set a 3D rotation as a quaternion (normalised here). */
+    setQuaternion(x, y, z, w) {
+        const len = Math.hypot(x, y, z, w) || 1;
+        const q = this._rotation;
+        q.x = x / len;
+        q.y = y / len;
+        q.z = z / len;
+        q.w = w / len;
+        this.angleZ = Number.NaN;
+        this._changed++;
+        this.localDirty = true;
+        return this;
+    }
+    /** Rotation from an axis (need not be unit length) and an angle in radians. */
+    setAxisAngle(ax, ay, az, radians) {
+        const len = Math.hypot(ax, ay, az) || 1;
+        const s = Math.sin(radians / 2) / len;
+        return this.setQuaternion(ax * s, ay * s, az * s, Math.cos(radians / 2));
+    }
+    /**
+     * Set the local matrix from a 3×4 row-major matrix at `m[o..o+12)` (an animation socket, a
+     * node world matrix). The 12 floats are copied as they are, so `world` is exact; `position`,
+     * `quaternion` and `scale` are decomposed from it (translation column, column lengths, the
+     * rotation of the normalised columns; a mirrored matrix carries the sign on `scale.z`), so a
+     * later setter rebuilds the nearest `T · R · S`. No allocation.
+     */
+    setMatrix(m, o = 0) {
+        const l = this.local;
+        for (let i = 0; i < MATRIX3X4_FLOATS; i++)
+            l[i] = m[o + i];
+        const p = this._position;
+        p.x = l[3];
+        p.y = l[7];
+        p.z = l[11];
+        const s = this._scale;
+        let sx = Math.hypot(l[0], l[4], l[8]);
+        let sy = Math.hypot(l[1], l[5], l[9]);
+        let sz = Math.hypot(l[2], l[6], l[10]);
+        const det = l[0] * (l[5] * l[10] - l[6] * l[9]) -
+            l[1] * (l[4] * l[10] - l[6] * l[8]) +
+            l[2] * (l[4] * l[9] - l[5] * l[8]);
+        if (det < 0)
+            sz = -sz;
+        s.x = sx;
+        s.y = sy;
+        s.z = sz;
+        sx = sx || 1;
+        sy = sy || 1;
+        sz = sz || 1;
+        // Rotation matrix columns (unit), row-major: r[row][col].
+        const r00 = l[0] / sx;
+        const r01 = l[1] / sy;
+        const r02 = l[2] / sz;
+        const r10 = l[4] / sx;
+        const r11 = l[5] / sy;
+        const r12 = l[6] / sz;
+        const r20 = l[8] / sx;
+        const r21 = l[9] / sy;
+        const r22 = l[10] / sz;
+        const q = this._rotation;
+        const trace = r00 + r11 + r22;
+        if (trace > 0) {
+            const w = Math.sqrt(trace + 1) * 0.5;
+            const k = 0.25 / w;
+            q.x = (r21 - r12) * k;
+            q.y = (r02 - r20) * k;
+            q.z = (r10 - r01) * k;
+            q.w = w;
+        }
+        else if (r00 > r11 && r00 > r22) {
+            const x = Math.sqrt(1 + r00 - r11 - r22) * 0.5;
+            const k = 0.25 / x;
+            q.x = x;
+            q.y = (r01 + r10) * k;
+            q.z = (r02 + r20) * k;
+            q.w = (r21 - r12) * k;
+        }
+        else if (r11 > r22) {
+            const y = Math.sqrt(1 + r11 - r00 - r22) * 0.5;
+            const k = 0.25 / y;
+            q.x = (r01 + r10) * k;
+            q.y = y;
+            q.z = (r12 + r21) * k;
+            q.w = (r02 - r20) * k;
+        }
+        else {
+            const z = Math.sqrt(1 + r22 - r00 - r11) * 0.5;
+            const k = 0.25 / z;
+            q.x = (r02 + r20) * k;
+            q.y = (r12 + r21) * k;
+            q.z = z;
+            q.w = (r10 - r01) * k;
+        }
+        this.angleZ = Number.NaN;
+        this._changed++;
+        this.localDirty = false;
+        this.worldDirty = true;
+        return this;
+    }
+    get parent() {
+        return this._parent;
+    }
+    set parent(p) {
+        for (let q = p; q; q = q._parent) {
+            if (q === this)
+                throw new Error('Transform: parent cycle');
+        }
+        this._parent = p;
+        this.parentVersion = -1;
+        this._changed++;
+        this.worldDirty = true;
+    }
+    /** Local matrix (3×4 row-major), recomputed if a setter ran since the last read. */
+    get localMatrix() {
+        if (this.localDirty)
+            this.updateLocal();
+        return this.local;
+    }
+    /**
+     * World matrix (3×4 row-major): the parent's world times the local matrix. Cached; it
+     * recomputes only after a setter on this transform or a change anywhere up the chain.
+     */
+    get world() {
+        const p = this._parent;
+        if (p) {
+            const pw = p.world;
+            if (this.localDirty || this.worldDirty || p.worldVersion !== this.parentVersion) {
+                multiplyMatrix3x4(this._world, pw, this.localMatrix);
+                this.parentVersion = p.worldVersion;
+                this.worldDirty = false;
+                this.worldVersion++;
+            }
+        }
+        else if (this.localDirty || this.worldDirty) {
+            this._world.set(this.localMatrix);
+            this.worldDirty = false;
+            this.worldVersion++;
+        }
+        return this._world;
+    }
+    updateLocal() {
+        const m = this.local;
+        const s = this._scale;
+        const p = this._position;
+        if (!Number.isNaN(this.angleZ)) {
+            writeMatrix2d(m, 0, p.x, p.y, s.x, s.y, this.angleZ);
+            m[10] = s.z;
+            m[11] = p.z;
+        }
+        else {
+            const { x, y, z, w } = this._rotation;
+            const xx = x * x;
+            const yy = y * y;
+            const zz = z * z;
+            const xy = x * y;
+            const xz = x * z;
+            const yz = y * z;
+            const wx = w * x;
+            const wy = w * y;
+            const wz = w * z;
+            m[0] = (1 - 2 * (yy + zz)) * s.x;
+            m[1] = 2 * (xy - wz) * s.y;
+            m[2] = 2 * (xz + wy) * s.z;
+            m[3] = p.x;
+            m[4] = 2 * (xy + wz) * s.x;
+            m[5] = (1 - 2 * (xx + zz)) * s.y;
+            m[6] = 2 * (yz - wx) * s.z;
+            m[7] = p.y;
+            m[8] = 2 * (xz - wy) * s.x;
+            m[9] = 2 * (yz + wx) * s.y;
+            m[10] = (1 - 2 * (xx + yy)) * s.z;
+            m[11] = p.z;
+        }
+        this.localDirty = false;
+        this.worldDirty = true;
+    }
+}

package/dist/render/wgsl.d.ts

@@ -0,0 +1,131 @@
+import { type VertexLayout } from './mesh.js';
+/**
+ * Create a shader module and surface compile errors with file/line context. Compilation is
+ * async in the browser; errors are logged as soon as they are known.
+ */
+export declare function createShaderModule(device: GPUDevice, code: string, label: string): GPUShaderModule;
+/**
+ * Per-frame engine bindings for every material and drawable, in `@group(0)`:
+ *
+ * - `@binding(0) globals`: `logicalSize`, `targetSize` (scene target px), `time`, `dt`.
+ * - `@binding(1) camera` (the camera block): `view`, `proj`, `view_proj` (world → clip),
+ *   `camera_pos` (world eye position, w = 1), `viewport` (target px: x, y, w, h),
+ *   `view_index` (`camera.viewIndex`: 0, or the eye index of an XR view), `inv_view_proj`
+ *   (clip → world, the inverse of `view_proj`; `camera.invViewProj` on the CPU side),
+ *   `prev_view_proj` and `prev_view` (last frame's unjittered `view_proj` and `view`) and
+ *   `jitter` (clip-space dx, dy; the pixel offset x, y).
+ */
+export declare const WGSL_GLOBALS = "\nstruct EngineGlobals {\n  logicalSize: vec2f,\n  targetSize: vec2f,\n  time: f32,\n  dt: f32,\n  _pad: vec2f,\n};\n@group(0) @binding(0) var<uniform> globals: EngineGlobals;\nstruct EngineCamera {\n  view: mat4x4f,\n  proj: mat4x4f,\n  view_proj: mat4x4f,\n  camera_pos: vec4f,\n  viewport: vec4f,\n  view_index: u32,\n  _pad0: u32, _pad1: u32, _pad2: u32,\n  inv_view_proj: mat4x4f,\n  prev_view_proj: mat4x4f,\n  prev_view: mat4x4f,\n  jitter: vec4f,\n};\n@group(0) @binding(1) var<uniform> camera: EngineCamera;\n";
+/**
+ * The Lambert BRDF for `wgslLightLoop`: `N·L` clamped at 0, the reflected fraction of a light's
+ * colour before the albedo (the light's colour × this is what `engine_lambert` returns per light).
+ */
+export declare const WGSL_LAMBERT_BRDF = "vec3f(max(dot(normal, l), 0.0))";
+/**
+ * Generate the engine light loop as a WGSL function `name(world_pos: vec3f, normal: vec3f,
+ * layer_mask: u32${params}) -> vec3f`: the sum over the lights whose `layers` share a bit with
+ * `layer_mask` of the light's colour × its attenuation × `brdf`. The sun (× `engine_shadow`),
+ * the `(1 - d/radius)²` point falloff and the spot cone (`engine_spot_cone` × the same falloff)
+ * are the loop's; the BRDF is the material's.
+ *
+ * WGSL has no function pointers, so the material supplies `brdf` as a WGSL expression that the
+ * loop body inlines once per light kind. In it, `l` is the unit direction from the surface to
+ * the light, `normal` and `world_pos` are the function's parameters and `params` (`', v: vec3f,
+ * f0: vec3f'` and so on; leading comma) adds whatever else it needs to the signature. The
+ * expression must be finite for any `l` (it is multiplied by 0 for lights that do not reach).
+ * `WGSL_LIGHTS` instantiates it as `engine_light_accum` with `WGSL_LAMBERT_BRDF`; `WGSL_PBR` as
+ * `engine_pbr_accum` with `engine_brdf(...)`. Generate rather than copy: the loop then changes
+ * in one place when the block gains a light kind.
+ */
+export declare function wgslLightLoop(name: string, brdf: string, params?: string): string;
+/**
+ * The lighting block, `@group(0) @binding(2)` (see `Lights` / `lights.ts`), in every material
+ * and drawable prelude: `lights.ambient`, `lights.point_count`, `lights.sun_dir` (the way
+ * the light travels), `lights.sun_color`, `lights.points[i]` (`position`, `radius`, `color`),
+ * `lights.sun_view_proj` (world → sun clip), `lights.shadow_params` (bias, map texel size,
+ * enabled, pad), `lights.fog` (rgb, density), `lights.fog_range` (near, far, pad, pad),
+ * `lights.spot_count`, `lights.sun_layers` (the sun's layer mask), `lights.point_layers`
+ * (`array<vec4u, 4>`: the mask of point `i` is `point_layers[i >> 2u][i & 3u]`) and
+ * `lights.spots[i]` (`position`, `radius`, `direction`, `cos_outer`, `color`, `cos_inner`,
+ * `layers`). The sun's shadow map (`texture_depth_2d`) and its comparison sampler sit at
+ * `@binding(3)` and `@binding(4)`; with no shadow pass a 1×1 depth texture is bound there.
+ *
+ * Helpers a game may call or ignore: `engine_point_lights(normal, world_pos)` sums the point
+ * lights' diffuse (Lambert × a smooth falloff that reaches zero at `radius`), all layers;
+ * `engine_spot_cone(cos_theta, cos_outer, cos_inner)` is a spot's cone factor;
+ * `engine_instance_layers(flags)` is the instance's layer bits from `VSOut.flags`;
+ * `engine_light_accum(world_pos, normal, layer_mask)` sums the sun (× `engine_shadow`), point
+ * and spot Lambert terms of every light whose `layers` share a bit with `layer_mask`;
+ * `engine_shadow(world_pos)` is the sun's visibility, 0..1 (3×3 PCF over the shadow map; 1
+ * outside the map or when there is no shadow pass); `engine_fog(color, world_pos)` blends
+ * `color` toward the fog colour by the distance to the camera (linear over `fog_range` when
+ * `far > near`, else exponential past `near`; identity when density is 0);
+ * `engine_lambert(normal, world_pos)` is ambient + `engine_light_accum` over every layer, so
+ * with the default block it returns `vec3f(1.0)` and `albedo * engine_lambert(...)` is unlit;
+ * `engine_lambert_layers(normal, world_pos, layer_mask)` is the same against the instance's
+ * layers (`engine_instance_layers(in.flags)`), so masked lights skip it.
+ *
+ * `engine_light_accum` is `wgslLightLoop('engine_light_accum', WGSL_LAMBERT_BRDF)`: the one
+ * light loop, generated with a Lambert BRDF; `WGSL_PBR` generates the same loop with its GGX BRDF.
+ */
+export declare const WGSL_LIGHTS: string;
+/** Hash / value-noise / fbm helpers available to every material and fullscreen pass. */
+export declare const WGSL_NOISE = "\nfn engine_hash21(p: vec2f) -> f32 {\n  var p3 = fract(vec3f(p.x, p.y, p.x) * 0.1031);\n  p3 += dot(p3, p3.yzx + 33.33);\n  return fract((p3.x + p3.y) * p3.z);\n}\nfn engine_hash22(p: vec2f) -> vec2f {\n  var p3 = fract(vec3f(p.x, p.y, p.x) * vec3f(0.1031, 0.1030, 0.0973));\n  p3 += dot(p3, p3.yzx + 33.33);\n  return fract((p3.xx + p3.yz) * p3.zy);\n}\nfn engine_noise(p: vec2f) -> f32 {\n  let i = floor(p);\n  let f = fract(p);\n  let u = f * f * (3.0 - 2.0 * f);\n  let a = engine_hash21(i);\n  let b = engine_hash21(i + vec2f(1.0, 0.0));\n  let c = engine_hash21(i + vec2f(0.0, 1.0));\n  let d = engine_hash21(i + vec2f(1.0, 1.0));\n  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);\n}\nfn engine_fbm(p: vec2f, octaves: i32) -> f32 {\n  var v = 0.0;\n  var amp = 0.5;\n  var q = p;\n  for (var i = 0; i < octaves; i++) {\n    v += amp * engine_noise(q);\n    q = q * 2.03 + vec2f(17.1, 9.2);\n    amp *= 0.5;\n  }\n  return v;\n}\nfn engine_luma(c: vec3f) -> f32 {\n  return dot(c, vec3f(0.2126, 0.7152, 0.0722));\n}\n";
+/** The `SkinPalette` binding inside the material's group: `@group(1) @binding(16)`. */
+export declare const SKIN_PALETTE_BINDING = 16;
+/**
+ * GPU skinning, emitted by `materialPrelude` for a layout with `skinned: true` (after
+ * `VertexIn`, which it reads). The palette is the material's storage buffer slot 0
+ * (`SkinPalette.buffer` passed as `buffers: [palette.buffer]`): a header (`joints` per
+ * instance, `instances`, `history`) and `rows`, three `vec4f` rows per joint (row-major 3×4, the layout
+ * `anim`'s `skinMatrices` writes), instance after instance. `engine_skin(v, position, normal)`
+ * sums the four weighted joint matrices of the vertex (`v.joints`, `v.weights`) for the
+ * instance's palette slot `u32(v.params.w)` and applies them to an object-space position and
+ * normal, before the instance matrix. A weight of 0 skips the fetch.
+ */
+export declare const WGSL_SKIN = "struct EngineSkinPalette {\n  joints: u32,\n  instances: u32,\n  history: u32,\n  _pad1: u32,\n  rows: array<vec4f>,\n};\n@group(1) @binding(16) var<storage, read> engine_skin_palette: EngineSkinPalette;\nstruct EngineSkinned {\n  position: vec3f,\n  normal: vec3f,\n};\nfn engine_skin(v: VertexIn, position: vec3f, normal: vec3f) -> EngineSkinned {\n  let base = u32(v.params.w) * engine_skin_palette.joints * 3u;\n  let p = vec4f(position, 1.0);\n  var skinned: EngineSkinned;\n  skinned.position = vec3f(0.0);\n  skinned.normal = vec3f(0.0);\n  for (var k = 0u; k < 4u; k++) {\n    let w = v.weights[k];\n    if (w == 0.0) { continue; }\n    let r = base + v.joints[k] * 3u;\n    let r0 = engine_skin_palette.rows[r];\n    let r1 = engine_skin_palette.rows[r + 1u];\n    let r2 = engine_skin_palette.rows[r + 2u];\n    skinned.position += w * vec3f(dot(r0, p), dot(r1, p), dot(r2, p));\n    skinned.normal += w * vec3f(dot(r0.xyz, normal), dot(r1.xyz, normal), dot(r2.xyz, normal));\n  }\n  return skinned;\n}\n// The previous frame's skinned position from the palette's history block (SkinPalette\n// with history), w = 1; w = 0 when the palette keeps none (velocity reads zero).\nfn engine_skin_previous(v: VertexIn, position: vec3f) -> vec4f {\n  if (engine_skin_palette.history == 0u) { return vec4f(0.0); }\n  let base = (engine_skin_palette.instances + u32(v.params.w)) * engine_skin_palette.joints * 3u;\n  let p = vec4f(position, 1.0);\n  var out = vec3f(0.0);\n  for (var k = 0u; k < 4u; k++) {\n    let w = v.weights[k];\n    if (w == 0.0) { continue; }\n    let r = base + v.joints[k] * 3u;\n    out += w * vec3f(dot(engine_skin_palette.rows[r], p), dot(engine_skin_palette.rows[r + 1u], p), dot(engine_skin_palette.rows[r + 2u], p));\n  }\n  return vec4f(out, 1.0);\n}";
+/**
+ * What a material prelude is generated for beyond the vertex layout (ws/render-4): the aux
+ * attachments of the target it draws into (`roughMetal`, `velocity`: `FragOut` gains
+ * `rough_metal` / `velocity` and `engine_write_aux` fills them) and `prevLane`, a third vertex
+ * buffer carrying each instance's previous 3×4 matrix (`InstanceList` with `velocity`), read
+ * by `engine_previous_world_position`. Every flag off is the plain prelude.
+ */
+export interface PreludeVariant {
+    roughMetal?: boolean;
+    velocity?: boolean;
+    prevLane?: boolean;
+}
+/** The plain variant: what every material compiled with before aux targets. */
+export declare const PLAIN_VARIANT: PreludeVariant;
+/**
+ * Three vertex locations in 10..15 the layout's attributes leave free, for the previous-matrix
+ * lane (`prevLane`), as `[p0, p1, p2]`.
+ */
+export declare function prevLaneLocations(layout: VertexLayout): [number, number, number];
+/** The previous-matrix vertex buffer layout (slot 2) for `layout`: 48 bytes per instance. */
+export declare function prevLaneBufferLayout(layout: VertexLayout): GPUVertexBufferLayout;
+/**
+ * Prelude prepended to every material, generated per vertex layout (and `PreludeVariant`).
+ * Declares `VertexIn` (the layout's vertex fields plus the 28-float instance: 3×4 world matrix
+ * rows `m0..m2`, `uvRect`, `tint`, `params`, `misc` = emissive, flags, size.xy), the default
+ * vertex entry `vs_main`, the `VSOut` varyings (`flags` is the instance's flag bits: bit 0 set
+ * means `receiveShadow: false`, bits 1..23 are its layers; `tangent` the world-space file
+ * tangent, w = 0 without one; `uv1` the second uv set, `uv` without one) and the `FragOut` MRT
+ * struct.
+ *
+ * Helpers: `engine_local_position(v)` / `engine_local_normal(v)` / `engine_local_tangent(v)`
+ * (object space; skinned for a `skinned` layout), `engine_world_position(v)`,
+ * `engine_previous_world_position(v)` (last frame's, `vec4f`, w = 0 when unknown),
+ * `engine_vertex(v)`, `engine_velocity(in)` (screen-space uv motion since last frame, zero
+ * without a velocity target) and `engine_write_aux(&o, rough_metal, velocity)` (fills the
+ * target's aux outputs, a no-op without them); the lighting block and `engine_lambert` /
+ * `engine_point_lights` from `WGSL_LIGHTS`; `WGSL_SKIN` (`engine_skin`, the palette binding)
+ * for a skinned layout only. The text for the 2D and 3D layouts does not change with skinning
+ * (E-008).
+ */
+export declare function materialPrelude(layout: VertexLayout, variant?: PreludeVariant): string;
+/** The material prelude for the 2D vertex layout (what every 2D material compiles with). */
+export declare const WGSL_MATERIAL_PRELUDE: string;
+/** Prelude for fullscreen passes: `vs_fullscreen` emits one triangle covering the target. */
+export declare const WGSL_FULLSCREEN_PRELUDE = "\n\nfn engine_hash21(p: vec2f) -> f32 {\n  var p3 = fract(vec3f(p.x, p.y, p.x) * 0.1031);\n  p3 += dot(p3, p3.yzx + 33.33);\n  return fract((p3.x + p3.y) * p3.z);\n}\nfn engine_hash22(p: vec2f) -> vec2f {\n  var p3 = fract(vec3f(p.x, p.y, p.x) * vec3f(0.1031, 0.1030, 0.0973));\n  p3 += dot(p3, p3.yzx + 33.33);\n  return fract((p3.xx + p3.yz) * p3.zy);\n}\nfn engine_noise(p: vec2f) -> f32 {\n  let i = floor(p);\n  let f = fract(p);\n  let u = f * f * (3.0 - 2.0 * f);\n  let a = engine_hash21(i);\n  let b = engine_hash21(i + vec2f(1.0, 0.0));\n  let c = engine_hash21(i + vec2f(0.0, 1.0));\n  let d = engine_hash21(i + vec2f(1.0, 1.0));\n  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);\n}\nfn engine_fbm(p: vec2f, octaves: i32) -> f32 {\n  var v = 0.0;\n  var amp = 0.5;\n  var q = p;\n  for (var i = 0; i < octaves; i++) {\n    v += amp * engine_noise(q);\n    q = q * 2.03 + vec2f(17.1, 9.2);\n    amp *= 0.5;\n  }\n  return v;\n}\nfn engine_luma(c: vec3f) -> f32 {\n  return dot(c, vec3f(0.2126, 0.7152, 0.0722));\n}\n\nstruct FullscreenIn {\n  @builtin(position) pos: vec4f,\n  @location(0) uv: vec2f,\n};\n@vertex fn vs_fullscreen(@builtin(vertex_index) i: u32) -> FullscreenIn {\n  let p = vec2f(f32((i << 1u) & 2u), f32(i & 2u));\n  var o: FullscreenIn;\n  o.pos = vec4f(p * 2.0 - 1.0, 0.0, 1.0);\n  o.uv = vec2f(p.x, 1.0 - p.y);\n  return o;\n}\n";