@jgengine/core 0.11.0 → 0.13.0

package/dist/combat/magazine.js

@@ -92,5 +92,32 @@ export function createMagazine(config) {
             }
             reloadElapsedMs = null;
         },
+        snapshot() {
+            return {
+                loaded,
+                reloadElapsedMs,
+                reserve: isInfiniteReserve ? null : reserve.current(),
+            };
+        },
+        restore(snapshot) {
+            if (isInfiniteReserve !== (snapshot.reserve === null))
+                return false;
+            if (!isInfiniteReserve) {
+                const desired = Math.max(0, snapshot.reserve);
+                const current = Math.max(0, reserve.current());
+                if (desired > current && reserve.gain === undefined)
+                    return false;
+                if (desired < current && !reserve.spend(current - desired))
+                    return false;
+                if (desired > current)
+                    reserve.gain?.(desired - current);
+            }
+            loaded = clampLoaded(snapshot.loaded);
+            reloadElapsedMs =
+                snapshot.reloadElapsedMs === null
+                    ? null
+                    : Math.max(0, Math.min(reloadMs, snapshot.reloadElapsedMs));
+            return true;
+        },
     };
 }

package/dist/combat/vfxPresets.d.ts

@@ -0,0 +1,176 @@
+import type { VfxKind } from "../game/events.js";
+/**
+ * A named visual flavor for a one-shot `combat.vfx` burst: the archetype (`kind`),
+ * a `0xRRGGBB` tint, and optional default `durationMs`/`radius`. Purely presentation —
+ * a preset never touches damage, range, or any authoritative value; it just answers
+ * "what does this attack look like" so a game does not hand-roll colors and archetypes.
+ */
+export interface VfxPreset {
+    kind: VfxKind;
+    /** `0xRRGGBB` tint. */
+    color: number;
+    /** Overrides the shell's per-`kind` default lifetime when set. */
+    durationMs?: number;
+    /** Default effect radius for `nova`/aura flavors. */
+    radius?: number;
+}
+/**
+ * Ready-made visual flavors for the things players actually shoot, swing, and cast —
+ * so `ctx.scene.entity.vfx({ preset: "arrow", from, to })` renders a visible bolt with
+ * zero tuning, and `"lightning"`, `"web"`, `"slash"`, `"shield"`, `"heal"`, `"explosion"`
+ * likewise just work. Each entry only picks a `kind` (`projectile | beam | nova | glow |
+ * spark`), a color, and a lifetime; it is visual vocabulary (like named CSS colors), not a
+ * gameplay archetype — combat numbers stay in the caller's own effect/ability data. Any
+ * field passed to `vfx()` overrides the preset, and unknown names fall back to `spark` so a
+ * flavor typo still shows *something* rather than nothing.
+ *
+ * @capability vfx-presets render a named attack visual (arrow, fireball, lightning, web, slash, shield, heal, explosion) in one call
+ */
+export declare const vfxPresets: {
+    readonly arrow: {
+        readonly kind: "projectile";
+        readonly color: 14207392;
+    };
+    readonly bolt: {
+        readonly kind: "projectile";
+        readonly color: 16777215;
+    };
+    readonly fireball: {
+        readonly kind: "projectile";
+        readonly color: 16738842;
+        readonly durationMs: 460;
+    };
+    readonly firebolt: {
+        readonly kind: "projectile";
+        readonly color: 16742954;
+    };
+    readonly frostbolt: {
+        readonly kind: "projectile";
+        readonly color: 9360127;
+    };
+    readonly ice: {
+        readonly kind: "projectile";
+        readonly color: 9360127;
+    };
+    readonly poison: {
+        readonly kind: "projectile";
+        readonly color: 8841322;
+    };
+    readonly shadowbolt: {
+        readonly kind: "projectile";
+        readonly color: 10116592;
+    };
+    readonly arcane: {
+        readonly kind: "projectile";
+        readonly color: 14256895;
+    };
+    readonly magicMissile: {
+        readonly kind: "projectile";
+        readonly color: 14256895;
+    };
+    readonly holybolt: {
+        readonly kind: "projectile";
+        readonly color: 16771488;
+    };
+    readonly rock: {
+        readonly kind: "projectile";
+        readonly color: 11049606;
+    };
+    readonly bullet: {
+        readonly kind: "projectile";
+        readonly color: 16773808;
+        readonly durationMs: 140;
+    };
+    readonly lightning: {
+        readonly kind: "beam";
+        readonly color: 12576511;
+        readonly durationMs: 200;
+    };
+    readonly laser: {
+        readonly kind: "beam";
+        readonly color: 16731469;
+    };
+    readonly beam: {
+        readonly kind: "beam";
+        readonly color: 9360127;
+    };
+    readonly web: {
+        readonly kind: "beam";
+        readonly color: 15790320;
+        readonly durationMs: 320;
+    };
+    readonly chain: {
+        readonly kind: "beam";
+        readonly color: 16771488;
+    };
+    readonly slash: {
+        readonly kind: "spark";
+        readonly color: 14078148;
+    };
+    readonly sword: {
+        readonly kind: "spark";
+        readonly color: 14078148;
+    };
+    readonly melee: {
+        readonly kind: "spark";
+        readonly color: 14078148;
+    };
+    readonly spark: {
+        readonly kind: "spark";
+        readonly color: 16773808;
+    };
+    readonly hit: {
+        readonly kind: "spark";
+        readonly color: 16765562;
+    };
+    readonly explosion: {
+        readonly kind: "nova";
+        readonly color: 16747066;
+        readonly radius: 3;
+    };
+    readonly blast: {
+        readonly kind: "nova";
+        readonly color: 16747066;
+        readonly radius: 3;
+    };
+    readonly shockwave: {
+        readonly kind: "nova";
+        readonly color: 12576511;
+        readonly radius: 3;
+    };
+    readonly frostNova: {
+        readonly kind: "nova";
+        readonly color: 9360127;
+        readonly radius: 3;
+    };
+    readonly heal: {
+        readonly kind: "glow";
+        readonly color: 8841322;
+    };
+    readonly buff: {
+        readonly kind: "glow";
+        readonly color: 16771488;
+    };
+    readonly shield: {
+        readonly kind: "glow";
+        readonly color: 9360127;
+    };
+    readonly cast: {
+        readonly kind: "glow";
+        readonly color: 14256895;
+    };
+};
+/** A named key into {@link vfxPresets} (`"arrow" | "fireball" | "lightning" | "web" | "slash" | "shield" | "heal" | ...`). */
+export type VfxPresetName = keyof typeof vfxPresets;
+/** The fallback flavor used when a `vfx()` call names an unknown preset — so a typo still shows a spark instead of nothing. */
+export declare const DEFAULT_VFX_PRESET: VfxPresetName;
+/**
+ * Resolve a named visual flavor into a concrete `{ kind, color, durationMs?, radius? }`,
+ * with any provided `overrides` winning field by field. An unknown name resolves to
+ * {@link DEFAULT_VFX_PRESET} rather than throwing, so a flavor typo degrades to a visible
+ * spark. Used by `ctx.scene.entity.vfx({ preset })`; call it directly when you need the raw
+ * numbers (e.g. to seed a retained `vfxInstance` from the same vocabulary).
+ *
+ * @capability vfx-preset-resolve turn a named attack flavor into concrete vfx kind/color/duration with per-field overrides
+ */
+export declare function resolveVfxPreset(name: string | undefined, overrides?: Partial<VfxPreset>): VfxPreset;

package/dist/combat/vfxPresets.js

@@ -0,0 +1,74 @@
+/**
+ * Ready-made visual flavors for the things players actually shoot, swing, and cast —
+ * so `ctx.scene.entity.vfx({ preset: "arrow", from, to })` renders a visible bolt with
+ * zero tuning, and `"lightning"`, `"web"`, `"slash"`, `"shield"`, `"heal"`, `"explosion"`
+ * likewise just work. Each entry only picks a `kind` (`projectile | beam | nova | glow |
+ * spark`), a color, and a lifetime; it is visual vocabulary (like named CSS colors), not a
+ * gameplay archetype — combat numbers stay in the caller's own effect/ability data. Any
+ * field passed to `vfx()` overrides the preset, and unknown names fall back to `spark` so a
+ * flavor typo still shows *something* rather than nothing.
+ *
+ * @capability vfx-presets render a named attack visual (arrow, fireball, lightning, web, slash, shield, heal, explosion) in one call
+ */
+export const vfxPresets = {
+    // Traveling bolts — a thing flies from caster to target.
+    arrow: { kind: "projectile", color: 0xd8c9a0 },
+    bolt: { kind: "projectile", color: 0xffffff },
+    fireball: { kind: "projectile", color: 0xff6a1a, durationMs: 460 },
+    firebolt: { kind: "projectile", color: 0xff7a2a },
+    frostbolt: { kind: "projectile", color: 0x8ed2ff },
+    ice: { kind: "projectile", color: 0x8ed2ff },
+    poison: { kind: "projectile", color: 0x86e86a },
+    shadowbolt: { kind: "projectile", color: 0x9a5df0 },
+    arcane: { kind: "projectile", color: 0xd98aff },
+    magicMissile: { kind: "projectile", color: 0xd98aff },
+    holybolt: { kind: "projectile", color: 0xffe9a0 },
+    rock: { kind: "projectile", color: 0xa89a86 },
+    bullet: { kind: "projectile", color: 0xfff2b0, durationMs: 140 },
+    // Connecting lines — a beam/tether links caster and target.
+    lightning: { kind: "beam", color: 0xbfe6ff, durationMs: 200 },
+    laser: { kind: "beam", color: 0xff4d4d },
+    beam: { kind: "beam", color: 0x8ed2ff },
+    web: { kind: "beam", color: 0xf0f0f0, durationMs: 320 },
+    chain: { kind: "beam", color: 0xffe9a0 },
+    // Melee / impact — a spark scatters at the point of contact.
+    slash: { kind: "spark", color: 0xd6d0c4 },
+    sword: { kind: "spark", color: 0xd6d0c4 },
+    melee: { kind: "spark", color: 0xd6d0c4 },
+    spark: { kind: "spark", color: 0xfff2b0 },
+    hit: { kind: "spark", color: 0xffd27a },
+    // Ground bursts — an expanding ring/shockwave from a point.
+    explosion: { kind: "nova", color: 0xff8a3a, radius: 3 },
+    blast: { kind: "nova", color: 0xff8a3a, radius: 3 },
+    shockwave: { kind: "nova", color: 0xbfe6ff, radius: 3 },
+    frostNova: { kind: "nova", color: 0x8ed2ff, radius: 3 },
+    // Auras — a soft glow that lingers on caster or target.
+    heal: { kind: "glow", color: 0x86e86a },
+    buff: { kind: "glow", color: 0xffe9a0 },
+    shield: { kind: "glow", color: 0x8ed2ff },
+    cast: { kind: "glow", color: 0xd98aff },
+};
+/** The fallback flavor used when a `vfx()` call names an unknown preset — so a typo still shows a spark instead of nothing. */
+export const DEFAULT_VFX_PRESET = "spark";
+/**
+ * Resolve a named visual flavor into a concrete `{ kind, color, durationMs?, radius? }`,
+ * with any provided `overrides` winning field by field. An unknown name resolves to
+ * {@link DEFAULT_VFX_PRESET} rather than throwing, so a flavor typo degrades to a visible
+ * spark. Used by `ctx.scene.entity.vfx({ preset })`; call it directly when you need the raw
+ * numbers (e.g. to seed a retained `vfxInstance` from the same vocabulary).
+ *
+ * @capability vfx-preset-resolve turn a named attack flavor into concrete vfx kind/color/duration with per-field overrides
+ */
+export function resolveVfxPreset(name, overrides) {
+    const base = name !== undefined && name in vfxPresets
+        ? vfxPresets[name]
+        : vfxPresets[DEFAULT_VFX_PRESET];
+    const durationMs = overrides?.durationMs ?? base.durationMs;
+    const radius = overrides?.radius ?? base.radius;
+    return {
+        kind: overrides?.kind ?? base.kind,
+        color: overrides?.color ?? base.color,
+        ...(durationMs === undefined ? {} : { durationMs }),
+        ...(radius === undefined ? {} : { radius }),
+    };
+}

package/dist/combat/weaponFire.d.ts

@@ -0,0 +1,114 @@
+import { type DamageHitInput, type DamageHitResolution } from "./damageResolution.js";
+import { type Magazine, type MagazineConfig } from "./magazine.js";
+/** Tuning for {@link createFireCadence}: the minimum interval between actions and whether it starts ready. */
+export interface FireCadenceConfig {
+    /** Minimum milliseconds between successful `fire()` calls. `<= 0` disables the limit (always ready). */
+    intervalMs: number;
+    /** Start ready to fire (default) or mid-cooldown. */
+    ready?: boolean;
+}
+/**
+ * A minimal minimum-interval rate gate for a repeated action — weapon fire, ability
+ * spam, any "no faster than N per second" rule. Deterministic and serializable: its
+ * whole state is the elapsed time since the last action, exposed via {@link FireCadence.elapsedMs}.
+ */
+export interface FireCadence {
+    /** True when at least `intervalMs` has elapsed since the last successful `fire()`. */
+    ready(): boolean;
+    /** Progress toward ready in `[0, 1]`; `1` when ready. */
+    readyFraction(): number;
+    /** Milliseconds until ready; `0` when ready. */
+    remainingMs(): number;
+    /** Consume the gate: resets the interval and returns `true`, or returns `false` without effect when not `ready()`. */
+    fire(): boolean;
+    /** Advance the internal clock by `dtSeconds`. */
+    tick(dtSeconds: number): void;
+    /** Elapsed milliseconds since the last successful `fire()` (capped at `intervalMs`) — the full serializable state. */
+    elapsedMs(): number;
+    /** Restore a prior {@link FireCadence.elapsedMs} value (e.g. from a save/replay snapshot). */
+    restore(elapsedMs: number): void;
+}
+/**
+ * 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 declare function createFireCadence(config: FireCadenceConfig): FireCadence;
+/** Why a {@link WeaponRuntime.fire} attempt resolved the way it did. */
+export type WeaponFireStatus = "fired" | "cooling" | "empty" | "reloading";
+/**
+ * The result of a {@link WeaponRuntime.fire} attempt. On `"fired"`, `hits` is whatever the
+ * caller's raycast returned and `resolutions` holds the portable damage provenance for each hit
+ * that produced a {@link DamageHitInput}; on any blocked status both are empty and no round was spent.
+ */
+export interface WeaponFireResult<THit> {
+    status: WeaponFireStatus;
+    /** The hits the caller's `resolveHits` returned (empty when the shot was blocked). */
+    hits: readonly THit[];
+    /** One {@link DamageHitResolution} per hit that mapped to a {@link DamageHitInput}. */
+    resolutions: readonly DamageHitResolution[];
+    /** Loaded rounds remaining after the attempt, or `null` when the weapon has no magazine. */
+    loaded: number | null;
+}
+/**
+ * Configuration for {@link createWeaponRuntime}. Everything time/ammo-related is plain data; the
+ * two callbacks are where the caller keeps ownership of aiming, its own raycaster/projectile query,
+ * and how a hit maps to damage. There is deliberately no default weapon, projectile, or damage
+ * table here — those are game content.
+ */
+export interface WeaponRuntimeConfig<TAim, THit> {
+    /** Minimum milliseconds between shots. From a rounds-per-second fire rate, pass `1000 / roundsPerSecond`. */
+    cadenceMs: number;
+    /** Optional discrete-ammo model; omit for an unlimited-fire weapon. */
+    magazine?: MagazineConfig;
+    /** Start the cadence ready to fire (default) or mid-cooldown. */
+    ready?: boolean;
+    /**
+     * Caller-owned aim → hits. This is where the game runs its OWN raycaster, projectile sweep, or
+     * spatial query and returns whatever hit shape it likes. Called once per fired shot.
+     */
+    resolveHits: (aim: TAim) => readonly THit[];
+    /**
+     * Map one resolved hit into a portable {@link DamageHitInput}, or `null` to skip damage for that
+     * hit (e.g. a wall). The runtime feeds the result to {@link resolveDamageHit}.
+     */
+    damageFor: (hit: THit, aim: TAim) => DamageHitInput | null;
+    /** Deterministic RNG forwarded to status rolls in {@link resolveDamageHit} when a hit's input omits its own. */
+    rng?: () => number;
+}
+/**
+ * A composed weapon fire controller: a {@link FireCadence} gate, an optional {@link Magazine}, the
+ * caller's raycast, and portable {@link resolveDamageHit} damage resolution wired together. The
+ * caller retains ownership of models, animations, muzzle flash, audio, input, camera, aiming, and
+ * the raycaster itself.
+ */
+export interface WeaponRuntime<TAim, THit> {
+    /**
+     * Attempt one shot with the given aim. Gates on cadence, reload state, and ammo (in that order);
+     * only a `"fired"` result spends a round, resets the cadence, runs `resolveHits`, and resolves damage.
+     */
+    fire(aim: TAim): WeaponFireResult<THit>;
+    /** Whether {@link WeaponRuntime.fire} would fire right now (cadence ready, not reloading, ammo available). */
+    canFire(): boolean;
+    /** Begin a magazine reload if possible; always `false` for a weapon with no magazine. */
+    startReload(): boolean;
+    /** Abort an in-progress reload. */
+    cancelReload(): void;
+    /** Advance the cadence gate and any magazine reload timer by `dtSeconds`. */
+    tick(dtSeconds: number): void;
+    /** The underlying cadence gate (for HUD readouts and snapshot/restore). */
+    readonly cadence: FireCadence;
+    /** The magazine, or `null` when the weapon has no ammo model. */
+    readonly magazine: Magazine | null;
+}
+/**
+ * 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 declare function createWeaponRuntime<TAim, THit>(config: WeaponRuntimeConfig<TAim, THit>): WeaponRuntime<TAim, THit>;

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,7 +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,7 +28,10 @@ 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";
 export { createStats } from "./stats/statModifiers.js";
+export { applyStatPoolDelta, changeStatPool, createStatPool, patchStatPool, } from "./stats/statPool.js";

package/dist/devtools/controls.d.ts

@@ -0,0 +1,38 @@
+import type { ChangeSignal } from "../store/changeSignal.js";
+import { type AngleUnit, type DevtoolsControlKind, type ResolvedAxisBounds, type TunableChoice, type TunableOptions } from "./tunableSchema.js";
+import type { Devtools, Tunable } from "./types.js";
+/** Internal mutable record backing a registered control: schema metadata, current value, and change listeners. */
+export interface ControlRecord {
+    name: string;
+    kind: DevtoolsControlKind;
+    label: string;
+    group: string;
+    initial: unknown;
+    value: unknown;
+    min?: number;
+    max?: number;
+    step?: number;
+    options?: readonly unknown[];
+    choices?: readonly TunableChoice[];
+    unit?: AngleUnit;
+    displayUnit?: AngleUnit;
+    wrap?: boolean;
+    integer?: boolean;
+    axisBounds?: ResolvedAxisBounds;
+    hasAlpha?: boolean;
+    schemaVersion: number;
+    listeners: Set<(value: unknown) => void>;
+}
+/** @internal */
+export declare function isStructuralKind(kind: DevtoolsControlKind): boolean;
+/** Controls subsystem: the public controls facade plus internal register/write helpers and the record map. */
+export interface ControlsModule {
+    controls: Devtools["controls"];
+    register: <T>(name: string, initial: T, options?: TunableOptions<T>) => Tunable<T>;
+    writeControl: (record: ControlRecord, raw: unknown) => boolean;
+    controlRecords: Map<string, ControlRecord>;
+}
+/** Create the controls subsystem that registers, validates, and mutates tunable controls, notifying on change. */
+export declare const createControlsModule: (deps: {
+    signal: ChangeSignal;
+}) => ControlsModule;