@jgengine/core 0.11.0 → 0.12.0

package/skills/jgengine/recipes/minimal-game.md

@@ -0,0 +1,88 @@
+# Recipe — minimal game (scaffold → authored scene → win)
+
+**What this wires:** the default end-to-end path from nothing to a complete, genre-free
+walk/interact/win game: a scaffold, one `defineGame` config off the happy-path kit, an
+authored scene edited in the browser, one system, one store slot, an empty-canvas HUD,
+and a win condition. Every new game starts here; add combat, multiplayer, or deeper
+world features only after this loop plays.
+
+## 1. Scaffold
+
+`npx jgengine create <name>` (inside the engine monorepo: `bun run new:game "<id-or-title>"`).
+The file set is thin and already runs:
+
+- `src/main.tsx` — mounts `GameHost` with `editor={() => import("@jgengine/editor")}`; the
+  host owns the F2+E / `?mode=editor` editor summon and the dev save endpoint.
+- `src/game.config.ts` — the whole game definition (below).
+- `src/editor.scene.json` + `src/editorLayers.ts` — the authored scene document, normalized
+  with `normalizeEditorLayers`. All placement lives here, never as coordinates in code.
+- `src/loop.ts` and `src/game/ui/GameUI.tsx` — systems and HUD.
+
+## 2. Define the game — one import surface
+
+```ts
+// game.config.ts — everything below comes from the kit; deeper paths are for outgrowing it.
+import { defineGame } from "@jgengine/shell/gameKit";
+
+import { editorLayers } from "./editorLayers";
+import { GameUI } from "./game/ui/GameUI";
+import { onNewPlayer, systems } from "./loop";
+
+export const game = defineGame({
+  name: "my-game",
+  // Binding movement actions makes the shell drive the walk controller — the game walks day one.
+  input: { moveForward: ["KeyW"], moveBack: ["KeyS"], moveLeft: ["KeyA"], moveRight: ["KeyD"], interact: ["KeyE"] },
+  systems,
+  loop: { onNewPlayer },
+  GameUI,
+  editorLayers, // the authored scene auto-mounts; the player spawns at its player_spawn marker
+});
+// Solo game: omit `multiplayer` entirely — offline is the shell default.
+```
+
+**World is optional and thin.** Omitting `world` is valid — a pure UI/rules game is not a
+spatial place. When the game *is* a place, declare only substrate + laws with `world()` from
+`@jgengine/core/world/place` (e.g. `{ id, ground: { mode: "flat", size: { x: Infinity, z: Infinity } }, physics: { gravity: -24 } }`,
+or `mode: "board"` for 2D). Never seed, sky, or vegetation in `world` — the engine renders its
+default sky until you author one in the editor, and foliage is editor scatter over the ground.
+
+
+```ts
+// loop.ts — one store slot for run state, one system for the rules tick.
+import { defineStore, defineSystem, authoredSpawnPosition, type GameContext } from "@jgengine/shell/gameKit";
+
+import { editorLayers } from "./editorLayers";
+
+export const run = defineStore("run", { collected: 0, won: false });
+
+export const systems = [
+  defineSystem({
+    id: "rules",
+    tick: { type: "fixed" },
+    update(ctx: GameContext) {
+      // System-check win alternative: read/update `run` here (e.g. win at collected >= 3).
+      if (run.read(ctx).collected >= 3) run.update(ctx, (s) => ({ ...s, won: true }));
+    },
+  }),
+];
+
+export function onNewPlayer(ctx: GameContext): void {
+  ctx.scene.entity.spawn("player", { id: ctx.player.userId, position: authoredSpawnPosition(editorLayers) ?? [0, 0, 0] });
+}
+```
+
+`GameUI` starts as an empty `HudCanvas` (`useHudLayout` + `HudCanvas` from the kit). That is
+intentional: **every game owns its UI**. Write a short UI art direction, then build custom
+panels for this pitch — do not ship stock drop-in widgets (`StatBar`, `Hotbar`, `Coins`, glass
+frames) as the product face. Reach for engine pieces only as headless data, layout, or
+interaction models under game-owned chrome (see `jgengine-ui`).
+
+## 3. Author, play, win
+
+1. `bun dev`, then F2+E opens the editor on `editor.scene.json` — move the spawn, place
+   props and trigger markers, Ctrl+S saves back to the document.
+2. The starter scene ships a goal marker with `{ on: "enter", action: "win" }` — walking
+   into it wins with zero game code. Author more rules the same way (triggers in the
+   editor), or read volumes yourself via the kit's `collectAuthoredTriggers(editorLayers)`.
+3. Prove it: `bun test` asserts the document (spawn, goal), and `jgengine-verify` covers
+   screenshot and gameplay evidence before any "it works" claim.

package/skills/jgengine-combat/SKILL.md

@@ -11,6 +11,11 @@ This skill owns combat resolution: target policy, combat stats, teams/factions a
 
 Search [capabilities.md](capabilities.md), then use [api.md](api.md) for signatures and [reference.md](reference.md) for complete pipelines.
 
+Existing projects keep their resource state and follow the
+[portable stat-pool recipe](recipes/portable-stat-pools.md). Adapt the caller's
+store through `StatPoolAccess`; do not require `StatValueMap`, `GameContext`, or
+a parallel entity store.
+
 ## Canonical pipeline
 
 1. Acquire eligible candidates from a bounded spatial source.
@@ -31,4 +36,3 @@ Compose stages through registration/policy seams; adding a damage type, effect,
 - Reward generation and allocation are different operations, especially in multiplayer.
 - Compose multiple loot pools with `createLootPipeline` (ordered stages, gates, fallbacks, roll modifiers, per-drop provenance) over `lootTable`; keep genre concepts (world/dedicated/boss/luck/pity) in game-space stages and modifiers, never in core.
 - UI bars, reticles, and feedback route to `jgengine-ui`.
-

package/skills/jgengine-combat/api.md

@@ -88,6 +88,12 @@
 - `ShotOriginPolicy` (type): type ShotOriginPolicy = | { kind: "converge"; muzzle?: EntityPosition; height?: number } | { kind: "eye"; height?: number } | { kind: "legacy" } | { kind: "entity" } | { kind: "entityOffset"; offset: EntityPosition } | { kind: "muzzle"; offset?: EntityPosition } | { kind: "camera"; origin: EntityPos… — How a shot's world-space origin (and optional direction) is resolved before prediction/settlement. - `converge` — the shot leaves the gun `muzzle` yet still passes through whatever the shooter's sightline (crosshair) covers: origin is the muzzle offset, direction is bent from the muzzle to the eye ray's aim point. The projectile system's default for a free `{ yaw, pitch }` aim, so a bullet visibly comes from the barrel without missing the reticle. Needs a scene raycast to find the aim point (`convergeShot`); a bare `resolveShot` degrades to a straight muzzle ray. Passes an explicit `{ origin, direction }` aim through untouched. - `eye` — `aim.origin` when present, else the shooter's entity position raised to eye height; the shot traces the shooter's sightline, so what the crosshair covers is what gets hit. - `legacy` — `aim.origin` when present, else the shooter's raw entity position (feet). - `entity` — always the shooter's entity position. - `entityOffset` / `muzzle` — entity-local offset rotated by the shooter's yaw (muzzle on a weapon model). - `camera` — explicit camera/reticle world origin (and optional direction override). - `world` — absolute world origin.
 - `SpawnProvider` (type): type SpawnProvider = ( params: Readonly<Record<string, unknown>>, ctx: SpawnProviderContext, ) => readonly EncounterSpawnRequest[] — A spawn provider: given the phase's `params` and context, returns the spawn requests to emit on enter. Deterministic; reads authored scene points from `ctx.spawnPoints` rather than embedding coordinates.
 - `SpawnProviderContext` (interface): interface SpawnProviderContext — Evaluation context a spawn provider receives when its phase is entered.
+- `StatPool` (interface): interface StatPool — Serializable state for any bounded named resource. The caller defines what the resource means.
+- `StatPoolAccess` (interface): interface StatPoolAccess<TOwnerId extends string = string, TStatId extends string = string> — Structural bridge to caller-owned resource state. Implement it over an ECS, Redux/Zustand store, plain object, database-backed model, or JGengine's native entity stats without moving ownership into the SDK.
+- `StatPoolAccessResult` (type): type StatPoolAccessResult = | ({ status: "ok" } & StatPoolChange) | { status: "rejected"; reason: string } — Outcome of changing a pool through {@link StatPoolAccess}.
+- `StatPoolChange` (interface): interface StatPoolChange — Inspectable result of a bounded pool change.
+- `StatPoolInput` (interface): interface StatPoolInput — Input used to create a normalized pool. `current` defaults to `max`; `min` defaults to zero.
+- `StatPoolPatch` (interface): interface StatPoolPatch — Partial update applied without mutating the previous pool.
 - `Stats` (interface): interface Stats<TStat extends string> — ⚠ undocumented
 - `StatusApplicationOutcome` (interface): interface StatusApplicationOutcome — The result of one status application: the outcome, the resulting instance (if any), and the roll.
 - `StatusApplicationSpec` (interface): interface StatusApplicationSpec — A serializable, effect-agnostic description of a status a hit tries to apply: an opaque `status` id the game routes to its own effect/DoT pipeline, a base landing `chance`, and the duration/ticks/magnitude/attribution/stacking data the resolver needs. The engine never interprets `status` — it is a reference, not a built-in condition.
@@ -109,7 +115,9 @@
 - `applyRenderAnimationEvent` (function): function applyRenderAnimationEvent(cues: EntityRenderCues, event: string): EntityRenderCues — Applies a `entity.animation` event (`"fire"` / `"reload"` / `"reloadEnd"`, or any game-defined name) to the cue set. Unknown event names are a no-op.
 - `applyRenderDeathEvent` (function): function applyRenderDeathEvent(cues: EntityRenderCues): EntityRenderCues — Marks the cue set dead after `entity.died`; sticky for the lifetime of the render component.
 - `applyRenderHitEvent` (function): function applyRenderHitEvent(cues: EntityRenderCues): EntityRenderCues — Marks a `combat.hitReaction` pulse; the caller clears `hit` again after its own pulse window.
+- `applyStatPoolDelta` (function): function applyStatPoolDelta<TOwnerId extends string, TStatId extends string>(access: StatPoolAccess<TOwnerId, TStatId>, ownerId: TOwnerId, statId: TStatId, amount: number): StatPoolAccessResult — Read, transition, and write a caller-owned pool through the structural adapter. Positive amounts increase the resource; negative amounts decrease it. The adapter receives a complete replacement value, never a hidden mutation.
 - `attackMeta` (function): function attackMeta(tags: readonly AttackTag[], extra?: Omit<AttackMeta, "tags">): AttackMeta — ⚠ undocumented
+- `changeStatPool` (function): function changeStatPool(pool: StatPool, amount: number): StatPoolChange — Pure bounded delta transition with the exact applied amount and boundary flags.
 - `convergeShot` (function): function convergeShot(deps: ShotOriginDeps, from: string, aim: Aim, range: number, sightHit: (origin: EntityPosition, direction: EntityPosition) => EntityPosition | null, muzzleOffset?: EntityPosition): ResolvedShot | null — Resolves a `converge` shot with scene knowledge: fires from the gun muzzle but bends the direction so the shot passes through the aim point the shooter's eye ray covers. `sightHit` casts the eye ray and returns where it lands (first impact), or `null` to fall back to a point `range` metres down the sightline. A `{ origin, direction }` aim is passed through unchanged (nothing to converge).
 - `counters` (function): function counters(meta: AttackMeta, move: CounterMove): boolean — ⚠ undocumented
 - `createAbilityKit` (function): function createAbilityKit(configs: readonly AbilitySlotConfig[], options: AbilityKitOptions = {}): AbilityKit — A bar of cooldown-gated abilities the player fires by slot, tracking readiness and cooldown per ability.
@@ -134,6 +142,7 @@
 - `createRegenShield` (function): function createRegenShield(config: RegenShieldConfig): RegenShield — Builds a {@link RegenShield} that suppresses regen for `regenDelayMs` after each hit.
 - `createResourcePool` (function): function createResourcePool(config: ResourcePoolConfig): ResourcePool — A regenerating resource pool — mana, stamina, energy — that actions spend from and that refills over time.
 - `createStaggerMeter` (function): function createStaggerMeter(config: StaggerMeterConfig): StaggerMeter — Build a stagger/poise gauge from landed hits toward a break threshold that staggers the target.
+- `createStatPool` (function): function createStatPool(input: StatPoolInput): StatPool — Normalize caller data into a complete plain-data pool.
 - `createStats` (function): function createStats<TStat extends string>(base: Record<TStat, number>, options?: CreateStatsOptions): Stats<TStat> — A stat block whose base values take stacking, timed buffs and debuffs, resolving the modified value on read.
 - `createThresholdTracker` (function): function createThresholdTracker(config: ThresholdCrossingConfig): ThresholdTracker — Track a numeric source against named thresholds and emit ordered crossing events with direction, hysteresis, once/repeat policy, and skipped-threshold handling. Deterministic and serializable; drives phase transitions, armor breaks, resource warnings, and any other threshold consumer.
 - `encounterProgress` (function): function encounterProgress<TData>(state: EncounterState<TData>): { completed: number; total: number; done: boolean; } — Progress across the whole tree: how many phases have completed out of the total node count, plus whether the encounter has finished. Counts injected phases.
@@ -145,6 +154,7 @@
 - `isBlockable` (function): function isBlockable(meta: AttackMeta): boolean — ⚠ undocumented
 - `isDodgeable` (function): function isDodgeable(meta: AttackMeta): boolean — ⚠ undocumented
 - `isParryable` (function): function isParryable(meta: AttackMeta): boolean — ⚠ undocumented
+- `patchStatPool` (function): function patchStatPool(pool: StatPool, patch: StatPoolPatch): StatPool — Apply new bounds/current to a pool, clamping the result and leaving the input untouched.
 - `phaseStatus` (function): function phaseStatus<TData>(state: EncounterState<TData>, id: string): PhaseStatus | null — The runtime status of a phase by id (pending/active/complete), or null if the id is unknown — for driving per-phase HUD ticks and objective checklists.
 - `resistanceScale` (function): function resistanceScale<TCategory extends string = string, TProperty extends string = string>(matrix: ResistanceMatrix<TCategory, TProperty>, category: TCategory | string, targetProperties: readonly (TProperty | string)[]): number — ⚠ undocumented
 - `resolveClaim` (function): function resolveClaim(pool: ClaimablePool, claimantId: string, options?: { nowMs?: number; private?: boolean }): ClaimOutcome — Resolve an authoritative claim against a pool. Idempotent: re-claiming an already-owned pool returns the same grants without re-awarding, a losing claimant gets no grants, and eligibility, reservation, and expiry are all enforced here — the authority, not UI hiding, decides ownership. Returns the updated (serializable) pool plus the grants owed.
@@ -540,6 +550,19 @@
 - `CheckResult` (interface): interface CheckResult — ⚠ undocumented
 - `rollCheck` (function): function rollCheck(input: CheckInput, rng: () => number = Math.random): CheckResult — Resolve a tabletop-style pass/fail roll against a target number with modifiers and crit/fumble bands.
 
+## @jgengine/core/stats/spawnLevelStats
+
+- `CreatureStatInstance` (interface): interface CreatureStatInstance<TStat extends string> — A single creature's serializable stat record — a reference to its species (`speciesId`), the current `level`, the per-stat count of distributed points, and how many post-capture domestic levels have been spent. Plain data: round-trips through JSON, save/load, and multiplayer sync. Resolve display values with {@link resolveSpawnStats}.
+- `SpawnSpeciesDef` (type): type SpawnSpeciesDef<TStat extends string> = Record<TStat, SpawnStatDef> — A species' stat table: every stat the creature owns keyed to its {@link SpawnStatDef}. The key order is the deterministic order random points are distributed over, so a serialized species definition reproduces the same rolls under the same rng sequence.
+- `SpawnStatDef` (interface): interface SpawnStatDef — Per-stat growth definition for one species. `base` is the level-1 value of the stat; `growth` is how much a single distributed point adds, expressed as a fraction of `base` — so a point on a `growth: 0.1` stat is worth +10% of base. The resolved value is `base * (1 + points * growth)`.
+- `applyCaptureEffectiveness` (function): function applyCaptureEffectiveness<TStat extends string>(species: SpawnSpeciesDef<TStat>, instance: CreatureStatInstance<TStat>, effectiveness: number, rng: () => number): CaptureResult<TStat> — Apply a capture at the given effectiveness: compute bonus levels via {@link captureBonusLevels}, distribute those extra points randomly with the injected rng, and return the post-capture instance (level raised to the tamed total) alongside the granted bonus levels and tamed level. The input instance is not mutated.
+- `captureBonusLevels` (function): function captureBonusLevels(level: number, effectiveness: number): number — Bonus levels granted by a capture at the given effectiveness: `floor(level * clamp01(effectiveness) / 2)`. A perfect (1.0) capture grants half the wild level; a botched (0) capture grants none. Effectiveness outside `[0,1]` clamps.
+- `resolveSpawnStats` (function): function resolveSpawnStats<TStat extends string>(species: SpawnSpeciesDef<TStat>, instance: CreatureStatInstance<TStat>): Record<TStat, number> — Resolve an instance's live stat values from its distributed points: `value = base * (1 + points * growth)` per stat. Stats with zero points return their base.
+- `restoreSpawnInstance` (function): function restoreSpawnInstance<TStat extends string>(data: CreatureStatInstance<TStat>): CreatureStatInstance<TStat> — Rehydrate a creature stat instance from decoded data (e.g. `JSON.parse` output), returning a fresh deep copy the caller owns. Inverse of {@link snapshotSpawnInstance}.
+- `rollSpawnInstance` (function): function rollSpawnInstance<TStat extends string>(speciesId: string, species: SpawnSpeciesDef<TStat>, level: number, rng: () => number): CreatureStatInstance<TStat> — Roll a fresh wild creature at `level`: distribute `(level - 1)` points randomly across the species' stats using the injected rng and return a serializable {@link CreatureStatInstance}. Deterministic — the same rng sequence yields the same point spread. Levels below 1 clamp to 1 (no points). Use `seededRng` from `../random/rng` for a persisted, reproducible stream.
+- `snapshotSpawnInstance` (function): function snapshotSpawnInstance<TStat extends string>(instance: CreatureStatInstance<TStat>): CreatureStatInstance<TStat> — Deep-copy an instance into a detached, serializable record — the transport/save counterpart of {@link restoreSpawnInstance}. Copies the points map so later edits don't leak into the snapshot.
+- `spendDomesticLevel` (function): function spendDomesticLevel<TStat extends string>(instance: CreatureStatInstance<TStat>, stat: TStat, options?: SpendLevelOptions): SpendLevelResult<TStat> — Spend one earned post-capture level into `stat`, adding a single growth increment (one point) and raising both `level` and `domesticLevels`. When `maxDomesticLevels` is set and already reached, the spend is refused (`spent: false`) and the instance is returned untouched. Pure: returns a new instance rather than mutating the input.
+
 ## @jgengine/core/stats/statModifiers
 
 - `CreateStatsOptions` (interface): interface CreateStatsOptions — ⚠ undocumented
@@ -547,3 +570,16 @@
 - `StatModifierSet` (type): type StatModifierSet<TStat extends string> = Partial<Record<TStat, StatModifier>> — ⚠ undocumented
 - `Stats` (interface): interface Stats<TStat extends string> — ⚠ undocumented
 - `createStats` (function): function createStats<TStat extends string>(base: Record<TStat, number>, options?: CreateStatsOptions): Stats<TStat> — A stat block whose base values take stacking, timed buffs and debuffs, resolving the modified value on read.
+
+## @jgengine/core/stats/statPool
+
+- `StatPool` (interface): interface StatPool — Serializable state for any bounded named resource. The caller defines what the resource means.
+- `StatPoolAccess` (interface): interface StatPoolAccess<TOwnerId extends string = string, TStatId extends string = string> — Structural bridge to caller-owned resource state. Implement it over an ECS, Redux/Zustand store, plain object, database-backed model, or JGengine's native entity stats without moving ownership into the SDK.
+- `StatPoolAccessResult` (type): type StatPoolAccessResult = | ({ status: "ok" } & StatPoolChange) | { status: "rejected"; reason: string } — Outcome of changing a pool through {@link StatPoolAccess}.
+- `StatPoolChange` (interface): interface StatPoolChange — Inspectable result of a bounded pool change.
+- `StatPoolInput` (interface): interface StatPoolInput — Input used to create a normalized pool. `current` defaults to `max`; `min` defaults to zero.
+- `StatPoolPatch` (interface): interface StatPoolPatch — Partial update applied without mutating the previous pool.
+- `applyStatPoolDelta` (function): function applyStatPoolDelta<TOwnerId extends string, TStatId extends string>(access: StatPoolAccess<TOwnerId, TStatId>, ownerId: TOwnerId, statId: TStatId, amount: number): StatPoolAccessResult — Read, transition, and write a caller-owned pool through the structural adapter. Positive amounts increase the resource; negative amounts decrease it. The adapter receives a complete replacement value, never a hidden mutation.
+- `changeStatPool` (function): function changeStatPool(pool: StatPool, amount: number): StatPoolChange — Pure bounded delta transition with the exact applied amount and boundary flags.
+- `createStatPool` (function): function createStatPool(input: StatPoolInput): StatPool — Normalize caller data into a complete plain-data pool.
+- `patchStatPool` (function): function patchStatPool(pool: StatPool, patch: StatPoolPatch): StatPool — Apply new bounds/current to a pool, clamping the result and leaving the input untouched.

package/skills/jgengine-combat/capabilities.md

@@ -12,6 +12,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createAntiOneShotPolicy` (function) · `import { createAntiOneShotPolicy } from "@jgengine/core/combat"`
 
+## capture-bonus-levels — convert wild level and capture effectiveness into bonus levels
+
+- `captureBonusLevels` (function) · `import { captureBonusLevels } from "@jgengine/core/stats/spawnLevelStats"`
+
+## capture-effectiveness-tame — apply capture effectiveness to grant and distribute bonus levels
+
+- `applyCaptureEffectiveness` (function) · `import { applyCaptureEffectiveness } from "@jgengine/core/stats/spawnLevelStats"`
+
 ## cast-bar — run a channeled cast timer that movement or damage can interrupt
 
 - `createCastRunner` (function) · `import { createCastRunner } from "@jgengine/core/combat"`
@@ -56,6 +64,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `rollCheck` (function) · `import { rollCheck } from "@jgengine/core/combat"`
 
+## domestic-level-spend — spend an earned post-capture level into a chosen stat under a cap
+
+- `spendDomesticLevel` (function) · `import { spendDomesticLevel } from "@jgengine/core/stats/spawnLevelStats"`
+
 ## dot-field — track stacking damage-over-time effects and drain damage each frame
 
 - `createDotField` (function) · `import { createDotField } from "@jgengine/core/combat"`
@@ -125,6 +137,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createDefensiveWindow` (function) · `import { createDefensiveWindow } from "@jgengine/core/combat"`
 
+## portable-stat-pool — apply deterministic bounded resource changes through a caller-owned stat adapter
+
+- `applyStatPoolDelta` (function) · `import { applyStatPoolDelta } from "@jgengine/core/combat"`
+
 ## projectiles — spawn and advance projectiles with travel and hit resolution
 
 - `createProjectileSystem` (function) · `import { createProjectileSystem } from "@jgengine/core/combat"`
@@ -147,6 +163,22 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `filterOutcomeFor` (function) · `import { filterOutcomeFor } from "@jgengine/core/combat"`
 - `resolveClaim` (function) · `import { resolveClaim } from "@jgengine/core/combat"`
 
+## spawn-instance-restore — rehydrate a creature stat instance from decoded snapshot data
+
+- `restoreSpawnInstance` (function) · `import { restoreSpawnInstance } from "@jgengine/core/stats/spawnLevelStats"`
+
+## spawn-instance-snapshot — deep-copy a creature stat instance into a serializable record
+
+- `snapshotSpawnInstance` (function) · `import { snapshotSpawnInstance } from "@jgengine/core/stats/spawnLevelStats"`
+
+## spawn-level-roll — distribute a wild creature's spawn level into random per-stat points
+
+- `rollSpawnInstance` (function) · `import { rollSpawnInstance } from "@jgengine/core/stats/spawnLevelStats"`
+
+## spawn-stat-values — resolve a creature's per-stat values from its distributed points
+
+- `resolveSpawnStats` (function) · `import { resolveSpawnStats } from "@jgengine/core/stats/spawnLevelStats"`
+
 ## stagger-meter — accumulate an ailment buildup (bleed, freeze) until it procs
 
 - `createBuildupMeter` (function) · `import { createBuildupMeter } from "@jgengine/core/combat"`
@@ -156,6 +188,18 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createStats` (function) · `import { createStats } from "@jgengine/core/combat"`
 
+## stat-pool — create a serializable current/min/max pool for any caller-named resource
+
+- `createStatPool` (function) · `import { createStatPool } from "@jgengine/core/combat"`
+
+## stat-pool-change — immutably increase or decrease any named bounded resource with clamp evidence
+
+- `changeStatPool` (function) · `import { changeStatPool } from "@jgengine/core/combat"`
+
+## stat-pool-patch — immutably retune a bounded resource's current value or bounds
+
+- `patchStatPool` (function) · `import { patchStatPool } from "@jgengine/core/combat"`
+
 ## status-application — resolve a data-defined status application with chance, matchup scaling, and stacking policy
 
 - `resolveStatusApplication` (function) · `import { resolveStatusApplication } from "@jgengine/core/combat"`

package/skills/jgengine-combat/recipes/portable-stat-pools.md

@@ -0,0 +1,122 @@
+# Use JGengine stat pools with an existing save model
+
+Use this recipe when a project already owns its entities and persistence but
+needs deterministic bounded resources such as shields, energy, stamina, XP, or
+durability. Resource names and meaning remain caller data; the portable
+contract has no privileged health field.
+
+## Install
+
+```sh
+bun add @jgengine/core
+```
+
+Import the focused, renderer-free module:
+
+```ts
+import {
+  applyStatPoolDelta,
+  createStatPool,
+  type StatPool,
+  type StatPoolAccess,
+} from "@jgengine/core/stats/statPool";
+```
+
+`@jgengine/core` has no runtime dependencies and does not require a JGengine
+entity store, game loop, renderer, React provider, or backend.
+
+## Minimal adapter
+
+Suppose the existing project saves resources inline on its own units:
+
+```ts
+interface UnitSave {
+  id: string;
+  resources: Record<string, StatPool>;
+}
+
+interface WorldSave {
+  units: Record<string, UnitSave>;
+}
+
+const world: WorldSave = {
+  units: {
+    rover: {
+      id: "rover",
+      resources: {
+        energy: createStatPool({ current: 8, max: 10 }),
+        durability: createStatPool({ max: 40 }),
+      },
+    },
+  },
+};
+
+const resources: StatPoolAccess = {
+  get(ownerId, statId) {
+    return world.units[ownerId]?.resources[statId] ?? null;
+  },
+  set(ownerId, statId, next) {
+    const unit = world.units[ownerId];
+    if (unit !== undefined) unit.resources[statId] = next;
+  },
+};
+```
+
+The adapter performs structural reads and complete replacement writes. It does
+not expose the caller's store implementation or hand mutation authority to the
+engine.
+
+## Apply a resource change
+
+```ts
+const spent = applyStatPoolDelta(resources, "rover", "energy", -3);
+
+if (spent.status === "ok") {
+  console.log(spent.pool.current); // 5
+  console.log(spent.applied);      // -3 (after clamping)
+  console.log(spent.hitMin);       // false
+}
+```
+
+Positive amounts increase a pool and negative amounts decrease it. The result
+records the previous and next values, the exact clamped amount, and whether a
+bound was reached. Missing owners or stat ids return a rejected result without
+writing.
+
+For reducer-style stores, call the pure `changeStatPool(pool, amount)` or
+`patchStatPool(pool, patch)` transition inside the project's existing action
+and commit the returned `pool` through that store's normal update path.
+
+## Save and restore
+
+`StatPool` is plain JSON data, so keep it in the project's existing save:
+
+```ts
+const serialized = JSON.stringify(world);
+const restored = JSON.parse(serialized) as WorldSave;
+```
+
+After restore, point the same adapter at `restored`. There is no second JGengine
+snapshot to reconcile, no registry to rebuild, and no required migration away
+from the caller's schema. If the existing schema uses different field names,
+translate only at `get`/`set`.
+
+## Ownership
+
+The existing project owns resource ids, entity ids, storage layout,
+persistence, replication, authority, UI, scheduling, and the decision to apply
+a change. JGengine owns normalization, clamping, pure transitions, and the
+small structural access contract. Native JGengine entity stats implement the
+same portable behavior through their existing API.
+
+## Common traps
+
+- Do not copy caller resources into a parallel `StatValueMap`; adapt the state
+  where it already lives.
+- Do not mutate the object returned by `get`. Commit the complete returned
+  `pool` through `set` or the caller's reducer/action.
+- Pool changes are signed: positive restores/fills, negative spends/drains.
+- Keep formulas, regeneration schedules, damage meaning, and resource names in
+  caller code. A stat pool only enforces bounds.
+- Persist `current`, `max`, and `min` together so a restored value is clamped
+  against the same bounds.

package/skills/jgengine-combat/reference.md

@@ -2,6 +2,17 @@
 
 Reference module for the [`jgengine-combat` API](SKILL.md) skill. Load this when you need the combat surface — effects, projectiles, death, feel, and abilities.
 
+## Portable named resources
+
+`StatPool` (`@jgengine/core/stats/statPool`) is the plain
+`{ current, max, min }` model for any caller-named bounded resource. Existing
+projects implement the two-method `StatPoolAccess` over their own ECS, reducer,
+or save model, then use `applyStatPoolDelta`; reducer-style integrations use
+the pure `createStatPool` / `patchStatPool` / `changeStatPool` transitions.
+Native scene entity stats are a compatibility bridge over the same model. See
+the [portable stat-pool recipe](recipes/portable-stat-pools.md) for complete
+imports, adapter code, ownership, and JSON save/restore.
+
 ## Effects and projectiles
 
 Effect ids are **game-defined strings**. Magnitudes **drain** stats: positive subtracts down `receive.<effect>.order` (spilling to the next stat in the order), negative restores. Heals pass a negative amount (`via: { amount: -flashHeal }`, typically read from a `weapon.heal` stat).
@@ -25,7 +36,7 @@ fireProjectile({ from, via, aim, effect })      // → shotId (pending)
 settleProjectile(shotId)                        // authoritative → { at, hits } | rejection
 ```
 
-`Aim = { origin, direction } | { yaw, pitch, spread? }`. A free `{ yaw, pitch }` aim defaults to `converge`: the bullet leaves the gun `muzzle` (so a tracer visibly comes from the barrel, not the camera) yet bends toward whatever the eye ray's crosshair covers, so the reticle stays truth. An explicit `{ origin, direction }` aim (enemy AI, turrets) passes through unchanged. Shot origin otherwise resolves via `ShotOriginPolicy` (`eye`: shooter position raised to eye height — 90% of the shooter's own hitbox top when colliders are known, ~1.6m otherwise — so shots trace the sightline and the crosshair is truth; `muzzle`/`camera`/`world` for custom rigs, `legacy` = raw entity position). Default entity hitbox is a body-covering AABB (feet to ~1.8m). Objects with a `visual.scale` get a matching grounded physical body automatically; explicit catalog `colliders`/`halfExtents` override. Hitscan settles into per-hit effects; ballistic shots (`weapon.projectile` with `fuseTime`/`settleOn`) settle to a landing point — the handler then calls `effect({ at: settle.at, radius })`. Settling twice rejects. Prediction is never authority.
+`Aim = { origin, direction } | { yaw, pitch, spread? }`. A free `{ yaw, pitch }` aim defaults to `converge`: the bullet leaves the gun `muzzle` (so a tracer visibly comes from the barrel, not the camera) yet bends toward whatever the eye ray's crosshair covers, so the reticle stays truth. An explicit `{ origin, direction }` aim (enemy AI, turrets) passes through unchanged. Shot origin otherwise resolves via `ShotOriginPolicy` (`eye`: shooter position raised to eye height — 90% of the shooter's own hitbox top when colliders are known, ~1.6m otherwise — so shots trace the sightline and the crosshair is truth; `muzzle`/`camera`/`world` for custom rigs, `legacy` = raw entity position). Hitboxes auto-fit the rendered model: an entity kind mapped in `entityModels` (or an object catalog id in `objectModels`) gets a grounded AABB matching its model's measured bounds — footprint x height composed with `scale`/`targetHeight` exactly like the renderer — so the damage box equals the visual without hand-tuning. Unmodeled entities keep the body-covering humanoid AABB default (feet to ~1.8m); unmodeled objects with a `visual.scale` get a matching grounded physical body. Catalog assets opted into `COLLISION_MESH_ASSET_IDS` (`@jgengine/assets`) go one step further: the fit raycasts the asset's actual triangles (BVH over a quantized mesh shipped in the index), so a shot through a torus hole or archway passes clean instead of hitting the fitted box — same shape on client and headless host. Explicit catalog `colliders`/`halfExtents` and per-instance `setColliders` always override the fit. Hitscan settles into per-hit effects; ballistic shots (`weapon.projectile` with `fuseTime`/`settleOn`) settle to a landing point — the handler then calls `effect({ at: settle.at, radius })`. Settling twice rejects. Prediction is never authority.
 
 Raycasts are **object-aware**: the default raycast checks placed scene objects as well as entities, discriminated by `RaycastHit.kind` (`"entity" | "object"` — an `ObjectRaycastHit` also carries `catalogId`). A crate or wall between shooter and target blocks or absorbs the shot instead of every projectile passing through scenery; supply `ProjectileSystemDeps.objects` (`{ list(), halfExtents?(catalogId) }`, matching `ObjectStore.list()` structurally) to opt in, with a `[0.5, 0.5, 0.5]` half-extent default per object.
 
@@ -95,4 +106,3 @@ Genre systems layered over the same effects/projectiles/targeting/loot primitive
 - **Spawn providers** — spawning is one optional node adapter: `spawn: { kind, params }` invoked on enter. `BUILTIN_SPAWN_PROVIDERS.points` reads a named authored scene point list from `ctx.spawnPoints` (coordinates stay in the scene, referenced by key — never embedded in the sequence); `list` echoes inline requests. Register catalog/director-backed providers via `config.spawnProviders`.
 - **Injection & scripted control** — `injectPhase(state, phase, { after | before | childOf })` inserts a phase or branch at runtime (e.g. a boss after the final wave) into the serializable tree without disturbing active/completed nodes; `forceCompletePhase` completes the active phase regardless of its predicate for scripted skips and failure/retry, restoring the authored predicate afterward.
 
-