@jgengine/core 0.12.0 → 0.13.0

package/dist/combat/weaponFire.js

@@ -0,0 +1,96 @@
+import { resolveDamageHit } from "./damageResolution.js";
+import { createMagazine } from "./magazine.js";
+/**
+ * Build a {@link FireCadence} rate gate. Reach for this instead of hand-tracking a
+ * `lastFiredAt` timestamp and comparing against a fire interval per game.
+ *
+ * @capability fire-cadence a serializable minimum-interval rate gate for repeated actions (weapon fire, ability spam)
+ */
+export function createFireCadence(config) {
+    const intervalMs = Math.max(0, config.intervalMs);
+    let elapsed = config.ready === false ? 0 : intervalMs;
+    const ready = () => intervalMs <= 0 || elapsed >= intervalMs;
+    return {
+        ready,
+        readyFraction: () => (intervalMs <= 0 ? 1 : Math.min(1, elapsed / intervalMs)),
+        remainingMs: () => (ready() ? 0 : intervalMs - elapsed),
+        fire() {
+            if (!ready())
+                return false;
+            elapsed = 0;
+            return true;
+        },
+        tick(dtSeconds) {
+            if (dtSeconds <= 0 || elapsed >= intervalMs)
+                return;
+            elapsed = Math.min(intervalMs, elapsed + dtSeconds * 1000);
+        },
+        elapsedMs: () => elapsed,
+        restore(value) {
+            elapsed = Math.max(0, Math.min(intervalMs, value));
+        },
+    };
+}
+/**
+ * Compose a portable weapon fire controller from the existing generic primitives — a
+ * {@link FireCadence} gate, an optional {@link Magazine}, a caller-provided raycast, and portable
+ * {@link resolveDamageHit} damage resolution. No `GameContext`, entity store, renderer, or default
+ * weapon is involved; the caller owns aiming, its raycaster, and all presentation, and the result
+ * carries full damage provenance for authority to apply and replicate.
+ *
+ * @capability weapon-runtime compose cadence, magazine, a caller-owned raycast, and portable damage resolution into a fire controller
+ */
+export function createWeaponRuntime(config) {
+    const cadence = createFireCadence({
+        intervalMs: config.cadenceMs,
+        ...(config.ready !== undefined ? { ready: config.ready } : {}),
+    });
+    const magazine = config.magazine === undefined ? null : createMagazine(config.magazine);
+    const loadedOf = () => (magazine === null ? null : magazine.loaded());
+    const blocked = (status) => ({
+        status,
+        hits: [],
+        resolutions: [],
+        loaded: loadedOf(),
+    });
+    const canFire = () => {
+        if (magazine !== null && magazine.isReloading())
+            return false;
+        if (!cadence.ready())
+            return false;
+        if (magazine !== null && !magazine.canFire(1))
+            return false;
+        return true;
+    };
+    return {
+        cadence,
+        magazine,
+        canFire,
+        startReload: () => (magazine === null ? false : magazine.startReload()),
+        cancelReload: () => magazine?.cancelReload(),
+        tick(dtSeconds) {
+            cadence.tick(dtSeconds);
+            magazine?.tick(dtSeconds);
+        },
+        fire(aim) {
+            if (magazine !== null && magazine.isReloading())
+                return blocked("reloading");
+            if (!cadence.ready())
+                return blocked("cooling");
+            if (magazine !== null && !magazine.canFire(1))
+                return blocked("empty");
+            cadence.fire();
+            magazine?.fire(1);
+            const hits = config.resolveHits(aim);
+            const resolutions = [];
+            for (const hit of hits) {
+                const input = config.damageFor(hit, aim);
+                if (input === null)
+                    continue;
+                const withRng = config.rng !== undefined && input.rng === undefined ? { ...input, rng: config.rng } : input;
+                resolutions.push(resolveDamageHit(withRng));
+            }
+            return { status: "fired", hits, resolutions, loaded: loadedOf() };
+        },
+    };
+}

package/dist/combat.d.ts

@@ -16,7 +16,7 @@ export { createDownedState } from "./combat/downed.js";
 export { createEffectSystem, type ReceiveMap } from "./combat/effects.js";
 export { BUILTIN_COMPLETION_PREDICATES, BUILTIN_SPAWN_PROVIDERS, activePhaseId, createEncounterState, encounterProgress, forceCompletePhase, injectPhase, phaseStatus, startEncounter, updateEncounter, type CompletionPredicate, type EncounterConfig, type EncounterContext, type EncounterEvent, type EncounterPhase, type EncounterSignals, type EncounterSpawnRequest, type EncounterState, type EncounterStep, type PhaseCompletionRef, type PhaseInjectAt, type PhaseRuntime, type PhaseSpawnRef, type PhaseStatus, type PredicateContext, type SpawnProvider, type SpawnProviderContext, } from "./combat/encounterSequence.js";
 export { impactPresets, resolveHitReaction, type HitReactionConfig } from "./combat/hitReaction.js";
-export { createMagazine, type Magazine, type MagazineReserve } from "./combat/magazine.js";
+export { createMagazine, type Magazine, type MagazineConfig, type MagazineReserve, type MagazineSnapshot, } from "./combat/magazine.js";
 export { createProjectileSystem, type ObjectRaycastHit, type ProjectileSystemDeps, type RaycastHit, } from "./combat/projectiles.js";
 export { resolveReceivedDamage, type DamageContext, type DamagePredicate, type ReceivedDamageResult, type ReceivedModifier, type ReceivedPolicy, } from "./combat/receivedDamage.js";
 export { createRegenShield } from "./combat/regenShield.js";
@@ -28,8 +28,10 @@ export { DEFAULT_EYE_HEIGHT, convergeShot, eyeHeightFromColliders, resolveShot,
 export { resolveStatusApplication, type StatusApplicationOutcome, type StatusApplicationSpec, type StatusImmunity, type StatusInstance, type StatusStackPolicy, } from "./combat/statusApplication.js";
 export { type TelegraphConfig, type TelegraphShape } from "./combat/telegraph.js";
 export { createThresholdTracker, type CrossingDirection, type CrossingPolicy, type CrossingTrigger, type ThresholdCrossing, type ThresholdCrossingConfig, type ThresholdMark, type ThresholdTracker, type ThresholdTrackerSnapshot, } from "./combat/thresholdCrossings.js";
+export { DEFAULT_VFX_PRESET, resolveVfxPreset, vfxPresets, type VfxPreset, type VfxPresetName, } from "./combat/vfxPresets.js";
+export { createFireCadence, createWeaponRuntime, type FireCadence, type FireCadenceConfig, type WeaponFireResult, type WeaponFireStatus, type WeaponRuntime, type WeaponRuntimeConfig, } from "./combat/weaponFire.js";
 export { createAccumulatorMeter, tierAt, type MeterAddResult } from "./stats/accumulatorMeter.js";
 export { createEventMeter, type EventMeter, type EventMeterFeedResult } from "./stats/eventMeter.js";
 export { rollCheck, type CheckAdvantage, type CheckResult } from "./stats/rollCheck.js";
-export { createStats, type Stats } from "./stats/statModifiers.js";
+export { createStats, type Stats, type StatsSnapshot } from "./stats/statModifiers.js";
 export { applyStatPoolDelta, changeStatPool, createStatPool, patchStatPool, type StatPool, type StatPoolAccess, type StatPoolAccessResult, type StatPoolChange, type StatPoolInput, type StatPoolPatch, } from "./stats/statPool.js";

package/dist/combat.js

@@ -16,7 +16,7 @@ export { createDownedState } from "./combat/downed.js";
 export { createEffectSystem } from "./combat/effects.js";
 export { BUILTIN_COMPLETION_PREDICATES, BUILTIN_SPAWN_PROVIDERS, activePhaseId, createEncounterState, encounterProgress, forceCompletePhase, injectPhase, phaseStatus, startEncounter, updateEncounter, } from "./combat/encounterSequence.js";
 export { impactPresets, resolveHitReaction } from "./combat/hitReaction.js";
-export { createMagazine } from "./combat/magazine.js";
+export { createMagazine, } from "./combat/magazine.js";
 export { createProjectileSystem, } from "./combat/projectiles.js";
 export { resolveReceivedDamage, } from "./combat/receivedDamage.js";
 export { createRegenShield } from "./combat/regenShield.js";
@@ -28,6 +28,8 @@ export { DEFAULT_EYE_HEIGHT, convergeShot, eyeHeightFromColliders, resolveShot,
 export { resolveStatusApplication, } from "./combat/statusApplication.js";
 export {} from "./combat/telegraph.js";
 export { createThresholdTracker, } from "./combat/thresholdCrossings.js";
+export { DEFAULT_VFX_PRESET, resolveVfxPreset, vfxPresets, } from "./combat/vfxPresets.js";
+export { createFireCadence, createWeaponRuntime, } from "./combat/weaponFire.js";
 export { createAccumulatorMeter, tierAt } from "./stats/accumulatorMeter.js";
 export { createEventMeter } from "./stats/eventMeter.js";
 export { rollCheck } from "./stats/rollCheck.js";

package/dist/devtools/urlFlags.d.ts

@@ -0,0 +1,22 @@
+/**
+ * URL-backed debug flags — the single seam hosts use to mirror an engine debug surface (the scene
+ * editor, the devtools overlay) into the page query string. Mirroring means the URL is the honest
+ * record of what is open: share it to reproduce the state, and strip the param (then reload) to get
+ * a clean game with the surface gone. All functions no-op safely off the main browser thread.
+ */
+/** The current query value of `param`, or null when absent (or no DOM). */
+export declare function readUrlParam(param: string): string | null;
+/** True when `param` is present and not an explicit off value (`0`/`false`/`off`/`no`). */
+export declare function readUrlFlag(param: string): boolean;
+/**
+ * Sets `param` to `value`, or removes it when `value` is null, rewriting the URL in place with
+ * `history.replaceState` so the rest of the query and the hash survive and no history entry is
+ * pushed. No-ops without a DOM, and skips the write when the URL already matches.
+ */
+export declare function writeUrlParam(param: string, value: string | null): void;
+/**
+ * Fires `listener` whenever the query string may have changed out from under a flag — browser
+ * back/forward (`popstate`). Manual address-bar edits reload the page, so initial reads cover
+ * those; this keeps in-app state honest across history navigation. Returns an unsubscribe.
+ */
+export declare function subscribeUrlChange(listener: () => void): () => void;

package/dist/devtools/urlFlags.js

@@ -0,0 +1,62 @@
+/**
+ * URL-backed debug flags — the single seam hosts use to mirror an engine debug surface (the scene
+ * editor, the devtools overlay) into the page query string. Mirroring means the URL is the honest
+ * record of what is open: share it to reproduce the state, and strip the param (then reload) to get
+ * a clean game with the surface gone. All functions no-op safely off the main browser thread.
+ */
+/** Values that read as "off" when a param is present but disabled — `?debug=0` stays closed. */
+const FALSY = new Set(["", "0", "false", "off", "no"]);
+/** The live browser window, or null when there is no DOM (SSR, tests, worker). */
+function browserWindow() {
+    const candidate = globalThis.window;
+    if (candidate === undefined || candidate.location === undefined || candidate.history === undefined) {
+        return null;
+    }
+    return candidate;
+}
+/** The current query value of `param`, or null when absent (or no DOM). */
+export function readUrlParam(param) {
+    const win = browserWindow();
+    if (win === null)
+        return null;
+    return new URLSearchParams(win.location.search).get(param);
+}
+/** True when `param` is present and not an explicit off value (`0`/`false`/`off`/`no`). */
+export function readUrlFlag(param) {
+    const value = readUrlParam(param);
+    return value !== null && !FALSY.has(value.toLowerCase());
+}
+/**
+ * Sets `param` to `value`, or removes it when `value` is null, rewriting the URL in place with
+ * `history.replaceState` so the rest of the query and the hash survive and no history entry is
+ * pushed. No-ops without a DOM, and skips the write when the URL already matches.
+ */
+export function writeUrlParam(param, value) {
+    const win = browserWindow();
+    if (win === null)
+        return;
+    const url = new URL(win.location.href);
+    if (value === null) {
+        if (!url.searchParams.has(param))
+            return;
+        url.searchParams.delete(param);
+    }
+    else {
+        if (url.searchParams.get(param) === value)
+            return;
+        url.searchParams.set(param, value);
+    }
+    win.history.replaceState(win.history.state, "", url.toString());
+}
+/**
+ * Fires `listener` whenever the query string may have changed out from under a flag — browser
+ * back/forward (`popstate`). Manual address-bar edits reload the page, so initial reads cover
+ * those; this keeps in-app state honest across history navigation. Returns an unsubscribe.
+ */
+export function subscribeUrlChange(listener) {
+    const win = browserWindow();
+    if (win === null)
+        return () => { };
+    win.addEventListener("popstate", listener);
+    return () => win.removeEventListener("popstate", listener);
+}

package/dist/game/clipRoles.d.ts

@@ -0,0 +1,51 @@
+import type { ModelAnimationConfig } from "./playableGame.js";
+/**
+ * Semantic animation roles a GLB clip name can map to. Rigged packs name the same motion
+ * differently (`Idle` / `Walking_A` / `Armature|Run`); roles are the pack-agnostic vocabulary
+ * the engine defaults from.
+ */
+export type ClipRole = "idle" | "walk" | "run" | "attack" | "hit" | "death" | "jump" | "spawn" | "interact" | "cheer";
+/**
+ * Keyword table driving {@link classifyClip}: lowercase keywords matched against a clip name's
+ * tokens (exact token match beats prefix match). Extend or replace per game/pack — the table is
+ * plain data, no genre assumptions.
+ */
+export interface ClipRoleTable {
+    readonly roles: Readonly<Partial<Record<ClipRole, readonly string[]>>>;
+    /** Tokens that disqualify a clip from classification entirely (e.g. `pose` for held-pose variants). */
+    readonly exclude?: readonly string[];
+}
+/** Default vocabulary covering KayKit, Quaternius, and Mixamo-style clip naming. */
+export declare const DEFAULT_CLIP_ROLE_TABLE: ClipRoleTable;
+/**
+ * Classify a single GLB clip name into a {@link ClipRole}, or `null` when nothing matches (or an
+ * exclusion token like `pose` disqualifies it). Deterministic: exact token matches beat prefix
+ * matches; remaining ties resolve by fixed role priority (death > hit > attack > … > idle).
+ *
+ * @capability clip-roles map a rigged asset's pack-specific clip name to its semantic animation role
+ */
+export declare function classifyClip(name: string, table?: ClipRoleTable): ClipRole | null;
+/**
+ * Group a GLB's clip names by role. Each role's variants are sorted simplest-first — fewest name
+ * tokens, then lexicographic — so the canonical variant (`Idle` over `2H_Melee_Idle`, KayKit
+ * `Walking_A` over `Walking_B`) is always first: stable output for the same clip set regardless
+ * of source order.
+ */
+export declare function rolesFromClips(clips: readonly string[], table?: ClipRoleTable): Partial<Record<ClipRole, string[]>>;
+/**
+ * Build the default `ModelConfig.animation` for a rigged asset from its catalog clip names:
+ * speed-driven idle/walk/run states plus hit/death/attack one-shots where identifiable. Returns
+ * `undefined` when no idle clip is identifiable — an ambiguous rig renders its bind pose rather
+ * than guessing. Walk falls back to idle when the pack has no walk clip.
+ *
+ * @capability clip-roles derive a complete default animation config from a rigged asset's clip names
+ */
+export declare function defaultAnimationForClips(clips: readonly string[], table?: ClipRoleTable): ModelAnimationConfig | undefined;
+/**
+ * Collapse `ModelConfig.animation`'s widened union to a concrete playback config: explicit
+ * configs pass through, `"none"`/absent render the bind pose, and `"auto"` derives states and
+ * one-shots from the model's clip names via {@link defaultAnimationForClips}. The shell calls
+ * this with the loaded GLB's actual clip names, so `"auto"` works on any rigged model —
+ * catalog-resolved ids are stamped `"auto"` automatically.
+ */
+export declare function resolveAnimationConfig(animation: ModelAnimationConfig | "auto" | "none" | undefined, clips: readonly string[] | undefined, table?: ClipRoleTable): ModelAnimationConfig | undefined;

package/dist/game/clipRoles.js

@@ -0,0 +1,142 @@
+/** Tie-break priority when a name matches several roles at equal strength ("Idle_Attack" → attack). */
+const ROLE_PRIORITY = [
+    "death",
+    "hit",
+    "attack",
+    "jump",
+    "spawn",
+    "interact",
+    "cheer",
+    "run",
+    "walk",
+    "idle",
+];
+/** Default vocabulary covering KayKit, Quaternius, and Mixamo-style clip naming. */
+export const DEFAULT_CLIP_ROLE_TABLE = {
+    roles: {
+        idle: ["idle"],
+        walk: ["walk"],
+        run: ["run", "sprint", "jog"],
+        attack: ["attack", "punch", "slash", "shoot", "chop", "stab", "cast", "swing", "strike", "kick", "throw"],
+        hit: ["hit", "receive", "impact", "hurt", "damage"],
+        death: ["death", "die", "dead", "dying"],
+        jump: ["jump"],
+        spawn: ["spawn"],
+        interact: ["interact", "use", "pickup"],
+        cheer: ["cheer", "victory", "dance", "wave"],
+    },
+    exclude: ["pose"],
+};
+/** Lowercased tokens of a clip name: rig prefixes (`Armature|`, `mixamo.com|`) stripped, split on `_ - . space`. */
+function tokenize(name) {
+    const segments = name.split("|");
+    const last = segments[segments.length - 1] ?? name;
+    return last
+        .toLowerCase()
+        .split(/[_\-. ]+/)
+        .filter((token) => token.length > 0);
+}
+/**
+ * Classify a single GLB clip name into a {@link ClipRole}, or `null` when nothing matches (or an
+ * exclusion token like `pose` disqualifies it). Deterministic: exact token matches beat prefix
+ * matches; remaining ties resolve by fixed role priority (death > hit > attack > … > idle).
+ *
+ * @capability clip-roles map a rigged asset's pack-specific clip name to its semantic animation role
+ */
+export function classifyClip(name, table = DEFAULT_CLIP_ROLE_TABLE) {
+    const tokens = tokenize(name);
+    if (tokens.length === 0)
+        return null;
+    const exclude = table.exclude ?? [];
+    for (const token of tokens) {
+        if (exclude.includes(token))
+            return null;
+    }
+    let best = null;
+    for (const role of ROLE_PRIORITY) {
+        const keywords = table.roles[role] ?? [];
+        let score = 0;
+        for (const token of tokens) {
+            for (const keyword of keywords) {
+                if (token === keyword)
+                    score = Math.max(score, 2);
+                else if (token.startsWith(keyword))
+                    score = Math.max(score, 1);
+            }
+        }
+        if (score > 0 && (best === null || score > best.score))
+            best = { role, score };
+    }
+    return best?.role ?? null;
+}
+/**
+ * Group a GLB's clip names by role. Each role's variants are sorted simplest-first — fewest name
+ * tokens, then lexicographic — so the canonical variant (`Idle` over `2H_Melee_Idle`, KayKit
+ * `Walking_A` over `Walking_B`) is always first: stable output for the same clip set regardless
+ * of source order.
+ */
+export function rolesFromClips(clips, table = DEFAULT_CLIP_ROLE_TABLE) {
+    const roles = {};
+    for (const clip of clips) {
+        const role = classifyClip(clip, table);
+        if (role === null)
+            continue;
+        (roles[role] ??= []).push(clip);
+    }
+    for (const variants of Object.values(roles)) {
+        variants.sort((a, b) => tokenize(a).length - tokenize(b).length || a.localeCompare(b));
+    }
+    return roles;
+}
+/** A role's variants as a one-shot binding: single name stays a string, several become a random-variant array. */
+function oneShotSpec(variants) {
+    if (variants === undefined || variants.length === 0)
+        return undefined;
+    return variants.length === 1 ? variants[0] : variants;
+}
+/**
+ * Build the default `ModelConfig.animation` for a rigged asset from its catalog clip names:
+ * speed-driven idle/walk/run states plus hit/death/attack one-shots where identifiable. Returns
+ * `undefined` when no idle clip is identifiable — an ambiguous rig renders its bind pose rather
+ * than guessing. Walk falls back to idle when the pack has no walk clip.
+ *
+ * @capability clip-roles derive a complete default animation config from a rigged asset's clip names
+ */
+export function defaultAnimationForClips(clips, table = DEFAULT_CLIP_ROLE_TABLE) {
+    const roles = rolesFromClips(clips, table);
+    const idle = roles.idle?.[0];
+    if (idle === undefined)
+        return undefined;
+    const walk = roles.walk?.[0] ?? idle;
+    const run = roles.run?.[0];
+    const oneShots = {};
+    const hit = oneShotSpec(roles.hit);
+    const death = oneShotSpec(roles.death);
+    const attack = oneShotSpec(roles.attack);
+    if (hit !== undefined)
+        oneShots.hit = hit;
+    if (death !== undefined)
+        oneShots.death = death;
+    if (attack !== undefined)
+        oneShots.attack = attack;
+    return {
+        states: { idle, walk, ...(run === undefined ? {} : { run }) },
+        ...(Object.keys(oneShots).length === 0 ? {} : { oneShots }),
+    };
+}
+/**
+ * Collapse `ModelConfig.animation`'s widened union to a concrete playback config: explicit
+ * configs pass through, `"none"`/absent render the bind pose, and `"auto"` derives states and
+ * one-shots from the model's clip names via {@link defaultAnimationForClips}. The shell calls
+ * this with the loaded GLB's actual clip names, so `"auto"` works on any rigged model —
+ * catalog-resolved ids are stamped `"auto"` automatically.
+ */
+export function resolveAnimationConfig(animation, clips, table = DEFAULT_CLIP_ROLE_TABLE) {
+    if (animation === undefined || animation === "none")
+        return undefined;
+    if (animation !== "auto")
+        return animation;
+    if (clips === undefined || clips.length === 0)
+        return undefined;
+    return defaultAnimationForClips(clips, table);
+}

package/dist/game/defineGame.d.ts

@@ -13,7 +13,7 @@ import { type EntityStore } from "../scene/entityStore.js";
 import type { StoreHandle } from "../store/defineStore.js";
 import type { TimeConfig } from "../time/simClock.js";
 import type { WorldFeature } from "../world/features.js";
-/** Tunes offline whole-world save (`defineGameDefinition({ persist })`). Defaults: continuous `autosave` to `localStorage`, one slot, no version. */
+/** Tunes offline whole-world save (`defineGameDefinition({ persist })`). Offline games already autosave to `localStorage` by default — pass this only to tune it (or `persist: false` to opt out). Defaults: continuous `autosave` to `localStorage`, one slot, no version. */
 export interface PersistConfig {
     /** `"autosave"` (default) writes on a debounce after any change; `"manual"` writes only on `ctx.game.save.checkpoint()` (save points / quest triggers). */
     mode?: RuntimeSaveMode;
@@ -173,7 +173,7 @@ export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef,
     server?: GameServerConfig;
     /** Hosted per-player save policy, read only by an authoritative multiplayer host. Solo games leave this unset (nothing persists by default) and use `persist` when they want a save at all. */
     save?: SaveConfig;
-    /** The one save knob for solo games: offline whole-world save. `true` autosaves the entire game to `localStorage`; a config object tunes the mode/cadence/target. Binds `ctx.game.save` — the game drives save points and restore. Ignored for multiplayer worlds (the host persists via `save`). */
+    /** The one save knob for solo games: offline whole-world save. **On by default** — an offline game autosaves the entire world to `localStorage` and binds `ctx.game.save` with no config at all; the game only drives save points and restore (`ctx.game.save.load()` at boot). Pass `false` to opt out entirely, or a config object to tune the mode/cadence/target (`storage: "memory"` for in-session-only). Ignored for multiplayer worlds (the host persists via `save`). */
     persist?: boolean | PersistConfig;
     ui?: unknown;
     loop?: GameLoop<GameContext>;

package/dist/game/partAnimation.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Procedural animation for part-composed (rig-less) models — characters kit-bashed from
+ * primitives/`ModelPart`s with no skeleton or clips. Pure, deterministic curve sampling:
+ * the same (time, speed, phase, flinch, death) input always yields the same pose, so
+ * replays and multi-client renders stay in lockstep and the hot path allocates nothing
+ * when an `out` pose is reused.
+ */
+/** Semantic motion role of one `ModelPart` in a part-composed character. */
+export type PartRole = "head" | "arm.l" | "arm.r" | "leg.l" | "leg.r" | "tail" | "wing.l" | "wing.r";
+/** Tuning for {@link samplePartPose}/{@link sampleBodyPose}; every field has a sensible default. */
+export interface PartMotionParams {
+    /** Full stride cycles per second at walking speed. Default 1.6. */
+    strideHz?: number;
+    /** Limb swing amplitude in radians at full walk. Default 0.7. */
+    swingRad?: number;
+    /** Body bob height in model units at full walk. Default 0.04. */
+    bobAmp?: number;
+    /** Idle sway/breathe amplitude in radians. Default 0.05. */
+    swayRad?: number;
+    /** Speed (world units/sec) treated as a full walk; swing/bob scale linearly below it. Default 2. */
+    walkSpeed?: number;
+    /** Backward flinch pitch in radians at flinch = 1. Default 0.35. */
+    flinchRad?: number;
+    /** Sideways topple roll in radians at death = 1. Default PI / 2. */
+    toppleRad?: number;
+    /**
+     * Squash-and-stretch amplitude for soft characters (blobs, slimes): footfall squash while
+     * walking, jelly breathe while idle, a squash pulse on flinch. Volume-conserving — the body
+     * bulges horizontally as it compresses. Default 0 (rigid; scale stays exactly 1).
+     */
+    squashAmp?: number;
+    /** How death reads: `"topple"` rolls sideways (default, hard characters); `"splat"` flattens the body out — right for blobs. */
+    deathStyle?: "topple" | "splat";
+}
+/** Sampled offsets to add onto a part's authored transform (or the character root). `scale` is multiplicative (1 = unchanged). */
+export interface PartPose {
+    position: [number, number, number];
+    rotation: [number, number, number];
+    scale: [number, number, number];
+}
+/** Live signals a driver feeds the samplers each frame. All values are render-side only. */
+export interface PartMotionInput {
+    /** Seconds since the driver started (any monotonic clock). */
+    timeSec: number;
+    /** Horizontal speed in world units/sec (smoothed by the driver). */
+    speed: number;
+    /** Per-character phase offset in [0, 1) so crowds don't stride in sync — see {@link partMotionPhase}. */
+    phase: number;
+    /** Hit-flinch envelope in [0, 1]; the driver sets 1 on a hit and decays it. */
+    flinch: number;
+    /** Death ramp in [0, 1]; the driver eases it to 1 after the entity dies. */
+    death: number;
+}
+/** A reusable identity pose (zero offsets, unit scale). */
+export declare function createPartPose(): PartPose;
+/**
+ * Deterministic per-character stride phase in [0, 1) from an id (e.g. the entity instance id),
+ * so a crowd of identical part-composed characters doesn't animate in lockstep.
+ */
+export declare function partMotionPhase(id: string): number;
+/**
+ * Sample the character-root pose: walk bob, idle breathe/sway, backward hit flinch, and death —
+ * a sideways topple by default, or a flatten-out splat with `deathStyle: "splat"`. With
+ * `squashAmp > 0` the body also squashes and stretches (footfall squash, jelly idle breathe,
+ * flinch squash pulse), volume-conserving. A driver applies this to the group wrapping the
+ * whole composition (base model plus parts) — limbs ride along, as they would on a real torso.
+ *
+ * @capability part-motion sample the root bob/sway/squash/flinch/death pose for a rig-less part-composed character
+ */
+export declare function sampleBodyPose(input: PartMotionInput, params?: PartMotionParams, out?: PartPose): PartPose;
+/**
+ * Sample one part's pose offset by role: counter-phase leg/arm swing driven by speed, a head
+ * counter-sway, tail wag, and wing flap. Offsets are added onto the part's authored
+ * position/rotation. Motion fades to zero as `death` ramps so the topple reads as one piece.
+ *
+ * @capability part-motion sample a limb/head/tail/wing pose offset for a role-tagged ModelPart
+ */
+export declare function samplePartPose(role: PartRole, input: PartMotionInput, params?: PartMotionParams, out?: PartPose): PartPose;