@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/anim/match.js

@@ -0,0 +1,153 @@
+/**
+ * Pose matching: a transition starts the target clip at the frame nearest the pose it leaves,
+ * instead of at 0, so a walk→run blend does not snap a planted foot to the other leg.
+ *
+ * `buildPoseFeatures` samples a clip at a fixed rate and stores, per sample, the root-space
+ * position and velocity of a few joints (feet, hands, head). `findBestFrame` compares a pose's
+ * world matrices (plus per-joint velocities) against every sample and returns the time of the
+ * cheapest one. Root space is the frame of one node (the first root by default) so a clip's
+ * baked travel and the instance's placement drop out. Allocates at build; the query allocates
+ * nothing when given an `out`.
+ */
+import { sampleClip } from './clip.js';
+import { invertAffine, poseToWorld, WORLD_NODE_FLOATS } from './pose.js';
+/** Floats per joint per sample. */
+const PER_JOINT = 6;
+const inv = new Float32Array(WORLD_NODE_FLOATS);
+const p = new Float32Array(3);
+/** `out = inverse root (3×4) · point`. */
+function toRoot(out, m, px, py, pz) {
+    out[0] = m[0] * px + m[1] * py + m[2] * pz + m[3];
+    out[1] = m[4] * px + m[5] * py + m[6] * pz + m[7];
+    out[2] = m[8] * px + m[9] * py + m[10] * pz + m[11];
+}
+/** @internal The first node with no parent (0 when none). */
+export function firstRoot(skeleton) {
+    const parents = skeleton.parents;
+    for (let i = 0; i < parents.length; i++)
+        if (parents[i] < 0)
+            return i;
+    return 0;
+}
+/**
+ * Sample `clip` on `skeleton` every `1 / sampleRate` seconds (the last sample at the clip's
+ * duration) and record, per sample and per joint of `opts.joints`, the joint's root-space
+ * position and velocity (finite difference to the next sample; the last sample wraps to the
+ * first, as a looping clip does). Allocates; call at load.
+ */
+export function buildPoseFeatures(clip, skeleton, opts) {
+    const rate = opts.sampleRate ?? 30;
+    if (!(rate > 0))
+        throw new Error(`buildPoseFeatures: sampleRate ${rate} must be > 0`);
+    const n = skeleton.parents.length;
+    const joints = Int16Array.from(opts.joints);
+    for (let j = 0; j < joints.length; j++) {
+        const node = joints[j];
+        if (node < 0 || node >= n)
+            throw new Error(`buildPoseFeatures: joint ${node} is not a node (${n} nodes)`);
+    }
+    const root = opts.root ?? firstRoot(skeleton);
+    if (root < 0 || root >= n)
+        throw new Error(`buildPoseFeatures: root ${root} is not a node (${n} nodes)`);
+    const duration = Math.max(0, clip.duration);
+    const count = Math.max(1, Math.round(duration * rate)) + 1;
+    const times = new Float32Array(count);
+    const stride = joints.length * PER_JOINT;
+    const data = new Float32Array(count * stride);
+    const pose = new Float32Array(skeleton.rest);
+    const world = new Float32Array(n * WORLD_NODE_FLOATS);
+    const cursor = new Uint32Array(Math.max(1, clip.channels.length));
+    // Positions first.
+    for (let s = 0; s < count; s++) {
+        const t = count > 1 ? (duration * s) / (count - 1) : 0;
+        times[s] = t;
+        pose.set(skeleton.rest);
+        sampleClip(clip, t, pose, 1, 'override', cursor);
+        poseToWorld(skeleton, pose, world);
+        invertAffine(inv, 0, world, root * WORLD_NODE_FLOATS);
+        for (let j = 0; j < joints.length; j++) {
+            const wo = joints[j] * WORLD_NODE_FLOATS;
+            toRoot(p, inv, world[wo + 3], world[wo + 7], world[wo + 11]);
+            const o = s * stride + j * PER_JOINT;
+            data[o] = p[0];
+            data[o + 1] = p[1];
+            data[o + 2] = p[2];
+        }
+    }
+    // Velocities: central difference, wrapping around the ends as a looping clip does (the
+    // last sample is the first again, so its neighbours are the second and the second to last).
+    const dt = count > 1 ? duration / (count - 1) : 1;
+    const span = count > 2 ? 2 * dt : dt;
+    for (let s = 0; s < count; s++) {
+        const next = s + 1 < count ? s + 1 : count > 2 ? 1 : s;
+        const prev = s > 0 ? s - 1 : count > 2 ? count - 2 : s;
+        for (let j = 0; j < joints.length; j++) {
+            const o = s * stride + j * PER_JOINT;
+            const no = next * stride + j * PER_JOINT;
+            const po = prev * stride + j * PER_JOINT;
+            data[o + 3] = span > 0 ? (data[no] - data[po]) / span : 0;
+            data[o + 4] = span > 0 ? (data[no + 1] - data[po + 1]) / span : 0;
+            data[o + 5] = span > 0 ? (data[no + 2] - data[po + 2]) / span : 0;
+        }
+    }
+    return { clip, joints, root, times, data, stride };
+}
+const DEFAULT_OUT = { time: 0, cost: 0 };
+/**
+ * Root-space positions of `joints` (3 floats each into `out`) from a pose's world matrices:
+ * what a velocity for `findBestFrame` is the time derivative of. Allocation-free.
+ */
+export function rootSpacePositions(poseWorld, root, joints, out) {
+    invertAffine(inv, 0, poseWorld, root * WORLD_NODE_FLOATS);
+    for (let j = 0; j < joints.length; j++) {
+        const wo = joints[j] * WORLD_NODE_FLOATS;
+        toRoot(p, inv, poseWorld[wo + 3], poseWorld[wo + 7], poseWorld[wo + 11]);
+        out[j * 3] = p[0];
+        out[j * 3 + 1] = p[1];
+        out[j * 3 + 2] = p[2];
+    }
+}
+/**
+ * The sample of `features` nearest a pose: `poseWorld` is `poseToWorld` of that pose (skeleton
+ * space; the root node's matrix in it defines root space), `velocity` holds the root-space
+ * velocity of each feature joint (`3 × joints` floats in `features.joints` order: the
+ * derivative of `rootSpacePositions`, so the root's own travel drops out), or `null` to match
+ * on positions alone. Cost per sample is the summed squared position gap plus `velocityWeight`
+ * times the summed squared velocity gap. Writes and returns `out` (a shared object when none
+ * is given). No allocation with `out`.
+ */
+export function findBestFrame(features, poseWorld, velocity, opts, out = DEFAULT_OUT) {
+    const vw = opts?.velocityWeight ?? 0.05;
+    const joints = features.joints;
+    const stride = features.stride;
+    const data = features.data;
+    invertAffine(inv, 0, poseWorld, features.root * WORLD_NODE_FLOATS);
+    let best = -1;
+    let bestCost = Number.POSITIVE_INFINITY;
+    const count = features.times.length;
+    for (let s = 0; s < count; s++) {
+        let cost = 0;
+        for (let j = 0; j < joints.length; j++) {
+            const wo = joints[j] * WORLD_NODE_FLOATS;
+            const o = s * stride + j * PER_JOINT;
+            toRoot(p, inv, poseWorld[wo + 3], poseWorld[wo + 7], poseWorld[wo + 11]);
+            const dx = p[0] - data[o];
+            const dy = p[1] - data[o + 1];
+            const dz = p[2] - data[o + 2];
+            cost += dx * dx + dy * dy + dz * dz;
+            if (velocity && vw > 0) {
+                const vx = velocity[j * 3] - data[o + 3];
+                const vy = velocity[j * 3 + 1] - data[o + 4];
+                const vz = velocity[j * 3 + 2] - data[o + 5];
+                cost += vw * (vx * vx + vy * vy + vz * vz);
+            }
+        }
+        if (cost < bestCost) {
+            bestCost = cost;
+            best = s;
+        }
+    }
+    out.time = best >= 0 ? features.times[best] : 0;
+    out.cost = best >= 0 ? bestCost : 0;
+    return out;
+}

package/dist/anim/mixer.d.ts

@@ -0,0 +1,113 @@
+/**
+ * `AnimationMixer`: plays clips on a skeleton as weighted, layered actions and writes one
+ * `Pose` per `update(dt)`.
+ *
+ * Composition, per update: `pose = rest`; then for each layer in ascending order, the layer's
+ * override actions are averaged by effective weight (so a crossfade whose weights sum to 1
+ * neither shrinks nor overshoots) and lerped onto the pose by `min(1, Σ weights)`, then the
+ * layer's additive actions are added with their own weights. An action's effective weight is
+ * `action.weight × fade`, where fades come from `fadeIn`, `crossFade` and `stop(action, fade)`.
+ *
+ * Actions come from a fixed pool (`maxActions`, default 8); `play` reuses a finished slot and
+ * throws when none is free. After the pool and the per-action cursors exist, `update` allocates
+ * nothing.
+ */
+import { type AnimationClip, type AnimBlendMode, type ClipCursor } from './clip.js';
+import { type Pose, type Skeleton } from './pose.js';
+export interface AnimPlayOptions {
+    /** Layer, ascending order of application. Default 0. */
+    layer?: number;
+    /** Target weight, 0..1. Default 1. */
+    weight?: number;
+    /** Loop at `clip.duration` (default true); `false` holds the last frame and sets `finished`. */
+    loop?: boolean;
+    /** Time scale; negative plays backwards. Default 1. */
+    speed?: number;
+    /** Seconds to fade the weight in from 0. Default 0. */
+    fadeIn?: number;
+    /** `'override'` (default) or `'additive'`, see `sampleClip`. */
+    blend?: AnimBlendMode;
+    /** Start time in seconds. Default 0 (or `clip.duration` when `speed < 0`). */
+    startTime?: number;
+}
+export type AnimationEventListener = (name: string, action: AnimationAction) => void;
+/** One playing clip. Fields marked settable may be changed between updates. */
+export declare class AnimationAction {
+    /** The clip; `null` while the slot is free. */
+    clip: AnimationClip | null;
+    layer: number;
+    /** Target weight (settable). */
+    weight: number;
+    /** Settable. */
+    loop: boolean;
+    /** Settable. */
+    speed: number;
+    /** Current time in seconds, settable (wrapped into `[0, duration)` when looping). */
+    time: number;
+    /** Settable: a paused action keeps its pose and weight but does not advance. */
+    paused: boolean;
+    blend: AnimBlendMode;
+    /** True once a non-looping action reached its end (or start when reversed). */
+    finished: boolean;
+    /** `weight × fade` from the last update; what the pose actually used. */
+    effectiveWeight: number;
+    /** @internal */
+    fadeFrom: number;
+    /** @internal */
+    fadeTo: number;
+    /** @internal */
+    fadeDuration: number;
+    /** @internal */
+    fadeElapsed: number;
+    /** @internal first update after `play` includes events at exactly `startTime`. */
+    fresh: boolean;
+    /** @internal */
+    cursor: ClipCursor;
+    /** True while the action contributes to the mixer. */
+    get active(): boolean;
+    /** The fade factor now (0..1). */
+    get fade(): number;
+    /** @internal */
+    startFade(to: number, seconds: number): void;
+}
+export interface AnimationMixerOptions {
+    /** Pool size: the most actions playing (including fading out) at once. Default 8. */
+    maxActions?: number;
+}
+export declare class AnimationMixer {
+    readonly skeleton: Skeleton;
+    /** The composed pose, rewritten by every `update`. */
+    readonly pose: Pose;
+    /** Every slot of the pool, free or not; filter on `active`. */
+    readonly actions: readonly AnimationAction[];
+    private readonly scratch;
+    private readonly listeners;
+    constructor(skeleton: Skeleton, opts?: AnimationMixerOptions);
+    /** Number of active actions. */
+    get playing(): number;
+    /** Start `clip` in a free slot. Throws when the pool (`maxActions`) is full. */
+    play(clip: AnimationClip, opts?: AnimPlayOptions): AnimationAction;
+    /**
+     * Fade `from` out over `seconds` (it stops at 0) while `to` fades in on the same layer; the
+     * two effective weights sum to `from.weight` throughout when `to.weight` matches. `to` may be
+     * a clip (started here) or an action already playing. Returns the incoming action.
+     */
+    crossFade(from: AnimationAction, to: AnimationClip | AnimationAction, seconds: number, opts?: AnimPlayOptions): AnimationAction;
+    /** Stop an action, at once or after a fade-out of `seconds`. */
+    stop(action: AnimationAction, seconds?: number): void;
+    /** Stop every action at once. */
+    stopAll(): void;
+    /** Listen for `clip.events` crossings. Returns the unsubscribe function. */
+    onEvent(cb: AnimationEventListener): () => void;
+    /** Advance every action by `dt` seconds and recompose `pose`. */
+    update(dt: number): void;
+    private release;
+    private advance;
+    /**
+     * Fire events whose time lies in `(prev, next]` (or `[prev, next]` when `inclusive`),
+     * unwrapped: looping actions see the clip repeated, so `e + k·duration` counts.
+     */
+    private fireEvents;
+    private crosses;
+    private emit;
+}

package/dist/anim/mixer.js

@@ -0,0 +1,314 @@
+/**
+ * `AnimationMixer`: plays clips on a skeleton as weighted, layered actions and writes one
+ * `Pose` per `update(dt)`.
+ *
+ * Composition, per update: `pose = rest`; then for each layer in ascending order, the layer's
+ * override actions are averaged by effective weight (so a crossfade whose weights sum to 1
+ * neither shrinks nor overshoots) and lerped onto the pose by `min(1, Σ weights)`, then the
+ * layer's additive actions are added with their own weights. An action's effective weight is
+ * `action.weight × fade`, where fades come from `fadeIn`, `crossFade` and `stop(action, fade)`.
+ *
+ * Actions come from a fixed pool (`maxActions`, default 8); `play` reuses a finished slot and
+ * throws when none is free. After the pool and the per-action cursors exist, `update` allocates
+ * nothing.
+ */
+import { createClipCursor, sampleClip, } from './clip.js';
+import { blendPose, createPose } from './pose.js';
+/** One playing clip. Fields marked settable may be changed between updates. */
+export class AnimationAction {
+    /** The clip; `null` while the slot is free. */
+    clip = null;
+    layer = 0;
+    /** Target weight (settable). */
+    weight = 1;
+    /** Settable. */
+    loop = true;
+    /** Settable. */
+    speed = 1;
+    /** Current time in seconds, settable (wrapped into `[0, duration)` when looping). */
+    time = 0;
+    /** Settable: a paused action keeps its pose and weight but does not advance. */
+    paused = false;
+    blend = 'override';
+    /** True once a non-looping action reached its end (or start when reversed). */
+    finished = false;
+    /** `weight × fade` from the last update; what the pose actually used. */
+    effectiveWeight = 0;
+    /** @internal */
+    fadeFrom = 1;
+    /** @internal */
+    fadeTo = 1;
+    /** @internal */
+    fadeDuration = 0;
+    /** @internal */
+    fadeElapsed = 0;
+    /** @internal first update after `play` includes events at exactly `startTime`. */
+    fresh = true;
+    /** @internal */
+    cursor = new Uint32Array(1);
+    /** True while the action contributes to the mixer. */
+    get active() {
+        return this.clip !== null;
+    }
+    /** The fade factor now (0..1). */
+    get fade() {
+        if (this.fadeDuration <= 0)
+            return this.fadeTo;
+        const u = Math.min(1, this.fadeElapsed / this.fadeDuration);
+        return this.fadeFrom + (this.fadeTo - this.fadeFrom) * u;
+    }
+    /** @internal */
+    startFade(to, seconds) {
+        this.fadeFrom = this.fade;
+        this.fadeTo = to;
+        this.fadeDuration = seconds;
+        this.fadeElapsed = 0;
+    }
+}
+export class AnimationMixer {
+    skeleton;
+    /** The composed pose, rewritten by every `update`. */
+    pose;
+    /** Every slot of the pool, free or not; filter on `active`. */
+    actions;
+    scratch;
+    listeners = [];
+    constructor(skeleton, opts = {}) {
+        this.skeleton = skeleton;
+        this.pose = createPose(skeleton);
+        this.scratch = createPose(skeleton);
+        const n = Math.max(1, opts.maxActions ?? 8);
+        const pool = [];
+        for (let i = 0; i < n; i++)
+            pool.push(new AnimationAction());
+        this.actions = pool;
+    }
+    /** Number of active actions. */
+    get playing() {
+        let n = 0;
+        for (const a of this.actions)
+            if (a.clip)
+                n++;
+        return n;
+    }
+    /** Start `clip` in a free slot. Throws when the pool (`maxActions`) is full. */
+    play(clip, opts = {}) {
+        let slot = null;
+        for (const a of this.actions) {
+            if (!a.clip) {
+                slot = a;
+                break;
+            }
+        }
+        if (!slot)
+            throw new Error(`AnimationMixer: all ${this.actions.length} action slots are playing`);
+        slot.clip = clip;
+        slot.layer = opts.layer ?? 0;
+        slot.weight = opts.weight ?? 1;
+        slot.loop = opts.loop ?? true;
+        slot.speed = opts.speed ?? 1;
+        slot.blend = opts.blend ?? 'override';
+        slot.paused = false;
+        slot.finished = false;
+        slot.fresh = true;
+        slot.time = opts.startTime ?? (slot.speed < 0 ? clip.duration : 0);
+        slot.fadeFrom = 1;
+        slot.fadeTo = 1;
+        slot.fadeDuration = 0;
+        slot.fadeElapsed = 0;
+        if (opts.fadeIn && opts.fadeIn > 0) {
+            slot.fadeFrom = 0;
+            slot.fadeDuration = opts.fadeIn;
+        }
+        slot.effectiveWeight = slot.weight * slot.fade;
+        if (slot.cursor.length < clip.channels.length)
+            slot.cursor = createClipCursor(clip);
+        else
+            slot.cursor.fill(0);
+        return slot;
+    }
+    /**
+     * Fade `from` out over `seconds` (it stops at 0) while `to` fades in on the same layer; the
+     * two effective weights sum to `from.weight` throughout when `to.weight` matches. `to` may be
+     * a clip (started here) or an action already playing. Returns the incoming action.
+     */
+    crossFade(from, to, seconds, opts = {}) {
+        const target = to instanceof AnimationAction
+            ? to
+            : this.play(to, {
+                layer: from.layer,
+                weight: from.weight,
+                blend: from.blend,
+                ...opts,
+                fadeIn: seconds,
+            });
+        if (target !== from) {
+            if (to instanceof AnimationAction && (target.fade < 1 || target.fadeTo < 1)) {
+                target.startFade(1, seconds);
+                target.effectiveWeight = target.weight * target.fade;
+            }
+            this.stop(from, seconds);
+        }
+        return target;
+    }
+    /** Stop an action, at once or after a fade-out of `seconds`. */
+    stop(action, seconds = 0) {
+        if (!action.clip)
+            return;
+        if (seconds > 0)
+            action.startFade(0, seconds);
+        else
+            this.release(action);
+    }
+    /** Stop every action at once. */
+    stopAll() {
+        for (const a of this.actions)
+            if (a.clip)
+                this.release(a);
+        this.pose.set(this.skeleton.rest);
+    }
+    /** Listen for `clip.events` crossings. Returns the unsubscribe function. */
+    onEvent(cb) {
+        this.listeners.push(cb);
+        return () => {
+            const i = this.listeners.indexOf(cb);
+            if (i >= 0)
+                this.listeners.splice(i, 1);
+        };
+    }
+    /** Advance every action by `dt` seconds and recompose `pose`. */
+    update(dt) {
+        const actions = this.actions;
+        let minLayer = Number.POSITIVE_INFINITY;
+        let maxLayer = Number.NEGATIVE_INFINITY;
+        for (const a of actions) {
+            if (!a.clip)
+                continue;
+            this.advance(a, dt);
+            if (!a.clip)
+                continue;
+            if (a.layer < minLayer)
+                minLayer = a.layer;
+            if (a.layer > maxLayer)
+                maxLayer = a.layer;
+        }
+        const pose = this.pose;
+        pose.set(this.skeleton.rest);
+        if (minLayer > maxLayer)
+            return;
+        const scratch = this.scratch;
+        for (let layer = minLayer; layer <= maxLayer; layer++) {
+            let sum = 0;
+            for (const a of actions) {
+                if (!a.clip || a.layer !== layer || a.blend !== 'override' || a.effectiveWeight <= 0)
+                    continue;
+                if (sum === 0)
+                    scratch.set(pose);
+                sum += a.effectiveWeight;
+                sampleClip(a.clip, a.time, scratch, a.effectiveWeight / sum, 'override', a.cursor);
+            }
+            if (sum > 0)
+                blendPose(pose, scratch, Math.min(sum, 1), pose);
+            for (const a of actions) {
+                if (!a.clip || a.layer !== layer || a.blend !== 'additive' || a.effectiveWeight <= 0)
+                    continue;
+                sampleClip(a.clip, a.time, pose, a.effectiveWeight, 'additive', a.cursor);
+            }
+        }
+    }
+    release(action) {
+        action.clip = null;
+        action.effectiveWeight = 0;
+        action.fadeTo = 1;
+        action.fadeFrom = 1;
+        action.fadeDuration = 0;
+    }
+    advance(a, dt) {
+        const clip = a.clip;
+        if (a.fadeDuration > 0) {
+            a.fadeElapsed += dt;
+            if (a.fadeElapsed >= a.fadeDuration) {
+                a.fadeFrom = a.fadeTo;
+                a.fadeDuration = 0;
+                if (a.fadeTo <= 0) {
+                    this.release(a);
+                    return;
+                }
+            }
+        }
+        a.effectiveWeight = a.weight * a.fade;
+        const d = clip.duration;
+        const prev = a.time;
+        const fresh = a.fresh;
+        a.fresh = false;
+        if (a.paused || (a.finished && !a.loop)) {
+            if (fresh)
+                this.fireEvents(a, prev, prev, true);
+            return;
+        }
+        let next = prev + dt * a.speed;
+        if (d <= 0) {
+            a.time = 0;
+            if (!a.loop)
+                a.finished = true;
+            return;
+        }
+        if (!a.loop) {
+            if (a.speed >= 0 && next >= d) {
+                next = d;
+                a.finished = true;
+            }
+            else if (a.speed < 0 && next <= 0) {
+                next = 0;
+                a.finished = true;
+            }
+            this.fireEvents(a, prev, next, fresh);
+            a.time = next;
+            return;
+        }
+        this.fireEvents(a, prev, next, fresh);
+        // Wrap into [0, d).
+        let w = next % d;
+        if (w < 0)
+            w += d;
+        a.time = w;
+    }
+    /**
+     * Fire events whose time lies in `(prev, next]` (or `[prev, next]` when `inclusive`),
+     * unwrapped: looping actions see the clip repeated, so `e + k·duration` counts.
+     */
+    fireEvents(a, prev, next, inclusive) {
+        const clip = a.clip;
+        const events = clip.events;
+        if (!events || events.length === 0 || this.listeners.length === 0)
+            return;
+        const d = clip.duration;
+        const forward = next >= prev;
+        const lo = forward ? prev : next;
+        const hi = forward ? next : prev;
+        // Loop repetitions that can touch [lo, hi]; events fire in playback order (k outer, the
+        // clip's event order inner, both reversed when playing backwards).
+        const loops = a.loop && d > 0;
+        const kLo = loops ? Math.floor(lo / d) - 1 : 0;
+        const kHi = loops ? Math.floor(hi / d) + 1 : 0;
+        const n = events.length;
+        for (let s = 0; s <= kHi - kLo; s++) {
+            const k = forward ? kLo + s : kHi - s;
+            for (let j = 0; j < n; j++) {
+                const e = events[forward ? j : n - 1 - j];
+                const et = e.time + k * d;
+                if (this.crosses(et, prev, next, inclusive && k === 0, forward))
+                    this.emit(e.name, a);
+            }
+        }
+    }
+    crosses(et, prev, next, inclusive, forward) {
+        if (forward)
+            return (inclusive ? et >= prev : et > prev) && et <= next;
+        return (inclusive ? et <= prev : et < prev) && et >= next;
+    }
+    emit(name, a) {
+        for (let i = 0; i < this.listeners.length; i++)
+            this.listeners[i](name, a);
+    }
+}

package/dist/anim/morph.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Morph targets (blend shapes) on the CPU: `base + Σ weight × delta` per vertex, written into
+ * the position and normal lanes of an interleaved vertex buffer the mesh then uploads
+ * (`Mesh.update`). The arithmetic is here; the parser (`assets/gltf.ts`) fills `MorphTarget`s
+ * and the loader (`assets/gltf-load.ts`) owns the buffers and the upload. Nothing allocates
+ * after `createMorphBlender`.
+ */
+/** Per-vertex deltas of one target, 3 floats per vertex, or null when it leaves that lane alone. */
+export interface MorphTarget {
+    position: Float32Array | null;
+    normal: Float32Array | null;
+}
+/**
+ * Where positions and normals sit in an interleaved vertex: `floats` per vertex, and the float
+ * offsets of the position (default 0) and normal (default 3; null when the layout has none).
+ * `VERTEX_LAYOUT_3D` from `render/mesh.ts` fits as is.
+ */
+export interface MorphLayout {
+    readonly floats: number;
+    readonly positionOffset?: number;
+    readonly normalOffset?: number | null;
+}
+export interface MorphBlender {
+    /** One weight per target; the game (or `sampleWeights`) writes here, `apply` reads. */
+    readonly weights: Float32Array;
+    readonly targetCount: number;
+    readonly vertexCount: number;
+    /**
+     * Write `base + Σ weights[i] × targets[i]` into `out`'s position and normal lanes (normals
+     * renormalised). Returns false, writing nothing, when no weight changed since the last apply
+     * into this same `out`; a first call or a new `out` copies the whole base first. No allocation.
+     */
+    apply(out: Float32Array): boolean;
+}
+/**
+ * A blender over `base` (the primitive's interleaved vertices in `layout`) and its `targets`.
+ * `weights` may be the array the blender should read (shared between the primitives of a mesh);
+ * it defaults to zeros, `targets.length` long. Throws when a target's deltas do not cover
+ * `base`'s vertices or `weights` is shorter than `targets`.
+ */
+export declare function createMorphBlender(base: Float32Array, targets: readonly MorphTarget[], layout: MorphLayout, weights?: Float32Array): MorphBlender;