@jgengine/core 0.10.0 → 0.12.0

package/skills/jgengine-combat/capabilities.md

@@ -0,0 +1,213 @@
+<!-- GENERATED by scripts/gen-capability-index.ts — do not edit. Regenerate: bun run gen:capabilities -->
+
+# jgengine-combat — capability index
+
+Reach for these before hand-rolling. Each row is *the thing you need* → *the primitive that already does it*.
+
+## ability-bar — a bar of cooldown-gated abilities the player triggers by slot
+
+- `createAbilityKit` (function) · `import { createAbilityKit } from "@jgengine/core/combat"`
+
+## anti-one-shot — clamp a near-lethal hit to leave a health floor then grant recovery immunity
+
+- `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"`
+
+## charge-meter — fill a gauge toward named tier thresholds as a value accumulates
+
+- `createAccumulatorMeter` (function) · `import { createAccumulatorMeter } from "@jgengine/core/combat"`
+
+## combo-chain — advance a chained melee string from timed button inputs
+
+- `createComboRunner` (function) · `import { createComboRunner } from "@jgengine/core/combat"`
+
+## combo-points — build up and spend finisher/combo points
+
+- `createComboPoints` (function) · `import { createComboPoints } from "@jgengine/core/combat"`
+
+## damage-clamp — cap incoming damage per hit at a configured maximum
+
+- `createDamageClamp` (function) · `import { createDamageClamp } from "@jgengine/core/combat"`
+
+## damage-hit — resolve a full data-defined damage hit — matchup, impact, receiver modifiers, and status application — with provenance
+
+- `resolveDamageHit` (function) · `import { resolveDamageHit } from "@jgengine/core/combat"`
+
+## damage-interception — intercept a pending damage application before lethal resolution with ordered, inspectable stages
+
+- `resolveDamage` (function) · `import { resolveDamage } from "@jgengine/core/combat"`
+
+## damage-matchup — score a data-defined damage channel against a target's traits into independent typed multipliers
+
+- `resolveMatchup` (function) · `import { resolveMatchup } from "@jgengine/core/combat"`
+
+## damage-pipeline — install and remove ordered damage interceptors that transitions toggle at runtime
+
+- `createDamagePipeline` (function) · `import { createDamagePipeline } from "@jgengine/core/combat"`
+
+## death-system — resolve entity death and its on-death consequences
+
+- `createDeathSystem` (function) · `import { createDeathSystem } from "@jgengine/core/combat"`
+
+## dice-check — resolve a pass/fail roll against a target number with modifiers and crits
+
+- `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"`
+
+## downed-revive — a downed/bleed-out state teammates can revive before death
+
+- `createDownedState` (function) · `import { createDownedState } from "@jgengine/core/combat"`
+
+## encounter-active-phase — read the id of the phase an encounter is currently waiting on
+
+- `activePhaseId` (function) · `import { activePhaseId } from "@jgengine/core/combat"`
+
+## encounter-advance — step a hierarchical encounter, resolving predicate-gated completion, repeats, and nested advance with lifecycle events
+
+- `updateEncounter` (function) · `import { updateEncounter } from "@jgengine/core/combat"`
+
+## encounter-force-complete — externally complete an active encounter phase to drive scripted or failure-retry transitions
+
+- `forceCompletePhase` (function) · `import { forceCompletePhase } from "@jgengine/core/combat"`
+
+## encounter-inject-phase — dynamically insert a phase or branch into a running encounter, e.g. a boss on the final wave
+
+- `injectPhase` (function) · `import { injectPhase } from "@jgengine/core/combat"`
+
+## encounter-phase-status — read whether a specific encounter phase is pending, active, or complete
+
+- `phaseStatus` (function) · `import { phaseStatus } from "@jgengine/core/combat"`
+
+## encounter-predicates — gate encounter phase completion on timers, cleared spawns, metrics, events, or a quorum of conditions
+
+- `BUILTIN_COMPLETION_PREDICATES` (const) · `import { BUILTIN_COMPLETION_PREDICATES } from "@jgengine/core/combat"`
+
+## encounter-progress — read completed-vs-total progress across a hierarchical encounter for HUD or objective display
+
+- `encounterProgress` (function) · `import { encounterProgress } from "@jgengine/core/combat"`
+
+## encounter-spawn-providers — turn an entered encounter phase into spawn requests from authored scene points or an inline list
+
+- `BUILTIN_SPAWN_PROVIDERS` (const) · `import { BUILTIN_SPAWN_PROVIDERS } from "@jgengine/core/combat"`
+
+## encounter-start — enter the first phase of a hierarchical encounter and emit its opening spawn events
+
+- `startEncounter` (function) · `import { startEncounter } from "@jgengine/core/combat"`
+
+## encounter-state — create the serializable starting state of a hierarchical encounter sequence
+
+- `createEncounterState` (function) · `import { createEncounterState } from "@jgengine/core/combat"`
+
+## event-meter — a heat/streak gauge that builds from repeated hits and cools down over time
+
+- `createEventMeter` (function) · `import { createEventMeter } 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"`
+
+## impact-feel — calibrated hitstop + trauma preset for a named impact event
+
+- `impactPresets` (const) · `import { impactPresets } from "@jgengine/core/combat"`
+- `resolveHitReaction` (function) · `import { resolveHitReaction } from "@jgengine/core/combat"`
+
+## magazine — a weapon magazine with capacity, timed reload, and reserve-pool interaction
+
+- `createMagazine` (function) · `import { createMagazine } from "@jgengine/core/combat"`
+
+## parry-window — time a block/parry/i-frame defensive window against incoming hits
+
+- `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"`
+
+## received-damage — apply data-defined receiver-side damage modifiers (amplify, reduce, cap, convert, redirect, immunity) with typed predicates
+
+- `resolveReceivedDamage` (function) · `import { resolveReceivedDamage } from "@jgengine/core/combat"`
+
+## regen-shield — a rechargeable overshield that absorbs damage and refills after a lull
+
+- `createRegenShield` (function) · `import { createRegenShield } from "@jgengine/core/combat"`
+
+## resource-pool — a regenerating pool like mana or stamina that actions spend from
+
+- `createResourcePool` (function) · `import { createResourcePool } from "@jgengine/core/combat"`
+
+## reward-allocation — distribute reward results among multiplayer participants deterministically
+
+- `allocateRewards` (function) · `import { allocateRewards } from "@jgengine/core/combat"`
+- `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"`
+- `createStaggerMeter` (function) · `import { createStaggerMeter } from "@jgengine/core/combat"`
+
+## stat-block — base stats with stacking, expiring buffs and debuffs applied on read
+
+- `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"`
+
+## status-effects — apply and tick timed status effects and buffs on entities
+
+- `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"`

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

@@ -0,0 +1,108 @@
+# jgengine domain API — Combat
+
+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).
+
+```ts
+ctx.scene.entity.canReceive(instanceId, effect, magnitude?)  // null | reason — reads catalog receive
+ctx.scene.entity.preview({ from, to, effect, via })      // magnitude, no state change
+ctx.scene.entity.effect({ from, to, effect, via })                          // single target
+ctx.scene.entity.effect({ from, effect, via, at, radius, falloff?, los? })  // AoE at a point
+```
+
+AoE: `inRadius(at, radius)` → LoS filter (default on) → `canReceive` per target → absorption; `falloff: "linear" | "none"`. `via` = `{ item }` (magnitude from weapon stats) or `{ amount }`. `canReceive`'s `pools-depleted` reason checks headroom in the effect's direction: a positive (draining) magnitude needs a stat above its min, a negative (restorative) magnitude needs a stat below its max — so a heal can still raise a stat sitting at its minimum. Omitting `magnitude` assumes the draining direction.
+
+`canReceive`'s optional signed `magnitude` makes the check direction-aware: positive (or omitted) keeps the standard `"pools-depleted"` check; negative checks the opposite direction and returns `"pools-full"` only when every stat in the receive order is already at max — so a heal (`via: { amount: -n }`) correctly reaches a fully-depleted target and is rejected only when there's nothing left to restore.
+
+**Projectiles** (aim-based — no target ids):
+
+```ts
+willHitProjectile({ from, via, aim, effect })   // prediction only, for crosshair UI
+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). 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.
+
+## Death
+
+Resolved **once** by the engine when the last stat in the receive order hits min. No HP polling in `onTick`, ever.
+
+- `entity.died` is emitted (before despawn — handlers can still read the victim's stats), then reason-matching `onDeath` entries run.
+- `DeathReason = { kind: "player_kill", killerUserId, via? } | { kind: "environment", source } | { kind: "self", source }`. Kills by the local player attribute automatically.
+- `onDeath.drops` tables are rolled and **granted to the killer** on player kills (emits `loot.granted`) when `onDeath.dropMode` is `"grant"` (default); `onDeath.command` runs through `ctx.game.commands`.
+- `onDeath.dropMode: "world"` routes item drops through a scatter impulse into ground `worldItem`s instead of straight to inventory (currency drops still grant directly) — tune the impulse with `onDeath.scatter: { radius, minRadius?, height? }` (defaults from `game/worldItem`'s `DEFAULT_SCATTER`).
+- Respawning under the same instance id revives it (it can die again). Same-id respawn must not happen synchronously inside the `entity.died` handler — defer a tick.
+- `quest.bind("entity.died")` credits kill objectives from the same event; leaderboards and kill feeds hang off it too.
+
+## Damage interception and threshold transitions
+
+Two genre-agnostic seams that sit **before** lethal resolution and drive **phase** logic, so games never hand-code "crossed threshold" branches or a boss-only invuln path. Both are pure/serializable `@jgengine/core/combat` factories.
+
+- **Interception pipeline** (`combat/damageInterceptors`) — `resolveDamage(interceptors, pending, ctx)` runs a `PendingDamage` through an ordered list; each `DamageInterceptor.intercept` returns `pass | transform | clamp | redirect | split | defer | reject`, and every decision lands in `DamageResolution.provenance` (no hidden callbacks). Split parts continue at the *next* interceptor and total work is capped by `MAX_INTERCEPT_STEPS`, so redirect/split can't recurse. `createDamagePipeline()` is the mutable install/remove chain a transition toggles (`install`/`remove`/`has`). `ctx` carries `nowMs` (deterministic clock) and optional `healthOf(target)`.
+- **Reusable policies** — `createDamageClamp({ maxPerHit })` caps a hit; `createImmunityWindow(id)` is a per-target invuln window (`grant`/`grantFor`/`active`/`clear`/`clearExpired`, `snapshot`/`restore`) installed and removed by transitions — i-frames and phase invuln are ordinary policies, not a boss branch; `createAntiOneShotPolicy({ guardAboveFraction, leaveFraction, recoverMs })` is the "cannot cross lethal while above X, leave Y, recover for Z" composition (clamps the killing blow to a health floor, then arms recovery immunity).
+- **Threshold crossings** (`combat/thresholdCrossings`) — `createThresholdTracker({ thresholds, trigger?, hysteresis?, policy?, initial? })` watches any numeric source (boss HP %, stamina, armor, an objective counter). `update(value)` returns ordered `ThresholdCrossing[]` with `direction` (`falling`/`rising`), honoring `trigger` filtering, a `hysteresis` dead-band, `once`/`repeat` policy, and skipped-threshold handling (a single big jump emits every mark it passed, in travel order). `snapshot`/`restore` round-trip the sides + once-ledger for save/load. Wire crossings to whatever a phase owns — installing an immunity interceptor, swapping AI, music, objectives. Non-health consumers (resource warnings) use the same tracker.
+## Reward allocation (multiplayer distribution)
+
+Generation and allocation are different operations. A loot table (`@jgengine/core/game/lootTable`) or any roll produces `RewardResult`s; `@jgengine/core/combat`'s `allocateRewards(kind, request)` then decides **who gets what** among participants — the co-op question single-player kills never ask. It is deterministic and serializable: the same seeds, recipients, and results yield a byte-identical `AllocationOutcome` on host and every peer regardless of join order, so allocation replicates as data without re-rolling.
+
+- Policies (`kind`): `instanced` (each recipient rolls its own results from a stable per-id stream — private by default), `copy` (full copy to everyone), `shared` (weight-split one count with a conserving largest-remainder distribution), `roundRobin` (one result each in deterministic rotation), `assigned` (caller `assignment` map), `claimed` (defer results into a `ClaimablePool`).
+- Keep `allocationSeed` (ordering, splits, rotation, reservation) separate from `generationSeed` (per-recipient `instanced` rolls) so a late joiner never perturbs existing players' rolls. Recipient order is seed-shuffled, never input order.
+- Claims resolve authoritatively via `resolveClaim(pool, claimantId, { nowMs })` — idempotent (re-claiming your own pool re-returns the same grants), with eligibility, `reservedFor`, and `expiresAtMs` enforced by the authority, not UI hiding. `first` pools are open/contested; `reserved` pools tie to one recipient (personal quest reward).
+- `filterOutcomeFor(outcome, viewerId)` is the replication filter: private grants for other recipients and pools the viewer cannot claim are dropped, so private rewards never leak. Provenance (`grant.via`) survives projection.
+- Works for any reward, not just items — split XP/currency by contribution weight the same way.
+
+## Combat feel (melee, defense, telegraphs)
+
+Layered on top of effects/projectiles/death — none of it replaces them, it adds **feel**. All models are renderer-free pure `@jgengine/core` factories a game composes per entity (like the `ctx`-vs-factory split above); the shell renders the telegraphs, styled damage numbers, hitstop shake.
+
+- **Animation state machine** (`combat/animationState`) is the root the rest hangs on. A `AnimationClip` is catalog data — `{ frames, fps, ranges }` where each `FrameRange` tags a window `windup | active | recovery | cancel` (cancel may overlap recovery). `createAnimationState({ clips })` gives a per-entity SM: `play(clipId)`, `tick(dt)` → `{ entered, exited, completed }`, and queries combat/defense subscribe to — `inPhase("active")`, `isActive()`, `canCancel()`, `activeWindowMs()`. Frame ranges are the "commit frame" contract for delayed/feinted attacks.
+- **Attack tags** (`combat/attackTags`) — `attackMeta(["unblockable" | "thrust" | "sweep" | "grab" | …], { effect, power })`. Defense logic reads them: `isBlockable`, `isParryable`, `isDodgeable`, `counters(meta, "mikiri")`. A grab beats all defenses; an unblockable is parry/dodge-only.
+- **Defensive window** (`combat/defensiveWindow`) — a parry/block/dodge with `{ startupMs, activeMs, recoveryMs, iframes }`. `resolveDefense({ config, elapsedMs, attack })` is the pure overlap of the defender's window against the moment the attacker's `active` frames land → `parry | block | iframe | hit`. `createDefensiveWindow(config)` tracks the open time (`open(now)` / `evaluate(now, attack)` / `isInvulnerable(now)`).
+- **Combo strings** (`combat/comboString`) — `ComboStep`s with `cancelInto` + `cancelPhases` + optional `stance`, over the anim SM. `advanceCombo(...)` (pure) accepts the next attack only inside the current step's cancel window and matching stance; `createComboRunner(combo, anim)` drives the SM.
+- **Meters share one accumulator** (`stats/accumulatorMeter`) — `createAccumulatorMeter({ max, mode: "hold" | "reset", decayPerSecond, decayDelayMs, tiers })`: fill via `add(n)` → `MeterAddResult { fired, overflow, tier, tierChanged }`, `tick(dt)` decays after an idle grace, reading its current tier off the pure `tierAt(value, tiers)` lookup. `combat/breakMeters` builds two on it: `createStaggerMeter` (mode `hold` — fills from hits, `broke()` stays true until `recover()` after a riposte/deathblow) and `createBuildupMeter` (mode `reset` — `add(n)` returns a `BuildupProc { status, durationMs }` at threshold for bleed/frost/rot, then decays). The same base backs G6's ult/streak meters.
+- **Delayed-regen shield** (`combat/regenShield`) — `createRegenShield(config)` is a shield pool that pauses regen for `regenDelayMs` after every hit, then refills at `regenPerSecond`; `damage`/`tick` replace snapshot-comparing a stat to detect "took damage."
+- **DoT field** (`combat/dotField`) — `createDotField()` schedules recurring damage-over-time instances (bleed/poison/burn) keyed by id; `tick` drains due damage per interval. Pairs with `combat/breakMeters`' `BuildupProc` — a fired buildup applies a DoT instead of one-shot damage.
+- **Magazine** (`combat/magazine`) — `createMagazine({ capacity, reloadMs, loaded?, reserve? })` is the per-weapon mag-size/reload/reserve-pool primitive (#536.2): `fire(rounds?)` spends loaded ammo, `startReload()`/`tick(dt)` run the timed refill, `canFire`/`canReload`/`isEmpty`/`isFull`/`reloadFraction` drive the HUD. `reserve` is a plain number for a self-contained pool, a `MagazineReserve` (`{ current, spend, gain? }`) to bridge reload draws into an externally-owned pool (a shared ammo-type stat, another `ResourcePool`), or omitted for an infinite reserve.
+- **Dash / dodge** (`movement/dash`) — `createDashState({ distance, durationMs, iframes, staminaCost, staminaMax, staminaRegenPerSecond, cooldownMs })`: `tryDash(dir, now)` → burst or `{ reason: "no-stamina" | "cooldown" | "dashing" }`, `isInvulnerable(now)` for the i-frame window, `offset(now)` for the burst displacement, `tick(dt, now)` regens stamina.
+- **Hit reaction** (`combat/hitReaction`) — `resolveHitReaction(config, { attackerPos, targetPos, power })` (pure) → `{ hitstopMs, impulse, shake, trauma, timescale }`. `config` is a raw `HitReactionConfig` **or** a named `impactPresets` event — `resolveHitReaction("explosion", input)` gives calibrated hitstop + trauma with zero hand-tuning (`pickup` 0.15 / `jumpLand` 0.2 / `enemyKilled` 0.3 @ 40ms hitstop / `playerHit` 0.4 @ 70ms / `explosion` 0.7 @ 90ms, heavy hits at `timescale: 0.05`; trauma clamps to 1.0). Wired on `ctx`: `ctx.scene.entity.hitReaction({ from, to, config, power? })` knocks the target back and emits `combat.hitReaction` with `trauma` set when the config resolved from `trauma` — the shell's `CombatCameraShake` feeds it into the trauma² camera-shake channel (`@jgengine/shell/camera`'s `traumaShake`; see `jgengine-ui`), or reads `shake` for the amplitude/decay channel when `config.shake` is set instead.
+- **Render cues** (`combat/renderCues`, #542) - the pure math behind a custom `renderEntity`/viewmodel rig's motion feel: `EntityRenderCues { speed, bobPhase, firing, reloading, recoil, hit, dead }`, `advanceMotionCues(cues, speed, dt, tuning?)` advances `bobPhase`/decays `recoil` from a live `groundSpeed(entity)` sample, `applyRenderAnimationEvent(cues, event)` folds in `"fire"` / `"reload"` / `"reloadEnd"` from `ctx.game.playEntityAnimation`, `applyRenderHitEvent`/`applyRenderDeathEvent` fold in `combat.hitReaction`/`entity.died`. `RenderCueTuning` overrides `cyclesPerUnit`/`recoilDecayPerSecond`/`firePulseSeconds`/`hitPulseSeconds`. A game never calls these directly — `@jgengine/shell/render`'s `useEntityRenderCues(instanceId)` (see `jgengine-ui`) wires all four into one ref-returning hook for `useFrame` consumers.
+- **Telegraph** (`combat/telegraph`) — a `TelegraphShape` (`circle | ring | cone | line`) + `windupMs`. `ctx.scene.entity.telegraph({ from, shape, at, dir?, windupMs, kind?, effect? })` emits `combat.telegraph` for the shell to draw a ground decal that fills over the windup, and — if `effect` is bound — applies that effect to everyone inside the shape (`pointInTelegraph`) at activation. Returns a cancel handle. **Turn-scoped variant**, for tactics/turn-based enemy intents instead of a real-time windup: set `TelegraphConfig.turns` (a count of turns instead of `windupMs`), then read `telegraphTurnProgress(config, startedTurn, currentTurn)` (0..1 fill fraction), `telegraphFiredAtTurn(config, startedTurn, currentTurn)` (has it resolved), and `telegraphTurnsRemaining(config, startedTurn, currentTurn)` — the same "enemy will hit this tile" decal, advanced by `turnLoop.round()`/`active()` instead of a clock.
+- **Damage-number typing** — `ctx.scene.entity.floatText({ …, crit?, element?, hitType?, scale? })` (and the `entity.floatText` event) carry hit metadata; the shell's `resolveFloatTextStyle` (`@jgengine/shell/world/floatTextStyle`) maps crit/element to color + scale + glow.
+- **VFX — one-shot vs retained** — `ctx.scene.entity.vfx({ kind, color, from?, to?, radius?, durationMs? })` fires a **one-shot** burst (`combat.vfx`, `kind: projectile | beam | nova | glow | spark`) the shell renders once and expires. For a **long-lived** effect whose endpoints/params move over time (held beam, tether, zone, target line, looping emitter) use the retained registry `ctx.scene.entity.vfxInstance` (`createVfxInstanceStore`, `@jgengine/core/game/vfxInstance`): `upsert({ id?, kind, color, from?, to?, radius?, params?, ttlMs? })` creates or replaces by stable id, `update(id, patch)` nudges dynamic params (a missing id is a no-op, not a throw), `stop(id, { fadeMs? })` disposes with an optional fade, and `tick(now)` enforces the TTL heartbeat; `list()`/`count()` are for debug. Endpoints are `VfxRef`s — an entity **instance id** (the shell resolves its live pose each frame, so the effect follows a moving entity with no per-frame commands) or a fixed `[x, y, z]` world point. State is headless/serializable and the store is renderer-independent; each op emits `combat.vfxInstance` which the shell's `RetainedVfx` overlay binds to render resources (beam is the first shipped retained renderer). Call `vfxInstance.clear()` on scene/level reset. Duet Keys' prism beam is the first adopter (driven from its `onTick`).
+
+## Abilities, resources, auto-target, resistance, run drafts
+
+Genre systems layered over the same effects/projectiles/targeting/loot primitives — all renderer-free pure `@jgengine/core` factories a game holds per player and ticks on **game-time** `dt` (so pause/fast-forward carry through). The ability kit is deliberately **separate from inventory items**: an item is a stackable id, an ability slot is cooldown/charge/resource state the HUD's four slot-states bind to.
+
+- **Ability kit** (`combat/abilityKit`) — `createAbilityKit([{ id, cooldownMs, chargesMax?, resourceCost?, castType?, flashMs? }])`. `state(id, resourceAvailable?)` → `AbilitySlotSnapshot { state: "ready" | "cooldown" | "no-resource" | "just-cast", charges, chargesMax, cooldownRemainingMs, cooldownFraction, justCast, ready }`; `cast(id, resourceAvailable?)` consumes a charge, starts the recharge, and flashes just-cast; `canCast` / `tick(dt)` / `reset` / `retuneSlot(id, { cooldownMs?, resourceCost? })` (rebalance a slot at runtime — patches the config in place without touching charges or an in-flight cooldown timer, returns `false` for an unknown slot). The kit is resource-**agnostic** — it reports `no-resource` by comparing `resourceCost` to a supplied `resourceAvailable` (a mana stat, or an ult meter), and never spends the resource itself; the game's handler spends it and calls `cast`. Charges recharge one at a time; the four states drive the hotbar slot art. Cooldowns tick on `dt`, so hang `kit.tick(dt)` in `onTick`.
+- **Event-fed meters** (`stats/eventMeter`, built on `stats/accumulatorMeter`) — `createEventMeter({ max, mode, gains, resets?, tiers?, decayPerSecond? })`. `feed(tag, scale?)` maps a tagged combat event to a gain (or a reset when `tag ∈ resets`) → `EventMeterFeedResult { fired, ready, tier, tierChanged, reset }`. Mode `"hold"` is the **ult/adrenaline** economy — charges off `{ damageDealt, damageTaken, kill }` events, `ready()` at full, `consume()` spends it (Overwatch/Marvel Rivals). Mode `"reset"` is the **streak/combo** meter — builds on `kill`, resets on a break tag like `damageTaken`, climbs ascending `tiers` (Returnal adrenaline, DMC style rank). One primitive, two catalog configs.
+- **Auto-target policy** (`scene/autoTarget`) — `selectAutoTarget(policy, fromId, deps)` / `createAutoTargeter(policy, deps)` evaluated each tick with zero input: `"nearest" | "farthest" | "random" | "strongest" | "weakest" | "first" | "last"`. `deps` supplies `candidates`/`distance` and optional `strength` (health/threat) + `progress` (path progress for first/last-on-path). Bullet-heaven auto-fire (Vampire Survivors nearest), Bloons tower priority (first/last on path). Feed the picked id to `abilityKit.cast` + `effect`.
+- **Resistance matrix** (`combat/resistance`) — a damage-category × target-property table distinct from `combat/attackTags` (those are defense tags). `resolveResistance(matrix, category, targetProperties)` → `{ verdict: "immune" | "resist" | "normal" | "vulnerable", multiplier, immune }`; `resistanceScale` returns just the multiplier (default `immune:0, resist:0.5, normal:1, vulnerable:2`, overridable). Immune on any property wins; resists stack multiplicatively. Sits over the `receive` gate — the handler multiplies its effect `amount` by the scale (Bloons lead/camo immunities, elemental RPG weaknesses).
+- **Run draft** (`game/runDraft`, built on `world/scatterItems` `pickWeighted` + `stats/statModifiers`) — `createRunModifierStack(offers)` accumulates stacking picks (`add`, `count`, `atMax`, `total(stat)` aggregating adds × exponentiated multiplies, `apply(stats)` onto a `createStats` source). `createRunDraft({ offers, rng? })` adds the pause-flow: `present(n)` draws N distinct weighted offers (excluding maxed-out ones), `choose(id)` applies to the stack. Pause/resume is game-side (`ctx.time.pause()` before `present`, `play()` after `choose`). Vampire Survivors level-up picks, Hades boons, Risk of Rain stacking items.
+
+## Encounter sequencing
+
+`combat/encounterSequence` is the genre-agnostic hierarchical sequencer behind arenas, raids, tutorials, races, defense phases, and scripted objectives — a serializable state machine over caller-defined phase `data` with **no built-in wave/boss concept**. State is plain JSON (the working tree, per-node runtime, active path, elapsed) so a mid-encounter save round-trips; the predicate/spawn registries live in the config you re-supply alongside it, the way `advanceSpawnDirector` pairs config with state.
+
+- **Tree + lifecycle** — `createEncounterState(config)` deep-copies the authored phase tree (unique ids enforced) and leaves it pending; `startEncounter` enters the first leaf; `updateEncounter(config, state, dt, ctx)` advances one bounded step, emitting provenance-rich `enter`/`spawn`/`complete`/`done` events. A group (has `children`) runs them in order and completes when they do — plus its own predicate if set (survive-the-timer-while-adds-run); a leaf without a predicate is an immediate marker. `activePhaseId` / `phaseStatus` / `encounterProgress` drive the HUD. A phase that spawns is deferred one tick before it can complete, so freshly-spawned "cleared" gates never satisfy against stale counts.
+- **Completion predicates** — `completion: { kind, params }` names a registered evaluator; `BUILTIN_COMPLETION_PREDICATES` ships `immediate`, `manual`/`flag`, `timer` (phase seconds), `cleared` (tagged count drained), `metric` (live threshold), `event` (cumulative count), and `quorum` (N of nested predicates). Signals (`counts`/`metrics`/`events`/`flags`) come in through `ctx.signals`; evaluation is deterministic. Register your own via `config.predicates`.
+- **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.
+

package/skills/jgengine-gameplay/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: jgengine-gameplay
+description: Compose serializable game state, systems, progression, and non-combat rules.
+---
+
+# JGengine gameplay
+
+## Ownership
+
+This skill owns non-combat rules and state: systems, catalogs, inventory/items, crafting, economy, quests, dialogue, social state, puzzles, survival, turns, tactics, sessions, and saveable game models. Combat math belongs to `jgengine-combat`; host persistence adapters belong to `jgengine-multiplayer`.
+
+Use [capabilities.md](capabilities.md) for intent discovery, [api.md](api.md) for signatures, and [reference-systems.md](reference-systems.md) for scheduling details before hand-rolling a subsystem.
+
+## Canonical workflow
+
+1. Define plain serializable state and stable ids.
+2. Put definitions in typed catalogs; keep per-instance mutable state separate.
+3. Express behavior as narrow systems or pure transitions with explicit inputs.
+4. Route player/AI intent through commands; emit typed results/events.
+5. Attach save/restore boundaries and versioning where state persists.
+6. Bind UI through selectors/hooks rather than duplicating state.
+
+Prefer `defineSystem` and `defineGame({ systems })` for scheduled capabilities. Keep boot/join in the game loop only when it is truly lifecycle glue. System ordering, frequency, and serialization are explicit; avoid a giant per-frame callback.
+
+## Design rules
+
+- Caller data owns nouns, formulas, tables, costs, tiers, and content.
+- Pure-data operations are the reusable core; stateful conveniences wrap them.
+- Transactions validate before mutation and return inspectable outcomes.
+- Random selection accepts injected RNG and stable ordering.
+- Large collections use indexes, queues, or bounded reconciliation rather than repeated scans.
+
+## Traps
+
+- A bare export mention is not an example; use capabilities for discovery and real imports/tests for adoption.
+- Do not invent a parallel store when an existing game-context feature owns the state.
+- Do not fuse save semantics with a specific cloud/backend adapter.
+- Targeting, damage, effects, abilities, and loot resolution route to `jgengine-combat`.
+- World movement/input/interaction route to `jgengine-world`; HUD rendering routes to `jgengine-ui`.