@jgengine/core 0.12.0 → 0.14.0

package/skills/jgengine-combat/capabilities.md

@@ -120,6 +120,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createEventMeter` (function) · `import { createEventMeter } from "@jgengine/core/combat"`
 
+## fire-cadence — a serializable minimum-interval rate gate for repeated actions (weapon fire, ability spam)
+
+- `createFireCadence` (function) · `import { createFireCadence } from "@jgengine/core/combat"`
+
 ## immunity-window — reject damage during a per-target invulnerability window installed by transitions
 
 - `createImmunityWindow` (function) · `import { createImmunityWindow } from "@jgengine/core/combat"`
@@ -204,10 +208,22 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `resolveStatusApplication` (function) · `import { resolveStatusApplication } from "@jgengine/core/combat"`
 
-## status-effects — apply and tick timed status effects and buffs on entities
+## status-effects — commit direct or area effects through caller-owned stat pools with ordered spillover and lethal results
 
 - `createEffectSystem` (function) · `import { createEffectSystem } from "@jgengine/core/combat"`
 
 ## threshold-crossings — emit ordered crossing events as a numeric source passes named thresholds with hysteresis and once/repeat policy
 
 - `createThresholdTracker` (function) · `import { createThresholdTracker } from "@jgengine/core/combat"`
+
+## vfx-preset-resolve — turn a named attack flavor into concrete vfx kind/color/duration with per-field overrides
+
+- `resolveVfxPreset` (function) · `import { resolveVfxPreset } from "@jgengine/core/combat"`
+
+## vfx-presets — render a named attack visual (arrow, fireball, lightning, web, slash, shield, heal, explosion) in one call
+
+- `vfxPresets` (const) · `import { vfxPresets } from "@jgengine/core/combat"`
+
+## weapon-runtime — compose cadence, magazine, a caller-owned raycast, and portable damage resolution into a fire controller
+
+- `createWeaponRuntime` (function) · `import { createWeaponRuntime } from "@jgengine/core/combat"`

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

package/skills/jgengine-combat/recipes/visible-attacks.md

@@ -0,0 +1,81 @@
+# Recipe — make an attack you can actually see
+
+**Seam:** authoritative hit resolution (`applyEffect` / `fireProjectile`) ↔ the one-shot
+`combat.vfx` visual the shell renders. They are deliberately separate: **resolving damage
+never draws anything on its own.** If you call `applyEffect`/`fireProjectile` and "nothing
+happens on screen," you have the hit but not the picture — emit a `vfx` burst next to it.
+
+The easy path is a named **preset**, so you never hand-pick a `VfxKind` or a hex color.
+
+## The one line
+
+```ts
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+
+// caster and enemy are entity instance ids (the shell follows their live pose)
+function shootArrow(ctx: GameContext, caster: string, enemy: string): void {
+  ctx.scene.entity.vfx({ preset: "arrow", from: caster, to: enemy });
+}
+```
+
+That renders a visible bolt traveling from the caster to the enemy. Swap the flavor for the
+attack you want — the vocabulary already covers the usual suspects:
+
+| Want | `preset` | Archetype |
+| --- | --- | --- |
+| arrow / bolt / bullet | `"arrow"`, `"bolt"`, `"bullet"` | traveling `projectile` |
+| fire / ice / poison / arcane spell | `"fireball"`, `"firebolt"`, `"frostbolt"`, `"poison"`, `"arcane"`, `"shadowbolt"`, `"holybolt"` | traveling `projectile` |
+| lightning / laser / web / chain | `"lightning"`, `"laser"`, `"web"`, `"chain"` | connecting `beam` |
+| sword swing / melee hit | `"slash"`, `"sword"`, `"melee"`, `"hit"` | impact `spark` |
+| explosion / shockwave | `"explosion"`, `"blast"`, `"shockwave"`, `"frostNova"` | ground `nova` |
+| heal / buff / shield aura | `"heal"`, `"buff"`, `"shield"`, `"cast"` | lingering `glow` |
+
+Full list lives in `vfxPresets` (`@jgengine/core/combat`).
+
+## Wiring it to a real projectile attack
+
+`fireProjectile` returns a shot id; `settleProjectile` resolves the hit. Fire the visual when
+you fire the shot so the bolt is in flight while it travels, then settle to apply damage:
+
+```ts
+function fireAt(ctx: GameContext, caster: string, enemy: string): void {
+  const shot = ctx.scene.entity.fireProjectile({
+    from: caster,
+    via: { item: "shortbow" },
+    aim: { yaw: 0, pitch: 0 },
+    effect: "arrow-hit",
+  });
+  ctx.scene.entity.vfx({ preset: "arrow", from: caster, to: enemy }); // <- the picture
+  ctx.scene.entity.settleProjectile(shot);                            // <- the damage
+}
+```
+
+For a melee swing there is no projectile — just resolve the effect and flash the spark:
+
+```ts
+ctx.scene.entity.effect({ from: caster, to: enemy, effect: "cleave" });
+ctx.scene.entity.vfx({ preset: "slash", from: caster, to: enemy });
+```
+
+## Overrides and custom bursts
+
+Any field on the call wins over the preset, so you keep the archetype but retint it:
+
+```ts
+ctx.scene.entity.vfx({ preset: "fireball", color: 0x00ff88, from: caster, to: enemy });
+```
+
+Skip `preset` entirely and pass `kind` + `color` for a fully bespoke burst. A **misspelled**
+flavor still shows a `spark` rather than nothing, so a typo never silently drops the effect.
+
+When you need the raw numbers — e.g. to seed a long-lived `vfxInstance` beam from the same
+vocabulary — call `resolveVfxPreset("lightning")` and read `{ kind, color, durationMs?, radius? }`.
+
+## Don't
+
+- Don't expect `applyEffect`/`fireProjectile`/`settleProjectile` to draw a visual — they are
+  headless authority. The `vfx` call is what the player sees.
+- Don't put damage numbers in a preset. Presets are colors and shapes; combat values live in
+  your effect/ability data.
+- Don't disable presentation and wonder where the effect went: `presentationEffects` is on by
+  default, but if a game passes `presentationEffects: { vfx: false }` the burst won't render.