@jgengine/core 0.18.1 → 0.21.0

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 {
@@ -11,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";
 /**
@@ -24,3 +31,13 @@ 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, 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
+ */
+export declare function animGraphFromConfig(config: ModelAnimationConfig): AnimGraph | undefined;

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 });
     }
@@ -31,3 +45,28 @@ 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, 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
+ */
+export function animGraphFromConfig(config) {
+    if (config.graph !== undefined)
+        return config.graph;
+    const states = config.states;
+    if (states === undefined || typeof states.idle !== "string" || states.idle.trim().length === 0)
+        return undefined;
+    return locomotionGraph({
+        idle: states.idle,
+        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,
+        ...(config.oneShots === undefined ? {} : { oneShots: config.oneShots }),
+    });
+}

package/dist/audio/audioFalloff.d.ts

@@ -24,9 +24,15 @@ 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;
+    /** 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;

package/dist/audio/engineLayers.js

@@ -0,0 +1,115 @@
+function indexLayers(layers) {
+    const byRpm = (a, b) => layers[a].rpm - layers[b].rpm;
+    const index = { on: [], off: [], any: [] };
+    layers.forEach((layer, i) => index[layer.load ?? "any"].push(i));
+    if (index.on.length === 0 || index.off.length === 0) {
+        index.any.push(...index.on, ...index.off);
+        index.on = [];
+        index.off = [];
+    }
+    index.on.sort(byRpm);
+    index.off.sort(byRpm);
+    index.any.sort(byRpm);
+    return index;
+}
+function smoothstep(edge0, edge1, x) {
+    if (edge1 <= edge0)
+        return x >= edge1 ? 1 : 0;
+    const t = Math.min(1, Math.max(0, (x - edge0) / (edge1 - edge0)));
+    return t * t * (3 - 2 * t);
+}
+/**
+ * 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 function createEngineLayers(initial) {
+    let config = initial;
+    let index = indexLayers(config.layers);
+    let mixes = [];
+    let load = 0;
+    const params = {};
+    function rebuild() {
+        index = indexLayers(config.layers);
+        mixes = config.layers.map((layer, i) => ({ id: `${config.id}:${i}`, sound: layer.sound, gain: 0, rate: 1 }));
+    }
+    rebuild();
+    function crossfade(set, rpm, weight) {
+        if (set.length === 0 || weight <= 0)
+            return;
+        const layers = config.layers;
+        let upper = 0;
+        while (upper < set.length && layers[set[upper]].rpm < rpm)
+            upper += 1;
+        if (upper === 0 || upper === set.length) {
+            const only = set[upper === 0 ? 0 : set.length - 1];
+            mixes[only].gain += weight;
+            return;
+        }
+        const lowIndex = set[upper - 1];
+        const highIndex = set[upper];
+        const low = layers[lowIndex].rpm;
+        const high = layers[highIndex].rpm;
+        const t = high > low ? (rpm - low) / (high - low) : 1;
+        mixes[lowIndex].gain += weight * Math.cos((t * Math.PI) / 2);
+        mixes[highIndex].gain += weight * Math.sin((t * Math.PI) / 2);
+    }
+    return {
+        update(dt, signals) {
+            const rpm = Number.isFinite(signals.rpm) ? Math.max(0, signals.rpm) : 0;
+            const target = Number.isFinite(signals.load) ? Math.min(1, Math.max(0, signals.load)) : 0;
+            const response = config.loadResponse ?? 10;
+            load = Number.isFinite(response) ? load + (target - load) * (1 - Math.exp(-response * Math.max(0, dt))) : target;
+            const [from, to] = config.loadCrossfade ?? [0.15, 0.6];
+            const onWeight = smoothstep(from, to, load);
+            for (let i = 0; i < mixes.length; i += 1) {
+                const layer = config.layers[i];
+                mixes[i].gain = 0;
+                mixes[i].rate = layer.rpm > 0 ? rpm / layer.rpm : 1;
+            }
+            crossfade(index.any, rpm, 1);
+            crossfade(index.on, rpm, Math.sin((onWeight * Math.PI) / 2));
+            crossfade(index.off, rpm, Math.cos((onWeight * Math.PI) / 2));
+            for (let i = 0; i < mixes.length; i += 1)
+                mixes[i].gain *= config.layers[i].gain ?? 1;
+            return mixes;
+        },
+        play(audio, options = {}) {
+            const scale = options.gain ?? 1;
+            const loopOptions = options.at === undefined ? undefined : { at: options.at };
+            params.at = options.at;
+            params.velocity = options.velocity;
+            params.lowpass = options.lowpass;
+            params.highpass = options.highpass;
+            for (const mix of mixes) {
+                audio.loop(mix.id, mix.sound, loopOptions);
+                params.rate = mix.rate;
+                params.gain = mix.gain * scale;
+                audio.setLoop(mix.id, params);
+            }
+        },
+        stop(audio) {
+            for (const mix of mixes)
+                audio.stopLoop(mix.id);
+        },
+        mix: () => mixes,
+        retune(next) {
+            config = next;
+            rebuild();
+        },
+        snapshot: () => ({ load }),
+        restore(state) {
+            load = state.load;
+        },
+        reset() {
+            load = 0;
+            for (const mix of mixes) {
+                mix.gain = 0;
+                mix.rate = 1;
+            }
+        },
+    };
+}

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;
@@ -76,5 +95,6 @@ export interface AbilityKit {
  * A bar of cooldown-gated abilities the player fires by slot, tracking readiness and cooldown per ability.
  *
  * @capability ability-bar a bar of cooldown-gated abilities the player triggers by slot
+ * @capability global-cooldown share one cooldown across every ability slot (MMO global cooldown) with a cooldown group
  */
 export declare function createAbilityKit(configs: readonly AbilitySlotConfig[], options?: AbilityKitOptions): AbilityKit;

package/dist/combat/abilityKit.js

@@ -43,6 +43,7 @@ function snapshotOf(runtime, resourceAvailable, group) {
  * A bar of cooldown-gated abilities the player fires by slot, tracking readiness and cooldown per ability.
  *
  * @capability ability-bar a bar of cooldown-gated abilities the player triggers by slot
+ * @capability global-cooldown share one cooldown across every ability slot (MMO global cooldown) with a cooldown group
  */
 export function createAbilityKit(configs, options = {}) {
     const boundResource = options.resource;
@@ -107,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();
@@ -114,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) => {
@@ -125,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 {
@@ -18,6 +19,13 @@ export interface OnDeathCommandRule {
     };
 }
 export type DropMode = "grant" | "world";
+/**
+ * Catalog `onDeath` for an entity: loot tables to roll, `dropMode: "world"` to scatter drops on the ground
+ * (rendered with loot beams) instead of granting them into the killer's bag, and commands to run. Fires only
+ * when the entity dies through `ctx.scene.entity.effect`, not a raw `stats.delta`.
+ *
+ * @capability on-death-drops make a killed enemy drop loot on the ground or into the killer's bag via catalog onDeath
+ */
 export interface OnDeathSpec {
     drops?: string | OnDeathDropRule[];
     command?: string | OnDeathCommandRule;
@@ -40,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 = {