@jgengine/core 0.18.0 → 0.19.0

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,35 @@
+import type { ModelAnimationConfig } from "../game/playableGame.js";
+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;
+/**
+ * The graph a model animation config plays: its `graph`, or the {@link locomotionGraph} its
+ * `states` and `oneShots` describe (a `string[]` one-shot uses its first variant). `undefined` for a
+ * single-clip config. The shell plays this and the editor inspects it, so both see the same graph.
+ *
+ * @capability locomotion-graph resolve the animation graph a model config plays
+ */
+export declare function animGraphFromConfig(config: ModelAnimationConfig): AnimGraph | undefined;

package/dist/anim/locomotionGraph.js

@@ -0,0 +1,62 @@
+/** 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 }],
+    };
+}
+/**
+ * The graph a model animation config plays: its `graph`, or the {@link locomotionGraph} its
+ * `states` and `oneShots` describe (a `string[]` one-shot uses its first variant). `undefined` for a
+ * single-clip config. The shell plays this and the editor inspects it, so both see the same graph.
+ *
+ * @capability locomotion-graph resolve the animation graph a model config plays
+ */
+export function animGraphFromConfig(config) {
+    if (config.graph !== undefined)
+        return config.graph;
+    const states = config.states;
+    if (states === undefined)
+        return undefined;
+    const oneShots = {};
+    for (const [event, spec] of Object.entries(config.oneShots ?? {})) {
+        const clip = typeof spec === "string" ? spec : spec[0];
+        if (clip !== undefined)
+            oneShots[event] = clip;
+    }
+    return locomotionGraph({
+        idle: states.idle,
+        walk: states.walk,
+        ...(states.run === undefined ? {} : { run: states.run }),
+        walkSpeed: states.walkSpeed,
+        runSpeed: states.runSpeed,
+        fadeSec: states.fadeSec,
+        ...(Object.keys(oneShots).length === 0 ? {} : { oneShots }),
+    });
+}

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,18 @@ 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;
+    /** Doppler strength for retained loops: 1 is physical, 0 or absent is off. Emitter velocity comes from `setLoop({ velocity })`, listener velocity from the camera. */
+    doppler?: number;
+    /** 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;

package/dist/audio/doppler.d.ts

@@ -0,0 +1,21 @@
+/** Speed of sound in air at 20 °C, metres per second — the default for {@link dopplerRate}. */
+export declare const SPEED_OF_SOUND = 343;
+type Vec3Tuple = readonly [number, number, number];
+/** Options for {@link dopplerRate}. */
+export interface DopplerOptions {
+    /** Scales both velocities; 1 is physical, 0 disables the shift. Default 1. */
+    factor?: number;
+    /** World units per second sound travels. Default {@link SPEED_OF_SOUND}. */
+    speedOfSound?: number;
+    /** Clamp window for the returned multiplier. Default `[0.5, 2]`. */
+    range?: readonly [number, number];
+}
+/**
+ * Doppler pitch multiplier for an emitter heard by a listener: `(c + vListener) / (c - vEmitter)`,
+ * where each speed is the component along the line between them, positive when closing. Multiply a
+ * loop's playback rate by it. Pure and allocation-free.
+ *
+ * @capability doppler-pitch pitch a moving sound up as it approaches and down as it passes, from listener and emitter velocity
+ */
+export declare function dopplerRate(listenerPosition: Vec3Tuple, listenerVelocity: Vec3Tuple, emitterPosition: Vec3Tuple, emitterVelocity: Vec3Tuple, options?: DopplerOptions): number;
+export {};

package/dist/audio/doppler.js

@@ -0,0 +1,32 @@
+/** Speed of sound in air at 20 °C, metres per second — the default for {@link dopplerRate}. */
+export const SPEED_OF_SOUND = 343;
+/**
+ * Doppler pitch multiplier for an emitter heard by a listener: `(c + vListener) / (c - vEmitter)`,
+ * where each speed is the component along the line between them, positive when closing. Multiply a
+ * loop's playback rate by it. Pure and allocation-free.
+ *
+ * @capability doppler-pitch pitch a moving sound up as it approaches and down as it passes, from listener and emitter velocity
+ */
+export function dopplerRate(listenerPosition, listenerVelocity, emitterPosition, emitterVelocity, options = {}) {
+    const factor = options.factor ?? 1;
+    const c = options.speedOfSound ?? SPEED_OF_SOUND;
+    const min = options.range?.[0] ?? 0.5;
+    const max = options.range?.[1] ?? 2;
+    const dx = emitterPosition[0] - listenerPosition[0];
+    const dy = emitterPosition[1] - listenerPosition[1];
+    const dz = emitterPosition[2] - listenerPosition[2];
+    const distance = Math.hypot(dx, dy, dz);
+    if (factor === 0 || c <= 0 || distance < 1e-6)
+        return 1;
+    const ux = dx / distance;
+    const uy = dy / distance;
+    const uz = dz / distance;
+    const listenerClosing = factor * (listenerVelocity[0] * ux + listenerVelocity[1] * uy + listenerVelocity[2] * uz);
+    const emitterClosing = -factor * (emitterVelocity[0] * ux + emitterVelocity[1] * uy + emitterVelocity[2] * uz);
+    const numerator = c + Math.max(-c * 0.99, listenerClosing);
+    const denominator = c - Math.min(c * 0.99, emitterClosing);
+    const rate = numerator / denominator;
+    if (!Number.isFinite(rate))
+        return 1;
+    return rate < min ? min : rate > max ? max : rate;
+}

package/dist/audio/engineLayers.d.ts

@@ -0,0 +1,83 @@
+/** One recorded engine sample, keyed by the rpm it was recorded at. */
+export interface EngineLayer {
+    /** Catalog sound id of the loop. */
+    sound: string;
+    /** Rpm the sample was recorded at; playback rate is `rpm / layer.rpm`. */
+    rpm: number;
+    /** Which load set the layer belongs to: `"on"` (throttle), `"off"` (coast/overrun) or `"any"` (always). Default `"any"`. */
+    load?: "on" | "off" | "any";
+    /** Extra gain for this layer. Default 1. */
+    gain?: number;
+}
+/** Config for {@link createEngineLayers}. */
+export interface EngineLayersConfig {
+    /** Prefix for the retained loop ids, one per layer: `${id}:${index}`. */
+    id: string;
+    layers: readonly EngineLayer[];
+    /** Load window the off-load set crossfades to the on-load set across. Default `[0.15, 0.6]`. */
+    loadCrossfade?: readonly [number, number];
+    /** Exponential rate the load follows `engineLoad` with, so a lifted throttle does not click between sets. Default 10. */
+    loadResponse?: number;
+}
+/** One layer's live mix. */
+export interface EngineLayerMix {
+    /** Retained loop id. */
+    id: string;
+    sound: string;
+    gain: number;
+    rate: number;
+}
+/** Serializable {@link EngineLayers} state. */
+export interface EngineLayersState {
+    load: number;
+}
+/** Per-tick parameters {@link EngineLayers.play} forwards to every layer's loop. */
+export interface EngineLayersPlayOptions {
+    at?: readonly [number, number, number];
+    velocity?: readonly [number, number, number];
+    /** Overall gain multiplier. Default 1. */
+    gain?: number;
+    lowpass?: number;
+    highpass?: number;
+}
+/** The part of `ctx.game.audio` {@link EngineLayers} drives. */
+export interface EngineLayersAudio {
+    loop(id: string, sound: string, options?: {
+        at?: readonly [number, number, number];
+    }): void;
+    setLoop(id: string, params: {
+        rate?: number;
+        gain?: number;
+        at?: readonly [number, number, number];
+        velocity?: readonly [number, number, number];
+        lowpass?: number;
+        highpass?: number;
+    }): void;
+    stopLoop(id: string): void;
+}
+/** A layered engine loop: N rpm-keyed samples crossfaded by rpm, with on- and off-load sets picked by engine load. */
+export interface EngineLayers {
+    /** Advance by `dt` and return each layer's gain and rate. The returned array and its entries are reused between calls. */
+    update(dt: number, signals: {
+        rpm: number;
+        load: number;
+    }): readonly EngineLayerMix[];
+    /** Start (idempotently) and update every layer's retained loop from the last {@link update}. */
+    play(audio: EngineLayersAudio, options?: EngineLayersPlayOptions): void;
+    /** Stop every layer's loop. */
+    stop(audio: EngineLayersAudio): void;
+    mix(): readonly EngineLayerMix[];
+    retune(next: EngineLayersConfig): void;
+    snapshot(): EngineLayersState;
+    restore(state: EngineLayersState): void;
+    reset(): void;
+}
+/**
+ * Layered engine sound: each set of rpm-keyed samples is equal-power crossfaded between the two
+ * samples bracketing the current rpm and pitched by `rpm / layer.rpm`; the on- and off-load sets are
+ * equal-power crossfaded by smoothed `engineLoad`. A config with only one load set plays it at every
+ * load. `play` drives `ctx.game.audio` directly, so a game needs no per-layer glue.
+ *
+ * @capability engine-layers layered engine audio: rpm-keyed samples crossfaded, with on-load and off-load sets picked by engine load
+ */
+export declare function createEngineLayers(initial: EngineLayersConfig): EngineLayers;