@ludic-labs/assembly 0.0.0-stage → 0.4.0

package/dist/browser.js

@@ -0,0 +1,534 @@
+import { requireValue } from "./required.js";
+import { appendMesh, emptyMesh, meshForAsset } from "./mesh.js";
+import { bakeMesh } from "./bake.js";
+import { cross, dot, normalize } from "./math.js";
+import { poseAsset, posedMesh, samplePose } from "./motion.js";
+export const assetMesh = meshForAsset;
+const DRAG_RADIANS_PER_PIXEL = 0.012;
+const KEY_RADIANS = Math.PI / 12;
+const clampPitch = (value) => Math.max(0.05, Math.min(1.5, value));
+/**
+ * A CPU preview with optional scheduled clip playback. Call dispose when removed.
+ *
+ * Dragging grabs the model: it turns with the pointer horizontally and tilts vertically. When the
+ * canvas has focus, arrow keys orbit the same way (Shift for finer steps) and Home restores the
+ * initial view.
+ */
+export function createPreview(canvas, options = {}) {
+    const context = canvas.getContext("2d");
+    if (!context)
+        throw new Error("Canvas 2D is unavailable");
+    const size = options.size ?? 360;
+    const maxTriangles = options.maxTriangles ?? 20_000;
+    if (!Number.isInteger(maxTriangles) || maxTriangles < 1)
+        throw new RangeError("Invalid preview triangle budget");
+    if (!Number.isInteger(size) || size < 64 || size > 768)
+        throw new RangeError("Preview size must be 64–768 pixels");
+    const frameCacheBytes = options.frameCacheBytes ?? 24 * 1024 * 1024;
+    if (!Number.isSafeInteger(frameCacheBytes) || frameCacheBytes < 0)
+        throw new RangeError("Invalid preview frame cache budget");
+    canvas.width = size;
+    canvas.height = size;
+    let asset = null, tint = null, mesh = null, frame = null, basis = null;
+    const initialYaw = options.yaw ?? Math.atan2(24, -26), initialPitch = options.pitch ?? Math.atan2(28, Math.hypot(24, 26));
+    let yaw = initialYaw, pitch = initialPitch, disposed = false, drag = null, moved = false;
+    let ppu = 1, ox = 0, oy = 0, framing = null, pickOffset = [0, 0, 0];
+    let playback = null;
+    const frameCache = new Map();
+    let cacheBytes = 0, cacheConfig = "", currentPose = null, rendered = null;
+    const invalidateFrames = () => {
+        frameCache.clear();
+        cacheBytes = 0;
+    };
+    const identities = new WeakMap();
+    let nextIdentity = 0;
+    const identity = (value) => {
+        if (!identities.has(value))
+            identities.set(value, ++nextIdentity);
+        return requireValue(identities.get(value));
+    };
+    const draw = (value) => {
+        ({ frame, basis, ppu, ox, oy } = value);
+        context.clearRect(0, 0, size, size);
+        if (value.image)
+            context.putImageData(value.image, ox, oy);
+        canvas.dataset.rendered = "true";
+    };
+    const playbackMesh = () => {
+        const p = requireValue(playback), combined = emptyMesh();
+        appendMesh(combined, posedMesh(p.source, requireValue(currentPose), p.options.tint), p.options.offset ?? [0, 0, 0]);
+        for (const prop of p.options.props ?? [])
+            appendMesh(combined, meshForAsset(prop.asset, prop.tint), prop.offset ?? [0, 0, 0]);
+        if (combined.indices.length / 3 > maxTriangles)
+            throw new RangeError("Preview triangle budget exceeded");
+        return combined;
+    };
+    const render = () => {
+        if (disposed)
+            return;
+        if (!mesh && playback && currentPose)
+            mesh = playbackMesh();
+        if (!mesh)
+            return;
+        const back = [Math.sin(yaw) * Math.cos(pitch), Math.sin(pitch), Math.cos(yaw) * Math.cos(pitch)], right = normalize(cross([0, 1, 0], back));
+        basis = { back, right, up: cross(back, right) };
+        let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+        const extend = (p) => {
+            const x = dot(p, requireValue(basis).right), y = dot(p, requireValue(basis).up);
+            minX = Math.min(minX, x);
+            maxX = Math.max(maxX, x);
+            minY = Math.min(minY, y);
+            maxY = Math.max(maxY, y);
+        };
+        // A playing clip uses fixed framing so the camera does not rescale as limbs move.
+        if (framing)
+            for (const x of [framing.min[0], framing.max[0]])
+                for (const y of [framing.min[1], framing.max[1]])
+                    for (const z of [framing.min[2], framing.max[2]])
+                        extend([x, y, z]);
+        else
+            for (let i = 0; i < mesh.positions.length; i += 3)
+                extend(mesh.positions.slice(i, i + 3));
+        const extent = Math.max(maxX - minX, maxY - minY);
+        if (!Number.isFinite(extent) || extent <= 0)
+            throw new RangeError("Preview requires nonempty geometry");
+        ppu = (size - 32) / extent;
+        const viewport = framing
+            ? {
+                left: -Math.round((size - (maxX - minX) * ppu) / 2 - minX * ppu),
+                top: Math.round((size - (maxY - minY) * ppu) / 2 + maxY * ppu),
+                width: size,
+                height: size,
+            }
+            : null;
+        const raster = bakeMesh(mesh, ppu, 1, basis, viewport);
+        const { color, depth: _depth, ...metadata } = raster;
+        frame = metadata;
+        if (viewport) {
+            ox = Math.round(frame.left * ppu) - viewport.left;
+            oy = viewport.top - Math.round(frame.top * ppu);
+        }
+        else {
+            ox = Math.floor((size - frame.width) / 2);
+            oy = Math.floor((size - frame.height) / 2);
+        }
+        rendered = {
+            frame,
+            basis,
+            ppu,
+            ox,
+            oy,
+            image: frame.width && frame.height
+                ? new ImageData(new Uint8ClampedArray(color.buffer), frame.width, frame.height)
+                : null,
+        };
+        draw(rendered);
+    };
+    const pick = (x, y) => {
+        if (disposed || !basis || !frame)
+            return null;
+        // Picking needs instance identity; material-only animation meshes do not.
+        if (!asset && playback && currentPose)
+            asset = poseAsset(playback.source, currentPose);
+        if (!asset)
+            return null;
+        const atX = (x - ox) / ppu + frame.left, atY = frame.top - (y - oy) / ppu;
+        let best = -Infinity, id = null;
+        for (const instance of asset.instances)
+            for (let i = 0; i < instance.mesh.indices.length; i += 3) {
+                const ps = instance.mesh.indices.slice(i, i + 3).map((index) => {
+                    const s = instance.mesh.positions, p = [
+                        requireValue(s[index * 3]) + pickOffset[0],
+                        requireValue(s[index * 3 + 1]) + pickOffset[1],
+                        requireValue(s[index * 3 + 2]) + pickOffset[2],
+                    ];
+                    return [
+                        dot(p, requireValue(basis).right),
+                        dot(p, requireValue(basis).up),
+                        dot(p, requireValue(basis).back),
+                    ];
+                });
+                const [a, b, c] = ps, area = (b[1] - c[1]) * (a[0] - c[0]) + (c[0] - b[0]) * (a[1] - c[1]);
+                if (Math.abs(area) < 1e-12)
+                    continue;
+                const u = ((b[1] - c[1]) * (atX - c[0]) + (c[0] - b[0]) * (atY - c[1])) / area, v = ((c[1] - a[1]) * (atX - c[0]) + (a[0] - c[0]) * (atY - c[1])) / area, w = 1 - u - v;
+                const depth = u * a[2] + v * b[2] + w * c[2];
+                if (u >= 0 && v >= 0 && w >= 0 && depth > best) {
+                    best = depth;
+                    id = instance.id;
+                }
+            }
+        return id;
+    };
+    /** Turn the camera; the next frame is rendered from the new view. */
+    const orbit = (deltaYaw, deltaPitch) => {
+        const nextPitch = clampPitch(pitch + deltaPitch);
+        if (!deltaYaw && nextPitch === pitch)
+            return;
+        invalidateFrames();
+        yaw += deltaYaw;
+        pitch = nextPitch;
+        render();
+    };
+    // Grab-to-rotate: the model's near side follows the pointer, horizontally and vertically.
+    const down = (e) => {
+        if (disposed || drag || (e.pointerType === "mouse" && e.button !== 0))
+            return;
+        drag = { pointer: e.pointerId, x: e.clientX, y: e.clientY, startX: e.clientX, startY: e.clientY };
+        moved = false;
+        canvas.setPointerCapture(e.pointerId);
+    };
+    const move = (e) => {
+        if (!drag || drag.pointer !== e.pointerId || disposed)
+            return;
+        moved ||= Math.hypot(e.clientX - drag.startX, e.clientY - drag.startY) > 3;
+        const dx = e.clientX - drag.x, dy = e.clientY - drag.y;
+        drag.x = e.clientX;
+        drag.y = e.clientY;
+        orbit(-dx * DRAG_RADIANS_PER_PIXEL, dy * DRAG_RADIANS_PER_PIXEL);
+    };
+    const up = (e) => {
+        if (!drag || drag.pointer !== e.pointerId)
+            return;
+        drag = null;
+        if (!moved) {
+            const r = canvas.getBoundingClientRect();
+            options.onPick?.(pick(((e.clientX - r.left) * size) / r.width, ((e.clientY - r.top) * size) / r.height));
+        }
+        if (canvas.hasPointerCapture(e.pointerId))
+            canvas.releasePointerCapture(e.pointerId);
+    };
+    const cancel = (e) => {
+        if (drag?.pointer === e.pointerId)
+            drag = null;
+    };
+    // Arrow keys orbit like a drag in that direction; Home restores the initial view.
+    const key = (e) => {
+        if (disposed || e.altKey || e.ctrlKey || e.metaKey)
+            return;
+        const step = e.shiftKey ? KEY_RADIANS / 3 : KEY_RADIANS;
+        if (e.key === "ArrowLeft")
+            orbit(step, 0);
+        else if (e.key === "ArrowRight")
+            orbit(-step, 0);
+        else if (e.key === "ArrowUp")
+            orbit(0, -step / 2);
+        else if (e.key === "ArrowDown")
+            orbit(0, step / 2);
+        else if (e.key === "Home") {
+            invalidateFrames();
+            yaw = initialYaw;
+            pitch = initialPitch;
+            render();
+        }
+        else
+            return;
+        e.preventDefault();
+    };
+    const showFrame = (n) => {
+        const p = requireValue(playback);
+        p.frame = n;
+        const pose = samplePose(p.source, p.clip, { frame: n, fps: p.fps }, { face: p.options.face });
+        currentPose = pose;
+        asset = null;
+        mesh = null;
+        pickOffset = p.options.offset ?? [0, 0, 0];
+        const config = JSON.stringify([
+            p.options.tint,
+            p.options.offset,
+            canvas.width,
+            canvas.height,
+            p.options.face && identity(p.options.face),
+            p.options.props?.map((prop) => [identity(prop.asset), prop.tint, prop.offset]),
+        ]);
+        if (config !== cacheConfig) {
+            invalidateFrames();
+            cacheConfig = config;
+        }
+        // Exact sampled geometry guards against fractional loop lengths, floating-point phase
+        // drift and face overlays with independent periods. Travel is reported, never drawn.
+        const key = frameCacheBytes && p.clip.loop
+            ? JSON.stringify([
+                n % Math.max(1, Math.round(p.clip.duration * p.fps)),
+                pose.transforms,
+                pose.root,
+                pose.states,
+            ])
+            : null;
+        const cached = key === null ? null : frameCache.get(key);
+        if (cached) {
+            frameCache.delete(requireValue(key));
+            frameCache.set(requireValue(key), cached);
+            rendered = cached.rendered;
+            draw(rendered);
+        }
+        else {
+            render();
+            if (key !== null && rendered) {
+                const bytes = (rendered.image?.data.byteLength ?? 0) + key.length * 2 + 256;
+                if (bytes <= frameCacheBytes) {
+                    while (cacheBytes + bytes > frameCacheBytes) {
+                        const oldest = requireValue(frameCache.keys().next().value);
+                        cacheBytes -= requireValue(frameCache.get(oldest)).bytes;
+                        frameCache.delete(oldest);
+                    }
+                    frameCache.set(key, { rendered, bytes });
+                    cacheBytes += bytes;
+                }
+            }
+        }
+        options.onFrame?.(n, pose);
+    };
+    const lastFrame = () => requireValue(playback).clip.loop
+        ? Infinity
+        : Math.round(requireValue(playback).clip.duration * requireValue(playback).fps);
+    const tick = (now) => {
+        const p = playback;
+        if (!p || disposed || !p.raf || !p.requested)
+            return;
+        // A frame timestamp can precede the moment playback started; never step backwards.
+        const n = Math.min(lastFrame(), p.startFrame + Math.max(0, Math.floor(((now - p.start) * p.fps) / 1000)));
+        if (n !== p.frame)
+            showFrame(n);
+        if (disposed || playback !== p)
+            return;
+        if (n >= lastFrame()) {
+            p.raf = 0;
+            p.requested = false;
+            return;
+        }
+        if (!p.requested || hidden())
+            return;
+        p.raf = requestAnimationFrame(tick);
+    };
+    const halt = () => {
+        if (playback?.raf)
+            cancelAnimationFrame(playback.raf);
+        if (playback)
+            playback.raf = 0;
+    };
+    const start = () => {
+        const p = requireValue(playback);
+        halt();
+        p.requested = p.frame < lastFrame();
+        p.startFrame = p.frame;
+        p.start = performance.now();
+        if (p.requested && !hidden())
+            p.raf = requestAnimationFrame(tick);
+    };
+    const stopPlayback = () => {
+        halt();
+        playback = null;
+        currentPose = null;
+        rendered = null;
+        invalidateFrames();
+        framing = null;
+        pickOffset = [0, 0, 0];
+    };
+    const ownerDocument = canvas.ownerDocument;
+    let intersecting = true;
+    const hidden = () => options.pauseWhenHidden !== false && (!!ownerDocument?.hidden || !intersecting);
+    const visibilityChanged = () => {
+        if (!playback?.requested || disposed)
+            return;
+        if (hidden())
+            halt();
+        else if (!playback.raf)
+            start();
+    };
+    const observer = options.pauseWhenHidden !== false && typeof IntersectionObserver !== "undefined"
+        ? new IntersectionObserver((entries) => {
+            for (const entry of entries)
+                if (entry.target === canvas)
+                    intersecting = entry.isIntersecting;
+            visibilityChanged();
+        })
+        : null;
+    observer?.observe(canvas);
+    if (options.pauseWhenHidden !== false)
+        ownerDocument?.addEventListener("visibilitychange", visibilityChanged);
+    canvas.addEventListener("pointerdown", down);
+    canvas.addEventListener("pointermove", move);
+    canvas.addEventListener("pointerup", up);
+    canvas.addEventListener("pointercancel", cancel);
+    canvas.addEventListener("lostpointercapture", cancel);
+    canvas.addEventListener("keydown", key);
+    return {
+        setAsset(value, shownTint) {
+            if (disposed)
+                throw new Error("Preview is disposed");
+            if (value.triangles > maxTriangles)
+                throw new RangeError("Preview triangle budget exceeded");
+            stopPlayback();
+            asset = value;
+            mesh = assetMesh(value, shownTint);
+            tint = shownTint ?? null;
+            render();
+        },
+        setMesh(value) {
+            if (disposed)
+                throw new Error("Preview is disposed");
+            if (value.indices.length / 3 > maxTriangles)
+                throw new RangeError("Preview triangle budget exceeded");
+            stopPlayback();
+            asset = null;
+            tint = null;
+            mesh = value;
+            render();
+        },
+        /** Recolor the current asset without restarting its pose, framing or playback clock. */
+        setTint(value = null) {
+            if (disposed)
+                throw new Error("Preview is disposed");
+            if (value !== null && !/^#[a-fA-F0-9]{6}$/.test(value))
+                throw new RangeError("Tint must be #rrggbb");
+            if (!asset && !playback)
+                throw new Error("No asset is loaded");
+            if (value === (playback ? (playback.options.tint ?? null) : tint))
+                return;
+            invalidateFrames();
+            if (playback) {
+                const { tint: _oldTint, ...retained } = playback.options;
+                playback.options = value === null ? retained : { ...retained, tint: value };
+                asset = null;
+                mesh = null;
+            }
+            else {
+                tint = value;
+                mesh = tint === null ? assetMesh(requireValue(asset)) : assetMesh(requireValue(asset), tint);
+            }
+            render();
+        },
+        setCamera(value) {
+            if (disposed)
+                throw new Error("Preview is disposed");
+            if (!Number.isFinite(value.yaw) || (value.pitch !== undefined && !Number.isFinite(value.pitch)))
+                throw new RangeError("Camera must be finite");
+            invalidateFrames();
+            yaw = value.yaw;
+            pitch = clampPitch(value.pitch ?? pitch);
+            render();
+        },
+        /** The current camera, including any orbit from dragging or the keyboard. */
+        get camera() {
+            return { yaw, pitch };
+        },
+        pick,
+        /** The current frame's scene and camera, e.g. for `exportGLB` or `bakeScene` from `/export`. */
+        snapshot() {
+            if (disposed)
+                throw new Error("Preview is disposed");
+            const scene = [], result = { scene, camera: { yaw, pitch } };
+            if (playback && currentPose) {
+                asset ??= poseAsset(playback.source, currentPose);
+                scene.push({ asset, tint: playback.options.tint, offset: playback.options.offset });
+                for (const prop of playback.options.props ?? [])
+                    scene.push({ ...prop });
+                if (framing)
+                    result.fit = { min: [...framing.min], max: [...framing.max] };
+                result.clip = playback.clip.name;
+                result.frame = playback.frame;
+            }
+            else if (asset)
+                scene.push({ asset, ...(tint === null ? {} : { tint }) });
+            return result;
+        },
+        /**
+         * Play a compiled clip of a rigged asset. Framing is fixed to the union of sampled
+         * bounds, travel is not applied (the clip plays in place), and frames are scheduled only while playing.
+         */
+        play(source, clip, play = {}) {
+            if (disposed)
+                throw new Error("Preview is disposed");
+            const fps = play.fps ?? 30;
+            if (!Number.isInteger(fps) || fps < 1 || fps > 120)
+                throw new RangeError("Preview fps must be 1–120");
+            stopPlayback();
+            const offset = play.offset ?? [0, 0, 0], min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity], include = (b, o) => {
+                for (let i = 0; i < 3; i++) {
+                    min[i] = Math.min(requireValue(min[i]), requireValue(b.min[i]) + requireValue(o[i]));
+                    max[i] = Math.max(requireValue(max[i]), requireValue(b.max[i]) + requireValue(o[i]));
+                }
+            };
+            if (play.fit)
+                include(play.fit, [0, 0, 0]);
+            else {
+                for (let k = 0; k < 24; k++)
+                    include(poseAsset(source, samplePose(source, clip, { phase: k / (clip.loop ? 24 : 23) })).bounds, offset);
+                for (const prop of play.props ?? [])
+                    include(prop.asset.bounds, prop.offset ?? [0, 0, 0]);
+            }
+            framing = { min, max };
+            playback = {
+                source,
+                clip,
+                options: play,
+                fps,
+                frame: 0,
+                startFrame: 0,
+                start: 0,
+                raf: 0,
+                requested: false,
+            };
+            showFrame(0);
+            if (play.autoplay !== false)
+                start();
+        },
+        pause() {
+            if (playback)
+                playback.requested = false;
+            halt();
+        },
+        resume() {
+            if (disposed)
+                throw new Error("Preview is disposed");
+            if (playback && !playback.requested && playback.frame < lastFrame())
+                start();
+        },
+        /** Show one integer frame of the playing clip; playback continues from it if it was running. */
+        seek(n) {
+            if (disposed)
+                throw new Error("Preview is disposed");
+            if (!playback)
+                throw new Error("No clip is loaded");
+            if (!Number.isInteger(n) || n < 0)
+                throw new RangeError("Frames are nonnegative integers");
+            const running = playback.requested;
+            showFrame(Math.min(n, lastFrame()));
+            if (running)
+                start();
+        },
+        get playing() {
+            return !!playback?.requested;
+        },
+        get suspended() {
+            return !!playback?.requested && hidden();
+        },
+        get frame() {
+            return playback?.frame;
+        },
+        dispose() {
+            if (disposed)
+                return;
+            stopPlayback();
+            disposed = true;
+            asset = null;
+            mesh = null;
+            frame = null;
+            drag = null;
+            observer?.disconnect();
+            ownerDocument?.removeEventListener("visibilitychange", visibilityChanged);
+            canvas.removeEventListener("pointerdown", down);
+            canvas.removeEventListener("pointermove", move);
+            canvas.removeEventListener("pointerup", up);
+            canvas.removeEventListener("pointercancel", cancel);
+            canvas.removeEventListener("lostpointercapture", cancel);
+            canvas.removeEventListener("keydown", key);
+            context.clearRect(0, 0, size, size);
+            delete canvas.dataset.rendered;
+        },
+        get disposed() {
+            return disposed;
+        },
+    };
+}

package/dist/compat.d.ts

@@ -0,0 +1,17 @@
+import type { MeshData, Vec3 } from "./types.js";
+export { fromLegacyRig, type LegacyJointMapping, type LegacyRig } from "./legacy.js";
+export declare const linear: (v: number) => number;
+export declare class MeshBuilder {
+    readonly mesh: MeshData;
+    joint: number;
+    constructor(jointPivots?: readonly [number, number]);
+    face(points: Vec3[], color: number, center: Vec3): void;
+    box(x: number, y: number, z: number, w: number, h: number, d: number, color: number, bevel?: number): this;
+    beam(a: Vec3, b: Vec3, width: number, color: number): this;
+    /** A round shaft in any direction; the asset supplies its physical endpoints. */
+    tube(a: Vec3, b: Vec3, radius: number, color: number): this;
+    funnel(x: number, y: number, z: number, bottomRadius: number, topRadius: number, height: number, color: number): this;
+    /** Coil in the YZ plane. Small cross-section segments keep distant details economical. */
+    coil(x: number, y: number, z: number, radius: number, thickness: number, color: number): this;
+    cylinder(x: number, y: number, z: number, r: number, h: number, color: number): this;
+}