@jgengine/core 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -10,7 +10,79 @@ let consumers pick up the better stuff, not just to list what moved.
 Agents building on the published SDK can also read this programmatically:
 `import { VERSION, CHANGELOG } from "@jgengine/core/meta/changelog"` gives the
 same data as typed values, so an updater can diff its installed version against
-the latest and surface the migration steps.
+the latest and surface the migration steps. Easier still: `npx jgengine upgrade`
+run inside a game project diffs the installed `@jgengine/*` versions against the
+latest release and prints every Migrate step and Adopt-worthy addition in
+between (`--json` for structured output).
+
+## [Unreleased]
+
+<!--
+Every PR that changes `packages/*/src` records its consumer-facing change here, so
+the next release's notes are complete by construction. Add a bullet under the right
+subhead below. `bun run check-changelog` fails a source PR whose `[Unreleased]` block
+is untouched; pure refactors/tests bypass with `[skip changelog]` in a commit message.
+At publish, rename this heading to the new version and mirror the entries into
+`packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
+-->
+
+### Migrate
+
+- _Nothing yet._
+
+### Added
+
+### Changed
+
+### Removed
+
+## 0.14.0
+
+### Migrate
+
+- **Nothing required** — this release is additive drop-in primitives, editor authoring, CLI discovery, and fixes. Bump `@jgengine/*` pins to `^0.14.0` (CLI `jgengine` is 0.11.0; `@jgengine/github` unchanged at 0.1.0) and rebuild.
+- One behavior fix to know about: in a `rig: "chase"` game, on-foot movement and aim are now camera-relative (the chase rig reports its yaw to the shell like every other rig). If a game somehow relied on world-yaw-0 movement under a chase camera, that was the bug this fixes.
+
+### Added
+
+- One authoring gesture for scatterable coverage: `@jgengine/core/world/scatterCoverage` owns shared density/budget semantics (per-kind unit, requested→count→capped, one clamp-and-warn phrasing) for `grass_field`/`scatter`/`city`; the editor inspector leads each kind with the same Area → Assets → Density coverage section, scatter truncates to the shared 250k instance budget, and city single-sources its 2,600-lot cap.
+- **Created games ship a drive/playtest script** (#1248) — `npx jgengine create` scaffolds now include `scripts/drive.mjs` (`bun run drive`): dependency-free headless play/testing of the running game — ordered `--click`/`--key`/`--wait`/`--shot`/`--rpc` steps against the agent bridge, plus `--playtest --strict` progress/softlock verdicts off `capture.probe`. Shared Chrome/CDP machinery lives in `scripts/browser.mjs`; `scripts/shoot.mjs` is unchanged in behavior, now a thin CLI over it.
+- Editor: viewport clip preview for rigged assets (Animation dock "Clips" mode — pick a rig or placed instance, play/scrub/loop/speed any catalog clip) and an Inspector "Animation" section that authors a placement's `ModelConfig.animation` (role→clip dropdowns, auto/none, walk/run/fade, one-shot event bindings) as undoable `marker.meta.animation` edits. New subpaths: `@jgengine/editor/shell/clipPreview`, `@jgengine/editor/modelAnimationAuthoring`, `@jgengine/editor/ClipPreviewLayer`.
+- **`npx jgengine find <intent>`** — active capability discovery: searches every shipped domain's `capabilities.md` (staged inside the CLI tarball, so it works regardless of which `@jgengine/*` packages a project installed) and prints the drop-in primitive + its import for an intent like `"toggleable window"`, `inventory`, or `minimap`. Scaffolded games are now briefed (in `AGENTS.md` and the `jgengine` intake skill) to reach for it before hand-rolling a HUD/inventory/window/rig.
+- **`EntityPreview`** (`@jgengine/shell/render/EntityPreview`) — drop-in live 3D entity portrait for character screens, unit inspectors, and loadout viewers. Owns the nested `<Canvas>`, the `GameContextBridge`, and a `StudioStage` lighting rig with optional turntable / face-camera; the game passes its own `renderEntity` as children (or a native `model` + `instanceId`) and, bound to a live entity, the portrait walks/flinches/topples in sync with the world.
+- **`GameContextBridge`** (`@jgengine/react`) — re-provide the running `GameContext` across a nested React reconciler boundary (the R3F `<Canvas>`), so a game building its own preview canvas no longer re-derives the bridge by hand.
+
+### Changed
+
+- **Chase rig reports its yaw to the shell** — `ChaseRig` now writes the camera yaw back to the shared yaw ref like every other player-facing rig, so on-foot movement and aim in a `rig: "chase"` game are camera-relative instead of frozen to world yaw 0 (WASD no longer fights the camera the moment it swings behind the player). Interior views (cockpit/hood/rear) report the vehicle heading.
+- **Combat VFX no longer render as black squares under AO/DOF post-processing** (#1247) — GTAO/Bokeh scene prepasses skip overlay effects. Games with custom additive overlay effects opt out the same way: spread `POSTFX_OVERLAY_USERDATA` (`@jgengine/shell/postfx/postfxOverlay`) onto the overlay group's `userData`.
+- **`PanelHost` windows stack above the HUD by default** (`@jgengine/react`) — the host establishes its own stacking context at `zIndexBase` (default 40), so open windows always paint over stat bars / nameplates / frames instead of bleeding through. Overridable per instance.
+
+## 0.13.0
+
+### Migrate
+
+- **Nothing required** — this release is additive fixes, defaults, and new drop-in primitives. Bump `@jgengine/*` pins to `^0.13.0` (CLI `jgengine` is 0.10.0; `@jgengine/github` unchanged at 0.1.0) and rebuild.
+- Two defaults changed in the player's favor, both overridable: **offline games now persist to localStorage automatically** (#1207) and **rigged catalog assets animate by default** via clip metadata + semantic clip roles (#1209). If a game relied on rigged models staying frozen or on saves being memory-only, opt out explicitly; otherwise you get better behavior for free.
+
+### Added
+
+- **Drop-in inventory grid, window manager, and character sheet** (#1220) — `@jgengine/react` ships `InventoryGrid` (real drag/stack/split), a toggleable-window system (`panels`: bag, character sheet, spellbook-style windows with `@jgengine/core/ui/panelModel` state), and a `CharacterSheet` paperdoll, all HudTheme-skinnable — wire in a line or two instead of re-deriving from raw divs.
+- **Serializable runtime snapshots** (#1179) — capture/restore of live runtime state, including magazine state (`@jgengine/core/combat/magazine`) and stat modifiers, for saves and replication.
+- **Portable weapon plumbing** (#1211) — `@jgengine/core/combat/weaponFire` composes trigger → magazine → spread → projectile/hitscan as data, no game-local glue.
+- **Portable leveling** (#1206) and **portable damage-pool access** (#1208) — progression and damage pools exposed as genre-agnostic seams on the game context.
+- **Named combat VFX presets** (#1204) — `@jgengine/core/combat/vfxPresets`: a visible attack is one line.
+- **Runtime-measured render-bounds hitboxes** (#1227) — colliders wrap what the shell actually mounts, not the raw asset bounds.
+- **Character motion feel** — procedural part motion for rig-less part-composed characters (#1222) plus squash & stretch and death splat (#1229).
+- **City fabric** (#1191) — `streetGenerator` + `cityGenerator`, editor bake verb, street-aware lots, road junctions, grounding, and a web playground.
+- **`jgengine recipe` CLI** (#1214, #1231) — vetted wired compositions, compile-pinned against the SDK, listed and copied from the CLI.
+- **Editor/debug modes mirror to the URL** with a proper editor exit (#1203); game template ships a dependency-free WebGL screenshot script (#1202).
+
+### Changed
+
+- Offline games persist to localStorage by default (#1207); rigged assets animate by default (#1209).
+- RTS camera pan inversion fixed (#1228); sprite raycast warning silenced and duplicate nameplate health bars removed (#1194); scaffolded F2+E editor Tailwind `@source` renders its theme (#1195).
+- Outside-game DX: stat-pool no-op stability, camera-transparent decor, cleaner install/version output, headless UI-intent seam (#1223); new-game briefs direct engine bugs/gaps upstream (#1200).
 
 ## 0.12.0
 

package/dist/combat/effects.d.ts

@@ -1,5 +1,5 @@
 import type { EntityPosition } from "../scene/entityStore.js";
-import { type StatValueMap } from "../scene/entityStats.js";
+import { type StatPool, type StatPoolAccess } from "../stats/statPool.js";
 export interface ReceiveRule {
     order: string[];
     modifiers?: Record<string, number>;
@@ -58,7 +58,13 @@ export interface AreaTarget {
 export declare function resolveAreaTargets(spatial: CombatSpatialDeps, input: AreaTargetInput, accept?: (instanceId: string) => boolean): AreaTarget[];
 export interface EffectSystemDeps {
     resolveReceive(instanceId: string): ReceiveMap | null | undefined;
-    resolveStats(instanceId: string): StatValueMap | undefined;
+    /** Preferred portable bridge to caller-owned resource state. */
+    statPools?: StatPoolAccess;
+    /**
+     * Legacy native bridge retained for source compatibility. New integrations
+     * should provide {@link statPools} and keep their own state model.
+     */
+    resolveStats?(instanceId: string): Record<string, StatPool> | undefined;
     getStat(itemId: string, stat: string): number | null;
     spatial: CombatSpatialDeps;
     drainStatByEffect?: Record<string, string>;
@@ -70,8 +76,9 @@ export interface EffectSystem {
     applyEffect(input: EffectInput): EffectResult[];
 }
 /**
- * Apply, stack, and tick timed status effects — buffs, debuffs, DoTs — on entities.
+ * Resolve direct or area resource effects through caller-owned stat pools,
+ * including ordered absorption, restoration, modifiers, and lethal context.
  *
- * @capability status-effects apply and tick timed status effects and buffs on entities
+ * @capability status-effects commit direct or area effects through caller-owned stat pools with ordered spillover and lethal results
  */
 export declare function createEffectSystem(deps: EffectSystemDeps): EffectSystem;

package/dist/combat/effects.js

@@ -1,5 +1,5 @@
-import { applyPoolDelta } from "../scene/entityStats.js";
 import { distanceBetween } from "../scene/spatial.js";
+import { applyStatPoolDelta } from "../stats/statPool.js";
 export function resolveAreaTargets(spatial, input, accept) {
     const falloff = input.falloff ?? "none";
     const los = input.los ?? true;
@@ -22,11 +22,24 @@ export function resolveAreaTargets(spatial, input, accept) {
 }
 const DEFAULT_DRAIN_STAT = "damage";
 /**
- * Apply, stack, and tick timed status effects — buffs, debuffs, DoTs — on entities.
+ * Resolve direct or area resource effects through caller-owned stat pools,
+ * including ordered absorption, restoration, modifiers, and lethal context.
  *
- * @capability status-effects apply and tick timed status effects and buffs on entities
+ * @capability status-effects commit direct or area effects through caller-owned stat pools with ordered spillover and lethal results
  */
 export function createEffectSystem(deps) {
+    const statPools = deps.statPools ?? {
+        get(instanceId, statId) {
+            return deps.resolveStats?.(instanceId)?.[statId] ?? null;
+        },
+        set(instanceId, statId, next) {
+            const stats = deps.resolveStats?.(instanceId);
+            if (stats === undefined)
+                return false;
+            stats[statId] = next;
+            return true;
+        },
+    };
     function resolveRule(instanceId, effect) {
         return deps.resolveReceive(instanceId)?.[effect] ?? null;
     }
@@ -49,13 +62,12 @@ export function createEffectSystem(deps) {
         const rule = resolveRule(instanceId, effect);
         if (rule === null)
             return "not-receivable";
-        const stats = deps.resolveStats(instanceId);
-        if (stats === undefined)
+        if (deps.statPools === undefined && deps.resolveStats?.(instanceId) === undefined)
             return "unknown-instance";
         const restorative = magnitude !== undefined && magnitude < 0;
         const anyPoolHasHeadroom = rule.order.some((statId) => {
-            const stat = stats[statId];
-            if (stat === undefined)
+            const stat = statPools.get(instanceId, statId);
+            if (stat === null)
                 return false;
             return restorative ? stat.current < stat.max : stat.current > stat.min;
         });
@@ -63,7 +75,7 @@ export function createEffectSystem(deps) {
             return "pools-depleted";
         return null;
     }
-    function drainPools(instanceId, effect, rule, stats, drainMagnitude) {
+    function drainPools(instanceId, effect, rule, drainMagnitude) {
         const applied = [];
         const lastStatId = rule.order[rule.order.length - 1];
         let remaining = drainMagnitude;
@@ -71,14 +83,10 @@ export function createEffectSystem(deps) {
         for (const statId of rule.order) {
             if (remaining === 0)
                 break;
-            const before = stats[statId];
-            if (before === undefined)
-                continue;
-            const result = applyPoolDelta(stats, statId, -remaining);
+            const result = applyStatPoolDelta(statPools, instanceId, statId, -remaining);
             if (result.status === "rejected")
                 continue;
-            stats[statId] = result.stat;
-            const delta = result.stat.current - before.current;
+            const delta = result.applied;
             if (delta !== 0)
                 applied.push({ statId, delta });
             remaining += delta;
@@ -89,13 +97,12 @@ export function createEffectSystem(deps) {
     }
     function applyTo(instanceId, effect, via, from, scale) {
         const rule = resolveRule(instanceId, effect);
-        const stats = deps.resolveStats(instanceId);
-        if (rule === null || stats === undefined)
+        if (rule === null)
             return null;
         const drainMagnitude = modifiedDrainMagnitude(baseDrainMagnitude(effect, via) * scale, rule);
         if (canReceive(instanceId, effect, drainMagnitude) !== null)
             return null;
-        const result = drainPools(instanceId, effect, rule, stats, drainMagnitude);
+        const result = drainPools(instanceId, effect, rule, drainMagnitude);
         if (result.lethal)
             deps.onLethal?.(instanceId, { from, via, effect });
         return result;

package/dist/combat/magazine.d.ts

@@ -17,6 +17,12 @@ export interface MagazineConfig {
      */
     reserve?: number | MagazineReserve;
 }
+/** Complete serializable state for a {@link Magazine}; `reserve: null` means infinite reserve. */
+export interface MagazineSnapshot {
+    loaded: number;
+    reloadElapsedMs: number | null;
+    reserve: number | null;
+}
 /**
  * A per-weapon magazine: discrete loaded rounds, a timed reload that refills from a reserve pool,
  * and the reserve-pool interaction itself — the primitive that replaces hand-rolling mag size,
@@ -45,6 +51,13 @@ export interface Magazine {
     addReserve(amount: number): void;
     /** Advance the reload timer; completes the reload once `reloadMs` has elapsed. */
     tick(dtSeconds: number): void;
+    /** Return detached plain data for save, rollback, replay, or worker transfer. */
+    snapshot(): MagazineSnapshot;
+    /**
+     * Restore decoded snapshot data. Returns false without changing loaded/reload
+     * state when reserve kinds differ or an external reserve cannot reconcile.
+     */
+    restore(snapshot: MagazineSnapshot): boolean;
 }
 /**
  * Builds a {@link Magazine}: discrete loaded ammo, a timed reload, and reserve-pool interaction.

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>;