@jgengine/core 0.11.0 → 0.13.0

package/skills/jgengine-combat/recipes/portable-damage-effects.md

@@ -0,0 +1,197 @@
+# Apply damage to caller-owned resources
+
+Use this recipe when an existing JavaScript/TypeScript game wants JGengine's
+damage math, ordered interceptors, status resolution, shield spillover, and
+lethal result without adopting `GameContext`, the entity store, renderer, React,
+or JGengine's game loop.
+
+## Install and focused imports
+
+```sh
+bun add @jgengine/core
+```
+
+```ts
+import {
+  createEffectSystem,
+  type ReceiveMap,
+} from "@jgengine/core/combat/effects";
+import {
+  createDamageClamp,
+  resolveDamage,
+} from "@jgengine/core/combat/damageInterceptors";
+import { resolveDamageHit } from "@jgengine/core/combat/damageResolution";
+import {
+  createStatPool,
+  type StatPool,
+  type StatPoolAccess,
+} from "@jgengine/core/stats/statPool";
+import { seededRng } from "@jgengine/core/random/rng";
+```
+
+## Caller-owned state and adapter
+
+This example uses an immutable store-shaped object. A Redux, Zustand, ECS, or
+custom store can implement the same two methods without copying its entities
+into JGengine.
+
+```ts
+interface UnitState {
+  pools: Record<string, StatPool>;
+  receive: ReceiveMap;
+  statuses: Record<string, unknown>;
+}
+
+interface ExistingSave {
+  units: Record<string, UnitState>;
+}
+
+let save: ExistingSave = {
+  units: {
+    enemy_7: {
+      pools: {
+        shield: createStatPool({ current: 25, max: 25 }),
+        vitality: createStatPool({ current: 80, max: 80 }),
+      },
+      receive: { damage: { order: ["shield", "vitality"] } },
+      statuses: {},
+    },
+  },
+};
+
+const statPools: StatPoolAccess = {
+  get(ownerId, statId) {
+    return save.units[ownerId]?.pools[statId] ?? null;
+  },
+  set(ownerId, statId, next) {
+    const unit = save.units[ownerId];
+    if (unit === undefined) return false;
+    save = {
+      ...save,
+      units: {
+        ...save.units,
+        [ownerId]: { ...unit, pools: { ...unit.pools, [statId]: next } },
+      },
+    };
+    return true;
+  },
+};
+```
+
+`set` receives a complete plain replacement pool. The SDK never asks for the
+store itself and never mutates an entity object behind the adapter.
+
+## Build the effect committer
+
+```ts
+const existingEventQueue: unknown[] = [];
+const existingEvents = {
+  emit(name: string, payload: unknown) {
+    existingEventQueue.push({ name, payload });
+  },
+};
+
+const effects = createEffectSystem({
+  resolveReceive: (unitId) => save.units[unitId]?.receive,
+  statPools,
+  getStat: (_itemId, _statId) => null,
+  spatial: {
+    inRadius: (_center, _radius) => [],
+    hasLineOfSight: (_from, _to) => true,
+    positionOf: (_unitId) => undefined,
+  },
+  onLethal(unitId, context) {
+    existingEvents.emit("unit-defeated", { unitId, context });
+  },
+});
+```
+
+The spatial adapter is only used by area effects. Connect those three methods
+to the existing project's spatial index and line-of-sight query when needed;
+single-target effects do no world scan.
+
+## Resolve and apply a hit
+
+Keep resolution and commitment explicit. The pure stages return provenance and
+status state; authority decides what to persist and then routes final
+applications into the structural effect committer.
+
+```ts
+const seededRandom = seededRng("shot-2048");
+const simulationNowMs = 4_000;
+
+const hit = resolveDamageHit({
+  channel: "arc",
+  impact: 40,
+  source: "player",
+  target: "enemy_7",
+  targetTraits: ["shielded"],
+  status: { status: "charged", chance: 0.35, durationMs: 2_000 },
+  rng: seededRandom, // caller-owned deterministic stream
+});
+
+const intercepted = resolveDamage(
+  [createDamageClamp({ id: "per-hit-cap", maxPerHit: 30 })],
+  {
+    source: "player",
+    target: "enemy_7",
+    amount: hit.impact,
+    tag: hit.channel,
+  },
+  { nowMs: simulationNowMs }, // caller-owned deterministic clock
+);
+
+for (const application of intercepted.applications) {
+  effects.applyEffect({
+    from: application.source,
+    to: application.target,
+    effect: "damage",
+    via: { amount: application.amount },
+  });
+}
+
+if (hit.status?.instance !== null && hit.status?.instance !== undefined) {
+  save.units.enemy_7!.statuses[hit.status.instance.status] = hit.status.instance;
+}
+```
+
+`intercepted.provenance` records each ordered policy decision. `hit.matchup`,
+`hit.received`, and `hit.status` retain the pure resolution evidence. The effect
+result lists exact per-pool deltas in the receive order and reports lethality
+when the final pool reaches its minimum.
+
+## Save and restore
+
+The authoritative pools and returned status instances are already plain data:
+
+```ts
+const encoded = JSON.stringify(save);
+save = JSON.parse(encoded) as ExistingSave;
+```
+
+Recreate the small adapters over the restored store. Interceptor functions and
+catalog rules are configuration, so re-supply them rather than serializing
+closures. Persist any stateful interceptor records separately when their API
+exposes serializable state.
+
+## Ownership
+
+The existing project retains entity identity, resource names, store updates,
+save schema, status collection, authority, spatial queries, death/despawn,
+events, clock, RNG, content, presentation, and its update loop. JGengine owns
+the pure resolution stages, bounded ordered interception, pool spillover math,
+and inspectable results.
+
+## Common traps
+
+- Use positive effect magnitudes to drain pools and negative magnitudes to
+  restore them; the receive rule determines which named pools participate.
+- Put shields or other absorbers before the final lethal pool in `order`.
+- Pass final interceptor applications to `applyEffect`; do not apply the
+  pre-interceptor impact as well.
+- Persist the returned status `instance`; `resolveDamageHit` is intentionally
+  pure and does not hide a status store.
+- Use a bounded spatial index for `inRadius`; do not add a full-world scan per
+  area effect.
+- Keep audio, particles, hit flashes, animations, camera shake, and models in
+  the existing project. Drive them from the returned results and provenance.

package/skills/jgengine-combat/recipes/portable-runtime-state.md

@@ -0,0 +1,154 @@
+# Save and restore closure-backed combat runtimes
+
+Use this recipe when an existing project wants JGengine's convenient magazine
+or stat-modifier runtime but keeps its own save system, clock, entities, and
+authority. Both runtimes expose detached plain snapshots; no JGengine store or
+`GameContext` is required.
+
+## Install and focused imports
+
+```sh
+bun add @jgengine/core
+```
+
+```ts
+import {
+  createMagazine,
+  type MagazineSnapshot,
+} from "@jgengine/core/combat/magazine";
+import {
+  createStats,
+  type StatsSnapshot,
+} from "@jgengine/core/stats/statModifiers";
+```
+
+## Caller-owned save data
+
+```ts
+type VehicleStat = "speed" | "handling";
+
+interface VehicleRuntimeSave {
+  magazine: MagazineSnapshot;
+  stats: StatsSnapshot<VehicleStat>;
+}
+
+interface ExistingSave {
+  nowMs: number;
+  vehicle: VehicleRuntimeSave;
+  sharedAmmo: number;
+}
+```
+
+The project owns this schema and decides when it is written, replicated,
+rolled back, replayed, or transferred to a worker.
+
+## Run and snapshot
+
+```ts
+let nowMs = 4_000;
+let sharedAmmo = 18;
+
+const magazine = createMagazine({
+  capacity: 6,
+  reloadMs: 900,
+  reserve: {
+    current: () => sharedAmmo,
+    spend(amount) {
+      if (amount > sharedAmmo) return false;
+      sharedAmmo -= amount;
+      return true;
+    },
+    gain(amount) {
+      sharedAmmo += amount;
+    },
+  },
+});
+
+const stats = createStats<VehicleStat>(
+  { speed: 12, handling: 8 },
+  { now: () => nowMs },
+);
+stats.addSource("boost", { speed: { multiply: 1.25 } }, { expiresAtMs: 7_000 });
+
+magazine.fire(2);
+magazine.startReload();
+magazine.tick(0.3);
+
+const save: ExistingSave = {
+  nowMs,
+  vehicle: {
+    magazine: magazine.snapshot(),
+    stats: stats.snapshot(),
+  },
+  sharedAmmo,
+};
+
+const serialized = JSON.stringify(save);
+```
+
+Snapshots are detached from the live closures. Mutating or continuing the
+runtime after this point does not rewrite `save`.
+
+## Restore and resume
+
+```ts
+const decoded = JSON.parse(serialized) as ExistingSave;
+nowMs = decoded.nowMs;
+sharedAmmo = decoded.sharedAmmo; // restore caller-owned reserve first
+
+const resumedMagazine = createMagazine({
+  capacity: 6,
+  reloadMs: 900,
+  loaded: 0,
+  reserve: {
+    current: () => sharedAmmo,
+    spend(amount) {
+      if (amount > sharedAmmo) return false;
+      sharedAmmo -= amount;
+      return true;
+    },
+    gain(amount) {
+      sharedAmmo += amount;
+    },
+  },
+});
+if (!resumedMagazine.restore(decoded.vehicle.magazine)) {
+  throw new Error("magazine save does not match its reserve configuration");
+}
+
+const resumedStats = createStats<VehicleStat>(
+  { speed: 0, handling: 0 },
+  { now: () => nowMs },
+);
+resumedStats.restore(decoded.vehicle.stats);
+
+resumedMagazine.tick(0.6); // finishes the same in-progress 900ms reload
+nowMs = 7_000;
+resumedStats.get("speed"); // injected clock expires the boost deterministically
+```
+
+For a self-managed numeric magazine reserve, the magazine snapshot contains
+and restores that reserve directly. For a caller-owned `MagazineReserve`, save
+and restore the caller's reserve first; `restore` returns `false` rather than
+partially changing loaded/reload state when it cannot reconcile the reserve.
+
+## Ownership
+
+The existing project owns save versioning, entity identity, clock value,
+reserve state, networking/rollback policy, content, and when ticks occur.
+JGengine owns the closure convenience methods, snapshot encoding shape,
+detached copies, and deterministic continuation once the caller supplies the
+same config and clock.
+
+## Common traps
+
+- Re-supply immutable configuration such as magazine capacity/reload duration
+  and the stat id set when rebuilding a runtime; snapshots contain mutable
+  state, not content catalogs.
+- Restore externally-owned reserve data before calling `Magazine.restore`.
+- Persist the injected clock alongside expiring modifier snapshots or convert
+  expiry timestamps in the project's migration layer.
+- Do not keep a live snapshot object as mutable state. Restore it into a runtime
+  and take a fresh snapshot for the next save.
+- Check the boolean returned by `Magazine.restore`; reserve-kind mismatches and
+  unreconcilable external reserves are rejected without partial magazine state.

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/recipes/portable-weapon-plumbing.md

@@ -0,0 +1,156 @@
+# Fire a weapon with your own Three.js raycaster
+
+Use this recipe when an existing Three.js/JavaScript game wants JGengine's fire
+cadence, magazine/reload, and deterministic damage resolution but keeps its own
+models, animations, muzzle flash, audio, input, camera, aiming, and — crucially —
+its own raycaster and entity list. There is no default gun: you compose generic
+primitives. No `GameContext`, entity store, renderer, or React is required.
+
+## Install and focused imports
+
+```sh
+bun add @jgengine/core three
+```
+
+```ts
+import {
+  createWeaponRuntime,
+  type WeaponRuntime,
+} from "@jgengine/core/combat";
+import type { DamageHitInput } from "@jgengine/core/combat";
+import * as THREE from "three";
+```
+
+## Caller-owned aim, entities, and raycaster
+
+The engine never touches your scene. You own the raycast; it returns whatever hit
+shape you like.
+
+```ts
+interface Enemy {
+  id: string;
+  mesh: THREE.Object3D;
+  armored: boolean;
+}
+
+const enemies: Enemy[] = loadEnemies();
+const raycaster = new THREE.Raycaster();
+
+function raycastFromCamera(camera: THREE.Camera): Enemy[] {
+  raycaster.setFromCamera(new THREE.Vector2(0, 0), camera); // center-screen shot
+  const meshes = enemies.map((e) => e.mesh);
+  const intersects = raycaster.intersectObjects(meshes, true);
+  const first = intersects[0];
+  if (first === undefined) return [];
+  const enemy = enemies.find((e) => e.mesh === first.object || e.mesh === first.object.parent);
+  return enemy === undefined ? [] : [enemy];
+}
+```
+
+## Compose the weapon runtime
+
+`cadenceMs`, `magazine`, and `ready` are plain data; `resolveHits` runs your
+raycaster and `damageFor` maps a hit to a portable damage input (return `null` to
+skip damage, e.g. a wall). Derive `cadenceMs` from a rounds-per-second fire rate
+with `1000 / roundsPerSecond`.
+
+```ts
+const rifle: WeaponRuntime<THREE.Camera, Enemy> = createWeaponRuntime({
+  cadenceMs: 1000 / 8, // 8 rounds/sec
+  magazine: { capacity: 30, reloadMs: 1800, reserve: 120 },
+  resolveHits: (camera) => raycastFromCamera(camera),
+  damageFor: (enemy): DamageHitInput => ({
+    channel: "kinetic",
+    impact: 24,
+    target: enemy.id,
+    targetTraits: enemy.armored ? ["armored"] : [],
+    matchup: { entries: { kinetic: { armored: { impact: 0.5 } } } },
+  }),
+});
+```
+
+## Fire, tick, and apply results
+
+```ts
+// Your input handler:
+function onTriggerDown(camera: THREE.Camera): void {
+  const result = rifle.fire(camera);
+  if (result.status === "fired") {
+    playMuzzleFlash();
+    for (const hit of result.resolutions) {
+      // Apply the resolved impact to YOUR health store, spawn YOUR hit spark, etc.
+      applyDamageToMyEntities(hit); // hit.impact, hit.channel, hit.status, hit.received
+    }
+  } else if (result.status === "empty") {
+    rifle.startReload();
+    playReloadAnim();
+  } // "cooling" and "reloading" are silent no-ops you can ignore or feed to the HUD
+}
+
+// Your frame loop:
+function update(dtSeconds: number): void {
+  rifle.tick(dtSeconds); // advances cadence + reload timers
+  hud.setAmmo(rifle.magazine?.loaded() ?? Infinity, rifle.magazine?.reserve() ?? null);
+  hud.setReload(rifle.magazine?.reloadFraction() ?? 0);
+}
+```
+
+`resolveHits` and `damageFor` are only called on a `"fired"` result, so a blocked
+trigger pull never touches your raycaster or ammo.
+
+## Bring your own ammo economy
+
+Point the magazine's `reserve` at a caller-owned pool with a `MagazineReserve`
+adapter instead of a plain number, so reloads draw from your shared inventory:
+
+```ts
+import type { MagazineReserve } from "@jgengine/core/combat";
+
+const backpack = { rifleAmmo: 240 };
+const reserve: MagazineReserve = {
+  current: () => backpack.rifleAmmo,
+  spend: (n) => (n <= backpack.rifleAmmo ? ((backpack.rifleAmmo -= n), true) : false),
+  gain: (n) => { backpack.rifleAmmo += n; },
+};
+// magazine: { capacity: 30, reloadMs: 1800, reserve }
+```
+
+## Save and restore
+
+The magazine exposes `loaded()`/`reserve()`/`reloadFraction()` and the cadence
+exposes `elapsedMs()`/`restore()` for HUD and snapshots:
+
+```ts
+const snapshot = {
+  cadenceMs: rifle.cadence.elapsedMs(),
+  loaded: rifle.magazine?.loaded() ?? null,
+};
+// After load: recreate the runtime from the same config, then:
+rifle.cadence.restore(snapshot.cadenceMs);
+```
+
+Recreate the magazine at its saved `loaded` via `MagazineConfig.loaded`. (Full
+magazine snapshot/restore lands with the serializable-runtime-state slice.)
+
+## Ownership
+
+The existing project keeps entities, meshes, the raycaster, aim, input, camera,
+muzzle flash, audio, animation, the health/damage sink, ammo inventory, weapon
+content and stats, and when the trigger fires. JGengine owns fire-rate gating,
+magazine/reload bookkeeping, and deterministic damage resolution (matchup,
+receiver modifiers, status rolls) with full provenance.
+
+## Common traps
+
+- `fire()` gates in order **reloading → cooling → empty**; a `"cooling"` result
+  means the cadence, not the magazine, blocked the shot. Tick before expecting
+  `"empty"`.
+- Only a `"fired"` result spends a round and resets cadence; blocked attempts are
+  free, so you can call `fire()` every input frame.
+- Firing does not auto-reload or fire-cancel a reload; call `startReload()` /
+  `cancelReload()` from your own input policy.
+- `damageFor` returning `null` keeps the hit in `result.hits` but produces no
+  `DamageHitResolution` — use it for terrain/props your raycast also returns.
+- Pass a seeded `rng` in the config for deterministic status rolls in multiplayer
+  authority, replays, or tests; per-hit `DamageHitInput.rng` overrides it.
+- Convert fire rate to `cadenceMs` with `1000 / roundsPerSecond`, not the reverse.