@jgengine/core 0.18.1 → 0.19.0

package/dist/anim/animGraph.d.ts

@@ -113,7 +113,10 @@ export interface AnimGraphOutput {
         name: string;
         clip: string;
     }[];
+    /** Root-bone travel over this advance from `rootMotion` states, in the rig's local units. */
     rootDelta?: [number, number, number];
+    /** `true` while any layer's current state has `rootMotion`, even on an advance with no travel. */
+    rootMotion?: true;
 }
 /** The evaluator handle: arm triggers, advance, inspect, snapshot and restore. */
 export interface AnimGraphRuntime {
@@ -141,4 +144,12 @@ export declare function stateClipWeights(state: AnimState, params: AnimParams):
  * @capability anim-graph data-first animation state machine with blend trees, crossfades, layers, and clip events
  */
 export declare function createAnimGraphRuntime(initial: AnimGraph): AnimGraphRuntime;
+/**
+ * Validates untrusted JSON (a saved scene document, a network payload) as an {@link AnimGraph}.
+ * Malformed states, transitions to unknown states, and bad conditions are dropped; a layer whose
+ * entry state is missing is dropped; the result is `undefined` when no layer survives.
+ *
+ * @capability anim-graph load an animation graph from saved JSON without trusting its shape
+ */
+export declare function parseAnimGraph(value: unknown): AnimGraph | undefined;
 export {};

package/dist/anim/animGraph.js

@@ -197,6 +197,7 @@ export function createAnimGraphRuntime(initial) {
         advance(dt, params, clips) {
             const output = { clips: [], events: [] };
             const rootDelta = [0, 0, 0];
+            let rootMotion = false;
             for (const layer of graph.layers) {
                 const state = layers[layer.id];
                 if (state === undefined)
@@ -205,6 +206,8 @@ export function createAnimGraphRuntime(initial) {
                 if (def === undefined)
                     continue;
                 const layerWeight = layer.weight ?? 1;
+                if (def.rootMotion === true && layerWeight > 0)
+                    rootMotion = true;
                 const before = state.time;
                 state.time += dt * stateSpeed(def);
                 const weights = stateClipWeights(def, params);
@@ -280,7 +283,132 @@ export function createAnimGraphRuntime(initial) {
             triggers.clear();
             if (rootDelta[0] !== 0 || rootDelta[1] !== 0 || rootDelta[2] !== 0)
                 output.rootDelta = rootDelta;
+            if (rootMotion)
+                output.rootMotion = true;
             return output;
         },
     };
 }
+const COMPARES = [">", "<", ">=", "<=", "==", "!="];
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function optionalNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function parseState(value) {
+    const raw = record(value);
+    if (raw === null)
+        return null;
+    const extra = {
+        ...(optionalNumber(raw.speed) === undefined ? {} : { speed: raw.speed }),
+        ...(typeof raw.loop === "boolean" ? { loop: raw.loop } : {}),
+        ...(typeof raw.rootMotion === "boolean" ? { rootMotion: raw.rootMotion } : {}),
+    };
+    if (raw.kind === "clip" && typeof raw.clip === "string")
+        return { kind: "clip", clip: raw.clip, ...extra };
+    if (!Array.isArray(raw.points))
+        return null;
+    if (raw.kind === "blend1D" && typeof raw.param === "string") {
+        const points = raw.points.flatMap((point) => {
+            const entry = record(point);
+            return entry !== null && typeof entry.clip === "string" && optionalNumber(entry.at) !== undefined ? [{ at: entry.at, clip: entry.clip }] : [];
+        });
+        return { kind: "blend1D", param: raw.param, points, ...extra };
+    }
+    if (raw.kind === "blend2D" && Array.isArray(raw.params) && raw.params.length === 2 && raw.params.every((param) => typeof param === "string")) {
+        const points = raw.points.flatMap((point) => {
+            const entry = record(point);
+            const at = entry?.at;
+            return entry !== null && typeof entry.clip === "string" && Array.isArray(at) && at.length === 2 && at.every((n) => optionalNumber(n) !== undefined)
+                ? [{ at: [at[0], at[1]], clip: entry.clip }]
+                : [];
+        });
+        return { kind: "blend2D", params: [raw.params[0], raw.params[1]], points, ...extra };
+    }
+    return null;
+}
+function parseTransition(value, states) {
+    const raw = record(value);
+    if (raw === null || typeof raw.from !== "string" || typeof raw.to !== "string")
+        return null;
+    if (states[raw.to] === undefined || (raw.from !== "*" && states[raw.from] === undefined))
+        return null;
+    const when = Array.isArray(raw.when)
+        ? raw.when.flatMap((condition) => {
+            const entry = record(condition);
+            return entry !== null &&
+                typeof entry.param === "string" &&
+                COMPARES.includes(entry.op) &&
+                (typeof entry.value === "number" || typeof entry.value === "boolean")
+                ? [{ param: entry.param, op: entry.op, value: entry.value }]
+                : [];
+        })
+        : undefined;
+    return {
+        from: raw.from,
+        to: raw.to,
+        ...(when === undefined || when.length === 0 ? {} : { when }),
+        ...(typeof raw.trigger === "string" ? { trigger: raw.trigger } : {}),
+        ...(optionalNumber(raw.duration) === undefined ? {} : { duration: Math.max(0, raw.duration) }),
+        ...(optionalNumber(raw.exitTime) === undefined ? {} : { exitTime: raw.exitTime }),
+    };
+}
+/**
+ * Validates untrusted JSON (a saved scene document, a network payload) as an {@link AnimGraph}.
+ * Malformed states, transitions to unknown states, and bad conditions are dropped; a layer whose
+ * entry state is missing is dropped; the result is `undefined` when no layer survives.
+ *
+ * @capability anim-graph load an animation graph from saved JSON without trusting its shape
+ */
+export function parseAnimGraph(value) {
+    const raw = record(value);
+    if (raw === null || !Array.isArray(raw.layers))
+        return undefined;
+    const layers = [];
+    const seen = new Set();
+    for (const candidate of raw.layers) {
+        const layer = record(candidate);
+        if (layer === null || typeof layer.id !== "string" || seen.has(layer.id) || typeof layer.entry !== "string")
+            continue;
+        const rawStates = record(layer.states);
+        if (rawStates === null)
+            continue;
+        const states = {};
+        for (const [name, state] of Object.entries(rawStates)) {
+            const parsed = parseState(state);
+            if (parsed !== null)
+                states[name] = parsed;
+        }
+        if (states[layer.entry] === undefined)
+            continue;
+        const transitions = Array.isArray(layer.transitions)
+            ? layer.transitions.flatMap((transition) => {
+                const parsed = parseTransition(transition, states);
+                return parsed === null ? [] : [parsed];
+            })
+            : [];
+        const mask = Array.isArray(layer.mask) ? layer.mask.filter((prefix) => typeof prefix === "string") : undefined;
+        seen.add(layer.id);
+        layers.push({
+            id: layer.id,
+            entry: layer.entry,
+            states,
+            transitions,
+            ...(mask === undefined ? {} : { mask }),
+            ...(typeof layer.additive === "boolean" ? { additive: layer.additive } : {}),
+            ...(optionalNumber(layer.weight) === undefined ? {} : { weight: Math.min(1, Math.max(0, layer.weight)) }),
+        });
+    }
+    if (layers.length === 0)
+        return undefined;
+    const events = Array.isArray(raw.events)
+        ? raw.events.flatMap((event) => {
+            const entry = record(event);
+            return entry !== null && typeof entry.clip === "string" && typeof entry.name === "string" && optionalNumber(entry.atSec) !== undefined
+                ? [{ clip: entry.clip, atSec: entry.atSec, name: entry.name }]
+                : [];
+        })
+        : [];
+    return { layers, ...(events.length === 0 ? {} : { events }) };
+}

package/dist/anim/boneTexture.d.ts

@@ -0,0 +1,55 @@
+/** A clip to bake: its name and length in seconds. */
+export interface BoneTextureClipInput {
+    name: string;
+    duration: number;
+}
+/** One baked clip's rows in a {@link BoneTextureLayout}. */
+export interface BoneTextureClip {
+    name: string;
+    /** First texture row of the clip. */
+    startFrame: number;
+    /** Rows baked for the clip, first and last pose included. */
+    frameCount: number;
+    duration: number;
+}
+/**
+ * Where every bone matrix of every baked frame lives in a vertex-animation texture: one row per
+ * frame, four RGBA texels (matrix columns) per bone. Plain data, so a baked crowd can be cached,
+ * shipped or checked in a test without a renderer.
+ */
+export interface BoneTextureLayout {
+    boneCount: number;
+    fps: number;
+    width: number;
+    height: number;
+    clips: BoneTextureClip[];
+}
+/** Inputs for {@link planBoneTexture}. */
+export interface BoneTextureInput {
+    boneCount: number;
+    clips: readonly BoneTextureClipInput[];
+    /** Baked samples per second. Default 30. */
+    fps?: number;
+    /** Largest texture side the target GPU accepts. Default 4096. */
+    maxTextureSize?: number;
+}
+/**
+ * Plans a bone-matrix texture for a rig's clips. Throws when the rig or the clip set does not fit
+ * `maxTextureSize`; lower `fps` or bake fewer clips.
+ *
+ * @capability animation bake many clips of a rig into one bone-matrix texture for instanced crowds
+ */
+export declare function planBoneTexture(input: BoneTextureInput): BoneTextureLayout;
+/** Two texture rows around a playback time and the blend between them. */
+export interface BoneTextureSample {
+    rowA: number;
+    rowB: number;
+    t: number;
+}
+/**
+ * Finds the baked rows around `time` in a clip, wrapping when `loop` and holding the last pose
+ * otherwise. This is the CPU mirror of the crowd shader's lookup.
+ *
+ * @capability animation look up the baked frames and blend for a crowd member's playback time
+ */
+export declare function sampleBoneTexture(clip: BoneTextureClip, fps: number, time: number, loop: boolean, out?: BoneTextureSample): BoneTextureSample;

package/dist/anim/boneTexture.js

@@ -0,0 +1,43 @@
+/**
+ * Plans a bone-matrix texture for a rig's clips. Throws when the rig or the clip set does not fit
+ * `maxTextureSize`; lower `fps` or bake fewer clips.
+ *
+ * @capability animation bake many clips of a rig into one bone-matrix texture for instanced crowds
+ */
+export function planBoneTexture(input) {
+    const fps = input.fps ?? 30;
+    const maxSize = input.maxTextureSize ?? 4096;
+    if (!(fps > 0))
+        throw new Error(`planBoneTexture: fps must be positive, got ${fps}`);
+    const width = Math.max(1, input.boneCount) * 4;
+    if (width > maxSize)
+        throw new Error(`planBoneTexture: ${input.boneCount} bones need ${width} texels per row, over the ${maxSize} limit`);
+    const clips = [];
+    let row = 0;
+    for (const clip of input.clips) {
+        const duration = Math.max(0, clip.duration);
+        const frameCount = Math.max(2, Math.ceil(duration * fps) + 1);
+        clips.push({ name: clip.name, startFrame: row, frameCount, duration });
+        row += frameCount;
+    }
+    if (row > maxSize)
+        throw new Error(`planBoneTexture: ${row} frames exceed the ${maxSize}-row limit; lower fps or bake fewer clips`);
+    return { boneCount: input.boneCount, fps, width, height: Math.max(1, row), clips };
+}
+/**
+ * Finds the baked rows around `time` in a clip, wrapping when `loop` and holding the last pose
+ * otherwise. This is the CPU mirror of the crowd shader's lookup.
+ *
+ * @capability animation look up the baked frames and blend for a crowd member's playback time
+ */
+export function sampleBoneTexture(clip, fps, time, loop, out) {
+    const result = out ?? { rowA: 0, rowB: 0, t: 0 };
+    const span = clip.frameCount - 1;
+    const raw = time * fps;
+    const frame = loop ? ((raw % span) + span) % span : Math.min(Math.max(raw, 0), span);
+    const a = Math.floor(frame);
+    result.rowA = clip.startFrame + a;
+    result.rowB = clip.startFrame + Math.min(a + 1, span);
+    result.t = frame - a;
+    return result;
+}

package/dist/anim/footPlacement.d.ts

@@ -0,0 +1,57 @@
+/** One foot's animated ankle height and the ground found under it, both in world units. */
+export interface FootGroundSample {
+    /** Animated ankle (foot bone) height this frame, before any correction. */
+    ankleY: number;
+    /** Ground height under the foot, or `null` when the probe found nothing. */
+    groundY: number | null;
+}
+/** Inputs for {@link placeFeet}. All heights are world units. */
+export interface FootPlacementInput {
+    feet: readonly FootGroundSample[];
+    /** Height of the model origin, which the clips were authored to stand on. */
+    originY: number;
+    /** Ankle height above the sole in the rig's rest pose; the sole never ends below the ground. */
+    ankleHeight: number;
+    /** Largest correction applied to a foot or the pelvis, up or down. */
+    maxAdjust: number;
+    /** A lowest sole this far above its ground reads as airborne. */
+    airborneGap: number;
+}
+/** Result of {@link placeFeet}: where each ankle should go and how far the pelvis drops. */
+export interface FootPlacement {
+    /** Vertical pelvis shift, `<= 0`, so the lowest planted foot can reach its ground. */
+    pelvisOffset: number;
+    /** Target ankle height per foot, or `null` when that foot has no ground or no correction. */
+    ankleTargets: (number | null)[];
+    /** `false` while the feet are clear of the ground, so callers fade the correction out. */
+    grounded: boolean;
+}
+/**
+ * Resolves foot placement for a rig whose clips were authored on flat ground at its origin.
+ * Each foot keeps its animated lift and moves by its ground's height above or below the origin,
+ * the sole is never left under the ground, and the pelvis drops by the deepest reach so both legs
+ * stay within length. Pure and allocation-light; the renderer applies the targets with
+ * {@link solveTwoBone}.
+ *
+ * @capability animation ground rigged feet on slopes and steps without hiding the swing leg
+ */
+export declare function placeFeet(input: FootPlacementInput, out?: FootPlacement): FootPlacement;
+/** A bone as {@link inferLegChains} sees it: its name and its parent's name. */
+export interface RigBone {
+    name: string;
+    parent: string | null;
+}
+/** Thigh → shin → foot bone names for one leg. */
+export interface LegChain {
+    root: string;
+    mid: string;
+    tip: string;
+}
+/**
+ * Finds leg chains on a humanoid rig by bone name: a thigh-like bone (`UpLeg`, `UpperLeg`, `Thigh`)
+ * with its first child and grandchild as shin and foot. Control, IK-target and twist bones are
+ * skipped. Returns chains in rig order; an empty array means the rig has no recognizable legs.
+ *
+ * @capability animation find thigh, shin and foot bones on a humanoid rig for foot IK
+ */
+export declare function inferLegChains(bones: readonly RigBone[]): LegChain[];

package/dist/anim/footPlacement.js

@@ -0,0 +1,67 @@
+function clamp(value, limit) {
+    return Math.max(-limit, Math.min(limit, value));
+}
+/**
+ * Resolves foot placement for a rig whose clips were authored on flat ground at its origin.
+ * Each foot keeps its animated lift and moves by its ground's height above or below the origin,
+ * the sole is never left under the ground, and the pelvis drops by the deepest reach so both legs
+ * stay within length. Pure and allocation-light; the renderer applies the targets with
+ * {@link solveTwoBone}.
+ *
+ * @capability animation ground rigged feet on slopes and steps without hiding the swing leg
+ */
+export function placeFeet(input, out) {
+    const result = out ?? { pelvisOffset: 0, ankleTargets: [], grounded: false };
+    result.ankleTargets.length = input.feet.length;
+    const limit = Math.max(0, input.maxAdjust);
+    let lowestGap = Infinity;
+    let pelvis = 0;
+    for (let i = 0; i < input.feet.length; i += 1) {
+        const foot = input.feet[i];
+        if (foot.groundY === null) {
+            result.ankleTargets[i] = null;
+            continue;
+        }
+        lowestGap = Math.min(lowestGap, foot.ankleY - input.ankleHeight - foot.groundY);
+        const followed = foot.ankleY + clamp(foot.groundY - input.originY, limit);
+        const target = Math.min(foot.ankleY + limit, Math.max(followed, foot.groundY + input.ankleHeight));
+        result.ankleTargets[i] = target;
+        pelvis = Math.min(pelvis, target - foot.ankleY);
+    }
+    result.grounded = lowestGap <= input.airborneGap;
+    result.pelvisOffset = result.grounded ? Math.max(-limit, pelvis) : 0;
+    return result;
+}
+const THIGH = /(upleg|upperleg|thigh|femur)/;
+const HELPER = /(ik|control|ctrl|twist|pole|target|roll)/;
+/**
+ * Finds leg chains on a humanoid rig by bone name: a thigh-like bone (`UpLeg`, `UpperLeg`, `Thigh`)
+ * with its first child and grandchild as shin and foot. Control, IK-target and twist bones are
+ * skipped. Returns chains in rig order; an empty array means the rig has no recognizable legs.
+ *
+ * @capability animation find thigh, shin and foot bones on a humanoid rig for foot IK
+ */
+export function inferLegChains(bones) {
+    const children = new Map();
+    for (const bone of bones) {
+        if (bone.parent === null)
+            continue;
+        const list = children.get(bone.parent);
+        if (list === undefined)
+            children.set(bone.parent, [bone.name]);
+        else
+            list.push(bone.name);
+    }
+    const firstChild = (name) => children.get(name)?.find((child) => !HELPER.test(child.toLowerCase()));
+    const chains = [];
+    for (const bone of bones) {
+        const key = bone.name.toLowerCase().replace(/[^a-z0-9]/g, "");
+        if (!THIGH.test(key) || HELPER.test(key))
+            continue;
+        const mid = firstChild(bone.name);
+        const tip = mid === undefined ? undefined : firstChild(mid);
+        if (mid !== undefined && tip !== undefined)
+            chains.push({ root: bone.name, mid, tip });
+    }
+    return chains;
+}

package/dist/anim/locomotionGraph.d.ts

@@ -1,3 +1,4 @@
+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 {
@@ -24,3 +25,11 @@ export declare const LOCOMOTION_LAYER = "base";
  * @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

@@ -31,3 +31,32 @@ export function locomotionGraph(input) {
         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/audio/audioFalloff.d.ts

@@ -27,6 +27,8 @@ 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";

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;