@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/anim/spring-chain.js

@@ -0,0 +1,294 @@
+/**
+ * Secondary motion: a chain of joints (tail, cape, hair, antenna) simulated as Verlet particles
+ * in instance space that spring back toward the sampled pose, with gravity, damping, bone-length
+ * constraints, an angle limit and sphere/capsule colliders. After the step the joints' local
+ * rotations are rewritten so each bone points at its simulated child; translations are kept.
+ * The rest position each frame is the sampled pose, so the animation still drives the chain
+ * and the simulation adds lag and sway. Same conventions as `ik.ts`: `worldPose` is
+ * `poseToWorld` of the sampled `pose`, `instanceWorld` is the 3×4 instance matrix (`null` for
+ * the identity). Allocates in `createSpringChain`, nothing per frame.
+ */
+import { anyPerpendicular, applyDelta, IDENTITY, normalize, rotateBy, rotateByQuat, rotationBetween, transformDir, transformPoint, } from './ik.js';
+import { invertAffine, WORLD_NODE_FLOATS } from './pose.js';
+import { quatFromAxisAngle, quatMultiply, quatNormalize } from './quat.js';
+const EPS = 1e-6;
+/** Validate and allocate; call once. */
+export function createSpringChain(skeleton, desc) {
+    const n = skeleton.parents.length;
+    let joints;
+    if (desc.joints) {
+        joints = Int16Array.from(desc.joints);
+        if (joints.length < 2)
+            throw new Error('SpringChain: at least two joints');
+        if (joints[0] !== desc.root)
+            throw new Error('SpringChain: joints must start at root');
+    }
+    else {
+        if (desc.tip === undefined)
+            throw new Error('SpringChain: tip or joints');
+        let count = 0;
+        for (let j = desc.tip; j >= 0 && j !== desc.root; j = skeleton.parents[j])
+            count++;
+        joints = new Int16Array(count + 1);
+        let j = desc.tip;
+        for (let i = count; i >= 1; i--) {
+            joints[i] = j;
+            j = skeleton.parents[j];
+        }
+        joints[0] = j;
+        if (j !== desc.root)
+            throw new Error(`SpringChain: tip ${desc.tip} does not descend from root`);
+    }
+    for (let i = 0; i < joints.length; i++) {
+        const j = joints[i];
+        if (j < 0 || j >= n)
+            throw new Error(`SpringChain: joint ${j} must be in [0, ${n})`);
+        if (i > 0) {
+            let p = skeleton.parents[j];
+            while (p >= 0 && p !== joints[i - 1])
+                p = skeleton.parents[p];
+            if (p < 0)
+                throw new Error(`SpringChain: joint ${j} does not descend from ${joints[i - 1]}`);
+        }
+    }
+    const count = joints.length;
+    return {
+        joints,
+        stiffness: desc.stiffness ?? 80,
+        damping: desc.damping ?? 6,
+        gravity: Float32Array.from(desc.gravity ?? [0, -9.8, 0]),
+        drag: desc.drag ?? 0,
+        radius: desc.radius ?? 0,
+        limitAngle: desc.limitAngle ?? Math.PI,
+        collide: desc.collide ?? [],
+        maxDt: desc.maxDt ?? 1 / 120,
+        teleportDistance: desc.teleportDistance ?? 1,
+        positions: new Float32Array(count * 3),
+        animated: new Float32Array(count * 3),
+        prev: new Float32Array(count * 3),
+        animPrev: new Float32Array(count * 3),
+        lengths: new Float32Array(count),
+        started: false,
+        reset() {
+            this.started = false;
+        },
+    };
+}
+const inv = new Float32Array(WORLD_NODE_FLOATS);
+const p = new Float32Array(3);
+const a = new Float32Array(3);
+const b = new Float32Array(3);
+const delta = new Float32Array(4);
+const acc = new Float32Array(4);
+const dq = new Float32Array(4);
+/**
+ * Step the chain by `dt` (split into sub-steps of at most `maxDt`) and rewrite the chain's
+ * rotations in `pose`. Call after sampling and `poseToWorld`, before skinning. No allocation.
+ */
+export function updateSpringChain(pose, skeleton, worldPose, chain, instanceWorld, dt) {
+    const joints = chain.joints;
+    const count = joints.length;
+    const pos = chain.positions;
+    const prev = chain.prev;
+    const anim = chain.animated;
+    const animPrev = chain.animPrev;
+    // Sampled positions into instance space; bone lengths from them.
+    animPrev.set(anim);
+    for (let i = 0; i < count; i++) {
+        const wo = joints[i] * WORLD_NODE_FLOATS;
+        p[0] = worldPose[wo + 3];
+        p[1] = worldPose[wo + 7];
+        p[2] = worldPose[wo + 11];
+        if (instanceWorld)
+            transformPoint(a, instanceWorld, 0, p);
+        else
+            a.set(p);
+        anim[i * 3] = a[0];
+        anim[i * 3 + 1] = a[1];
+        anim[i * 3 + 2] = a[2];
+        if (i > 0) {
+            chain.lengths[i] = Math.hypot(a[0] - anim[i * 3 - 3], a[1] - anim[i * 3 - 2], a[2] - anim[i * 3 - 1]);
+        }
+    }
+    if (!chain.started) {
+        pos.set(anim);
+        prev.set(anim);
+        animPrev.set(anim);
+        chain.started = true;
+    }
+    else {
+        // A teleport moves the whole chain with the root, keeping its velocity.
+        const sx = anim[0] - animPrev[0];
+        const sy = anim[1] - animPrev[1];
+        const sz = anim[2] - animPrev[2];
+        if (Math.hypot(sx, sy, sz) > chain.teleportDistance) {
+            for (let i = 0; i < count; i++) {
+                pos[i * 3] = pos[i * 3] + sx;
+                pos[i * 3 + 1] = pos[i * 3 + 1] + sy;
+                pos[i * 3 + 2] = pos[i * 3 + 2] + sz;
+                prev[i * 3] = prev[i * 3] + sx;
+                prev[i * 3 + 1] = prev[i * 3 + 1] + sy;
+                prev[i * 3 + 2] = prev[i * 3 + 2] + sz;
+                animPrev[i * 3] = animPrev[i * 3] + sx;
+                animPrev[i * 3 + 1] = animPrev[i * 3 + 1] + sy;
+                animPrev[i * 3 + 2] = animPrev[i * 3 + 2] + sz;
+            }
+        }
+    }
+    // Verlet sub-steps.
+    const steps = dt > 0 ? Math.max(1, Math.ceil(dt / Math.max(chain.maxDt, 1e-4))) : 0;
+    const h = steps > 0 ? dt / steps : 0;
+    const decay = Math.max(0, 1 - chain.damping * h);
+    const drag = Math.min(1, Math.max(0, chain.drag)) / Math.max(1, steps);
+    const k = chain.stiffness * h * h;
+    const gx = chain.gravity[0] * h * h;
+    const gy = chain.gravity[1] * h * h;
+    const gz = chain.gravity[2] * h * h;
+    const limit = chain.limitAngle;
+    for (let s = 0; s < steps; s++) {
+        // Integrate every joint but the pinned root.
+        for (let i = 1; i < count; i++) {
+            const o = i * 3;
+            const x = pos[o];
+            const y = pos[o + 1];
+            const z = pos[o + 2];
+            const vx = (x - prev[o]) * decay + (anim[o] - animPrev[o]) * drag;
+            const vy = (y - prev[o + 1]) * decay + (anim[o + 1] - animPrev[o + 1]) * drag;
+            const vz = (z - prev[o + 2]) * decay + (anim[o + 2] - animPrev[o + 2]) * drag;
+            prev[o] = x;
+            prev[o + 1] = y;
+            prev[o + 2] = z;
+            pos[o] = x + vx + (anim[o] - x) * k + gx;
+            pos[o + 1] = y + vy + (anim[o + 1] - y) * k + gy;
+            pos[o + 2] = z + vz + (anim[o + 2] - z) * k + gz;
+        }
+        pos[0] = anim[0];
+        pos[1] = anim[1];
+        pos[2] = anim[2];
+        // Constraints, parent before child: bone length, angle limit, colliders.
+        for (let i = 1; i < count; i++) {
+            const o = i * 3;
+            const po = o - 3;
+            const len = chain.lengths[i];
+            a[0] = pos[o] - pos[po];
+            a[1] = pos[o + 1] - pos[po + 1];
+            a[2] = pos[o + 2] - pos[po + 2];
+            if (normalize(a) <= EPS) {
+                b[0] = anim[o] - anim[po];
+                b[1] = anim[o + 1] - anim[po + 1];
+                b[2] = anim[o + 2] - anim[po + 2];
+                if (normalize(b) <= EPS)
+                    anyPerpendicular(b, UP);
+                a.set(b);
+            }
+            if (limit < Math.PI) {
+                b[0] = anim[o] - anim[po];
+                b[1] = anim[o + 1] - anim[po + 1];
+                b[2] = anim[o + 2] - anim[po + 2];
+                if (normalize(b) > EPS) {
+                    rotationBetween(delta, b, a);
+                    if (delta[3] > limit) {
+                        a.set(b);
+                        rotateBy(a, delta, limit);
+                    }
+                }
+            }
+            pos[o] = pos[po] + a[0] * len;
+            pos[o + 1] = pos[po + 1] + a[1] * len;
+            pos[o + 2] = pos[po + 2] + a[2] * len;
+            const colliders = chain.collide;
+            for (let c = 0; c < colliders.length; c++)
+                pushOut(pos, o, colliders[c], chain.radius);
+        }
+    }
+    // Rotations: each joint turns so its bone points at the simulated child. Deltas accumulate
+    // down the chain (`acc`, instance space); each one's axis is taken back through the
+    // accumulated turn and the instance matrix before `applyDelta` sees the parent's old matrix.
+    if (instanceWorld)
+        invertAffine(inv, 0, instanceWorld, 0);
+    acc[0] = 0;
+    acc[1] = 0;
+    acc[2] = 0;
+    acc[3] = 1;
+    for (let i = 0; i + 1 < count; i++) {
+        const o = i * 3;
+        a[0] = anim[o + 3] - anim[o];
+        a[1] = anim[o + 4] - anim[o + 1];
+        a[2] = anim[o + 5] - anim[o + 2];
+        if (normalize(a) <= EPS)
+            continue;
+        rotateByQuat(a, acc, 0);
+        b[0] = pos[o + 3] - pos[o];
+        b[1] = pos[o + 4] - pos[o + 1];
+        b[2] = pos[o + 5] - pos[o + 2];
+        if (normalize(b) <= EPS)
+            continue;
+        rotationBetween(delta, a, b);
+        if (delta[3] < 1e-7)
+            continue;
+        quatFromAxisAngle(dq, 0, delta[0], delta[1], delta[2], delta[3]);
+        // Axis into the frame the parent's sampled matrix lives in.
+        acc[0] = -acc[0];
+        acc[1] = -acc[1];
+        acc[2] = -acc[2];
+        rotateByQuat(delta, acc, 0);
+        acc[0] = -acc[0];
+        acc[1] = -acc[1];
+        acc[2] = -acc[2];
+        if (instanceWorld) {
+            transformDir(delta, inv, 0, delta);
+            normalize(delta);
+        }
+        const j = joints[i];
+        const parent = skeleton.parents[j];
+        if (parent < 0)
+            applyDelta(pose, j, delta, IDENTITY, 0, null);
+        else
+            applyDelta(pose, j, delta, worldPose, parent * WORLD_NODE_FLOATS, null);
+        quatMultiply(acc, 0, dq, 0, acc, 0);
+        quatNormalize(acc, 0);
+    }
+}
+const UP = new Float32Array([0, 1, 0]);
+const cp = new Float32Array(3);
+/** Move `pos[o..]` out of `c`, keeping `radius` clear of its surface. */
+function pushOut(pos, o, c, radius) {
+    const x = pos[o];
+    const y = pos[o + 1];
+    const z = pos[o + 2];
+    if ('a' in c) {
+        // Closest point on the segment.
+        const ax = c.a[0];
+        const ay = c.a[1];
+        const az = c.a[2];
+        const dx = c.b[0] - ax;
+        const dy = c.b[1] - ay;
+        const dz = c.b[2] - az;
+        const dd = dx * dx + dy * dy + dz * dz;
+        let t = dd > EPS ? ((x - ax) * dx + (y - ay) * dy + (z - az) * dz) / dd : 0;
+        t = Math.min(1, Math.max(0, t));
+        cp[0] = ax + dx * t;
+        cp[1] = ay + dy * t;
+        cp[2] = az + dz * t;
+    }
+    else {
+        cp[0] = c.center[0];
+        cp[1] = c.center[1];
+        cp[2] = c.center[2];
+    }
+    const nx = x - cp[0];
+    const ny = y - cp[1];
+    const nz = z - cp[2];
+    const dist = Math.hypot(nx, ny, nz);
+    const want = c.radius + radius;
+    if (dist >= want)
+        return;
+    if (dist <= EPS) {
+        pos[o + 1] = y + want;
+        return;
+    }
+    const s = want / dist;
+    pos[o] = cp[0] + nx * s;
+    pos[o + 1] = cp[1] + ny * s;
+    pos[o + 2] = cp[2] + nz * s;
+}

package/dist/assets/atlas.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Runtime sprite atlas: `packAtlas` lays loose images out on one sheet (shelf packing, tallest
+ * first), `AtlasLayout.draw` paints them onto a 2D canvas context with their edges extruded into
+ * the padding, and `createAtlasTexture` does that into an `OffscreenCanvas` and uploads it with
+ * `loadTexture`. The packer is pure (no DOM), so Workers and Node tests run it on
+ * `{ width, height, data }` sources.
+ */
+import { type LoadTextureOptions, type Texture } from '../render/texture.js';
+/** Tightly packed RGBA8 texels (`ImageData` is one). */
+export interface AtlasPixels {
+    width: number;
+    height: number;
+    data: Uint8Array | Uint8ClampedArray;
+}
+/** An image the atlas can place: a decoded bitmap, a canvas, or raw RGBA8 texels. */
+export type AtlasSource = ImageBitmap | HTMLCanvasElement | OffscreenCanvas | AtlasPixels;
+export interface AtlasOptions {
+    /** Gap in px between two sprites' extruded slots, and nothing else (default 1). */
+    padding?: number;
+    /** Largest width or height the sheet may reach (default 4096); past it `packAtlas` throws. */
+    maxSize?: number;
+    /** Round the sheet's width and height up to powers of two (default true). */
+    powerOfTwo?: boolean;
+    /**
+     * Pixels of each sprite's edge copied outward on every side (default 1), so linear filtering
+     * and mip reduction at a sprite's border never bleed a neighbour or the clear colour in.
+     */
+    extrude?: number;
+    /**
+     * Order sprites tallest first, then widest, then by name (default true): the shelf packer's
+     * best case. `false` keeps the input order. Either way the result is deterministic.
+     */
+    sort?: boolean;
+}
+/** Where one image sits: pixels (`x y w h`) and texture coordinates (`u0 v0 u1 v1`). */
+export interface AtlasRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    u0: number;
+    v0: number;
+    u1: number;
+    v1: number;
+}
+/** The subset of a 2D context `AtlasLayout.draw` uses (so tests can hand it a fake). */
+export interface AtlasDrawContext {
+    drawImage(image: Exclude<AtlasSource, AtlasPixels>, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number): void;
+    createImageData(width: number, height: number): ImageData;
+    putImageData(data: ImageData, dx: number, dy: number): void;
+}
+export interface AtlasLayout<N extends string = string> {
+    width: number;
+    height: number;
+    rects: Record<N, AtlasRect>;
+    /** The `extrude` the layout was packed with (what `draw` paints around each sprite). */
+    extrude: number;
+    /**
+     * Paint every image at its rect, with `extrude` px of its edge pixels copied outward on each
+     * side. Bitmaps and canvases go through `drawImage`; pixel sources are extruded in TS and
+     * written with `putImageData`.
+     */
+    draw(ctx: AtlasDrawContext): void;
+}
+/**
+ * Lay `images` out on one sheet. Each sprite's slot is its size plus `extrude` on every side;
+ * slots are `padding` px apart and start at the sheet's top-left corner. Throws naming the image
+ * that does not fit when the sheet would exceed `maxSize`.
+ */
+export declare function packAtlas<N extends string>(images: Record<N, AtlasSource>, opts?: AtlasOptions): AtlasLayout<N>;
+/**
+ * Copy `src` into the centre of an RGBA buffer `(w + 2e) × (h + 2e)` and fill the border with
+ * the nearest edge pixel (clamp-to-edge in software). Exported for tests and custom drawers.
+ */
+export declare function extrudePixels(src: AtlasPixels, e: number, out: Uint8ClampedArray | Uint8Array): void;
+export interface AtlasTextureOptions extends LoadTextureOptions {
+    /** The canvas to draw into (default a new `OffscreenCanvas` of the layout's size). */
+    canvas?: OffscreenCanvas | HTMLCanvasElement;
+}
+/** The atlas on the GPU: `createAtlasTexture`'s result. */
+export interface AtlasTexture<N extends string = string> {
+    texture: Texture;
+    rects: Record<N, AtlasRect>;
+}
+/**
+ * Draw `layout` into an `OffscreenCanvas` and upload it with `loadTexture` (sRGB, mips on by
+ * default; pass `mips: false` for pixel art, with `filter` or `format` as `loadTexture` takes).
+ * Allocates; call it at load time.
+ */
+export declare function createAtlasTexture<N extends string>(device: GPUDevice, layout: AtlasLayout<N>, images: Record<N, AtlasSource>, opts?: AtlasTextureOptions): AtlasTexture<N>;

package/dist/assets/atlas.js

@@ -0,0 +1,212 @@
+/**
+ * Runtime sprite atlas: `packAtlas` lays loose images out on one sheet (shelf packing, tallest
+ * first), `AtlasLayout.draw` paints them onto a 2D canvas context with their edges extruded into
+ * the padding, and `createAtlasTexture` does that into an `OffscreenCanvas` and uploads it with
+ * `loadTexture`. The packer is pure (no DOM), so Workers and Node tests run it on
+ * `{ width, height, data }` sources.
+ */
+import { loadTexture } from '../render/texture.js';
+function isPixels(s) {
+    return 'data' in s && ArrayBuffer.isView(s.data);
+}
+function nextPow2(n) {
+    let p = 1;
+    while (p < n)
+        p *= 2;
+    return p;
+}
+/** Shelf-pack `slots` (in order) into `width`; returns positions and the height used. */
+function shelfPack(slots, width, padding) {
+    const pos = [];
+    let x = 0;
+    let y = 0;
+    let shelf = 0;
+    let used = 0;
+    for (const s of slots) {
+        if (s.w > width)
+            return { pos, height: 0, used, overflow: s.name };
+        if (x > 0 && x + s.w > width) {
+            x = 0;
+            y += shelf + padding;
+            shelf = 0;
+        }
+        pos.push({ x, y });
+        x += s.w + padding;
+        if (x - padding > used)
+            used = x - padding;
+        if (s.h > shelf)
+            shelf = s.h;
+    }
+    return { pos, height: slots.length ? y + shelf : 0, used, overflow: null };
+}
+/**
+ * Lay `images` out on one sheet. Each sprite's slot is its size plus `extrude` on every side;
+ * slots are `padding` px apart and start at the sheet's top-left corner. Throws naming the image
+ * that does not fit when the sheet would exceed `maxSize`.
+ */
+export function packAtlas(images, opts = {}) {
+    const padding = Math.max(0, Math.floor(opts.padding ?? 1));
+    const maxSize = Math.max(1, Math.floor(opts.maxSize ?? 4096));
+    const extrude = Math.max(0, Math.floor(opts.extrude ?? 1));
+    const pow2 = opts.powerOfTwo ?? true;
+    const sort = opts.sort ?? true;
+    const names = Object.keys(images);
+    const slots = names.map((name) => {
+        const img = images[name];
+        if (!(img.width > 0 && img.height > 0)) {
+            throw new Error(`packAtlas: image "${name}" is ${img.width}×${img.height}`);
+        }
+        return { name, w: img.width + 2 * extrude, h: img.height + 2 * extrude };
+    });
+    if (sort) {
+        slots.sort((a, b) => b.h - a.h || b.w - a.w || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    }
+    let area = 0;
+    let widest = 0;
+    for (const s of slots) {
+        area += (s.w + padding) * (s.h + padding);
+        if (s.w > widest)
+            widest = s.w;
+    }
+    const roundUp = (n) => (pow2 ? nextPow2(n) : Math.ceil(n));
+    if (widest > maxSize) {
+        const s = slots.find((s) => s.w === widest);
+        throw new Error(`packAtlas: image "${s.name}" is ${s.w}px wide with its extrusion; maxSize is ${maxSize}`);
+    }
+    let width = Math.min(maxSize, roundUp(Math.max(widest, Math.sqrt(area))));
+    let packed = shelfPack(slots, width, padding);
+    let height = roundUp(packed.height);
+    // A sheet taller than it is wide (or than maxSize) is widened until it fits or cannot grow.
+    while ((height > width || height > maxSize) && width < maxSize) {
+        width = Math.min(maxSize, pow2 ? width * 2 : Math.ceil(width * 1.25));
+        packed = shelfPack(slots, width, padding);
+        height = roundUp(packed.height);
+    }
+    if (packed.overflow !== null || height > maxSize) {
+        // The first slot whose bottom edge crosses maxSize is the one that does not fit.
+        let culprit = packed.overflow;
+        if (culprit === null) {
+            for (let i = 0; i < slots.length; i++) {
+                if (packed.pos[i].y + slots[i].h > maxSize) {
+                    culprit = slots[i].name;
+                    break;
+                }
+            }
+        }
+        throw new Error(`packAtlas: image "${culprit}" does not fit: ${slots.length} images need more than ${maxSize}×${maxSize}`);
+    }
+    // The sheet is only as wide as its widest shelf (rounded up when powerOfTwo).
+    width = Math.max(1, roundUp(packed.used));
+    if (height < 1)
+        height = 1;
+    const rects = {};
+    slots.forEach((s, i) => {
+        const p = packed.pos[i];
+        const x = p.x + extrude;
+        const y = p.y + extrude;
+        const w = s.w - 2 * extrude;
+        const h = s.h - 2 * extrude;
+        rects[s.name] = {
+            x,
+            y,
+            w,
+            h,
+            u0: x / width,
+            v0: y / height,
+            u1: (x + w) / width,
+            v1: (y + h) / height,
+        };
+    });
+    return {
+        width,
+        height,
+        rects,
+        extrude,
+        draw(ctx) {
+            for (const name of names)
+                drawOne(ctx, images[name], rects[name], extrude);
+        },
+    };
+}
+function drawOne(ctx, img, r, e) {
+    if (isPixels(img)) {
+        const out = ctx.createImageData(r.w + 2 * e, r.h + 2 * e);
+        extrudePixels(img, e, out.data);
+        ctx.putImageData(out, r.x - e, r.y - e);
+        return;
+    }
+    const { w, h } = r;
+    ctx.drawImage(img, 0, 0, w, h, r.x, r.y, w, h);
+    if (e <= 0)
+        return;
+    const x0 = r.x - e;
+    const y0 = r.y - e;
+    const x1 = r.x + w;
+    const y1 = r.y + h;
+    // Edges: a one-pixel strip of the source stretched across the extrusion.
+    ctx.drawImage(img, 0, 0, w, 1, r.x, y0, w, e); // top
+    ctx.drawImage(img, 0, h - 1, w, 1, r.x, y1, w, e); // bottom
+    ctx.drawImage(img, 0, 0, 1, h, x0, r.y, e, h); // left
+    ctx.drawImage(img, w - 1, 0, 1, h, x1, r.y, e, h); // right
+    // Corners: one source pixel each.
+    ctx.drawImage(img, 0, 0, 1, 1, x0, y0, e, e);
+    ctx.drawImage(img, w - 1, 0, 1, 1, x1, y0, e, e);
+    ctx.drawImage(img, 0, h - 1, 1, 1, x0, y1, e, e);
+    ctx.drawImage(img, w - 1, h - 1, 1, 1, x1, y1, e, e);
+}
+/**
+ * Copy `src` into the centre of an RGBA buffer `(w + 2e) × (h + 2e)` and fill the border with
+ * the nearest edge pixel (clamp-to-edge in software). Exported for tests and custom drawers.
+ */
+export function extrudePixels(src, e, out) {
+    const { width: w, height: h, data } = src;
+    const W = w + 2 * e;
+    const H = h + 2 * e;
+    if (out.length < W * H * 4)
+        throw new Error('extrudePixels: output too small');
+    for (let y = 0; y < H; y++) {
+        const sy = Math.min(h - 1, Math.max(0, y - e));
+        for (let x = 0; x < W; x++) {
+            const sx = Math.min(w - 1, Math.max(0, x - e));
+            const si = (sy * w + sx) * 4;
+            const di = (y * W + x) * 4;
+            out[di] = data[si];
+            out[di + 1] = data[si + 1];
+            out[di + 2] = data[si + 2];
+            out[di + 3] = data[si + 3];
+        }
+    }
+}
+/**
+ * Draw `layout` into an `OffscreenCanvas` and upload it with `loadTexture` (sRGB, mips on by
+ * default; pass `mips: false` for pixel art, with `filter` or `format` as `loadTexture` takes).
+ * Allocates; call it at load time.
+ */
+export function createAtlasTexture(device, layout, images, opts = {}) {
+    const { canvas: given, ...texOpts } = opts;
+    const canvas = given ?? new OffscreenCanvas(layout.width, layout.height);
+    if (canvas.width !== layout.width || canvas.height !== layout.height) {
+        canvas.width = layout.width;
+        canvas.height = layout.height;
+    }
+    const ctx = canvas.getContext('2d');
+    if (!ctx)
+        throw new Error('createAtlasTexture: no 2d context');
+    // `images` is the layout's own source map; a different one with the same names draws too.
+    packLayoutWith(layout, images).draw(ctx);
+    const texture = loadTexture(device, canvas, { label: 'atlas', ...texOpts });
+    return { texture, rects: layout.rects };
+}
+/** The layout's `draw` over `images` (the same object it was packed from, or a stand-in). */
+function packLayoutWith(layout, images) {
+    return {
+        draw(ctx) {
+            for (const name of Object.keys(layout.rects)) {
+                const img = images[name];
+                if (!img)
+                    throw new Error(`createAtlasTexture: no image for "${name}"`);
+                drawOne(ctx, img, layout.rects[name], layout.extrude);
+            }
+        },
+    };
+}

package/dist/assets/baked.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The manifest `pnpm bake` (`scripts/bake.mjs`) writes next to its baked bytes: what was baked
+ * from which sources, with a hash of the inputs. A game reads it to know which `.navm` and
+ * `.coll` files exist (and to decide whether to fall back to a runtime bake).
+ */
+/** What one baked file is. */
+export type BakeKind = 'nav' | 'collider';
+export interface BakeManifestEntry {
+    /** The config entry's `name`: the file is `<name>.navm` or `<name>.coll` beside the manifest. */
+    name: string;
+    kind: BakeKind;
+    /** The source files, as the config named them. */
+    sources: string[];
+    /** Hex SHA-256 over the sources' bytes and the entry's options. */
+    sha256: string;
+    /** Size of the baked file. */
+    bytes: number;
+    /** Bake time, milliseconds. */
+    ms: number;
+}
+export interface BakeManifest {
+    version: number;
+    /** ISO 8601. */
+    bakedAt: string;
+    entries: BakeManifestEntry[];
+}
+/** The manifest format this reader accepts. */
+export declare const BAKE_MANIFEST_VERSION = 1;
+/**
+ * Parse `bake-manifest.json` (a string or already-parsed JSON). Throws on another format version
+ * or a malformed entry, so a stale manifest fails loudly instead of naming files that are not there.
+ */
+export declare function readBakeManifest(json: string | unknown): BakeManifest;

package/dist/assets/baked.js

@@ -0,0 +1,38 @@
+/**
+ * The manifest `pnpm bake` (`scripts/bake.mjs`) writes next to its baked bytes: what was baked
+ * from which sources, with a hash of the inputs. A game reads it to know which `.navm` and
+ * `.coll` files exist (and to decide whether to fall back to a runtime bake).
+ */
+/** The manifest format this reader accepts. */
+export const BAKE_MANIFEST_VERSION = 1;
+/**
+ * Parse `bake-manifest.json` (a string or already-parsed JSON). Throws on another format version
+ * or a malformed entry, so a stale manifest fails loudly instead of naming files that are not there.
+ */
+export function readBakeManifest(json) {
+    const raw = typeof json === 'string' ? JSON.parse(json) : json;
+    if (!raw || typeof raw !== 'object')
+        throw new Error('bake-manifest: not an object');
+    const m = raw;
+    if (m.version !== BAKE_MANIFEST_VERSION) {
+        throw new Error(`bake-manifest: version ${String(m.version)}, expected ${BAKE_MANIFEST_VERSION}`);
+    }
+    if (!Array.isArray(m.entries))
+        throw new Error('bake-manifest: entries is not an array');
+    const entries = m.entries.map((e, i) => {
+        const r = (e ?? {});
+        const kind = r.kind;
+        if (typeof r.name !== 'string' || (kind !== 'nav' && kind !== 'collider')) {
+            throw new Error(`bake-manifest: entry ${i} has no name or an unknown kind`);
+        }
+        return {
+            name: r.name,
+            kind,
+            sources: Array.isArray(r.sources) ? r.sources.map(String) : [],
+            sha256: typeof r.sha256 === 'string' ? r.sha256 : '',
+            bytes: typeof r.bytes === 'number' ? r.bytes : 0,
+            ms: typeof r.ms === 'number' ? r.ms : 0,
+        };
+    });
+    return { version: BAKE_MANIFEST_VERSION, bakedAt: String(m.bakedAt ?? ''), entries };
+}