@jgengine/core 0.9.0 → 0.11.0

package/dist/combat/magazine.js

@@ -0,0 +1,96 @@
+function selfManagedReserve(initial) {
+    let value = Math.max(0, initial);
+    return {
+        current: () => value,
+        spend(amount) {
+            if (amount <= 0)
+                return true;
+            if (amount > value)
+                return false;
+            value -= amount;
+            return true;
+        },
+        gain(amount) {
+            if (amount > 0)
+                value += amount;
+        },
+    };
+}
+const INFINITE_RESERVE = {
+    current: () => Number.POSITIVE_INFINITY,
+    spend: () => true,
+};
+/**
+ * Builds a {@link Magazine}: discrete loaded ammo, a timed reload, and reserve-pool interaction.
+ *
+ * @capability magazine a weapon magazine with capacity, timed reload, and reserve-pool interaction
+ */
+export function createMagazine(config) {
+    const capacity = Math.max(0, config.capacity);
+    const reloadMs = Math.max(0, config.reloadMs);
+    const isInfiniteReserve = config.reserve === undefined;
+    const reserve = isInfiniteReserve
+        ? INFINITE_RESERVE
+        : typeof config.reserve === "number"
+            ? selfManagedReserve(config.reserve)
+            : config.reserve;
+    function clampLoaded(value) {
+        return Math.max(0, Math.min(capacity, value));
+    }
+    let loaded = clampLoaded(config.loaded ?? capacity);
+    let reloadElapsedMs = null;
+    return {
+        loaded: () => loaded,
+        capacity: () => capacity,
+        reserve: () => (isInfiniteReserve ? null : reserve.current()),
+        isReloading: () => reloadElapsedMs !== null,
+        reloadFraction: () => (reloadElapsedMs === null || reloadMs <= 0 ? 0 : Math.min(1, reloadElapsedMs / reloadMs)),
+        isEmpty: () => loaded <= 0,
+        isFull: () => loaded >= capacity,
+        canFire(rounds = 1) {
+            return rounds <= 0 || rounds <= loaded;
+        },
+        fire(rounds = 1) {
+            if (rounds <= 0)
+                return true;
+            if (rounds > loaded)
+                return false;
+            loaded -= rounds;
+            return true;
+        },
+        canReload() {
+            if (reloadElapsedMs !== null)
+                return false;
+            if (loaded >= capacity)
+                return false;
+            return isInfiniteReserve || reserve.current() > 0;
+        },
+        startReload() {
+            if (!this.canReload())
+                return false;
+            reloadElapsedMs = 0;
+            return true;
+        },
+        cancelReload() {
+            reloadElapsedMs = null;
+        },
+        addReserve(amount) {
+            if (amount > 0)
+                reserve.gain?.(amount);
+        },
+        tick(dtSeconds) {
+            if (dtSeconds <= 0 || reloadElapsedMs === null)
+                return;
+            reloadElapsedMs += dtSeconds * 1000;
+            if (reloadElapsedMs < reloadMs)
+                return;
+            const need = capacity - loaded;
+            if (need > 0) {
+                const take = isInfiniteReserve ? need : Math.min(need, reserve.current());
+                if (take > 0 && reserve.spend(take))
+                    loaded = clampLoaded(loaded + take);
+            }
+            reloadElapsedMs = null;
+        },
+    };
+}

package/dist/combat/projectiles.d.ts

@@ -1,6 +1,6 @@
 import type { BallisticSweep } from "../physics/ballisticSweep.js";
 import type { EntityPosition } from "../scene/entityStore.js";
-import type { EntityColliderSet } from "../scene/colliders.js";
+import { type EntityColliderSet } from "../scene/colliders.js";
 import { type SceneRaycastApi } from "../scene/sceneRaycast.js";
 import type { Aim } from "../scene/spatial.js";
 import type { CombatSpatialDeps, EffectResult, EffectSystem, EffectVia } from "./effects.js";
@@ -10,7 +10,7 @@ export interface ProjectileShotInput {
     via: EffectVia;
     aim: Aim;
     effect: string;
-    /** Defaults to `{ kind: "legacy" }` — aim.origin or shooter position. */
+    /** Defaults to `{ kind: "eye" }` — aim.origin when given, else shooter position at eye height. */
     originPolicy?: ShotOriginPolicy;
 }
 export interface EntityRaycastHit {
@@ -108,4 +108,9 @@ export interface ProjectileSystem {
     fireProjectile(input: ProjectileShotInput): string;
     settleProjectile(shotId: string): SettleResult;
 }
+/**
+ * Spawn and advance projectiles each frame, resolving travel, lifetime, and hits.
+ *
+ * @capability projectiles spawn and advance projectiles with travel and hit resolution
+ */
 export declare function createProjectileSystem(deps: ProjectileSystemDeps): ProjectileSystem;

package/dist/combat/projectiles.js

@@ -1,5 +1,6 @@
+import { defaultEntityColliders, resolveColliders } from "../scene/colliders.js";
 import { createSceneRaycast, firstImpact, hitsUntilBlocked, } from "../scene/sceneRaycast.js";
-import { aimDirection, aimSpreadDeg, resolveShot, } from "./shotOrigin.js";
+import { aimDirection, aimSpreadDeg, convergeShot, resolveShot, } from "./shotOrigin.js";
 const DEFAULT_RANGE = 100;
 const DEFAULT_PROJECTILE_SPEED = 15;
 const GRAVITY = 9.8;
@@ -66,11 +67,16 @@ function asSceneHits(hits) {
         normal: [0, 1, 0],
     }));
 }
+/**
+ * Spawn and advance projectiles each frame, resolving travel, lifetime, and hits.
+ *
+ * @capability projectiles spawn and advance projectiles with travel and hit resolution
+ */
 export function createProjectileSystem(deps) {
     const shots = new Map();
     let shotCounter = 0;
     const now = deps.now ?? (() => Date.now());
-    const defaultPolicy = deps.defaultOriginPolicy ?? { kind: "legacy" };
+    const defaultPolicy = deps.defaultOriginPolicy ?? { kind: "converge" };
     function itemStat(via, stat) {
         return via.item === undefined ? null : deps.getStat(via.item, stat);
     }
@@ -80,11 +86,25 @@ export function createProjectileSystem(deps) {
         const spread = itemStat(via, "spread");
         return spread === null ? aim : { ...aim, spread };
     }
-    function resolveShotFor(from, aim, policy) {
-        return resolveShot({
-            positionOf: deps.spatial.positionOf,
-            rotationYOf: deps.rotationYOf,
-        }, from, aim, policy ?? defaultPolicy);
+    const shotOriginDeps = {
+        positionOf: deps.spatial.positionOf,
+        rotationYOf: deps.rotationYOf,
+        collidersOf: deps.entityCollidersOf,
+    };
+    function resolveShotFor(from, aim, policy, range) {
+        const active = policy ?? defaultPolicy;
+        if (active.kind === "converge") {
+            return convergeShot(shotOriginDeps, from, aim, range, (origin, direction) => {
+                const all = internalSceneRaycast.raycastAll({
+                    origin,
+                    direction,
+                    maxDistance: range,
+                    excludeInstanceIds: [from],
+                });
+                return hitsUntilBlocked(all)[0]?.point ?? null;
+            }, active.muzzle);
+        }
+        return resolveShot(shotOriginDeps, from, aim, active);
     }
     const internalSceneRaycast = deps.sceneRaycast ??
         createSceneRaycast({
@@ -132,7 +152,7 @@ export function createProjectileSystem(deps) {
         });
     const raycast = deps.raycast ??
         ((from, aim, range, originPolicy) => {
-            const resolved = resolveShotFor(from, aim, originPolicy);
+            const resolved = resolveShotFor(from, aim, originPolicy, range);
             if (resolved === null)
                 return [];
             const { origin, direction } = resolved;
@@ -149,15 +169,26 @@ export function createProjectileSystem(deps) {
                 if (hit.targetKind === "entity" && spreadRad > 0) {
                     const position = deps.spatial.positionOf(hit.instanceId);
                     if (position !== undefined) {
-                        const dx = position[0] - origin[0];
-                        const dy = position[1] - origin[1];
-                        const dz = position[2] - origin[2];
+                        const colliders = resolveColliders(deps.entityCollidersOf?.(hit.instanceId) ?? defaultEntityColliders());
+                        const collider = colliders.find((candidate) => candidate.name === hit.colliderName) ?? colliders[0];
+                        const localOffset = collider?.shape.offset ?? [0, 0, 0];
+                        const slack = collider === undefined
+                            ? BASE_HIT_RADIUS
+                            : collider.shape.kind === "sphere"
+                                ? collider.shape.radius
+                                : Math.hypot(...collider.shape.halfExtents);
+                        const rotationY = deps.rotationYOf?.(hit.instanceId) ?? 0;
+                        const cos = Math.cos(rotationY);
+                        const sin = Math.sin(rotationY);
+                        const dx = position[0] + localOffset[0] * cos + localOffset[2] * sin - origin[0];
+                        const dy = position[1] + localOffset[1] - origin[1];
+                        const dz = position[2] - localOffset[0] * sin + localOffset[2] * cos - origin[2];
                         const along = dx * direction[0] + dy * direction[1] + dz * direction[2];
                         const px = dx - direction[0] * along;
                         const py = dy - direction[1] * along;
                         const pz = dz - direction[2] * along;
                         const perpendicular = Math.sqrt(px * px + py * py + pz * pz);
-                        if (perpendicular > 0.5 + Math.tan(spreadRad) * along)
+                        if (perpendicular > slack + Math.tan(spreadRad) * along)
                             continue;
                     }
                 }
@@ -172,7 +203,7 @@ export function createProjectileSystem(deps) {
         return itemStat(via, "projectile.fuseTime") !== null || itemStat(via, "explosion.radius") !== null;
     }
     function ballisticArc(input) {
-        const resolved = resolveShotFor(input.from, input.aim, input.originPolicy);
+        const resolved = resolveShotFor(input.from, input.aim, input.originPolicy, resolveRange(input.via));
         const origin = resolved?.origin ?? [0, 0, 0];
         const direction = resolved?.direction ?? aimDirection(input.aim) ?? [0, 0, 1];
         const speed = itemStat(input.via, "projectile.speed") ?? DEFAULT_PROJECTILE_SPEED;
@@ -210,7 +241,7 @@ export function createProjectileSystem(deps) {
     }
     function predictHits(input) {
         const aim = withWeaponSpread(input.via, input.aim);
-        const resolved = resolveShotFor(input.from, aim, input.originPolicy);
+        const resolved = resolveShotFor(input.from, aim, input.originPolicy, resolveRange(input.via));
         const rawHits = raycast(input.from, aim, resolveRange(input.via), input.originPolicy);
         const visible = rawHits.filter((hit) => isObjectHit(hit) || deps.spatial.hasLineOfSight(input.from, hit.instanceId));
         return {
@@ -221,10 +252,10 @@ export function createProjectileSystem(deps) {
         };
     }
     function missPoint(input) {
-        const resolved = resolveShotFor(input.from, input.aim, input.originPolicy);
+        const range = resolveRange(input.via);
+        const resolved = resolveShotFor(input.from, input.aim, input.originPolicy, range);
         if (resolved === null)
             return [0, 0, 0];
-        const range = resolveRange(input.via);
         return [
             resolved.origin[0] + resolved.direction[0] * range,
             resolved.origin[1] + resolved.direction[1] * range,
@@ -262,7 +293,7 @@ export function createProjectileSystem(deps) {
                 return { status: "rejected", shotId, reason: "already-settled" };
             shot.settled = true;
             const { input } = shot;
-            const resolved = resolveShotFor(input.from, input.aim, input.originPolicy);
+            const resolved = resolveShotFor(input.from, input.aim, input.originPolicy, resolveRange(input.via));
             const origin = resolved?.origin ?? [0, 0, 0];
             const originTuple = [origin[0], origin[1], origin[2]];
             if (isBallistic(input.via)) {

package/dist/combat/receivedDamage.d.ts

@@ -0,0 +1,117 @@
+import type { DamageChannelId } from "./damageMatchup.js";
+/**
+ * The facts a received-damage modifier predicates over: the incoming `channel`, who dealt it,
+ * the statuses the target currently carries, and any caller tags. All caller-owned strings; the
+ * engine never assigns meaning to a channel, source, status, or tag.
+ */
+export interface DamageContext {
+    channel: DamageChannelId;
+    /** Attacker/source id, when known. */
+    source?: string;
+    /** The receiving target's id. */
+    target: string;
+    /** Status ids currently on the target — lets a modifier fire only `whileStatus`. */
+    targetStatuses?: readonly string[];
+    /** Arbitrary caller tags on the hit (`"crit"`, `"melee"`, `"aoe"`). */
+    tags?: readonly string[];
+}
+/**
+ * A typed predicate over a {@link DamageContext}. Every listed facet must match (AND); a facet
+ * matches when the context value is in the list (channels/sources) or shares any member
+ * (targetStatuses/tags). An empty predicate matches every hit.
+ */
+export interface DamagePredicate {
+    /** Fire only for these channels. */
+    channels?: readonly DamageChannelId[];
+    /** Fire only for these attacker sources. */
+    sources?: readonly string[];
+    /** Fire only while the target carries one of these statuses. */
+    whileStatus?: readonly string[];
+    /** Fire only when the hit carries one of these tags. */
+    tags?: readonly string[];
+}
+/**
+ * What a matched modifier does to the incoming amount. Amplification is one policy beside
+ * reduction — both are `scale` (factor `> 1` amplifies, `< 1` reduces). `cap`/`floor` clamp,
+ * `flat` adds/subtracts, `convert` moves a portion to another channel on the same target,
+ * `redirect` moves a portion to another target, and `immune` zeroes the hit outright.
+ */
+export type ReceivedPolicy = {
+    kind: "scale";
+    factor: number;
+} | {
+    kind: "flat";
+    delta: number;
+} | {
+    kind: "cap";
+    max: number;
+} | {
+    kind: "floor";
+    min: number;
+} | {
+    kind: "convert";
+    toChannel: DamageChannelId;
+    portion?: number;
+} | {
+    kind: "redirect";
+    toTarget: string;
+    portion?: number;
+} | {
+    kind: "immune";
+};
+/** One serializable receiver-side rule: an optional predicate, a policy, and an ordering key. */
+export interface ReceivedModifier {
+    /** Stable id echoed in provenance; helps UI/debug attribute a change. */
+    id?: string;
+    /** When the modifier fires; omitted means always. */
+    when?: DamagePredicate;
+    policy: ReceivedPolicy;
+    /** Lower runs first; ties keep declaration order. Defaults to 0. */
+    order?: number;
+}
+/** One recorded transformation — the provenance a UI or debugger reads to explain a final number. */
+export interface ReceivedStep {
+    modifierId: string | null;
+    kind: ReceivedPolicy["kind"];
+    before: number;
+    after: number;
+    /** Portion diverted to a redirect target or converted channel, when the policy did so. */
+    diverted?: number;
+}
+/** A portion of the hit sent elsewhere by a `redirect`/`convert` policy. */
+export interface DamageDivert {
+    /** For a redirect: the receiving target. For a convert: unset. */
+    target?: string;
+    /** For a convert: the channel the portion becomes. For a redirect: unset. */
+    channel?: DamageChannelId;
+    amount: number;
+}
+/** The full, provenance-rich outcome of running received modifiers over one hit. */
+export interface ReceivedDamageResult {
+    /** Final amount landing on the primary target/channel; never negative. */
+    amount: number;
+    /** True when an `immune` policy zeroed the hit. */
+    immune: boolean;
+    /** Portions redirected to other targets. */
+    redirects: DamageDivert[];
+    /** Portions converted to other channels on the same target. */
+    conversions: DamageDivert[];
+    /** Ordered record of every modifier that ran and what it changed. */
+    steps: ReceivedStep[];
+}
+/** The incoming amount, its {@link DamageContext}, and the receiver's modifier list to run over it. */
+export interface ReceivedDamageInput {
+    amount: number;
+    context: DamageContext;
+    modifiers: readonly ReceivedModifier[];
+}
+/**
+ * Run receiver-side modifiers over an incoming hit, in ascending `order`, recording every step.
+ * Amplification, reduction, caps, conversion, redirection, and immunity are all data — the engine
+ * applies whichever policies the target's modifiers declare and never branches on channel names.
+ * Pure over serializable data with bounded work (one pass over the modifier list); an `immune`
+ * policy short-circuits the remaining modifiers.
+ *
+ * @capability received-damage apply data-defined receiver-side damage modifiers (amplify, reduce, cap, convert, redirect, immunity) with typed predicates
+ */
+export declare function resolveReceivedDamage(input: ReceivedDamageInput): ReceivedDamageResult;

package/dist/combat/receivedDamage.js

@@ -0,0 +1,92 @@
+function sharesAny(a, b) {
+    if (a === undefined)
+        return false;
+    for (const value of a)
+        if (b.includes(value))
+            return true;
+    return false;
+}
+function matches(predicate, ctx) {
+    if (predicate === undefined)
+        return true;
+    if (predicate.channels !== undefined && !predicate.channels.includes(ctx.channel))
+        return false;
+    if (predicate.sources !== undefined && (ctx.source === undefined || !predicate.sources.includes(ctx.source))) {
+        return false;
+    }
+    if (predicate.whileStatus !== undefined && !sharesAny(ctx.targetStatuses, predicate.whileStatus))
+        return false;
+    if (predicate.tags !== undefined && !sharesAny(ctx.tags, predicate.tags))
+        return false;
+    return true;
+}
+/**
+ * Run receiver-side modifiers over an incoming hit, in ascending `order`, recording every step.
+ * Amplification, reduction, caps, conversion, redirection, and immunity are all data — the engine
+ * applies whichever policies the target's modifiers declare and never branches on channel names.
+ * Pure over serializable data with bounded work (one pass over the modifier list); an `immune`
+ * policy short-circuits the remaining modifiers.
+ *
+ * @capability received-damage apply data-defined receiver-side damage modifiers (amplify, reduce, cap, convert, redirect, immunity) with typed predicates
+ */
+export function resolveReceivedDamage(input) {
+    const ctx = input.context;
+    const ordered = input.modifiers
+        .map((modifier, index) => ({ modifier, index }))
+        .filter((entry) => matches(entry.modifier.when, ctx))
+        .sort((a, b) => (a.modifier.order ?? 0) - (b.modifier.order ?? 0) || a.index - b.index);
+    let amount = Math.max(0, input.amount);
+    let immune = false;
+    const redirects = [];
+    const conversions = [];
+    const steps = [];
+    for (const { modifier } of ordered) {
+        const policy = modifier.policy;
+        const before = amount;
+        const id = modifier.id ?? null;
+        switch (policy.kind) {
+            case "scale":
+                amount = Math.max(0, amount * policy.factor);
+                steps.push({ modifierId: id, kind: "scale", before, after: amount });
+                break;
+            case "flat":
+                amount = Math.max(0, amount + policy.delta);
+                steps.push({ modifierId: id, kind: "flat", before, after: amount });
+                break;
+            case "cap":
+                amount = Math.min(amount, policy.max);
+                steps.push({ modifierId: id, kind: "cap", before, after: amount });
+                break;
+            case "floor":
+                amount = Math.max(amount, policy.min);
+                steps.push({ modifierId: id, kind: "floor", before, after: amount });
+                break;
+            case "convert": {
+                const portion = policy.portion ?? 1;
+                const moved = amount * Math.max(0, Math.min(1, portion));
+                amount -= moved;
+                if (moved > 0)
+                    conversions.push({ channel: policy.toChannel, amount: moved });
+                steps.push({ modifierId: id, kind: "convert", before, after: amount, diverted: moved });
+                break;
+            }
+            case "redirect": {
+                const portion = policy.portion ?? 1;
+                const moved = amount * Math.max(0, Math.min(1, portion));
+                amount -= moved;
+                if (moved > 0)
+                    redirects.push({ target: policy.toTarget, amount: moved });
+                steps.push({ modifierId: id, kind: "redirect", before, after: amount, diverted: moved });
+                break;
+            }
+            case "immune":
+                amount = 0;
+                immune = true;
+                steps.push({ modifierId: id, kind: "immune", before, after: 0 });
+                break;
+        }
+        if (immune)
+            break;
+    }
+    return { amount, immune, redirects, conversions, steps };
+}

package/dist/combat/regenShield.d.ts

@@ -0,0 +1,39 @@
+/** Tuning for `createRegenShield`: pool size, refill rate, and the post-damage grace period. */
+export interface RegenShieldConfig {
+    max: number;
+    /** Points restored per second once the post-damage grace period has elapsed. */
+    regenPerSecond: number;
+    /** Grace period after the last damage before regen resumes. */
+    regenDelayMs: number;
+    /** Starting value; defaults to `max` (full). */
+    current?: number;
+}
+/**
+ * A shield pool that stops regenerating for `regenDelayMs` after every hit, then refills at
+ * `regenPerSecond` — the delayed-regen primitive that replaces snapshot-comparing stat values per
+ * tick to detect "damage taken" (#536.3). `damage` resets the grace timer; `tick` counts it down and
+ * regenerates once it elapses.
+ */
+export interface RegenShield {
+    current(): number;
+    max(): number;
+    setMax(value: number): void;
+    fraction(): number;
+    isFull(): boolean;
+    isBroken(): boolean;
+    /** True while the post-damage grace period is suppressing regen. */
+    suppressed(): boolean;
+    /** Absorb `amount` and reset the regen grace timer; returns damage that got through (0 while the shield holds). */
+    damage(amount: number): number;
+    /** Add `amount` without touching the regen timer (a pickup or scripted refill). */
+    restore(amount: number): void;
+    set(value: number): void;
+    /** Advance time: count down the grace period, then regenerate once it has elapsed. */
+    tick(dtSeconds: number): void;
+}
+/**
+ * Builds a {@link RegenShield} that suppresses regen for `regenDelayMs` after each hit.
+ *
+ * @capability regen-shield a rechargeable overshield that absorbs damage and refills after a lull
+ */
+export declare function createRegenShield(config: RegenShieldConfig): RegenShield;

package/dist/combat/regenShield.js

@@ -0,0 +1,49 @@
+/**
+ * Builds a {@link RegenShield} that suppresses regen for `regenDelayMs` after each hit.
+ *
+ * @capability regen-shield a rechargeable overshield that absorbs damage and refills after a lull
+ */
+export function createRegenShield(config) {
+    let max = Math.max(0, config.max);
+    const regenPerSecond = Math.max(0, config.regenPerSecond);
+    const regenDelayMs = Math.max(0, config.regenDelayMs);
+    function clamp(value, ceiling) {
+        return Math.max(0, Math.min(ceiling, value));
+    }
+    let current = clamp(config.current ?? max, max);
+    let sinceDamageMs = regenDelayMs;
+    return {
+        current: () => current,
+        max: () => max,
+        setMax(value) {
+            max = Math.max(0, value);
+            current = clamp(current, max);
+        },
+        fraction: () => (max <= 0 ? 0 : current / max),
+        isFull: () => current >= max,
+        isBroken: () => current <= 0,
+        suppressed: () => sinceDamageMs < regenDelayMs,
+        damage(amount) {
+            if (amount <= 0)
+                return 0;
+            sinceDamageMs = 0;
+            const overflow = Math.max(0, amount - current);
+            current = clamp(current - amount, max);
+            return overflow;
+        },
+        restore(amount) {
+            if (amount > 0)
+                current = clamp(current + amount, max);
+        },
+        set(value) {
+            current = clamp(value, max);
+        },
+        tick(dtSeconds) {
+            if (dtSeconds <= 0)
+                return;
+            sinceDamageMs += dtSeconds * 1000;
+            if (sinceDamageMs >= regenDelayMs)
+                current = clamp(current + regenPerSecond * dtSeconds, max);
+        },
+    };
+}

package/dist/combat/renderCues.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Per-entity render cues: the motion/animation signal a custom `renderEntity`
+ * or first-person viewmodel component needs to drive gait, muzzle flash,
+ * reload poses, and hit reactions — without diffing the parent group's
+ * position itself or reading a game-side module map for attack timing.
+ */
+export interface EntityRenderCues {
+    /** Horizontal ground speed in world units/sec (e.g. `groundSpeed(entity)`). */
+    speed: number;
+    /** 0..1 walk-cycle phase, advancing with `speed`; wraps every full stride. */
+    bobPhase: number;
+    /** True for a short pulse after a `"fire"` `entity.animation` event. */
+    firing: boolean;
+    /** True from a `"reload"` `entity.animation` event until `"reloadEnd"`. */
+    reloading: boolean;
+    /** 0..1 recoil kick, set to 1 on `"fire"` and decaying over time. */
+    recoil: number;
+    /** True for a short pulse after a `combat.hitReaction` event. */
+    hit: boolean;
+    /** True once `entity.died` fires for this instance; stays true. */
+    dead: boolean;
+}
+/** Neutral starting cue set: idle, unarmed, undamaged. */
+export declare const DEFAULT_RENDER_CUES: Readonly<EntityRenderCues>;
+/** Tuning knobs for `advanceMotionCues` / `useEntityRenderCues`; every field has a default, override only what a weapon/rig's feel needs to differ. */
+export interface RenderCueTuning {
+    /** Bob-cycle phase advanced per world unit of travel. Default 0.6. */
+    cyclesPerUnit?: number;
+    /** Recoil decay toward 0, per second. Default 6. */
+    recoilDecayPerSecond?: number;
+    /** Seconds `firing` stays true after a `"fire"` event. Default 0.12. */
+    firePulseSeconds?: number;
+    /** Seconds `hit` stays true after a `combat.hitReaction` event. Default 0.2. */
+    hitPulseSeconds?: number;
+}
+/** Default `RenderCueTuning.cyclesPerUnit`. */
+export declare const DEFAULT_CYCLES_PER_UNIT = 0.6;
+/** Default `RenderCueTuning.recoilDecayPerSecond`. */
+export declare const DEFAULT_RECOIL_DECAY_PER_SECOND = 6;
+/** Default `RenderCueTuning.firePulseSeconds`. */
+export declare const DEFAULT_FIRE_PULSE_SECONDS = 0.12;
+/** Default `RenderCueTuning.hitPulseSeconds`. */
+export declare const DEFAULT_HIT_PULSE_SECONDS = 0.2;
+/** Advances `bobPhase` and decays `recoil` from a live `speed` sample (e.g. `groundSpeed(entity)`); leaves event-driven fields untouched. */
+export declare function advanceMotionCues(cues: EntityRenderCues, speed: number, dt: number, tuning?: RenderCueTuning): EntityRenderCues;
+/** Applies a `entity.animation` event (`"fire"` / `"reload"` / `"reloadEnd"`, or any game-defined name) to the cue set. Unknown event names are a no-op. */
+export declare function applyRenderAnimationEvent(cues: EntityRenderCues, event: string): EntityRenderCues;
+/** Marks a `combat.hitReaction` pulse; the caller clears `hit` again after its own pulse window. */
+export declare function applyRenderHitEvent(cues: EntityRenderCues): EntityRenderCues;
+/** Marks the cue set dead after `entity.died`; sticky for the lifetime of the render component. */
+export declare function applyRenderDeathEvent(cues: EntityRenderCues): EntityRenderCues;

package/dist/combat/renderCues.js

@@ -0,0 +1,44 @@
+/** Neutral starting cue set: idle, unarmed, undamaged. */
+export const DEFAULT_RENDER_CUES = Object.freeze({
+    speed: 0,
+    bobPhase: 0,
+    firing: false,
+    reloading: false,
+    recoil: 0,
+    hit: false,
+    dead: false,
+});
+/** Default `RenderCueTuning.cyclesPerUnit`. */
+export const DEFAULT_CYCLES_PER_UNIT = 0.6;
+/** Default `RenderCueTuning.recoilDecayPerSecond`. */
+export const DEFAULT_RECOIL_DECAY_PER_SECOND = 6;
+/** Default `RenderCueTuning.firePulseSeconds`. */
+export const DEFAULT_FIRE_PULSE_SECONDS = 0.12;
+/** Default `RenderCueTuning.hitPulseSeconds`. */
+export const DEFAULT_HIT_PULSE_SECONDS = 0.2;
+/** Advances `bobPhase` and decays `recoil` from a live `speed` sample (e.g. `groundSpeed(entity)`); leaves event-driven fields untouched. */
+export function advanceMotionCues(cues, speed, dt, tuning) {
+    const cyclesPerUnit = tuning?.cyclesPerUnit ?? DEFAULT_CYCLES_PER_UNIT;
+    const recoilDecayPerSecond = tuning?.recoilDecayPerSecond ?? DEFAULT_RECOIL_DECAY_PER_SECOND;
+    const bobPhase = speed > 0.05 ? (cues.bobPhase + speed * cyclesPerUnit * dt) % 1 : cues.bobPhase;
+    const recoil = Math.max(0, cues.recoil - recoilDecayPerSecond * dt);
+    return { ...cues, speed, bobPhase, recoil };
+}
+/** Applies a `entity.animation` event (`"fire"` / `"reload"` / `"reloadEnd"`, or any game-defined name) to the cue set. Unknown event names are a no-op. */
+export function applyRenderAnimationEvent(cues, event) {
+    if (event === "fire")
+        return { ...cues, firing: true, recoil: 1 };
+    if (event === "reload")
+        return { ...cues, reloading: true };
+    if (event === "reloadEnd")
+        return { ...cues, reloading: false };
+    return cues;
+}
+/** Marks a `combat.hitReaction` pulse; the caller clears `hit` again after its own pulse window. */
+export function applyRenderHitEvent(cues) {
+    return { ...cues, hit: true };
+}
+/** Marks the cue set dead after `entity.died`; sticky for the lifetime of the render component. */
+export function applyRenderDeathEvent(cues) {
+    return { ...cues, dead: true };
+}

package/dist/combat/resourcePool.d.ts

@@ -17,4 +17,9 @@ export interface ResourcePool {
     isFull(): boolean;
     isEmpty(): boolean;
 }
+/**
+ * A regenerating resource pool — mana, stamina, energy — that actions spend from and that refills over time.
+ *
+ * @capability resource-pool a regenerating pool like mana or stamina that actions spend from
+ */
 export declare function createResourcePool(config: ResourcePoolConfig): ResourcePool;