@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/fx/decals.js

@@ -0,0 +1,607 @@
+import { blendState } from '../render/blend.js';
+import { Mesh, VERTEX_LAYOUT_3D, VERTEX3D_FLOATS, VERTEX3D_STRIDE } from '../render/mesh.js';
+import { auxSuffix, ScenePipelineCache } from '../render/scene-pipelines.js';
+import { createShaderModule } from '../render/wgsl.js';
+import { WGSL_DECAL_BOX, WGSL_DECAL_DEPTH_COPY, WGSL_DECAL_QUAD } from './decals-wgsl.js';
+import { defaultFxRandom } from './random.js';
+/**
+ * Floats per decal instance (6 × vec4f = 96 bytes):
+ *
+ * | floats | WGSL (`DecalVertex`) | content |
+ * | --- | --- | --- |
+ * | 0..11 | `m0..m2` @location(3..5) | world → local 3×4 matrix, row-major (unit box) |
+ * | 12..15 | `uv_rect` @location(6) | atlas rect: u0, v0, du, dv |
+ * | 16..19 | `color` @location(7) | linear RGBA multiplier |
+ * | 20..23 | `life` @location(8) | age / lifetime (0 when infinite), lifetime, 0, 0 |
+ */
+export const DECAL_INSTANCE_FLOATS = 24;
+/** Floats in the decals' params block: `inv_view_proj` (16), `shape` (4), `fade` (4). */
+export const DECAL_PARAMS_FLOATS = 24;
+const DEPTH_COPY_FORMAT = 'depth32float';
+const F = DECAL_INSTANCE_FLOATS;
+/**
+ * Projected decals: an atlas stamped onto scenery, every live decal in one instanced draw.
+ * `frame.drawable(decals, order)` draws them; `update(dt)` ages them.
+ *
+ * Two implementations behind one API. **Box** (under a depth camera): each decal is a unit box
+ * in its own frame; the fragment shader reconstructs the world position under the pixel from a
+ * copy of the scene depth, rejects what is outside the box and samples the atlas by the local
+ * xy, so the decal wraps whatever it covers (depth test and write off). The depth is this
+ * frame's opaque depth, from the renderer's depth hook (`readsDepth`, `afterOpaque`), so a decal
+ * on a moving surface stays on it. With `readsDepth: false` (or a target whose depth cannot be
+ * copied) the fallback copy is taken in `prepare`, before the scene pass, and holds the
+ * **previous frame's** depth: a decal placed this frame appears next frame. **Quad**
+ * (no depth, or `mode: 'quad'`): a camera-independent quad lifted along the normal by `offset`
+ * (depth test on, write off).
+ *
+ * Handles are monotonic ids; `remove` marks a decal dead and the next `update` (or `prepare`)
+ * compacts the live ones to the front, keeping the id → slot map. Nothing allocates per frame
+ * when nothing died.
+ */
+export class Decals {
+    capacity;
+    mode;
+    /** The mode the last `prepare` resolved (`auto` → by the frame's depth); null before. */
+    activeMode = null;
+    /** Default lifetime for `add` (seconds). Live. */
+    lifetime;
+    /** Quad lift along the normal. Live. */
+    offset;
+    /** Box: minimum cosine between the surface and decal normals. Live. */
+    normalBias;
+    /** Box: share of the half depth faded at each end. Live. */
+    fadeEdge;
+    /** Alpha at age 0 and at the lifetime. Live. */
+    fade;
+    /** Box: take this frame's depth from the renderer's hook (see `DecalsOptions`). Live. */
+    readsDepth;
+    /** The stream `'random'` rotations and tiles draw from. Live. */
+    random;
+    renderer;
+    device;
+    columns;
+    rows;
+    multiply;
+    data;
+    ages;
+    lives;
+    ids;
+    alive;
+    slotOf = new Map();
+    live = 0;
+    /** Slots in use, dead ones included until the next compaction. */
+    used = 0;
+    dirty = false;
+    nextId = 1;
+    params;
+    paramsBuffer;
+    instanceBuffer;
+    box;
+    quad;
+    layout;
+    sampler;
+    texture;
+    dummyDepth;
+    group;
+    boxModule;
+    quadModule;
+    pipelineLayout;
+    blend;
+    /**
+     * Pipelines per mode: depth format (null: none) × the view target's aux key, built on first
+     * use from `renderer.sceneTargets` (ws/render-10).
+     */
+    boxPipelines = new ScenePipelineCache();
+    quadPipelines = new ScenePipelineCache();
+    // Depth copy (box mode).
+    copyLayout;
+    copyPipeline;
+    copyAtt;
+    copyPass;
+    copyTex = null;
+    copySrc = null;
+    copySrcGroup = null;
+    /** The box draw has a depth copy to read this frame. */
+    depthReady = false;
+    /** The bind group over the fallback copy (`copyTex`). */
+    copyGroup = null;
+    /** The renderer's `depthCopy` view the hook group was made for. */
+    hookView = null;
+    hookGroup = null;
+    noDepthGroup;
+    constructor(renderer, opts) {
+        const device = renderer.device;
+        this.renderer = renderer;
+        this.device = device;
+        this.capacity = Math.max(1, Math.floor(opts.capacity ?? 256));
+        this.mode = opts.mode ?? 'auto';
+        this.lifetime = opts.lifetime ?? Number.POSITIVE_INFINITY;
+        this.offset = opts.offset ?? 0.01;
+        this.normalBias = opts.normalBias ?? 0.3;
+        this.fadeEdge = opts.fadeEdge ?? 0.2;
+        this.fade = [opts.fade?.[0] ?? 1, opts.fade?.[1] ?? 0];
+        this.readsDepth = opts.readsDepth ?? this.mode !== 'quad';
+        this.random = opts.random ?? defaultFxRandom('decals');
+        this.columns = Math.max(1, opts.atlas?.columns ?? 1);
+        this.rows = Math.max(1, opts.atlas?.rows ?? 1);
+        const blend = opts.blend ?? 'alpha';
+        this.multiply = blend === 'multiply';
+        this.texture = opts.texture;
+        const cap = this.capacity;
+        this.data = new Float32Array(cap * F);
+        this.ages = new Float32Array(cap);
+        this.lives = new Float32Array(cap);
+        this.ids = new Float64Array(cap);
+        this.alive = new Uint8Array(cap);
+        this.params = new Float32Array(DECAL_PARAMS_FLOATS);
+        this.paramsBuffer = device.createBuffer({
+            label: 'decals-params',
+            size: this.params.byteLength,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        this.instanceBuffer = device.createBuffer({
+            label: 'decals-instances',
+            size: this.data.byteLength,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+        this.box = new Mesh(device, { ...unitBox(), layout: VERTEX_LAYOUT_3D, label: 'decal-box' });
+        this.quad = new Mesh(device, { ...unitQuad(), layout: VERTEX_LAYOUT_3D, label: 'decal-quad' });
+        this.sampler = device.createSampler({
+            label: 'decals',
+            magFilter: 'linear',
+            minFilter: 'linear',
+            mipmapFilter: 'linear',
+            addressModeU: 'clamp-to-edge',
+            addressModeV: 'clamp-to-edge',
+        });
+        this.dummyDepth = device.createTexture({
+            label: 'decals-depth-none',
+            size: [1, 1],
+            format: DEPTH_COPY_FORMAT,
+            usage: GPUTextureUsage.TEXTURE_BINDING,
+        });
+        this.layout = device.createBindGroupLayout({
+            label: 'decals-layout',
+            entries: [
+                {
+                    binding: 0,
+                    visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
+                    buffer: {},
+                },
+                { binding: 1, visibility: GPUShaderStage.FRAGMENT, sampler: {} },
+                { binding: 2, visibility: GPUShaderStage.FRAGMENT, texture: {} },
+                { binding: 3, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: 'depth' } },
+            ],
+        });
+        this.noDepthGroup = this.makeGroup(this.dummyDepth.createView());
+        this.group = this.noDepthGroup;
+        this.pipelineLayout = device.createPipelineLayout({
+            bindGroupLayouts: [renderer.globalsLayout, this.layout],
+        });
+        this.blend = blend === 'multiply' ? MULTIPLY_BLEND : blendState(blend);
+        this.boxModule = createShaderModule(device, WGSL_DECAL_BOX, 'decals-box');
+        this.quadModule = createShaderModule(device, WGSL_DECAL_QUAD, 'decals-quad');
+        this.copyLayout = device.createBindGroupLayout({
+            label: 'decals-depth-copy-layout',
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: 'depth' } },
+            ],
+        });
+        const copyModule = createShaderModule(device, WGSL_DECAL_DEPTH_COPY, 'decals-depth-copy');
+        this.copyPipeline = device.createRenderPipeline({
+            label: 'decals-depth-copy',
+            layout: device.createPipelineLayout({ bindGroupLayouts: [this.copyLayout] }),
+            vertex: { module: copyModule, entryPoint: 'vs' },
+            fragment: { module: copyModule, entryPoint: 'fs', targets: [] },
+            primitive: { topology: 'triangle-list' },
+            depthStencil: { format: DEPTH_COPY_FORMAT, depthWriteEnabled: true, depthCompare: 'always' },
+        });
+        this.copyAtt = {
+            view: undefined,
+            depthClearValue: 1,
+            depthLoadOp: 'clear',
+            depthStoreOp: 'store',
+        };
+        this.copyPass = {
+            label: 'decals-depth-copy',
+            colorAttachments: [],
+            depthStencilAttachment: this.copyAtt,
+        };
+    }
+    /** Live decals. */
+    get count() {
+        return this.live;
+    }
+    /** Whether `handle` is still live. */
+    has(handle) {
+        return this.slotOf.has(handle);
+    }
+    /**
+     * Place a decal at (`x`, `y`, `z`) facing along (`nx`, `ny`, `nz`), `size` wide. Returns its
+     * handle. When the system is full the oldest live decal is overwritten.
+     */
+    add(d) {
+        if (this.dirty)
+            this.compact();
+        if (this.used === this.capacity)
+            this.dropOldest();
+        const slot = this.used++;
+        const id = this.nextId++;
+        this.ids[slot] = id;
+        this.alive[slot] = 1;
+        this.ages[slot] = 0;
+        const life = d.lifetime ?? this.lifetime;
+        this.lives[slot] = life;
+        this.slotOf.set(id, slot);
+        this.live++;
+        this.writeInstance(slot, d, life);
+        return id;
+    }
+    /** Remove a decal; false when the handle is not live. Compacted on the next `update`. */
+    remove(handle) {
+        const slot = this.slotOf.get(handle);
+        if (slot === undefined)
+            return false;
+        this.alive[slot] = 0;
+        this.slotOf.delete(handle);
+        this.live--;
+        this.dirty = true;
+        return true;
+    }
+    /** Remove every decal. */
+    clear() {
+        this.slotOf.clear();
+        this.live = 0;
+        this.used = 0;
+        this.dirty = false;
+    }
+    /** Age every decal by `dt` seconds, expire the ones past their lifetime and compact. */
+    update(dt) {
+        const n = this.used;
+        for (let i = 0; i < n; i++) {
+            if (!this.alive[i])
+                continue;
+            const age = this.ages[i] + dt;
+            this.ages[i] = age;
+            const life = this.lives[i];
+            if (age >= life) {
+                this.alive[i] = 0;
+                this.slotOf.delete(this.ids[i]);
+                this.live--;
+                this.dirty = true;
+            }
+            else {
+                this.data[i * F + 20] = Number.isFinite(life) ? age / life : 0;
+            }
+        }
+        if (this.dirty)
+            this.compact();
+    }
+    /** Age of the decal at `handle`, seconds; -1 when not live. */
+    ageOf(handle) {
+        const slot = this.slotOf.get(handle);
+        return slot === undefined ? -1 : this.ages[slot];
+    }
+    /**
+     * Whether the box draw is waiting on the renderer's depth hook this frame: `readsDepth` on and
+     * the target's depth copyable. Otherwise `prepare` takes the fallback copy.
+     */
+    get hooked() {
+        return this.readsDepth && (this.renderer.target?.canCopyDepth ?? false);
+    }
+    /**
+     * Resolve the mode for this frame, upload the params block and the live instances. Box mode
+     * waits for the depth hook (`afterOpaque`), or takes the fallback copy of last frame's depth.
+     * Called by the renderer once per frame. No allocation.
+     */
+    prepare(encoder, frame) {
+        if (this.dirty)
+            this.compact();
+        const depth = frame?.depthFormat ?? null;
+        const mode = this.mode === 'auto' ? (depth ? 'box' : 'quad') : this.mode;
+        this.activeMode = mode === 'box' && !depth ? 'quad' : mode;
+        if (this.activeMode !== 'box') {
+            this.depthReady = false;
+        }
+        else if (this.hooked) {
+            // `afterOpaque` binds this frame's depth; until it runs the box draws nothing.
+            this.depthReady = false;
+            this.group = this.noDepthGroup;
+        }
+        else {
+            this.depthReady = this.copyDepth(encoder);
+            this.group = this.depthReady ? this.copyGroup : this.noDepthGroup;
+        }
+        const p = this.params;
+        const camera = this.renderer.camera;
+        if (camera)
+            p.set(camera.invViewProj, 0);
+        else
+            p.set(IDENTITY, 0);
+        p[16] = this.normalBias;
+        p[17] = this.fadeEdge;
+        p[18] = this.offset;
+        p[19] = this.multiply ? 1 : 0;
+        p[20] = this.fade[0];
+        p[21] = this.fade[1];
+        p[22] = 0;
+        p[23] = 0;
+        this.device.queue.writeBuffer(this.paramsBuffer, 0, p);
+        if (this.live > 0) {
+            this.device.queue.writeBuffer(this.instanceBuffer, 0, this.data.buffer, 0, this.live * F * 4);
+        }
+    }
+    /**
+     * The renderer's depth hook (`readsDepth`): bind this frame's opaque depth copy. The bind
+     * group is rebuilt only when the renderer's copy changes (a resize).
+     */
+    afterOpaque(_encoder, view) {
+        if (this.activeMode !== 'box' || !this.readsDepth)
+            return;
+        if (view.depthView !== this.hookView) {
+            this.hookView = view.depthView;
+            this.hookGroup = this.makeGroup(view.depthView);
+        }
+        this.group = this.hookGroup;
+        this.depthReady = true;
+    }
+    /** Draw every live decal in one instanced draw (nothing in box mode until depth exists). */
+    draw(pass, frame) {
+        if (this.live === 0)
+            return;
+        const mode = this.activeMode ?? 'quad';
+        if (mode === 'box' && !this.depthReady)
+            return;
+        const depth = frame?.depthFormat ?? null;
+        pass.setPipeline(this.pipelineFor(mode, depth, frame ? frame.auxKey : (this.renderer.target?.auxKey ?? 0)));
+        pass.setBindGroup(1, this.group);
+        const mesh = mode === 'box' ? this.box : this.quad;
+        pass.setVertexBuffer(0, mesh.vertexBuffer);
+        pass.setVertexBuffer(1, this.instanceBuffer);
+        pass.setIndexBuffer(mesh.indexBuffer, mesh.indexFormat);
+        pass.drawIndexed(mesh.indexCount, this.live);
+    }
+    destroy() {
+        this.paramsBuffer.destroy();
+        this.instanceBuffer.destroy();
+        this.box.destroy();
+        this.quad.destroy();
+        this.dummyDepth.destroy();
+        this.copyTex?.destroy();
+    }
+    writeInstance(slot, d, life) {
+        const o = slot * F;
+        const data = this.data;
+        // Frame: z along the normal, x and y tangent, spun by `rotation`.
+        let nx = d.nx;
+        let ny = d.ny;
+        let nz = d.nz;
+        const nl = Math.hypot(nx, ny, nz) || 1;
+        nx /= nl;
+        ny /= nl;
+        nz /= nl;
+        // Tangent x = helper × normal, the helper world up (so wall decals stand upright) or, for a
+        // floor or ceiling, -z (so a floor decal's x is world x and its y points away from +z).
+        const flat = Math.abs(ny) > 0.99;
+        const hy = flat ? 0 : 1;
+        const hz = flat ? -1 : 0;
+        let tx = hy * nz - hz * ny;
+        let ty = hz * nx;
+        let tz = -hy * nx;
+        const tl = Math.hypot(tx, ty, tz) || 1;
+        tx /= tl;
+        ty /= tl;
+        tz /= tl;
+        const bx = ny * tz - nz * ty;
+        const by = nz * tx - nx * tz;
+        const bz = nx * ty - ny * tx;
+        const rot = d.rotation === 'random' ? this.random.float(0, Math.PI * 2) : (d.rotation ?? 0);
+        const c = Math.cos(rot);
+        const s = Math.sin(rot);
+        const ax = tx * c + bx * s;
+        const ay = ty * c + by * s;
+        const az = tz * c + bz * s;
+        const yx = bx * c - tx * s;
+        const yy = by * c - ty * s;
+        const yz = bz * c - tz * s;
+        const inv = 1 / (d.size || 1);
+        // Rows of world → local: axis / size, -dot(axis, p) / size.
+        data[o] = ax * inv;
+        data[o + 1] = ay * inv;
+        data[o + 2] = az * inv;
+        data[o + 3] = -(ax * d.x + ay * d.y + az * d.z) * inv;
+        data[o + 4] = yx * inv;
+        data[o + 5] = yy * inv;
+        data[o + 6] = yz * inv;
+        data[o + 7] = -(yx * d.x + yy * d.y + yz * d.z) * inv;
+        data[o + 8] = nx * inv;
+        data[o + 9] = ny * inv;
+        data[o + 10] = nz * inv;
+        data[o + 11] = -(nx * d.x + ny * d.y + nz * d.z) * inv;
+        const tile = d.tile === 'random'
+            ? this.random.int(0, this.columns * this.rows - 1)
+            : Math.max(0, Math.floor(d.tile ?? 0));
+        const col = tile % this.columns;
+        const row = Math.floor(tile / this.columns) % this.rows;
+        data[o + 12] = col / this.columns;
+        data[o + 13] = row / this.rows;
+        data[o + 14] = 1 / this.columns;
+        data[o + 15] = 1 / this.rows;
+        const color = d.color;
+        data[o + 16] = color?.[0] ?? 1;
+        data[o + 17] = color?.[1] ?? 1;
+        data[o + 18] = color?.[2] ?? 1;
+        data[o + 19] = color?.[3] ?? 1;
+        data[o + 20] = 0;
+        data[o + 21] = life;
+        data[o + 22] = 0;
+        data[o + 23] = 0;
+    }
+    /** Move the live slots to the front, in order, and remap their handles. */
+    compact() {
+        let w = 0;
+        const n = this.used;
+        for (let r = 0; r < n; r++) {
+            if (!this.alive[r])
+                continue;
+            if (w !== r) {
+                this.data.copyWithin(w * F, r * F, r * F + F);
+                this.ages[w] = this.ages[r];
+                this.lives[w] = this.lives[r];
+                this.ids[w] = this.ids[r];
+                this.alive[w] = 1;
+                this.slotOf.set(this.ids[w], w);
+            }
+            w++;
+        }
+        this.used = w;
+        this.live = w;
+        this.dirty = false;
+    }
+    /** Full and compact: drop slot 0 (the oldest) and shift the rest down. */
+    dropOldest() {
+        const n = this.used;
+        this.slotOf.delete(this.ids[0]);
+        this.data.copyWithin(0, F, n * F);
+        this.ages.copyWithin(0, 1, n);
+        this.lives.copyWithin(0, 1, n);
+        this.ids.copyWithin(0, 1, n);
+        for (let i = 0; i < n - 1; i++)
+            this.slotOf.set(this.ids[i], i);
+        this.used = n - 1;
+        this.live = n - 1;
+    }
+    /** Copy the scene depth into our own texture; false when there is none yet. */
+    copyDepth(encoder) {
+        const src = this.renderer.target?.depth ?? null;
+        if (!src)
+            return false;
+        const device = this.device;
+        if (!this.copyTex || this.copyTex.width !== src.width || this.copyTex.height !== src.height) {
+            this.copyTex?.destroy();
+            this.copyTex = device.createTexture({
+                label: 'decals-depth',
+                size: [src.width, src.height],
+                format: DEPTH_COPY_FORMAT,
+                usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
+            });
+            const view = this.copyTex.createView();
+            this.copyAtt.view = view;
+            this.copyGroup = this.makeGroup(view);
+        }
+        if (this.copySrc !== src) {
+            this.copySrc = src;
+            this.copySrcGroup = device.createBindGroup({
+                label: 'decals-depth-copy',
+                layout: this.copyLayout,
+                entries: [{ binding: 0, resource: src.view }],
+            });
+        }
+        const pass = encoder.beginRenderPass(this.copyPass);
+        pass.setPipeline(this.copyPipeline);
+        pass.setBindGroup(0, this.copySrcGroup);
+        pass.draw(3);
+        pass.end();
+        return true;
+    }
+    makeGroup(depthView) {
+        return this.device.createBindGroup({
+            label: 'decals',
+            layout: this.layout,
+            entries: [
+                { binding: 0, resource: { buffer: this.paramsBuffer } },
+                { binding: 1, resource: this.sampler },
+                { binding: 2, resource: this.texture.view },
+                { binding: 3, resource: depthView },
+            ],
+        });
+    }
+    pipelineFor(mode, depth, aux) {
+        const box = mode === 'box';
+        const cache = box ? this.boxPipelines : this.quadPipelines;
+        const hit = cache.get(depth, aux);
+        if (hit)
+            return hit;
+        const module = box ? this.boxModule : this.quadModule;
+        const p = this.device.createRenderPipeline({
+            label: `decals:${mode}:${depth ?? 'none'}${auxSuffix(aux)}`,
+            layout: this.pipelineLayout,
+            vertex: { module, entryPoint: 'vs', buffers: [POSITION_LAYOUT, INSTANCE_LAYOUT] },
+            fragment: { module, entryPoint: 'fs', targets: this.renderer.sceneTargets(this.blend, aux) },
+            primitive: { topology: 'triangle-list', cullMode: box ? 'front' : 'none' },
+            ...(depth
+                ? {
+                    depthStencil: {
+                        format: depth,
+                        depthWriteEnabled: false,
+                        depthCompare: box ? 'always' : 'less-equal',
+                    },
+                }
+                : {}),
+        });
+        return cache.set(depth, aux, p);
+    }
+}
+const IDENTITY = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+/** `dst × lerp(1, src, a)`: the shader outputs the lerp, the blend multiplies. */
+const MULTIPLY_BLEND = {
+    color: { srcFactor: 'dst', dstFactor: 'zero', operation: 'add' },
+    alpha: { srcFactor: 'zero', dstFactor: 'one', operation: 'add' },
+};
+/** The mesh's position only (the 3D layout's location 0); the rest of the vertex is skipped. */
+const POSITION_LAYOUT = {
+    arrayStride: VERTEX3D_STRIDE,
+    stepMode: 'vertex',
+    attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' }],
+};
+const INSTANCE_LAYOUT = {
+    arrayStride: DECAL_INSTANCE_FLOATS * 4,
+    stepMode: 'instance',
+    attributes: [
+        { shaderLocation: 3, offset: 0, format: 'float32x4' },
+        { shaderLocation: 4, offset: 16, format: 'float32x4' },
+        { shaderLocation: 5, offset: 32, format: 'float32x4' },
+        { shaderLocation: 6, offset: 48, format: 'float32x4' },
+        { shaderLocation: 7, offset: 64, format: 'float32x4' },
+        { shaderLocation: 8, offset: 80, format: 'float32x4' },
+    ],
+};
+/** A vertex in the 3D layout: position, normal, uv, white. */
+function vertex(out, i, x, y, z) {
+    const o = i * VERTEX3D_FLOATS;
+    out[o] = x;
+    out[o + 1] = y;
+    out[o + 2] = z;
+    out[o + 3] = 0;
+    out[o + 4] = 0;
+    out[o + 5] = 1;
+    out[o + 6] = x + 0.5;
+    out[o + 7] = 0.5 - y;
+    out[o + 8] = out[o + 9] = out[o + 10] = out[o + 11] = 1;
+}
+/** Unit box centred on the origin: 8 vertices, 12 triangles wound outward. */
+function unitBox() {
+    const vertices = new Float32Array(8 * VERTEX3D_FLOATS);
+    for (let i = 0; i < 8; i++) {
+        vertex(vertices, i, i & 1 ? 0.5 : -0.5, i & 2 ? 0.5 : -0.5, i & 4 ? 0.5 : -0.5);
+    }
+    // biome-ignore format: one face per line
+    const indices = new Uint16Array([
+        4, 5, 7, 4, 7, 6, // +z
+        1, 0, 2, 1, 2, 3, // -z
+        5, 1, 3, 5, 3, 7, // +x
+        0, 4, 6, 0, 6, 2, // -x
+        6, 7, 3, 6, 3, 2, // +y
+        0, 1, 5, 0, 5, 4, // -y
+    ]);
+    return { vertices, indices };
+}
+/** Unit quad in the xy plane facing +z. */
+function unitQuad() {
+    const vertices = new Float32Array(4 * VERTEX3D_FLOATS);
+    vertex(vertices, 0, -0.5, -0.5, 0);
+    vertex(vertices, 1, 0.5, -0.5, 0);
+    vertex(vertices, 2, 0.5, 0.5, 0);
+    vertex(vertices, 3, -0.5, 0.5, 0);
+    return { vertices, indices: new Uint16Array([0, 1, 2, 0, 2, 3]) };
+}