@jgengine/core 0.18.0 → 0.18.1

package/dist/anim/animGraph.js

@@ -0,0 +1,286 @@
+const DEFAULT_FADE = 0.2;
+/** Entity blackboard key the shell reads extra graph parameters from: `ctx.scene.entity.blackboard.set(id, ANIM_PARAMS_KEY, { aiming: true })`. */
+export const ANIM_PARAMS_KEY = "anim.params";
+function compare(actual, op, value) {
+    const a = actual === undefined ? 0 : Number(actual);
+    const b = Number(value);
+    switch (op) {
+        case ">":
+            return a > b;
+        case "<":
+            return a < b;
+        case ">=":
+            return a >= b;
+        case "<=":
+            return a <= b;
+        case "==":
+            return a === b;
+        case "!=":
+            return a !== b;
+    }
+}
+/** Static clip weights of a state at `params`, before any crossfade. */
+export function stateClipWeights(state, params) {
+    const out = {};
+    if (state.kind === "clip") {
+        out[state.clip] = 1;
+        return out;
+    }
+    if (state.kind === "blend1D") {
+        const points = [...state.points].sort((x, y) => x.at - y.at);
+        if (points.length === 0)
+            return out;
+        const value = Number(params[state.param] ?? 0);
+        if (value <= points[0].at) {
+            out[points[0].clip] = 1;
+            return out;
+        }
+        const last = points[points.length - 1];
+        if (value >= last.at) {
+            out[last.clip] = 1;
+            return out;
+        }
+        for (let i = 0; i + 1 < points.length; i += 1) {
+            const lo = points[i];
+            const hi = points[i + 1];
+            if (value >= lo.at && value <= hi.at) {
+                const t = hi.at === lo.at ? 0 : (value - lo.at) / (hi.at - lo.at);
+                out[lo.clip] = (out[lo.clip] ?? 0) + (1 - t);
+                out[hi.clip] = (out[hi.clip] ?? 0) + t;
+                return out;
+            }
+        }
+        return out;
+    }
+    const x = Number(params[state.params[0]] ?? 0);
+    const y = Number(params[state.params[1]] ?? 0);
+    let total = 0;
+    const raw = [];
+    for (const point of state.points) {
+        const dx = point.at[0] - x;
+        const dy = point.at[1] - y;
+        const d2 = dx * dx + dy * dy;
+        if (d2 < 1e-9) {
+            out[point.clip] = 1;
+            return out;
+        }
+        const w = 1 / d2;
+        raw.push({ clip: point.clip, w });
+        total += w;
+    }
+    for (const entry of raw)
+        out[entry.clip] = (out[entry.clip] ?? 0) + entry.w / total;
+    return out;
+}
+function stateSpeed(state) {
+    return state.speed ?? 1;
+}
+function stateLoops(state) {
+    return state.loop !== false;
+}
+/** Longest clip in a state at these weights; the state's timeline length for exit times and events. */
+function stateDuration(weights, clips) {
+    let duration = 0;
+    for (const clip of Object.keys(weights))
+        duration = Math.max(duration, clipDuration(clips[clip]));
+    return duration;
+}
+function clipDuration(info) {
+    return typeof info === "number" ? info : info?.duration ?? 0;
+}
+function rootPosition(track, time, duration, loop) {
+    const count = Math.min(track.times.length, Math.floor(track.values.length / 3));
+    if (count === 0)
+        return [0, 0, 0];
+    const first = track.times[0] ?? 0;
+    const last = track.times[count - 1] ?? first;
+    const cycle = loop && duration > 0 ? Math.floor(time / duration) : 0;
+    const local = loop && duration > 0 ? ((time % duration) + duration) % duration : Math.min(Math.max(time, first), last);
+    let i = 0;
+    while (i + 1 < count && (track.times[i + 1] ?? 0) <= local)
+        i += 1;
+    const next = Math.min(i + 1, count - 1);
+    const span = (track.times[next] ?? 0) - (track.times[i] ?? 0);
+    const t = next === i || span <= 0 ? 0 : (local - (track.times[i] ?? 0)) / span;
+    const out = [0, 0, 0];
+    for (let axis = 0; axis < 3; axis += 1) {
+        const a = track.values[i * 3 + axis] ?? 0;
+        const b = track.values[next * 3 + axis] ?? a;
+        const cycleOffset = loop && duration > 0 ? ((track.values[(count - 1) * 3 + axis] ?? 0) - (track.values[axis] ?? 0)) * cycle : 0;
+        out[axis] = a + (b - a) * t + cycleOffset;
+    }
+    return out;
+}
+function clipTimeFor(time, duration, loop) {
+    if (!(duration > 0))
+        return 0;
+    if (loop)
+        return time % duration;
+    return Math.min(time, duration);
+}
+/**
+ * Headless animation state machine and blend evaluator. It owns every clip's playback time and weight, so the
+ * renderer only seeks and weights actions on a mixer, and headless hosts, replays, and tests advance the same
+ * graph without three.js. Transitions are data (parameter comparisons and consumed triggers), layers can be
+ * masked or additive, and events fire by clip time, including across loop wraps.
+ *
+ * @capability anim-graph data-first animation state machine with blend trees, crossfades, layers, and clip events
+ */
+export function createAnimGraphRuntime(initial) {
+    let graph = initial;
+    let triggers = new Set();
+    let layers = {};
+    function reset() {
+        layers = {};
+        for (const layer of graph.layers)
+            layers[layer.id] = { current: layer.entry, time: 0, transition: null };
+    }
+    reset();
+    function pickTransition(layer, state, params, normalized) {
+        for (const transition of layer.transitions) {
+            if (transition.from !== "*" && transition.from !== state.current)
+                continue;
+            if (transition.to === state.current && transition.from === "*")
+                continue;
+            if (transition.trigger !== undefined && !triggers.has(transition.trigger))
+                continue;
+            if (transition.exitTime !== undefined && normalized < transition.exitTime)
+                continue;
+            if (transition.when !== undefined && !transition.when.every((c) => compare(params[c.param], c.op, c.value)))
+                continue;
+            if (transition.trigger !== undefined)
+                triggers.delete(transition.trigger);
+            return transition;
+        }
+        return null;
+    }
+    function collectEvents(out, clip, before, after, duration, loop) {
+        if (graph.events === undefined || !(duration > 0))
+            return;
+        for (const event of graph.events) {
+            if (event.clip !== clip)
+                continue;
+            const at = event.atSec;
+            if (loop) {
+                const wrapped = after < before;
+                const hit = wrapped ? at > before || at <= after : at > before && at <= after;
+                if (hit)
+                    out.push({ name: event.name, clip });
+            }
+            else if (at > before && at <= after) {
+                out.push({ name: event.name, clip });
+            }
+        }
+    }
+    return {
+        graph: () => graph,
+        retune(next) {
+            graph = next;
+            const previous = layers;
+            reset();
+            for (const [id, state] of Object.entries(previous)) {
+                const layer = graph.layers.find((l) => l.id === id);
+                if (layer !== undefined && layer.states[state.current] !== undefined)
+                    layers[id] = state;
+            }
+        },
+        state: () => ({ layers, triggers: [...triggers] }),
+        snapshot: () => ({ layers: structuredClone(layers), triggers: [...triggers] }),
+        restore(next) {
+            layers = structuredClone(next.layers);
+            triggers = new Set(next.triggers);
+        },
+        trigger(name) {
+            triggers.add(name);
+        },
+        stateOf: (layerId) => layers[layerId]?.current ?? null,
+        advance(dt, params, clips) {
+            const output = { clips: [], events: [] };
+            const rootDelta = [0, 0, 0];
+            for (const layer of graph.layers) {
+                const state = layers[layer.id];
+                if (state === undefined)
+                    continue;
+                const def = layer.states[state.current];
+                if (def === undefined)
+                    continue;
+                const layerWeight = layer.weight ?? 1;
+                const before = state.time;
+                state.time += dt * stateSpeed(def);
+                const weights = stateClipWeights(def, params);
+                const duration = stateDuration(weights, clips);
+                const loop = stateLoops(def);
+                const normalized = duration > 0 ? (loop ? (state.time % duration) / duration : Math.min(1, state.time / duration)) : 1;
+                for (const clip of Object.keys(weights)) {
+                    const duration = clipDuration(clips[clip]);
+                    collectEvents(output.events, clip, clipTimeFor(before, duration, loop), clipTimeFor(state.time, duration, loop), duration, loop);
+                    if (def.rootMotion) {
+                        const info = clips[clip];
+                        if (typeof info !== "number" && info?.rootTrack !== undefined) {
+                            const from = rootPosition(info.rootTrack, before, duration, loop);
+                            const to = rootPosition(info.rootTrack, state.time, duration, loop);
+                            for (let axis = 0; axis < 3; axis += 1)
+                                rootDelta[axis] += (to[axis] - from[axis]) * weights[clip] * layerWeight;
+                        }
+                    }
+                }
+                const transition = state.transition;
+                if (transition !== null) {
+                    transition.elapsed += dt;
+                    const t = transition.duration > 0 ? Math.min(1, transition.elapsed / transition.duration) : 1;
+                    const merged = {};
+                    const times = {};
+                    for (const [clip, w] of Object.entries(transition.fromWeights)) {
+                        merged[clip] = (merged[clip] ?? 0) + w * (1 - t);
+                        times[clip] = transition.fromTimes[clip] ?? 0;
+                    }
+                    for (const [clip, w] of Object.entries(weights)) {
+                        merged[clip] = (merged[clip] ?? 0) + w * t;
+                        times[clip] = clipTimeFor(state.time, clipDuration(clips[clip]), loop);
+                    }
+                    for (const [clip, w] of Object.entries(merged)) {
+                        if (w <= 0)
+                            continue;
+                        output.clips.push({ clip, weight: w * layerWeight, time: times[clip] ?? 0, layer: layer.id });
+                    }
+                    if (t >= 1)
+                        state.transition = null;
+                }
+                else {
+                    for (const [clip, w] of Object.entries(weights)) {
+                        if (w <= 0)
+                            continue;
+                        output.clips.push({ clip, weight: w * layerWeight, time: clipTimeFor(state.time, clipDuration(clips[clip]), loop), layer: layer.id });
+                    }
+                }
+                const next = pickTransition(layer, state, params, normalized);
+                if (next !== null && next.to !== state.current) {
+                    const fromWeights = {};
+                    const fromTimes = {};
+                    for (const entry of output.clips) {
+                        if (entry.layer !== layer.id)
+                            continue;
+                        fromWeights[entry.clip] = (fromWeights[entry.clip] ?? 0) + entry.weight / (layerWeight || 1);
+                        fromTimes[entry.clip] = entry.time;
+                    }
+                    state.current = next.to;
+                    state.time = 0;
+                    state.transition = {
+                        to: next.to,
+                        elapsed: 0,
+                        duration: next.duration ?? DEFAULT_FADE,
+                        fromWeights,
+                        fromTimes,
+                    };
+                }
+                else if (next !== null && next.to === state.current) {
+                    state.time = 0;
+                }
+            }
+            triggers.clear();
+            if (rootDelta[0] !== 0 || rootDelta[1] !== 0 || rootDelta[2] !== 0)
+                output.rootDelta = rootDelta;
+            return output;
+        },
+    };
+}

package/dist/anim/ikSolver.d.ts

@@ -0,0 +1,51 @@
+/** A three-dimensional point or direction represented without a renderer dependency. */
+export type Vec3 = readonly [number, number, number];
+/** A mutable three-dimensional tuple used by allocation-aware solver outputs. */
+export type MutableVec3 = [number, number, number];
+/** A quaternion in `(x, y, z, w)` order. */
+export type Quat = readonly [number, number, number, number];
+/** Inputs for {@link solveTwoBone}. */
+export interface TwoBoneInput {
+    root: Vec3;
+    mid: Vec3;
+    tip: Vec3;
+    target: Vec3;
+    pole: Vec3;
+}
+/** Reused output buffers filled by {@link solveTwoBone}. */
+export interface TwoBoneOutput {
+    mid: MutableVec3;
+    tip: MutableVec3;
+}
+/** Iteration budget and convergence threshold for {@link solveFabrik}. */
+export interface FabrikOptions {
+    iterations?: number;
+    tolerance?: number;
+}
+/** Inputs for {@link lookAt}. Angles are in radians. */
+export interface LookAtInput {
+    from: Vec3;
+    target: Vec3;
+    up: Vec3;
+    maxYaw?: number;
+    maxPitch?: number;
+}
+/**
+ * Solves a two-segment chain analytically, placing the middle and tip joints toward `target` and `pole`.
+ * The root remains fixed, and unreachable targets are clamped to the chain's maximum reach.
+ *
+ * @capability animation inverse kinematics solve a two-bone chain from a target and bend pole
+ */
+export declare function solveTwoBone(input: TwoBoneInput, out: TwoBoneOutput): TwoBoneOutput;
+/**
+ * Solves a chain with the FABRIK forward-and-backward reaching algorithm.
+ * Returned tuples are new values; the input chain is not modified.
+ *
+ * @capability animation inverse kinematics solve an arbitrary tuple chain toward a target
+ */
+export declare function solveFabrik(chain: readonly Vec3[], target: Vec3, options?: FabrikOptions): MutableVec3[];
+/** Returns a quaternion that points a +Z bone from `from` toward `target`, with optional yaw and pitch limits.
+ *
+ * @capability animation inverse kinematics orient a bone toward a target with constrained yaw and pitch
+ */
+export declare function lookAt(input: LookAtInput): Quat;

package/dist/anim/ikSolver.js

@@ -0,0 +1,124 @@
+const EPSILON = 1e-8;
+function distance(a, b) {
+    return Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+}
+function normalize(x, y, z) {
+    const length = Math.hypot(x, y, z);
+    return length > EPSILON ? [x / length, y / length, z / length] : [0, 0, 0];
+}
+function cross(a, b) {
+    return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+}
+function addScaled(origin, direction, amount) {
+    return [origin[0] + direction[0] * amount, origin[1] + direction[1] * amount, origin[2] + direction[2] * amount];
+}
+/**
+ * Solves a two-segment chain analytically, placing the middle and tip joints toward `target` and `pole`.
+ * The root remains fixed, and unreachable targets are clamped to the chain's maximum reach.
+ *
+ * @capability animation inverse kinematics solve a two-bone chain from a target and bend pole
+ */
+export function solveTwoBone(input, out) {
+    const firstLength = distance(input.root, input.mid);
+    const secondLength = distance(input.mid, input.tip);
+    const toTarget = [input.target[0] - input.root[0], input.target[1] - input.root[1], input.target[2] - input.root[2]];
+    const targetDistance = Math.hypot(...toTarget);
+    const direction = targetDistance > EPSILON ? normalize(...toTarget) : normalize(input.mid[0] - input.root[0], input.mid[1] - input.root[1], input.mid[2] - input.root[2]);
+    const minReach = Math.abs(firstLength - secondLength);
+    const reach = Math.min(Math.max(targetDistance, minReach), firstLength + secondLength);
+    const clampedTarget = addScaled(input.root, direction, reach);
+    let bendNormal = normalize(...cross(direction, [input.pole[0] - input.root[0], input.pole[1] - input.root[1], input.pole[2] - input.root[2]]));
+    if (Math.hypot(...bendNormal) <= EPSILON) {
+        const fallback = Math.abs(direction[1]) < 0.9 ? [0, 1, 0] : [1, 0, 0];
+        bendNormal = normalize(...cross(direction, fallback));
+    }
+    const bendDirection = normalize(...cross(bendNormal, direction));
+    const along = (firstLength * firstLength - secondLength * secondLength + reach * reach) / (2 * reach || 1);
+    const height = Math.sqrt(Math.max(0, firstLength * firstLength - along * along));
+    const solvedMid = addScaled(addScaled(input.root, direction, along), bendDirection, height);
+    out.mid[0] = solvedMid[0];
+    out.mid[1] = solvedMid[1];
+    out.mid[2] = solvedMid[2];
+    out.tip[0] = clampedTarget[0];
+    out.tip[1] = clampedTarget[1];
+    out.tip[2] = clampedTarget[2];
+    return out;
+}
+/**
+ * Solves a chain with the FABRIK forward-and-backward reaching algorithm.
+ * Returned tuples are new values; the input chain is not modified.
+ *
+ * @capability animation inverse kinematics solve an arbitrary tuple chain toward a target
+ */
+export function solveFabrik(chain, target, options = {}) {
+    if (chain.length === 0)
+        return [];
+    if (chain.length === 1)
+        return [[chain[0][0], chain[0][1], chain[0][2]]];
+    const points = chain.map((point) => [point[0], point[1], point[2]]);
+    const lengths = chain.slice(1).map((point, index) => distance(chain[index], point));
+    const root = points[0];
+    const totalLength = lengths.reduce((sum, length) => sum + length, 0);
+    const rootDistance = distance(root, target);
+    const iterations = Math.max(0, Math.floor(options.iterations ?? 10));
+    const tolerance = Math.max(0, options.tolerance ?? 1e-3);
+    if (rootDistance >= totalLength) {
+        const direction = normalize(target[0] - root[0], target[1] - root[1], target[2] - root[2]);
+        for (let i = 1; i < points.length; i += 1)
+            points[i] = addScaled(points[i - 1], direction, lengths[i - 1]);
+        return points;
+    }
+    for (let iteration = 0; iteration < iterations; iteration += 1) {
+        points[points.length - 1] = [target[0], target[1], target[2]];
+        for (let i = points.length - 2; i >= 0; i -= 1) {
+            const direction = normalize(points[i][0] - points[i + 1][0], points[i][1] - points[i + 1][1], points[i][2] - points[i + 1][2]);
+            points[i] = addScaled(points[i + 1], direction, lengths[i]);
+        }
+        points[0] = [root[0], root[1], root[2]];
+        for (let i = 1; i < points.length; i += 1) {
+            const direction = normalize(points[i][0] - points[i - 1][0], points[i][1] - points[i - 1][1], points[i][2] - points[i - 1][2]);
+            points[i] = addScaled(points[i - 1], direction, lengths[i - 1]);
+        }
+        if (distance(points[points.length - 1], target) <= tolerance)
+            break;
+    }
+    return points;
+}
+function quaternionFromBasis(right, up, forward) {
+    const trace = right[0] + up[1] + forward[2];
+    if (trace > 0) {
+        const s = Math.sqrt(trace + 1) * 2;
+        return [(up[2] - forward[1]) / s, (forward[0] - right[2]) / s, (right[1] - up[0]) / s, 0.25 * s];
+    }
+    if (right[0] > up[1] && right[0] > forward[2]) {
+        const s = Math.sqrt(1 + right[0] - up[1] - forward[2]) * 2;
+        return [0.25 * s, (right[1] + up[0]) / s, (right[2] + forward[0]) / s, (up[2] - forward[1]) / s];
+    }
+    if (up[1] > forward[2]) {
+        const s = Math.sqrt(1 + up[1] - right[0] - forward[2]) * 2;
+        return [(right[1] + up[0]) / s, 0.25 * s, (up[2] + forward[1]) / s, (forward[0] - right[2]) / s];
+    }
+    const s = Math.sqrt(1 + forward[2] - right[0] - up[1]) * 2;
+    return [(right[2] + forward[0]) / s, (up[2] + forward[1]) / s, 0.25 * s, (right[1] - up[0]) / s];
+}
+/** Returns a quaternion that points a +Z bone from `from` toward `target`, with optional yaw and pitch limits.
+ *
+ * @capability animation inverse kinematics orient a bone toward a target with constrained yaw and pitch
+ */
+export function lookAt(input) {
+    let direction = normalize(input.target[0] - input.from[0], input.target[1] - input.from[1], input.target[2] - input.from[2]);
+    if (Math.hypot(...direction) <= EPSILON)
+        return [0, 0, 0, 1];
+    let yaw = Math.atan2(direction[0], direction[2]);
+    let pitch = Math.atan2(direction[1], Math.hypot(direction[0], direction[2]));
+    if (input.maxYaw !== undefined)
+        yaw = Math.max(-Math.abs(input.maxYaw), Math.min(Math.abs(input.maxYaw), yaw));
+    if (input.maxPitch !== undefined)
+        pitch = Math.max(-Math.abs(input.maxPitch), Math.min(Math.abs(input.maxPitch), pitch));
+    direction = [Math.sin(yaw) * Math.cos(pitch), Math.sin(pitch), Math.cos(yaw) * Math.cos(pitch)];
+    let right = normalize(...cross(input.up, direction));
+    if (Math.hypot(...right) <= EPSILON)
+        right = normalize(...cross([0, 1, 0], direction));
+    const up = cross(direction, right);
+    return quaternionFromBasis(right, up, direction);
+}

package/dist/anim/locomotionGraph.d.ts

@@ -0,0 +1,26 @@
+import type { AnimGraph } from "./animGraph.js";
+/** Inputs for {@link locomotionGraph}: the idle/walk/run clip names and the one-shot table a rig config already carries. */
+export interface LocomotionGraphInput {
+    idle: string;
+    walk: string;
+    run?: string;
+    /** Speed (world units/sec) above which the character walks. Default 0.5. */
+    walkSpeed?: number;
+    /** Speed above which it runs. Default 6. */
+    runSpeed?: number;
+    /** Crossfade seconds between locomotion states. Default 0.2. */
+    fadeSec?: number;
+    /** One-shot clips keyed by trigger name; `death` holds its last frame instead of returning. */
+    oneShots?: Readonly<Record<string, string>>;
+}
+/** The parameter name the shell feeds with the entity's smoothed ground speed. */
+export declare const LOCOMOTION_SPEED_PARAM = "speed";
+/** Layer id the locomotion graph uses; query `runtime.stateOf(LOCOMOTION_LAYER)`. */
+export declare const LOCOMOTION_LAYER = "base";
+/**
+ * The engine's default locomotion as an authored graph: a speed-driven blend between idle, walk, and run, plus a
+ * state per one-shot that plays once and returns (or clamps for `death`). What `useModelAnimation` used to hardcode.
+ *
+ * @capability locomotion-graph build the default idle/walk/run plus one-shot graph from clip names
+ */
+export declare function locomotionGraph(input: LocomotionGraphInput): AnimGraph;

package/dist/anim/locomotionGraph.js

@@ -0,0 +1,33 @@
+/** The parameter name the shell feeds with the entity's smoothed ground speed. */
+export const LOCOMOTION_SPEED_PARAM = "speed";
+/** Layer id the locomotion graph uses; query `runtime.stateOf(LOCOMOTION_LAYER)`. */
+export const LOCOMOTION_LAYER = "base";
+/**
+ * The engine's default locomotion as an authored graph: a speed-driven blend between idle, walk, and run, plus a
+ * state per one-shot that plays once and returns (or clamps for `death`). What `useModelAnimation` used to hardcode.
+ *
+ * @capability locomotion-graph build the default idle/walk/run plus one-shot graph from clip names
+ */
+export function locomotionGraph(input) {
+    const walkSpeed = input.walkSpeed ?? 0.5;
+    const runSpeed = input.runSpeed ?? 6;
+    const fade = input.fadeSec ?? 0.2;
+    const points = [
+        { at: 0, clip: input.idle },
+        { at: walkSpeed, clip: input.walk },
+        ...(input.run === undefined ? [] : [{ at: runSpeed, clip: input.run }]),
+    ];
+    const states = {
+        locomotion: { kind: "blend1D", param: LOCOMOTION_SPEED_PARAM, points },
+    };
+    const transitions = [];
+    for (const [name, clip] of Object.entries(input.oneShots ?? {})) {
+        states[name] = { kind: "clip", clip, loop: false };
+        transitions.push({ from: "*", to: name, trigger: name, duration: 0.1 });
+        if (name !== "death")
+            transitions.push({ from: name, to: "locomotion", exitTime: 1, duration: fade });
+    }
+    return {
+        layers: [{ id: LOCOMOTION_LAYER, entry: "locomotion", states, transitions }],
+    };
+}

package/dist/assets/spriteAtlas.d.ts

@@ -0,0 +1,21 @@
+/** Portable image atlas data shared by renderers and headless game logic. */
+export interface SpriteAtlas {
+    image: string;
+    size: [number, number];
+    frames: Record<string, {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        pivot?: [number, number];
+    }>;
+    animations: Record<string, {
+        frames: string[];
+        fps: number;
+        loop?: boolean;
+    }>;
+}
+/** Convert Aseprite JSON exports (hash or array frame layouts) to the portable atlas format. */
+export declare function fromAseprite(json: unknown): SpriteAtlas;
+/** Convert TexturePacker JSON exports to the portable atlas format. */
+export declare function fromTexturePacker(json: unknown): SpriteAtlas;

package/dist/assets/spriteAtlas.js

@@ -0,0 +1,103 @@
+function object(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${label} must be an object.`);
+    return value;
+}
+function number(value, label) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        throw new Error(`${label} must be a finite number.`);
+    return value;
+}
+function frame(value, label) {
+    const data = object(value, label);
+    const x = number(data.x, `${label}.x`);
+    const y = number(data.y, `${label}.y`);
+    const w = number(data.w ?? data.width, `${label}.w`);
+    const h = number(data.h ?? data.height, `${label}.h`);
+    if (w <= 0 || h <= 0 || x < 0 || y < 0)
+        throw new Error(`${label} has invalid bounds.`);
+    const pivotValue = data.pivot;
+    const pivot = pivotValue === undefined ? undefined : [number(pivotValue[0], `${label}.pivot[0]`), number(pivotValue[1], `${label}.pivot[1]`)];
+    return pivot ? { x, y, w, h, pivot } : { x, y, w, h };
+}
+function imageAndSize(root) {
+    const meta = object(root.meta, "meta");
+    const image = typeof meta.image === "string" ? meta.image : typeof root.image === "string" ? root.image : undefined;
+    if (!image)
+        throw new Error("Sprite atlas image is required.");
+    const rawSize = object(meta.size ?? root.size, "size");
+    const size = [number(rawSize.w ?? rawSize.width, "size[0]"), number(rawSize.h ?? rawSize.height, "size[1]")];
+    if (size[0] <= 0 || size[1] <= 0)
+        throw new Error("Sprite atlas size must be positive.");
+    return { image, size };
+}
+function animationFrames(names, fps = 10, loop = true) {
+    if (!names.length || !Number.isFinite(fps) || fps <= 0)
+        throw new Error("Animation requires frames and a positive fps.");
+    return { frames: names, fps, ...(loop ? {} : { loop: false }) };
+}
+/** Convert Aseprite JSON exports (hash or array frame layouts) to the portable atlas format. */
+export function fromAseprite(json) {
+    const root = object(json, "Aseprite export");
+    const framesRoot = root.frames;
+    const frames = {};
+    const durations = {};
+    const names = [];
+    if (Array.isArray(framesRoot)) {
+        for (const [index, entry] of framesRoot.entries()) {
+            const e = object(entry, `frames[${index}]`);
+            const name = typeof e.filename === "string" ? e.filename : String(index);
+            frames[name] = frame(e.frame, `frames[${index}].frame`);
+            if (e.duration !== undefined)
+                durations[name] = number(e.duration, `frames[${index}].duration`);
+            names.push(name);
+        }
+    }
+    else {
+        for (const [name, entry] of Object.entries(object(framesRoot, "frames"))) {
+            const e = object(entry, `frames.${name}`);
+            frames[name] = frame(e.frame ?? e, `frames.${name}`);
+            if (e.duration !== undefined)
+                durations[name] = number(e.duration, `frames.${name}.duration`);
+            names.push(name);
+        }
+    }
+    if (!names.length)
+        throw new Error("Aseprite export must contain frames.");
+    const size = imageAndSize(root);
+    const animations = {};
+    const tags = Array.isArray(root.meta?.frameTags) ? root.meta.frameTags : [];
+    for (const [index, tagValue] of tags.entries()) {
+        const tag = object(tagValue, `meta.frameTags[${index}]`);
+        const name = String(tag.name ?? "");
+        const from = Number(tag.from);
+        const to = Number(tag.to);
+        if (!name || !Number.isInteger(from) || !Number.isInteger(to) || from < 0 || to >= names.length || from > to)
+            throw new Error(`Invalid animation tag at index ${index}.`);
+        const direction = tag.direction === "reverse" ? -1 : 1;
+        const ordered = names.slice(from, to + 1);
+        if (direction < 0)
+            ordered.reverse();
+        const totalDuration = ordered.reduce((sum, frameName) => sum + (durations[frameName] ?? 100), 0);
+        animations[name] = animationFrames(ordered, ordered.length * 1000 / totalDuration, tag.direction !== "pingpong");
+    }
+    if (!Object.keys(animations).length)
+        animations.default = animationFrames(names);
+    return { image: size.image, size: size.size, frames, animations };
+}
+/** Convert TexturePacker JSON exports to the portable atlas format. */
+export function fromTexturePacker(json) {
+    const root = object(json, "TexturePacker export");
+    const size = imageAndSize(root);
+    const frames = {};
+    const source = Array.isArray(root.frames) ? root.frames.map((entry, index) => [String((object(entry, `frames[${index}]`).filename ?? index)), entry]) : Object.entries(object(root.frames, "frames"));
+    for (const [name, value] of source) {
+        const e = object(value, `frames.${name}`);
+        frames[name] = frame(e.frame ?? e, `frames.${name}.frame`);
+    }
+    const names = Object.keys(frames);
+    if (!names.length)
+        throw new Error("TexturePacker export must contain frames.");
+    const animations = { default: animationFrames(names) };
+    return { image: size.image, size: size.size, frames, animations };
+}

package/dist/audio/audioFalloff.d.ts

@@ -27,6 +27,16 @@ export interface SoundDef {
     /** Positional emitters attenuate by distance from the listener; non-positional sounds (UI, music) play at flat gain. Default true. */
     positional?: boolean;
     falloff?: AudioFalloffConfig;
+    /** Web Audio spatial panning configuration. When present, the shell uses a PannerNode. */
+    spatial?: {
+        panning: "hrtf" | "equalpower";
+        refDistance?: number;
+        maxDistance?: number;
+        rolloff?: number;
+        coneInner?: number;
+        coneOuter?: number;
+        coneOuterGain?: number;
+    };
 }
 export declare function computeFalloffGain(distance: number, config?: AudioFalloffConfig): number;
 export declare function resolveEmitterGain(distance: number, sound: Pick<SoundDef, "gain" | "positional" | "falloff">, busGain: number): number;