@jgengine/core 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -12,6 +12,58 @@ Agents building on the published SDK can also read this programmatically:
 same data as typed values, so an updater can diff its installed version against
 the latest and surface the migration steps.
 
+## 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
+
+### Migrate
+
+- **Author games through `defineGame` from `@jgengine/shell`** — it is the single public authoring entry (and carries the define-game capability tag). Core's constructor was renamed `defineGame` → `defineGameDefinition` (`@jgengine/core/game/defineGame`); only hosts and tooling call it. If you imported `defineGame` from core, switch the import to `@jgengine/shell`. `GamePlayer`/`GamePlayerShell` are `@internal` now — `GameHost` is the documented mount, and it owns the editor summon (`?mode=editor`, F2+E, dev save endpoint), so delete any per-game editor bootstrap.
+- **Declare your world with `world()`** (`@jgengine/core/world/place`): `world({ id, ground: { mode, size, surface? }, physics? })` with `flat` / `round` / `voxel` / `board` ground. New scaffolds emit a thin infinite flat place instead of the old 96 m meadow. `environment()` still works but is demoted to the legacy consumption path for editor-written scene data — **nothing required** for existing games; new worlds should use `world()` and author all dressing in the editor.
+- Everything else is additive — stat pools, minimap marker sources, auction house, city/path generation, editor workspaces require no changes to existing games.
+
+### Added
+
+- **World = place: `world()` API** (#1178) — a world is substrate + laws, not a coded diorama. `@jgengine/core/world/place` ships `world({ id, ground: { mode, size, surface?, generator? }, physics? })`; size is discriminated by mode (flat `{x,z}` with `Infinity` axes, round `{radius}`, voxel generator domain, board `{x,y}` cells — TS and runtime both reject mismatches). `ground.surface` carries matter/feel laws (metal vs slime vs felt) read by the same rule systems; per-place `physics` resolves over the game default; multiple worlds per game are first-class. The shell renders place substrates (`PlaceScene`) under the engine default sky; seeds derive from world id + save via `seedForPlace`.
+- **`@jgengine/shell/gameKit`** — happy-path authoring surface: authoring, mount, stores, systems, authored-scene helpers, HUD primitives, seeded rng in one import.
+- **Portable generic stat pools** — `@jgengine/core/stats/statPool`: bounded named pools (health, energy, heat, ammo…) with the entity-stats integration rebuilt on them; recipe in skill `jgengine-combat`.
+- **Auction-house economy primitives** (#1086) — `@jgengine/core/economy/auctionBook` (timed bid auctions, escrowed bids, outbid refunds, optional buyout, anti-snipe close extension, seller settlement minus house cut) plus market price history.
+- **Portable minimap marker sources** — core world seam feeding game minimaps; recipe in skill `jgengine-ui`.
+- **Unified seed-driven path network + city generation v2** (#1103, #1106) — streets/blocks/buildings with grid-ness, curviness, branching and block-size dials; zone bands, weighted building-class mixes, massing pieces, balance presets, junction-centered clustering, road-derived block polygons and parcels. Shell renders realistic roads: real intersections, curbs, lane lines, tunnels, and roads riding bridge decks.
+- **Physical fidelity** — mesh-accurate hitboxes (shots pass through holes in concave models, #1075), auto-fit entity/object colliders from measured model bounds (#1072), movement obstruction reading fitted boxes + compound-box openings (#1077).
+- **Editor overhaul** (#1110) — materials / lighting / scripting / animation-timeline / multiplayer workspaces, command palette, minimap bake wired end-to-end (#1036), real offscreen GLB thumbnails in the content browser, hierarchy drag-drop + keyboard + context menus + per-object visibility/lock, multi-select inspector, console RPC, asset drag-place, ortho projection, pivot modes, play chrome.
+- **Editor authoring pipeline** — author entity definitions and starter catalogs (#1012), author catalogs/schema fields in the Data tab (#1043), promote an authored scene folder into a runnable game (#1011), authored triggers promoted to a shared primitive with goal/win rules (#1013), asset import rewrites the game's `game/assets.ts` (#1042).
+- **Skills** — research-backed `game-design` and `level-design` skills (#962); every-game-owns-custom-UI invariant codified (#1148).
+
+### Changed
+
+- `npx jgengine create` scaffolds a thin infinite flat `world()` place; the editor `blankWorld` no longer pre-bakes seeded grass. Dressing belongs in `editor.scene.json`.
+- Environment studio visual-quality pass — turf tufts, depth-aware water, relief soil, weathered poles; grass fields no longer rebuild geometry per frame (#1090).
+
 ## 0.11.0
 
 ### Migrate

package/dist/ai/populationDirector.d.ts

@@ -0,0 +1,103 @@
+import type { NavPoint } from "../nav/navGrid.js";
+import { type RandomSeed } from "../random/rng.js";
+/** One species that ambiently populates a region: how heavily it is favoured and its alive ceiling. */
+export interface PopulationSpeciesEntry {
+    /** Opaque species/creature id the engine never interprets. */
+    species: string;
+    /** Relative pick weight among species below their cap (default 1). */
+    weight?: number;
+    /** Target/maximum number of this species alive in the region at once. */
+    cap: number;
+}
+/** Ambient population budget for a single region: its species ceilings, refill timing, and spawn geometry. */
+export interface PopulationRegionConfig {
+    /** Opaque region id the engine never interprets. */
+    region: string;
+    species: readonly PopulationSpeciesEntry[];
+    /** Seconds a freed slot waits before it becomes a spawn candidate (overrides the director default). */
+    respawnDelay?: number;
+    /** Candidate spawn locations; when present each request is tagged with one. */
+    spawnPoints?: readonly NavPoint[];
+}
+/** Full ambient-population configuration: per-region species budgets plus global refill limits and PRNG seed. */
+export interface PopulationDirectorConfig {
+    regions: readonly PopulationRegionConfig[];
+    /** Default respawn delay in game-seconds for regions without their own (default 0 — refill on the next tick). */
+    respawnDelay?: number;
+    /** Upper bound on spawn requests emitted per {@link PopulationDirector.tick} call (default 32). */
+    maxSpawnsPerTick?: number;
+    /** Seed for the persisted, serializable PRNG cursor (default 1). */
+    seed?: number;
+}
+/** A single ambient spawn the game should realise, refilling a region toward its species caps. */
+export interface PopulationSpawnRequest {
+    region: string;
+    species: string;
+    /** Chosen spawn location when the region declares `spawnPoints`. */
+    point?: NavPoint;
+}
+/** Per-call spawn-point selection hook, letting a game apply bias (distance from players, etc.) at tick time. */
+export interface PopulationTickContext {
+    /**
+     * Choose a spawn point for a request. Receives the region id, its configured candidates, and a
+     * deterministic roll in `[0, 1)` drawn from the persisted cursor. Return `null` to leave the
+     * request unplaced. When omitted, a candidate is picked uniformly from the roll.
+     */
+    pickSpawnPoint?(region: string, candidates: readonly NavPoint[], roll: number): NavPoint | null;
+}
+/** Live census of alive counts keyed `region -> species -> count`, used to reconcile the director to reality. */
+export type PopulationCensus = Record<string, Record<string, number>>;
+/**
+ * A queued refill slot awaiting its {@link PopulationDirectorState.elapsed} deadline.
+ * @internal
+ */
+export interface PopulationRespawnSlot {
+    region: string;
+    readyAt: number;
+}
+/**
+ * Opaque, JSON-serializable persistence for a {@link PopulationDirector}. Round-trip it through
+ * `snapshot`/`hydrate`; never read or mutate the fields directly.
+ */
+export interface PopulationDirectorState {
+    /** Accumulated game-seconds. */
+    elapsed: number;
+    /** Believed alive counts, `region -> species -> count`. */
+    alive: Record<string, Record<string, number>>;
+    /** Pending refill slots, each ready at its `readyAt` game-second. */
+    queue: readonly PopulationRespawnSlot[];
+    /** Opaque PRNG cursor — round-trip as part of the state, never read or set it directly. */
+    rng: RandomSeed;
+}
+/** Stateful ambient population manager for one world; drive it with `tick` and lifecycle notifications. */
+export interface PopulationDirector {
+    /**
+     * Advance by `dt` game-seconds and emit spawn requests for refill slots whose delay has elapsed,
+     * up to the per-tick cap. Only touches the bounded respawn queue — never scans the world.
+     */
+    tick(dt: number, ctx?: PopulationTickContext): PopulationSpawnRequest[];
+    /** Register that a creature left the region (killed/despawned/tamed), freeing a slot to refill after the delay. */
+    notifyRemoved(region: string, species: string, id?: string): void;
+    /** Register a creature the game introduced itself (not via a request), so caps account for it. */
+    notifySpawned(region: string, species: string, id?: string): void;
+    /** Snap believed alive counts to a live census and re-queue any deficit toward the caps. */
+    reconcile(census: PopulationCensus): void;
+    /** Believed alive count for a `(region, species)` pair. */
+    alive(region: string, species: string): number;
+    /** Serializable copy of the full director state (deep, safe to persist). */
+    snapshot(): PopulationDirectorState;
+    /** Replace the director state from a previously taken (and possibly JSON round-tripped) snapshot. */
+    hydrate(state: PopulationDirectorState): void;
+}
+/**
+ * Ambient open-world population director. Holds a target creature population per region and refills
+ * it over time, distinct from wave/horde spawning: instead of a budget draining down a wave, each
+ * region has per-species caps and a timed respawn queue. Removing a creature frees a slot; after a
+ * respawn delay `tick` emits weighted spawn requests (bounded per tick) that refill toward the caps
+ * without ever exceeding them. Species are chosen through a persisted, serializable {@link RandomSeed}
+ * cursor, so the same seed and the same lifecycle events always yield the same requests. Regions are
+ * independent, spawn points are optional, and the whole state round-trips through `snapshot`/`hydrate`.
+ *
+ * @capability population-director ambient per-region creature population manager with timed weighted respawns and caps
+ */
+export declare function createPopulationDirector(config: PopulationDirectorConfig): PopulationDirector;

package/dist/ai/populationDirector.js

@@ -0,0 +1,190 @@
+import { randomSeedFrom, stepRandomSeed } from "../random/rng.js";
+const DEFAULT_MAX_SPAWNS_PER_TICK = 32;
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+function cloneState(state) {
+    const alive = {};
+    for (const region of Object.keys(state.alive))
+        alive[region] = { ...state.alive[region] };
+    return {
+        elapsed: state.elapsed,
+        alive,
+        queue: state.queue.map((slot) => ({ region: slot.region, readyAt: slot.readyAt })),
+        rng: state.rng,
+    };
+}
+/**
+ * Ambient open-world population director. Holds a target creature population per region and refills
+ * it over time, distinct from wave/horde spawning: instead of a budget draining down a wave, each
+ * region has per-species caps and a timed respawn queue. Removing a creature frees a slot; after a
+ * respawn delay `tick` emits weighted spawn requests (bounded per tick) that refill toward the caps
+ * without ever exceeding them. Species are chosen through a persisted, serializable {@link RandomSeed}
+ * cursor, so the same seed and the same lifecycle events always yield the same requests. Regions are
+ * independent, spawn points are optional, and the whole state round-trips through `snapshot`/`hydrate`.
+ *
+ * @capability population-director ambient per-region creature population manager with timed weighted respawns and caps
+ */
+export function createPopulationDirector(config) {
+    const regions = new Map();
+    for (const region of config.regions)
+        regions.set(region.region, region);
+    const maxSpawnsPerTick = config.maxSpawnsPerTick ?? DEFAULT_MAX_SPAWNS_PER_TICK;
+    const defaultDelay = config.respawnDelay ?? 0;
+    let state = {
+        elapsed: 0,
+        alive: {},
+        queue: [],
+        rng: randomSeedFrom(config.seed ?? 1),
+    };
+    const totalCap = (region) => {
+        let sum = 0;
+        for (const entry of region.species)
+            sum += entry.cap;
+        return sum;
+    };
+    const totalAlive = (regionId) => {
+        const counts = state.alive[regionId];
+        if (counts === undefined)
+            return 0;
+        let sum = 0;
+        for (const key of Object.keys(counts))
+            sum += counts[key];
+        return sum;
+    };
+    const queuedCount = (regionId) => {
+        let sum = 0;
+        for (const slot of state.queue)
+            if (slot.region === regionId)
+                sum += 1;
+        return sum;
+    };
+    const delayFor = (region) => region.respawnDelay ?? defaultDelay;
+    const aliveFor = (regionId) => {
+        let counts = state.alive[regionId];
+        if (counts === undefined) {
+            counts = {};
+            state.alive[regionId] = counts;
+        }
+        return counts;
+    };
+    /** Top up the queue so `alive + queued` reaches the region cap, appending ready-at slots. */
+    const ensureDeficitQueued = (region, readyAt) => {
+        const deficit = totalCap(region) - totalAlive(region.region) - queuedCount(region.region);
+        if (deficit <= 0)
+            return;
+        const next = state.queue.slice();
+        for (let i = 0; i < deficit; i += 1)
+            next.push({ region: region.region, readyAt });
+        state.queue = next;
+    };
+    // Prime each region to fill toward its caps on the first ticks.
+    for (const region of config.regions) {
+        aliveFor(region.region);
+        ensureDeficitQueued(region, 0);
+    }
+    const pickSpecies = (region) => {
+        const counts = state.alive[region.region] ?? {};
+        let total = 0;
+        const eligible = [];
+        for (const entry of region.species) {
+            if ((counts[entry.species] ?? 0) >= entry.cap)
+                continue;
+            eligible.push(entry);
+            total += entry.weight ?? 1;
+        }
+        if (eligible.length === 0 || total <= 0)
+            return null;
+        const [roll, nextRng] = stepRandomSeed(state.rng);
+        state.rng = nextRng;
+        let cursor = roll * total;
+        for (const entry of eligible) {
+            cursor -= entry.weight ?? 1;
+            if (cursor <= 0)
+                return entry.species;
+        }
+        return eligible[eligible.length - 1].species;
+    };
+    const choosePoint = (region, ctx) => {
+        const points = region.spawnPoints;
+        if (points === undefined || points.length === 0)
+            return undefined;
+        const [roll, nextRng] = stepRandomSeed(state.rng);
+        state.rng = nextRng;
+        if (ctx?.pickSpawnPoint !== undefined) {
+            const chosen = ctx.pickSpawnPoint(region.region, points, roll);
+            return chosen ?? undefined;
+        }
+        return points[Math.min(points.length - 1, Math.floor(clamp01(roll) * points.length))];
+    };
+    return {
+        tick(dt, ctx) {
+            if (dt <= 0)
+                return [];
+            state.elapsed += dt;
+            const now = state.elapsed;
+            const requests = [];
+            const remaining = [];
+            for (const slot of state.queue) {
+                if (requests.length >= maxSpawnsPerTick || slot.readyAt > now) {
+                    remaining.push(slot);
+                    continue;
+                }
+                const region = regions.get(slot.region);
+                if (region === undefined)
+                    continue; // region no longer configured — drop the slot
+                const species = pickSpecies(region);
+                if (species === null)
+                    continue; // region already at cap (filled externally) — drop the slot
+                aliveFor(region.region)[species] = (state.alive[region.region][species] ?? 0) + 1;
+                const request = { region: region.region, species };
+                const point = choosePoint(region, ctx);
+                if (point !== undefined)
+                    request.point = point;
+                requests.push(request);
+            }
+            state.queue = remaining;
+            return requests;
+        },
+        notifyRemoved(region, species, _id) {
+            const counts = state.alive[region];
+            if (counts !== undefined) {
+                const current = counts[species] ?? 0;
+                if (current > 0)
+                    counts[species] = current - 1;
+            }
+            const regionConfig = regions.get(region);
+            if (regionConfig === undefined)
+                return;
+            const next = state.queue.slice();
+            next.push({ region, readyAt: state.elapsed + delayFor(regionConfig) });
+            state.queue = next;
+        },
+        notifySpawned(region, species, _id) {
+            if (!regions.has(region))
+                return;
+            const counts = aliveFor(region);
+            counts[species] = (counts[species] ?? 0) + 1;
+        },
+        reconcile(census) {
+            for (const region of config.regions) {
+                const observed = census[region.region] ?? {};
+                const counts = {};
+                for (const entry of region.species)
+                    counts[entry.species] = observed[entry.species] ?? 0;
+                state.alive[region.region] = counts;
+            }
+            for (const region of config.regions)
+                ensureDeficitQueued(region, state.elapsed);
+        },
+        alive(region, species) {
+            return state.alive[region]?.[species] ?? 0;
+        },
+        snapshot() {
+            return cloneState(state);
+        },
+        hydrate(next) {
+            state = cloneState(next);
+        },
+    };
+}

package/dist/ai/pursuit.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Composable pursuit/aggro step: the "I have a target — now chase it, stop at reach, hit it on a
+ * cooldown, and break off if led too far from home" loop that melee mobs, RTS units, and stationary
+ * turrets all re-implement by hand. This owns exactly that state machine and the per-entity attack
+ * cooldown; target *selection* stays separate (see {@link ./targetAcquisition}), and every side
+ * effect — move, attack, break off — is performed by the caller in response to the returned action.
+ *
+ * Deterministic and allocation-free: distances are measured by the caller and passed in as scalars,
+ * the only state is one serializable number ({@link PursuitState.attackCooldown}) advanced in place,
+ * and the returned {@link PursuitAction} is a string literal. No object is built per entity per step,
+ * and nothing here scans the world — feed it a target you already resolved.
+ */
+/** The action a pursuit step resolves to; the caller performs the matching side effect. */
+export type PursuitAction = 
+/** Home distance exceeded the leash — abandon the target and return home. */
+"leash"
+/** Out of range — advance toward the target. */
+ | "pursue"
+/** In range and the cooldown is ready — perform the attack, then {@link armPursuit}. */
+ | "attack"
+/** In range but the cooldown has not elapsed — hold (face the target, idle, etc.). */
+ | "wait"
+/** No engageable target this step (distance was `null`). */
+ | "idle";
+/**
+ * When the attack cooldown ticks down.
+ * - `"always"` (default): every step, like a wall-clock weapon timer that keeps counting during the
+ *   chase, so the entity can swing the instant it reaches its target.
+ * - `"inRange"`: only while within `stopDistance`, so the timer freezes during the chase and the
+ *   full interval is paid out after each contact.
+ */
+export type CooldownMode = "always" | "inRange";
+/** Per-entity cooldown state owned by the primitive. One serializable number; no methods. */
+export interface PursuitState {
+    /** Seconds remaining until the next attack may fire. Advanced toward `0` by {@link advancePursuit}. */
+    attackCooldown: number;
+}
+/** A fresh pursuit state, ready to attack immediately (`attackCooldown` at `0`). */
+export declare function createPursuitState(attackCooldown?: number): PursuitState;
+/** Set the cooldown after an attack fires (clamped at `0`). Call on the step that returned `"attack"`. */
+export declare function armPursuit(state: PursuitState, intervalSeconds: number): void;
+/**
+ * Advance one pursuit step for a single entity, mutating `state.attackCooldown`, and return the
+ * action the caller should perform. All spatial input is scalar and measured this frame:
+ *
+ * - `targetDistance` — self→target distance, or `null` when there is no engageable target (`"idle"`).
+ * - `stopDistance`   — attack once within this distance; pursue while beyond it.
+ * - `homeDistance` / `leashRange` — optional leash checked first: when `homeDistance > leashRange`
+ *   the step is `"leash"`. Leave at their defaults (`-Infinity` / `+Infinity`) to disable leashing.
+ * - `cooldownMode`   — see {@link CooldownMode}.
+ *
+ * On `"attack"` the caller applies the hit and calls {@link armPursuit} with the next interval.
+ *
+ * @capability pursuit chase-to-reach cooldown-gated attack with optional leash-to-home; owns the attack cooldown
+ */
+export declare function advancePursuit(state: PursuitState, dt: number, targetDistance: number | null, stopDistance: number, cooldownMode?: CooldownMode, homeDistance?: number, leashRange?: number): PursuitAction;

package/dist/ai/pursuit.js

@@ -0,0 +1,53 @@
+/**
+ * Composable pursuit/aggro step: the "I have a target — now chase it, stop at reach, hit it on a
+ * cooldown, and break off if led too far from home" loop that melee mobs, RTS units, and stationary
+ * turrets all re-implement by hand. This owns exactly that state machine and the per-entity attack
+ * cooldown; target *selection* stays separate (see {@link ./targetAcquisition}), and every side
+ * effect — move, attack, break off — is performed by the caller in response to the returned action.
+ *
+ * Deterministic and allocation-free: distances are measured by the caller and passed in as scalars,
+ * the only state is one serializable number ({@link PursuitState.attackCooldown}) advanced in place,
+ * and the returned {@link PursuitAction} is a string literal. No object is built per entity per step,
+ * and nothing here scans the world — feed it a target you already resolved.
+ */
+/** A fresh pursuit state, ready to attack immediately (`attackCooldown` at `0`). */
+export function createPursuitState(attackCooldown = 0) {
+    return { attackCooldown };
+}
+/** Set the cooldown after an attack fires (clamped at `0`). Call on the step that returned `"attack"`. */
+export function armPursuit(state, intervalSeconds) {
+    state.attackCooldown = intervalSeconds > 0 ? intervalSeconds : 0;
+}
+function tickCooldown(state, dt) {
+    if (state.attackCooldown > 0) {
+        const next = state.attackCooldown - dt;
+        state.attackCooldown = next > 0 ? next : 0;
+    }
+}
+/**
+ * Advance one pursuit step for a single entity, mutating `state.attackCooldown`, and return the
+ * action the caller should perform. All spatial input is scalar and measured this frame:
+ *
+ * - `targetDistance` — self→target distance, or `null` when there is no engageable target (`"idle"`).
+ * - `stopDistance`   — attack once within this distance; pursue while beyond it.
+ * - `homeDistance` / `leashRange` — optional leash checked first: when `homeDistance > leashRange`
+ *   the step is `"leash"`. Leave at their defaults (`-Infinity` / `+Infinity`) to disable leashing.
+ * - `cooldownMode`   — see {@link CooldownMode}.
+ *
+ * On `"attack"` the caller applies the hit and calls {@link armPursuit} with the next interval.
+ *
+ * @capability pursuit chase-to-reach cooldown-gated attack with optional leash-to-home; owns the attack cooldown
+ */
+export function advancePursuit(state, dt, targetDistance, stopDistance, cooldownMode = "always", homeDistance = Number.NEGATIVE_INFINITY, leashRange = Number.POSITIVE_INFINITY) {
+    if (cooldownMode === "always")
+        tickCooldown(state, dt);
+    if (homeDistance > leashRange)
+        return "leash";
+    if (targetDistance === null)
+        return "idle";
+    if (targetDistance > stopDistance)
+        return "pursue";
+    if (cooldownMode === "inRange")
+        tickCooldown(state, dt);
+    return state.attackCooldown <= 0 ? "attack" : "wait";
+}

package/dist/authoring.d.ts

@@ -5,7 +5,7 @@
  * advanced composition, but this module intentionally exposes common authored
  * concepts without requiring callers to understand the repository layout.
  */
-export { defineGame, type GameDefinition, type GameDefinitionConfig, type GameLoop, type InventoryDeclaration, type PhysicsConfig, type GameServerConfig, } from "./game/defineGame.js";
+export { type GameDefinition, type GameDefinitionConfig, type GameLoop, type InventoryDeclaration, type PhysicsConfig, type GameServerConfig, } from "./game/defineGame.js";
 export { lootTable, type LootTableDef, type LootEntry, type Drop, } from "./game/lootTable.js";
 export { biomes, voxel, plots, tilemap, flat, environment, terrain, rain, snow, grass, ocean, building, road, type WorldFeature, } from "./world/features.js";
 export { seededRng, seededStreams } from "./random/rng.js";

package/dist/authoring.js

@@ -5,7 +5,7 @@
  * advanced composition, but this module intentionally exposes common authored
  * concepts without requiring callers to understand the repository layout.
  */
-export { defineGame, } from "./game/defineGame.js";
+export {} from "./game/defineGame.js";
 export { lootTable, } from "./game/lootTable.js";
 export { biomes, voxel, plots, tilemap, flat, environment, terrain, rain, snow, grass, ocean, building, road, } from "./world/features.js";
 export { seededRng, seededStreams } from "./random/rng.js";

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.