@jgengine/core 0.19.0 → 0.22.0

package/dist/anim/animGraph.js

@@ -1,3 +1,4 @@
+import { resolveOneShotClip } from "../game/modelAnimation.js";
 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";
@@ -126,7 +127,7 @@ function clipTimeFor(time, duration, loop) {
  *
  * @capability anim-graph data-first animation state machine with blend trees, crossfades, layers, and clip events
  */
-export function createAnimGraphRuntime(initial) {
+export function createAnimGraphRuntime(initial, options = {}) {
     let graph = initial;
     let triggers = new Set();
     let layers = {};
@@ -136,6 +137,14 @@ export function createAnimGraphRuntime(initial) {
             layers[layer.id] = { current: layer.entry, time: 0, transition: null };
     }
     reset();
+    function chooseClip(state, def) {
+        if (def.kind === "clip" && def.variants !== undefined && def.variants.length > 0) {
+            state.selectedClip = resolveOneShotClip({ choice: def.variants }, "choice", options.rng?.() ?? 0) ?? def.clip;
+        }
+        else {
+            delete state.selectedClip;
+        }
+    }
     function pickTransition(layer, state, params, normalized) {
         for (const transition of layer.transitions) {
             if (transition.from !== "*" && transition.from !== state.current)
@@ -162,8 +171,7 @@ export function createAnimGraphRuntime(initial) {
                 continue;
             const at = event.atSec;
             if (loop) {
-                const wrapped = after < before;
-                const hit = wrapped ? at > before || at <= after : at > before && at <= after;
+                const hit = at >= 0 && at <= duration && Math.floor((after - at) / duration) > Math.floor((before - at) / duration);
                 if (hit)
                     out.push({ name: event.name, clip });
             }
@@ -205,18 +213,24 @@ export function createAnimGraphRuntime(initial) {
                 const def = layer.states[state.current];
                 if (def === undefined)
                     continue;
+                if (def.kind === "clip" && def.variants !== undefined && state.selectedClip === undefined)
+                    chooseClip(state, def);
                 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);
+                const weights = def.kind === "clip" && state.selectedClip !== undefined && def.variants?.includes(state.selectedClip)
+                    ? { [state.selectedClip]: 1 }
+                    : 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)) {
+                    if (!(weights[clip] * layerWeight > 0))
+                        continue;
                     const duration = clipDuration(clips[clip]);
-                    collectEvents(output.events, clip, clipTimeFor(before, duration, loop), clipTimeFor(state.time, duration, loop), duration, loop);
+                    collectEvents(output.events, clip, before, state.time, duration, loop);
                     if (def.rootMotion) {
                         const info = clips[clip];
                         if (typeof info !== "number" && info?.rootTrack !== undefined) {
@@ -235,7 +249,13 @@ export function createAnimGraphRuntime(initial) {
                     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;
+                        const playback = transition.fromPlayback?.[clip];
+                        if (w * (1 - t) * layerWeight > 0 && playback?.rootMotion === true)
+                            rootMotion = true;
+                        const time = transition.fromTimes[clip] ?? 0;
+                        const nextTime = playback === undefined ? time : clipTimeFor(time + dt * playback.speed, clipDuration(clips[clip]), playback.loop);
+                        transition.fromTimes[clip] = nextTime;
+                        times[clip] = nextTime;
                     }
                     for (const [clip, w] of Object.entries(weights)) {
                         merged[clip] = (merged[clip] ?? 0) + w * t;
@@ -257,28 +277,39 @@ export function createAnimGraphRuntime(initial) {
                     }
                 }
                 const next = pickTransition(layer, state, params, normalized);
-                if (next !== null && next.to !== state.current) {
+                if (next !== null) {
                     const fromWeights = {};
                     const fromTimes = {};
+                    const fromPlayback = {};
                     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;
+                        const previous = transition?.fromPlayback?.[entry.clip];
+                        const outgoingRoot = previous?.rootMotion === true && transition !== null &&
+                            transition.duration > 0 && transition.elapsed < transition.duration &&
+                            (transition.fromWeights[entry.clip] ?? 0) > 0;
+                        const playback = weights[entry.clip] === undefined && previous !== undefined
+                            ? previous : { speed: stateSpeed(def), loop };
+                        // Same-clip states share one clock, but an interrupted fade must retain either
+                        // influencing source's in-place policy until that source leaves the pose.
+                        fromPlayback[entry.clip] = { ...playback, ...(def.rootMotion === true || outgoingRoot ? { rootMotion: true } : {}) };
                     }
                     state.current = next.to;
                     state.time = 0;
+                    const target = layer.states[next.to];
+                    if (target !== undefined)
+                        chooseClip(state, target);
                     state.transition = {
                         to: next.to,
                         elapsed: 0,
                         duration: next.duration ?? DEFAULT_FADE,
                         fromWeights,
                         fromTimes,
+                        fromPlayback,
                     };
                 }
-                else if (next !== null && next.to === state.current) {
-                    state.time = 0;
-                }
             }
             triggers.clear();
             if (rootDelta[0] !== 0 || rootDelta[1] !== 0 || rootDelta[2] !== 0)
@@ -305,8 +336,10 @@ function parseState(value) {
         ...(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 (raw.kind === "clip" && typeof raw.clip === "string") {
+        const variants = Array.isArray(raw.variants) ? raw.variants.filter((clip) => typeof clip === "string" && clip.length > 0) : undefined;
+        return { kind: "clip", clip: raw.clip, ...(variants === undefined || variants.length === 0 ? {} : { variants }), ...extra };
+    }
     if (!Array.isArray(raw.points))
         return null;
     if (raw.kind === "blend1D" && typeof raw.param === "string") {
@@ -412,3 +445,158 @@ export function parseAnimGraph(value) {
         : [];
     return { layers, ...(events.length === 0 ? {} : { events }) };
 }
+/**
+ * Validate an authored graph without dropping broken combat states or weakening transition conditions.
+ * Known malformed fields and dangling references reject the whole graph with relative repair locations;
+ * valid data, including authored object/array order, is returned unchanged. Unknown extension fields are
+ * retained. Clip availability belongs to the imported-rig diagnostics. Use {@link parseAnimGraph} when
+ * permissive repair is intentional.
+ * @capability anim-graph validate authored animation graphs with located repair diagnostics without partial fallback
+ */
+export function validateAnimGraph(value) {
+    const diagnostics = [];
+    const issue = (path, message, repair) => { diagnostics.push({ path, message, repair }); };
+    const field = (path, key) => path === "" ? key : /^[A-Za-z_$][\w$]*$/.test(key) ? `${path}.${key}` : `${path}[${JSON.stringify(key)}]`;
+    const object = (candidate, path) => {
+        const raw = record(candidate);
+        if (raw === null)
+            issue(path, "Expected an animation graph object.", "Supply an object with the supported fields.");
+        return raw;
+    };
+    const text = (candidate, path, empty = false) => {
+        if (typeof candidate === "string" && (empty || candidate.trim().length > 0))
+            return true;
+        issue(path, "Expected a nonempty string.", "Set an explicit name from this graph or imported rig.");
+        return false;
+    };
+    const number = (candidate, path, min = -Infinity, max = Infinity) => {
+        if (typeof candidate === "number" && Number.isFinite(candidate) && candidate >= min && candidate <= max)
+            return true;
+        issue(path, `Expected a finite number${min === -Infinity && max === Infinity ? "" : max === Infinity ? ` at least ${min}` : ` between ${min} and ${max}`}.`, "Set a finite value in the supported range.");
+        return false;
+    };
+    const boolean = (candidate, path) => {
+        if (typeof candidate !== "boolean")
+            issue(path, "Expected a boolean.", "Set true or false, or omit the optional field.");
+    };
+    const array = (candidate, path) => {
+        if (Array.isArray(candidate))
+            return candidate;
+        issue(path, "Expected an array.", "Supply an array of supported entries.");
+        return null;
+    };
+    const tuple = (candidate, path, numeric) => {
+        const entries = array(candidate, path);
+        if (entries === null)
+            return;
+        if (entries.length !== 2)
+            issue(path, "Expected exactly two entries.", "Supply the two blend axes in authored order.");
+        entries.forEach((entry, index) => numeric ? number(entry, `${path}[${index}]`) : text(entry, `${path}[${index}]`));
+    };
+    const state = (candidate, path) => {
+        const raw = object(candidate, path);
+        if (raw === null)
+            return;
+        if (!["clip", "blend1D", "blend2D"].includes(raw.kind)) {
+            issue(`${path}.kind`, "Unknown animation state kind.", "Choose clip, blend1D or blend2D.");
+            return;
+        }
+        if (raw.speed !== undefined)
+            number(raw.speed, `${path}.speed`);
+        for (const key of ["loop", "rootMotion"])
+            if (raw[key] !== undefined)
+                boolean(raw[key], `${path}.${key}`);
+        const allowed = raw.kind === "clip" ? ["clip", "variants"] : raw.kind === "blend1D" ? ["param", "points"] : ["params", "points"];
+        for (const key of ["clip", "variants", "param", "params", "points"])
+            if (raw[key] !== undefined && !allowed.includes(key)) {
+                issue(`${path}.${key}`, `Field ${key} is not used by a ${raw.kind} state.`, "Remove the field or choose the matching state kind.");
+            }
+        if (raw.kind === "clip") {
+            text(raw.clip, `${path}.clip`);
+            if (raw.variants !== undefined)
+                array(raw.variants, `${path}.variants`)?.forEach((clip, index) => text(clip, `${path}.variants[${index}]`));
+            return;
+        }
+        if (raw.kind === "blend1D")
+            text(raw.param, `${path}.param`);
+        else
+            tuple(raw.params, `${path}.params`, false);
+        array(raw.points, `${path}.points`)?.forEach((candidate, index) => {
+            const pointPath = `${path}.points[${index}]`, point = object(candidate, pointPath);
+            if (point === null)
+                return;
+            text(point.clip, `${pointPath}.clip`);
+            if (raw.kind === "blend1D")
+                number(point.at, `${pointPath}.at`);
+            else
+                tuple(point.at, `${pointPath}.at`, true);
+        });
+    };
+    const raw = object(value, "");
+    if (raw === null)
+        return { graph: undefined, diagnostics };
+    const layers = array(raw.layers, "layers"), seen = new Set();
+    if (layers?.length === 0)
+        issue("layers", "An animation graph needs at least one layer.", "Add a layer with an entry state.");
+    layers?.forEach((candidate, index) => {
+        const path = `layers[${index}]`, layer = object(candidate, path);
+        if (layer === null)
+            return;
+        if (text(layer.id, `${path}.id`)) {
+            if (seen.has(layer.id))
+                issue(`${path}.id`, "Layer id is duplicated.", "Give each layer a distinct id.");
+            seen.add(layer.id);
+        }
+        const validEntry = text(layer.entry, `${path}.entry`), states = object(layer.states, `${path}.states`);
+        if (states !== null) {
+            for (const [name, candidate] of Object.entries(states)) {
+                text(name, field(`${path}.states`, name));
+                state(candidate, field(`${path}.states`, name));
+            }
+            if (validEntry && !Object.hasOwn(states, layer.entry))
+                issue(`${path}.entry`, "Entry state does not exist in this layer.", "Choose a state declared in this layer.");
+        }
+        if (layer.weight !== undefined)
+            number(layer.weight, `${path}.weight`, 0, 1);
+        if (layer.additive !== undefined)
+            boolean(layer.additive, `${path}.additive`);
+        if (layer.mask !== undefined)
+            array(layer.mask, `${path}.mask`)?.forEach((prefix, i) => text(prefix, `${path}.mask[${i}]`, true));
+        array(layer.transitions, `${path}.transitions`)?.forEach((candidate, i) => {
+            const edgePath = `${path}.transitions[${i}]`, edge = object(candidate, edgePath);
+            if (edge === null)
+                return;
+            for (const key of ["from", "to"])
+                if (text(edge[key], `${edgePath}.${key}`) && states !== null && !(key === "from" && edge[key] === "*") && !Object.hasOwn(states, edge[key])) {
+                    issue(`${edgePath}.${key}`, "Transition references an unknown state.", "Choose a state declared in this layer; only from may use *.");
+                }
+            if (edge.trigger !== undefined)
+                text(edge.trigger, `${edgePath}.trigger`);
+            if (edge.duration !== undefined)
+                number(edge.duration, `${edgePath}.duration`, 0);
+            if (edge.exitTime !== undefined)
+                number(edge.exitTime, `${edgePath}.exitTime`);
+            if (edge.when !== undefined)
+                array(edge.when, `${edgePath}.when`)?.forEach((candidate, i) => {
+                    const conditionPath = `${edgePath}.when[${i}]`, condition = object(candidate, conditionPath);
+                    if (condition === null)
+                        return;
+                    text(condition.param, `${conditionPath}.param`);
+                    if (!COMPARES.includes(condition.op))
+                        issue(`${conditionPath}.op`, "Unknown comparison operator.", "Choose >, <, >=, <=, == or !=.");
+                    if (typeof condition.value !== "boolean")
+                        number(condition.value, `${conditionPath}.value`);
+                });
+        });
+    });
+    if (raw.events !== undefined)
+        array(raw.events, "events")?.forEach((candidate, index) => {
+            const path = `events[${index}]`, event = object(candidate, path);
+            if (event === null)
+                return;
+            text(event.clip, `${path}.clip`);
+            text(event.name, `${path}.name`);
+            number(event.atSec, `${path}.atSec`, 0);
+        });
+    return { graph: diagnostics.length === 0 ? value : undefined, diagnostics };
+}

package/dist/anim/locomotionGraph.d.ts

@@ -12,10 +12,16 @@ export interface LocomotionGraphInput {
     /** 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>>;
+    oneShots?: Readonly<Record<string, string | readonly string[]>>;
 }
 /** The parameter name the shell feeds with the entity's smoothed ground speed. */
 export declare const LOCOMOTION_SPEED_PARAM = "speed";
+/** Ground contact reported by the shared player motor; absent for custom movers without authored parameters. */
+export declare const LOCOMOTION_GROUNDED_PARAM = "grounded";
+/** Resolved vertical velocity from the shared player motor, in world units/sec. */
+export declare const LOCOMOTION_VERTICAL_SPEED_PARAM = "verticalSpeed";
+/** Physically resolved crouch stance from the shared player motor. */
+export declare const LOCOMOTION_CROUCHED_PARAM = "crouched";
 /** Layer id the locomotion graph uses; query `runtime.stateOf(LOCOMOTION_LAYER)`. */
 export declare const LOCOMOTION_LAYER = "base";
 /**
@@ -27,8 +33,10 @@ export declare const LOCOMOTION_LAYER = "base";
 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.
+ * `states` and `oneShots` describe, retaining every one-shot variant. `undefined` for a
+ * single-clip config or incomplete locomotion roles. Idle must name a clip; an absent or blank
+ * walk role holds that idle clip at walking speeds until configured. 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
  */

package/dist/anim/locomotionGraph.js

@@ -1,5 +1,11 @@
 /** The parameter name the shell feeds with the entity's smoothed ground speed. */
 export const LOCOMOTION_SPEED_PARAM = "speed";
+/** Ground contact reported by the shared player motor; absent for custom movers without authored parameters. */
+export const LOCOMOTION_GROUNDED_PARAM = "grounded";
+/** Resolved vertical velocity from the shared player motor, in world units/sec. */
+export const LOCOMOTION_VERTICAL_SPEED_PARAM = "verticalSpeed";
+/** Physically resolved crouch stance from the shared player motor. */
+export const LOCOMOTION_CROUCHED_PARAM = "crouched";
 /** Layer id the locomotion graph uses; query `runtime.stateOf(LOCOMOTION_LAYER)`. */
 export const LOCOMOTION_LAYER = "base";
 /**
@@ -20,10 +26,18 @@ export function locomotionGraph(input) {
     const states = {
         locomotion: { kind: "blend1D", param: LOCOMOTION_SPEED_PARAM, points },
     };
+    const oneShots = Object.entries(input.oneShots ?? {}).filter(([, spec]) => typeof spec === "string" || spec.length > 0);
+    for (const [name, spec] of oneShots) {
+        const clip = typeof spec === "string" ? spec : spec[0];
+        states[name] = { kind: "clip", clip, loop: false, ...(typeof spec === "string" || spec.length < 2 ? {} : { variants: [...spec] }) };
+    }
     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 });
+    oneShots.sort(([a], [b]) => Number(b === "death") - Number(a === "death"));
+    for (const [name] of oneShots) {
+        for (const from of Object.keys(states)) {
+            if (from !== "death")
+                transitions.push({ from, to: name, trigger: name, duration: 0.1 });
+        }
         if (name !== "death")
             transitions.push({ from: name, to: "locomotion", exitTime: 1, duration: fade });
     }
@@ -33,8 +47,10 @@ export function locomotionGraph(input) {
 }
 /**
  * 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.
+ * `states` and `oneShots` describe, retaining every one-shot variant. `undefined` for a
+ * single-clip config or incomplete locomotion roles. Idle must name a clip; an absent or blank
+ * walk role holds that idle clip at walking speeds until configured. 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
  */
@@ -42,21 +58,15 @@ export function animGraphFromConfig(config) {
     if (config.graph !== undefined)
         return config.graph;
     const states = config.states;
-    if (states === undefined)
+    if (states === undefined || typeof states.idle !== "string" || states.idle.trim().length === 0)
         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 }),
+        walk: typeof states.walk === "string" && states.walk.trim().length > 0 ? states.walk : states.idle,
+        ...(typeof states.run !== "string" || states.run.trim().length === 0 ? {} : { run: states.run }),
         walkSpeed: states.walkSpeed,
         runSpeed: states.runSpeed,
         fadeSec: states.fadeSec,
-        ...(Object.keys(oneShots).length === 0 ? {} : { oneShots }),
+        ...(config.oneShots === undefined ? {} : { oneShots: config.oneShots }),
     });
 }

package/dist/audio/audioFalloff.d.ts

@@ -24,6 +24,10 @@ export interface SoundDef {
     /** Base gain before bus/falloff multipliers. Default 1. */
     gain?: number;
     loop?: boolean;
+    /** Maximum simultaneous reservations for this sound, including pending loads. Default the engine's total voice limit. */
+    maxVoices?: number;
+    /** Playback priority; higher priorities survive voice-budget pressure. Default 0. */
+    priority?: number;
     /** Positional emitters attenuate by distance from the listener; non-positional sounds (UI, music) play at flat gain. Default true. */
     positional?: boolean;
     falloff?: AudioFalloffConfig;

package/dist/audio/voiceAllocator.d.ts

@@ -0,0 +1,46 @@
+/** One reserved playback slot, including sources still loading. */
+export interface AudioVoice {
+    id: number;
+    soundId: string;
+    priority: number;
+}
+/** Detached allocator state; ids increase monotonically for deterministic oldest-first ties. */
+export interface VoiceAllocatorSnapshot {
+    nextId: number;
+    voices: AudioVoice[];
+}
+/** Caller-owned reservation storage. Reads and writes use detached state. */
+export interface VoiceAllocatorStorage {
+    read(): VoiceAllocatorSnapshot;
+    write(state: VoiceAllocatorSnapshot): void;
+}
+/** Playback budget. Zero disables playback; default 64. */
+export interface VoiceAllocatorConfig {
+    maxTotal?: number;
+    /** At capacity, steal the lowest-priority oldest voice, or reject new voices. Default "steal-lowest". */
+    overflow?: "steal-lowest" | "reject";
+    storage?: VoiceAllocatorStorage;
+}
+/** Admission result; stop every stolen source before starting the admitted voice. */
+export type VoiceAllocation = {
+    ok: false;
+} | {
+    ok: true;
+    voiceId: number;
+    stolen: number[];
+};
+/** Bounded reservations with higher-priority protection and oldest-first ties. */
+export interface VoiceAllocator {
+    request(soundId: string, priority?: number, maxVoices?: number): VoiceAllocation;
+    release(voiceId: number): void;
+    snapshot(): VoiceAllocatorSnapshot;
+    restore(state: VoiceAllocatorSnapshot): void;
+    /** Return reservations removed to meet the new limit; the playback owner stops them. */
+    retune(config: Pick<VoiceAllocatorConfig, "maxTotal" | "overflow">): number[];
+}
+/**
+ * Reserve bounded sound playback before fetching or constructing a graph. Equal priorities steal
+ * the oldest reservation; lower priorities cannot interrupt higher priorities. Policy is retunable.
+ * @capability audio-voice-budget bound simultaneous sound playback with per-sound caps, priorities, and deterministic stealing
+ */
+export declare function createVoiceAllocator(config?: VoiceAllocatorConfig): VoiceAllocator;

package/dist/audio/voiceAllocator.js

@@ -0,0 +1,76 @@
+function limit(value) {
+    if (!Number.isFinite(value) || value < 0)
+        throw new RangeError("Voice limit must be finite and nonnegative");
+    return Math.floor(value);
+}
+function copy(state) {
+    return { nextId: state.nextId, voices: state.voices.map((voice) => ({ ...voice })) };
+}
+function weakest(voices) {
+    return [...voices].sort((a, b) => a.priority - b.priority || a.id - b.id);
+}
+/**
+ * Reserve bounded sound playback before fetching or constructing a graph. Equal priorities steal
+ * the oldest reservation; lower priorities cannot interrupt higher priorities. Policy is retunable.
+ * @capability audio-voice-budget bound simultaneous sound playback with per-sound caps, priorities, and deterministic stealing
+ */
+export function createVoiceAllocator(config = {}) {
+    let maxTotal = limit(config.maxTotal ?? 64);
+    let overflow = config.overflow ?? "steal-lowest";
+    let memory = { nextId: 1, voices: [] };
+    const storage = config.storage ?? { read: () => memory, write: (next) => { memory = next; } };
+    function snapshot() { return copy(storage.read()); }
+    function restore(state) {
+        const ids = new Set();
+        if (!Number.isSafeInteger(state.nextId) || state.nextId < 1 || state.voices.length > maxTotal)
+            throw new RangeError("Invalid voice state");
+        for (const voice of state.voices) {
+            if (!Number.isSafeInteger(voice.id) || voice.id < 1 || voice.id >= state.nextId || ids.has(voice.id) || !Number.isFinite(voice.priority))
+                throw new RangeError("Invalid voice state");
+            ids.add(voice.id);
+        }
+        storage.write(copy(state));
+    }
+    restore(snapshot());
+    return {
+        snapshot, restore,
+        request(soundId, priority = 0, maxVoices = maxTotal) {
+            if (!Number.isFinite(priority))
+                throw new RangeError("Voice priority must be finite");
+            const soundLimit = limit(maxVoices);
+            if (maxTotal === 0 || soundLimit === 0)
+                return { ok: false };
+            const state = snapshot();
+            const same = weakest(state.voices.filter((voice) => voice.soundId === soundId));
+            const victims = same.slice(0, Math.max(0, same.length - soundLimit + 1));
+            const selected = new Set(victims.map((voice) => voice.id));
+            const remaining = weakest(state.voices.filter((voice) => !selected.has(voice.id)));
+            victims.push(...remaining.slice(0, Math.max(0, state.voices.length - victims.length - maxTotal + 1)));
+            if ((overflow === "reject" && victims.length > 0) || victims.some((voice) => voice.priority > priority))
+                return { ok: false };
+            const stolen = victims.map((voice) => voice.id);
+            const removed = new Set(stolen);
+            const voiceId = state.nextId++;
+            state.voices = state.voices.filter((voice) => !removed.has(voice.id));
+            state.voices.push({ id: voiceId, soundId, priority });
+            restore(state);
+            return { ok: true, voiceId, stolen };
+        },
+        release(voiceId) {
+            const state = snapshot();
+            state.voices = state.voices.filter((voice) => voice.id !== voiceId);
+            restore(state);
+        },
+        retune(next) {
+            const nextLimit = limit(next.maxTotal ?? maxTotal);
+            const state = snapshot();
+            const removed = weakest(state.voices).slice(0, Math.max(0, state.voices.length - nextLimit)).map((voice) => voice.id);
+            const ids = new Set(removed);
+            state.voices = state.voices.filter((voice) => !ids.has(voice.id));
+            maxTotal = nextLimit;
+            overflow = next.overflow ?? overflow;
+            restore(state);
+            return removed;
+        },
+    };
+}

package/dist/combat/abilityKit.d.ts

@@ -51,6 +51,21 @@ export interface AbilitySlotRetune {
     cooldownMs?: number;
     resourceCost?: number;
 }
+/** Mutable kit state; slot/group definitions and any bound resource are saved by the caller. */
+export interface AbilityKitState {
+    slots: {
+        id: string;
+        cooldownMs: number;
+        resourceCost: number;
+        charges: number;
+        rechargeRemainingMs: number;
+        flashRemainingMs: number;
+    }[];
+    groups: {
+        id: string;
+        remainingMs: number;
+    }[];
+}
 export type AbilityCastResult = {
     ok: true;
     slot: AbilitySlotSnapshot;
@@ -62,8 +77,12 @@ export type AbilityCastResult = {
 export interface AbilityKit {
     slots(): readonly string[];
     config(slotId: string): AbilitySlotConfig | null;
+    /** Detached persistence state, including in-flight timers and slot retuning. */
+    state(): AbilityKitState;
     state(slotId: string, resourceAvailable?: number): AbilitySlotSnapshot | null;
     snapshot(resourceAvailable?: number): AbilitySlotSnapshot[];
+    /** Restore without spending resources; returns false without mutation for mismatched slot/group ids. */
+    restore(next: AbilityKitState): boolean;
     canCast(slotId: string, resourceAvailable?: number): AbilityCastResult;
     cast(slotId: string, resourceAvailable?: number): AbilityCastResult;
     tick(dtSeconds: number): void;

package/dist/combat/abilityKit.js

@@ -108,6 +108,26 @@ export function createAbilityKit(configs, options = {}) {
             return fail(slotId, "no-resource", resourceAvailable);
         return { ok: true, slot: snapshotOf(runtime, resourceAvailable, groupBlockOf(runtime)) };
     }
+    function state(slotId, resourceAvailable) {
+        if (slotId !== undefined) {
+            const runtime = runtimes.get(slotId);
+            return runtime === undefined ? null : snapshotOf(runtime, currentResource(resourceAvailable), groupBlockOf(runtime));
+        }
+        return {
+            slots: order.map((id) => {
+                const runtime = runtimes.get(id);
+                return {
+                    id,
+                    cooldownMs: runtime.config.cooldownMs,
+                    resourceCost: runtime.config.resourceCost,
+                    charges: runtime.charges,
+                    rechargeRemainingMs: runtime.rechargeRemainingMs,
+                    flashRemainingMs: runtime.flashRemainingMs,
+                };
+            }),
+            groups: Array.from(groupRemaining, ([id, remainingMs]) => ({ id, remainingMs })),
+        };
+    }
     return {
         slots() {
             return order.slice();
@@ -115,10 +135,7 @@ export function createAbilityKit(configs, options = {}) {
         config(slotId) {
             return runtimes.get(slotId)?.config ?? null;
         },
-        state(slotId, resourceAvailable) {
-            const runtime = runtimes.get(slotId);
-            return runtime === undefined ? null : snapshotOf(runtime, currentResource(resourceAvailable), groupBlockOf(runtime));
-        },
+        state,
         snapshot(resourceAvailable) {
             const available = currentResource(resourceAvailable);
             return order.map((slotId) => {
@@ -126,6 +143,25 @@ export function createAbilityKit(configs, options = {}) {
                 return snapshotOf(runtime, available, groupBlockOf(runtime));
             });
         },
+        restore(next) {
+            if (next.slots.length !== runtimes.size || next.groups.length !== groupRemaining.size ||
+                new Set(next.slots.map((slot) => slot.id)).size !== runtimes.size ||
+                new Set(next.groups.map((group) => group.id)).size !== groupRemaining.size ||
+                next.slots.some((slot) => !runtimes.has(slot.id)) ||
+                next.groups.some((group) => !groupRemaining.has(group.id)))
+                return false;
+            for (const slot of next.slots) {
+                const runtime = runtimes.get(slot.id);
+                runtime.config.cooldownMs = Math.max(0, slot.cooldownMs);
+                runtime.config.resourceCost = Math.max(0, slot.resourceCost);
+                runtime.charges = Math.max(0, Math.min(runtime.config.chargesMax, slot.charges));
+                runtime.rechargeRemainingMs = Math.max(0, slot.rechargeRemainingMs);
+                runtime.flashRemainingMs = Math.max(0, slot.flashRemainingMs);
+            }
+            for (const group of next.groups)
+                groupRemaining.set(group.id, Math.max(0, group.remainingMs));
+            return true;
+        },
         canCast(slotId, resourceAvailable) {
             return evaluate(slotId, currentResource(resourceAvailable));
         },

package/dist/combat/death.d.ts

@@ -6,8 +6,9 @@ import type { EffectVia } from "./effects.js";
 export type DeathReasonKind = DeathReason["kind"];
 export interface OnDeathDropRule {
     table: string;
+    /** `"any"` explicitly permits world item drops without a player killer. */
     when?: {
-        reason: DeathReasonKind;
+        reason: DeathReasonKind | "any";
     };
 }
 export interface OnDeathCommandRule {
@@ -47,13 +48,13 @@ export interface DeathIdentity {
     position: [number, number, number];
 }
 export interface DeathSystemDeps {
-    resolveOnDeath(instanceId: string): OnDeathSpec | null | undefined;
+    resolveOnDeath(instanceId: string, reason?: DeathReason): OnDeathSpec | null | undefined;
     resolveIdentity(instanceId: string): DeathIdentity | null;
     loot: {
         roll(tableId: string): Drop[];
     };
     events: GameEvents;
-    runCommand?(name: string, args: unknown): void;
+    runCommand?(name: string, args: unknown, reason?: DeathReason): void;
     despawn(instanceId: string): void;
 }
 export type DeathResolution = {