@jgengine/core 0.19.0 → 0.22.0

package/skills/jgengine-combat/api.md

@@ -4,7 +4,7 @@
 
 ## @jgengine/core/combat
 
-- `AbilityKit` (interface): interface AbilityKit { slots(): readonly string[]; config(slotId: string): AbilitySlotConfig | null; state(slotId: string, resourceAvailable?: number): AbilitySlotSnapshot | null; snapshot(resourceAvailable?: number): AbilitySlotSnapshot[]; canCast(slotId: stri… — ⚠ undocumented · used by `createAbilityKit`: A bar of cooldown-gated abilities the player fires by slot, tracking readiness and cooldown per ability.
+- `AbilityKit` (interface): interface AbilityKit { slots(): readonly string[]; config(slotId: string): AbilitySlotConfig | null; state(): AbilityKitState; state(slotId: string, resourceAvailable?: number): AbilitySlotSnapshot | null; snapshot(resourceAvailable?: number): AbilitySlotSnapsh… — ⚠ undocumented · used by `createAbilityKit`: A bar of cooldown-gated abilities the player fires by slot, tracking readiness and cooldown per ability.
 - `AbilitySlotSnapshot` (interface): interface AbilitySlotSnapshot { id: string; state: AbilitySlotState; castType: AbilityCastType; resourceCost: number; charges: number; chargesMax: number; cooldownRemainingMs: number; cooldownFraction: number; groupRemainingMs: number; justCast: boolean; ready: boolean … — ⚠ undocumented · used by `actionFromAbilitySlot` (@jgengine/react): Composable React renderers over the headless action view model (`@jgengine/core/ui/actionModel`) — the data/renderer/chrome split for an RTS…
 - `AbilitySlotState` (type): type AbilitySlotState = "ready" | "cooldown" | "no-resource" | "just-cast" — ⚠ undocumented
 - `AllocationOutcome` (interface): interface AllocationOutcome — The serializable result of an allocation pass — immediate `grants` plus any deferred `pools`.
@@ -55,7 +55,7 @@
 - `EncounterState` (interface): interface EncounterState<TData = unknown> — Full serializable encounter state: the working phase tree (including any injected phases), a per-node runtime map, the active path from root to the deepest open node, accumulated time, and whether the sequence has finished. Round-trips through JSON with no behavioral change; the registries live in {@link EncounterConfig}, not here.
 - `EncounterStep` (interface): interface EncounterStep<TData = unknown> — Result of a step: the (mutated, returned) state and the events emitted this step.
 - `EntityRenderCues` (interface): interface EntityRenderCues — Per-entity render cues: the motion/animation signal a custom `renderEntity` or first-person viewmodel component needs to drive gait, muzzle flash, reload poses, and hit reactions — without diffing the parent group's position itself or reading a game-side module map for attack timing.
-- `EventMeter` (interface): interface EventMeter { value(): number; fraction(): number; tier(): string | null; ready(): boolean; feed(tag: string, scale?: number): EventMeterFeedResult; consume(): boolean; drain(amount: number): void; reset(): void; tick(dtSeconds: number): void } — ⚠ undocumented · used by `createEventMeter`: A heat/hype gauge that rises as tagged events land and cools between them, firing when it fills or breaks — the streak/overdrive meter shoot…
+- `EventMeter` (interface): interface EventMeter { state(): EventMeterState; restore(next: EventMeterState): void; value(): number; fraction(): number; tier(): string | null; ready(): boolean; feed(tag: string, scale?: number): EventMeterFeedResult; consume(): boolean; drain(amount: numbe… — ⚠ undocumented · used by `createEventMeter`: A heat/hype gauge that rises as tagged events land and cools between them, firing when it fills or breaks — the streak/overdrive meter shoot…
 - `EventMeterFeedResult` (interface): interface EventMeterFeedResult { tag: string; reset: boolean; amount: number; value: number; fraction: number; fired: boolean; ready: boolean; overflow: number; tier: string | null; tierChanged: boolean } — ⚠ undocumented
 - `FireCadence` (interface): interface FireCadence — A minimal minimum-interval rate gate for a repeated action — weapon fire, ability spam, any "no faster than N per second" rule. Deterministic and serializable: its whole state is the elapsed time since the last action, exposed via {@link FireCadence.elapsedMs}.
 - `FireCadenceConfig` (interface): interface FireCadenceConfig — Tuning for {@link createFireCadence}: the minimum interval between actions and whether it starts ready.
@@ -207,8 +207,9 @@
 - `AbilityCastResult` (type): type AbilityCastResult = | { ok: true; slot: AbilitySlotSnapshot } | { ok: false; reason: AbilityCastReason; slot: AbilitySlotSnapshot | null } — ⚠ undocumented
 - `AbilityCastType` (type): type AbilityCastType = "instant" | "projectile" | "channel" | "targeted" — ⚠ undocumented
 - `AbilityCooldownGroup` (interface): interface AbilityCooldownGroup — A cooldown shared across every member slot: casting any member starts it, and no member can cast while it runs. One group that every slot joins is an MMO global cooldown.
-- `AbilityKit` (interface): interface AbilityKit { slots(): readonly string[]; config(slotId: string): AbilitySlotConfig | null; state(slotId: string, resourceAvailable?: number): AbilitySlotSnapshot | null; snapshot(resourceAvailable?: number): AbilitySlotSnapshot[]; canCast(slotId: stri… — ⚠ undocumented · used by `createAbilityKit`: A bar of cooldown-gated abilities the player fires by slot, tracking readiness and cooldown per ability.
+- `AbilityKit` (interface): interface AbilityKit { slots(): readonly string[]; config(slotId: string): AbilitySlotConfig | null; state(): AbilityKitState; state(slotId: string, resourceAvailable?: number): AbilitySlotSnapshot | null; snapshot(resourceAvailable?: number): AbilitySlotSnapsh… — ⚠ undocumented · used by `createAbilityKit`: A bar of cooldown-gated abilities the player fires by slot, tracking readiness and cooldown per ability.
 - `AbilityKitOptions` (interface): interface AbilityKitOptions { groups?: readonly AbilityCooldownGroup[]; resource?: AbilityResource } — ⚠ undocumented · used by `createAbilityKit`: A bar of cooldown-gated abilities the player fires by slot, tracking readiness and cooldown per ability.
+- `AbilityKitState` (interface): interface AbilityKitState — Mutable kit state; slot/group definitions and any bound resource are saved by the caller.
 - `AbilityResource` (interface): interface AbilityResource — A spendable resource pool (mana, energy, rage) bound to an ability kit. When bound, `cast` deducts a slot's `resourceCost` on success and `state`/`snapshot`/`canCast` reflect affordability without a per-call `resourceAvailable` argument — the cast path actually spends instead of only gating (#357).
 - `AbilitySlotConfig` (interface): interface AbilitySlotConfig { id: string; cooldownMs: number; chargesMax?: number; resourceCost?: number; castType?: AbilityCastType; flashMs?: number; groups?: readonly string[] } — ⚠ undocumented · used by `createAbilityKit`: A bar of cooldown-gated abilities the player fires by slot, tracking readiness and cooldown per ability.
 - `AbilitySlotRetune` (interface): interface AbilitySlotRetune { cooldownMs?: number; resourceCost?: number } — ⚠ undocumented
@@ -327,12 +328,12 @@
 - `DeathReasonKind` (type): type DeathReasonKind = DeathReason["kind"] — ⚠ undocumented
 - `DeathResolution` (type): type DeathResolution = | { status: "resolved"; drops: Drop[]; ranCommand: string | null } | { status: "rejected"; reason: string } — ⚠ undocumented
 - `DeathSystem` (interface): interface DeathSystem { resolveDeath(instanceId: string, reason: DeathReason): DeathResolution; revive(instanceId: string): boolean } — ⚠ undocumented · used by `createDeathSystem`: Resolve entity death and the on-death consequences — drops, respawn eligibility, kill credit.
-- `DeathSystemDeps` (interface): interface DeathSystemDeps { resolveOnDeath(instanceId: string): OnDeathSpec | null | undefined; resolveIdentity(instanceId: string): DeathIdentity | null; loot: {roll(tableId: string): Drop[]}; events: GameEvents; runCommand?(name: string, args: unknown): void; desp… — ⚠ undocumented · used by `createDeathSystem`: Resolve entity death and the on-death consequences — drops, respawn eligibility, kill credit.
+- `DeathSystemDeps` (interface): interface DeathSystemDeps { resolveOnDeath(instanceId: string, reason?: DeathReason): OnDeathSpec | null | undefined; resolveIdentity(instanceId: string): DeathIdentity | null; loot: {roll(tableId: string): Drop[]}; events: GameEvents; runCommand?(name: string, args… — ⚠ undocumented · used by `createDeathSystem`: Resolve entity death and the on-death consequences — drops, respawn eligibility, kill credit.
 - `DropMode` (type): type DropMode = "grant" | "world" — ⚠ undocumented
 - `EffectDeathContext` (interface): interface EffectDeathContext { from: string; via?: EffectVia; userIdOf?(instanceId: string): string | undefined } — ⚠ undocumented
 - `NormalizedOnDeath` (interface): interface NormalizedOnDeath { drops: OnDeathDropRule[]; command: OnDeathCommandRule | null; dropMode: DropMode; scatter?: ScatterOptions } — ⚠ undocumented
 - `OnDeathCommandRule` (interface): interface OnDeathCommandRule { name: string; args?: unknown; when?: {reason: DeathReasonKind} } — ⚠ undocumented
-- `OnDeathDropRule` (interface): interface OnDeathDropRule { table: string; when?: {reason: DeathReasonKind} } — ⚠ undocumented
+- `OnDeathDropRule` (interface): interface OnDeathDropRule { table: string; when?: {reason: DeathReasonKind | "any"} } — ⚠ undocumented
 - `OnDeathSpec` (interface): interface OnDeathSpec — Catalog `onDeath` for an entity: loot tables to roll, `dropMode: "world"` to scatter drops on the ground (rendered with loot beams) instead of granting them into the killer's bag, and commands to run. Fires only when the entity dies through `ctx.scene.entity.effect`, not a raw `stats.delta`.
 - `createDeathSystem` (function): function createDeathSystem(deps: DeathSystemDeps): DeathSystem — Resolve entity death and the on-death consequences — drops, respawn eligibility, kill credit.
 - `deathReasonFromEffect` (function): function deathReasonFromEffect(ctx: EffectDeathContext): DeathReason — ⚠ undocumented
@@ -441,19 +442,27 @@
 - `MagazineConfig` (interface): interface MagazineConfig — Tuning for `createMagazine`: mag capacity, reload delay, and where reserve ammo is drawn from.
 - `MagazineReserve` (interface): interface MagazineReserve — Draws ammo for a `Magazine`'s reload from wherever the reserve pool actually lives.
 - `MagazineSnapshot` (interface): interface MagazineSnapshot — Complete serializable state for a {@link Magazine}; `reserve: null` means infinite reserve.
+- `MagazineTuning` (interface): interface MagazineTuning — Live magazine tuning; shrinking below loaded rounds rejects unless overflow is explicit.
 - `createMagazine` (function): function createMagazine(config: MagazineConfig): Magazine — Builds a {@link Magazine}: discrete loaded ammo, a timed reload, and reserve-pool interaction.
 
 ## @jgengine/core/combat/projectiles
 
 - `EntityRaycastHit` (interface): interface EntityRaycastHit { kind: "entity"; instanceId: string; distance: number; at: EntityPosition; colliderName?: string; damageEligible?: boolean; blocks?: boolean } — ⚠ undocumented
+- `LiveProjectile` (interface): interface LiveProjectile — Detached pose of one active projectile pellet for presentation.
 - `ObjectRaycastHit` (interface): interface ObjectRaycastHit { kind: "object"; instanceId: string; catalogId: string; distance: number; at: EntityPosition; colliderName?: string; damageEligible?: boolean; blocks?: boolean } — ⚠ undocumented
+- `ProjectileFlightState` (interface): interface ProjectileFlightState — Serializable motion state of one projectile pellet.
 - `ProjectileHit` (type): type ProjectileHit = | { kind: "entity"; instanceId: string; distance: number; colliderName?: string; damageEligible?: boolean; } | { kind: "object"; instanceId: string; catalogId: string; distance: number; colliderName?: string; damageEligible?: boolean; } — ⚠ undocumented
 - `ProjectileObjectsDeps` (interface): interface ProjectileObjectsDeps { list(): readonly {instanceId: string; catalogId: string; position: readonly [number, number, number]; rotationY?: number;}[]; inBox?(min: EntityPosition, max: EntityPosition): readonly {instanceId: string; catalogId: string; position: rea… — ⚠ undocumented
 - `ProjectilePrediction` (interface): interface ProjectilePrediction { hits: ProjectileHit[]; blocked?: boolean; origin?: EntityPosition; direction?: EntityPosition; firstImpact?: ProjectileHit | null } — ⚠ undocumented
-- `ProjectileSettleReport` (interface): interface ProjectileSettleReport { from: string; origin: EntityPosition; at: EntityPosition; effect: string; hit: boolean; ballistic: boolean } — ⚠ undocumented
-- `ProjectileShotInput` (interface): interface ProjectileShotInput { from: string; via: EffectVia; aim: Aim; effect: string; originPolicy?: ShotOriginPolicy } — ⚠ undocumented
-- `ProjectileSystem` (interface): interface ProjectileSystem { willHitProjectile(input: ProjectileShotInput): ProjectilePrediction; fireProjectile(input: ProjectileShotInput): string; settleProjectile(shotId: string): SettleResult } — ⚠ undocumented · used by `createProjectileSystem`: Spawn and advance projectiles each frame, resolving travel, lifetime, and hits.
+- `ProjectileSettleReport` (interface): interface ProjectileSettleReport — Exactly-once settlement with launch identity and actual applied effects.
+- `ProjectileShotInput` (interface): interface ProjectileShotInput { from: string; via: EffectVia; aim: Aim; effect: string; originPolicy?: ShotOriginPolicy; travel?: ProjectileTravelConfig } — ⚠ undocumented
+- `ProjectileShotState` (interface): interface ProjectileShotState — Serializable captured launch and settlement state.
+- `ProjectileSystem` (interface): interface ProjectileSystem { willHitProjectile(input: ProjectileShotInput): ProjectilePrediction; fireProjectile(input: ProjectileShotInput): string; settleProjectile(shotId: string): SettleResult; advanceProjectiles(dt: number, time: number): SettleResult[]; activeP… — ⚠ undocumented · used by `createProjectileSystem`: Spawn and advance projectiles each frame, resolving travel, lifetime, and hits.
 - `ProjectileSystemDeps` (interface): interface ProjectileSystemDeps { effects: EffectSystem; spatial: CombatSpatialDeps; getStat(itemId: string, stat: string): number | null; raycast?: Raycast; sceneRaycast?: SceneRaycastApi; objects?: ProjectileObjectsDeps; entityCollidersOf?(instanceId: string): EntityCol… — ⚠ undocumented · used by `createProjectileSystem`: Spawn and advance projectiles each frame, resolving travel, lifetime, and hits.
+- `ProjectileSystemState` (interface): interface ProjectileSystemState — Detached projectile owner state for replay and restore.
+- `ProjectileTravelConfig` (interface): interface ProjectileTravelConfig — Captured launch settings for authoritative live travel.
+- `ProjectileTravelDeps` (interface): interface ProjectileTravelDeps — Authoritative clock, collision and environmental acceleration providers.
+- `ProjectileTravelImpact` (interface): interface ProjectileTravelImpact — Nearest contact returned by a live segment sweep.
 - `Raycast` (type): type Raycast = (from: string, aim: Aim, range: number, originPolicy?: ShotOriginPolicy) => RaycastHit[] — ⚠ undocumented
 - `RaycastHit` (type): type RaycastHit = EntityRaycastHit | ObjectRaycastHit — ⚠ undocumented
 - `SettleResult` (type): type SettleResult = | { status: "settled"; shotId: string; at: [number, number, number]; hits: EffectResult[]; origin?: [number, number, number]; } | { status: "rejected"; shotId: string; reason: string } — ⚠ undocumented
@@ -477,6 +486,7 @@
 - `RegenShieldConfig` (interface): interface RegenShieldConfig — Tuning for `createRegenShield`: pool size, refill rate, and the post-damage grace period.
 - `RegenShieldPool` (interface): interface RegenShieldPool — External storage a {@link RegenShield} reads and writes instead of keeping the value itself — an entity stat, a replicated store, a save record. This is the same port `Magazine` exposes as `MagazineReserve`, and it exists for the same reason: in most games the shield value is already owned by the stat system that damage, the HUD, and replication all read, so a primitive that insists on owning the number privately cannot be adopted without creating a second source of truth.
 - `RegenShieldRates` (interface): interface RegenShieldRates — Per-tick rate overrides, for games that derive regen from live state — a talent tree, a buff, an equipped mod — rather than a constant fixed when the shield was built. Omit to use the configured values; the grace period in effect is whichever `regenDelayMs` was last passed to `tick`.
+- `RegenShieldState` (interface): interface RegenShieldState — Complete mutable shield state, including pending external damage detection.
 - `createRegenShield` (function): function createRegenShield(config: RegenShieldConfig): RegenShield — Builds a {@link RegenShield} that suppresses regen for `regenDelayMs` after each hit.
 
 ## @jgengine/core/combat/renderCues
@@ -635,8 +645,9 @@
 
 ## @jgengine/core/stats/accumulatorMeter
 
-- `AccumulatorMeter` (interface): interface AccumulatorMeter { value(): number; fraction(): number; tier(): string | null; broke(): boolean; add(amount: number): MeterAddResult; drain(amount: number): void; reset(): void; tick(dtSeconds: number): void } — ⚠ undocumented · used by `createAccumulatorMeter`: A raw accumulating gauge that crosses named tier thresholds as a value builds, with optional decay — the primitive under charge, rage, and c…
+- `AccumulatorMeter` (interface): interface AccumulatorMeter { state(): AccumulatorMeterState; restore(next: AccumulatorMeterState): void; value(): number; fraction(): number; tier(): string | null; broke(): boolean; add(amount: number): MeterAddResult; drain(amount: number): void; reset(): void; tic… — ⚠ undocumented · used by `createAccumulatorMeter`: A raw accumulating gauge that crosses named tier thresholds as a value builds, with optional decay — the primitive under charge, rage, and c…
 - `AccumulatorMeterConfig` (interface): interface AccumulatorMeterConfig { max: number; mode?: MeterMode; decayPerSecond?: number; decayDelayMs?: number; tiers?: readonly MeterTier[] } — ⚠ undocumented · used by `createAccumulatorMeter`: A raw accumulating gauge that crosses named tier thresholds as a value builds, with optional decay — the primitive under charge, rage, and c…
+- `AccumulatorMeterState` (interface): interface AccumulatorMeterState — Mutable meter value, hold latch, and time since the last gain.
 - `MeterAddResult` (interface): interface MeterAddResult { value: number; fired: boolean; overflow: number; tier: string | null; tierChanged: boolean } — ⚠ undocumented
 - `MeterMode` (type): type MeterMode = "hold" | "reset" — ⚠ undocumented
 - `MeterTier` (interface): interface MeterTier { id: string; at: number } — ⚠ undocumented · used by `tierAt`: The highest tier id whose `at` threshold `value` has reached, or `null` below every tier — the pure lookup `createAccumulatorMeter`/`createE…
@@ -645,9 +656,10 @@
 
 ## @jgengine/core/stats/eventMeter
 
-- `EventMeter` (interface): interface EventMeter { value(): number; fraction(): number; tier(): string | null; ready(): boolean; feed(tag: string, scale?: number): EventMeterFeedResult; consume(): boolean; drain(amount: number): void; reset(): void; tick(dtSeconds: number): void } — ⚠ undocumented · used by `createEventMeter`: A heat/hype gauge that rises as tagged events land and cools between them, firing when it fills or breaks — the streak/overdrive meter shoot…
+- `EventMeter` (interface): interface EventMeter { state(): EventMeterState; restore(next: EventMeterState): void; value(): number; fraction(): number; tier(): string | null; ready(): boolean; feed(tag: string, scale?: number): EventMeterFeedResult; consume(): boolean; drain(amount: numbe… — ⚠ undocumented · used by `createEventMeter`: A heat/hype gauge that rises as tagged events land and cools between them, firing when it fills or breaks — the streak/overdrive meter shoot…
 - `EventMeterConfig` (interface): interface EventMeterConfig { max: number; mode?: MeterMode; decayPerSecond?: number; decayDelayMs?: number; tiers?: readonly MeterTier[]; gains: Record<string, number>; resets?: readonly string[] } — ⚠ undocumented · used by `createEventMeter`: A heat/hype gauge that rises as tagged events land and cools between them, firing when it fills or breaks — the streak/overdrive meter shoot…
 - `EventMeterFeedResult` (interface): interface EventMeterFeedResult { tag: string; reset: boolean; amount: number; value: number; fraction: number; fired: boolean; ready: boolean; overflow: number; tier: string | null; tierChanged: boolean } — ⚠ undocumented
+- `EventMeterState` (type): type EventMeterState = AccumulatorMeterState — Event meter persistence uses the underlying accumulator's complete state.
 - `createEventMeter` (function): function createEventMeter(config: EventMeterConfig): EventMeter — A heat/hype gauge that rises as tagged events land and cools between them, firing when it fills or breaks — the streak/overdrive meter shooters and fighters hand-roll.
 
 ## @jgengine/core/stats/rollCheck

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

@@ -1,8 +1,8 @@
 # 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
+Use this recipe when an existing project wants JGengine's combat runtimes but
+keeps its own save system, clock, entities, and authority. The runtimes expose
+detached plain state; no JGengine store or
 `GameContext` is required.
 
 ## Install and focused imports
@@ -132,18 +132,72 @@ 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.
 
+## Retune without reconstructing the magazine
+
+Equipment or upgrades can change capacity and reload duration in place:
+
+```ts
+if (!magazine.retune({ capacity: 8, reloadMs: 750 })) {
+  throw new Error("capacity would strand loaded rounds");
+}
+```
+
+Growing capacity never grants ammo. Retuning preserves loaded rounds, shared
+reserve identity/value, and elapsed reload milliseconds. A shorter duration
+can put `reloadFraction()` at 1; only the next positive `tick` completes the
+reload and draws reserve. Save the current tuning in the caller's equipment
+schema and supply it when recreating the runtime before restoring its snapshot.
+
+Shrinking below the loaded count rejects the entire tuning by default. Choose
+`overflow: "return-to-reserve"` to return exactly the excess to a finite reserve
+with `gain`, or `overflow: "discard"` to explicitly destroy those rounds. Returning
+to an infinite reserve or a read/spend-only adapter rejects without changing
+capacity, duration, or ammo.
+
+## Abilities, shields, and meters
+
+Ability kits, shields, and meters use the same save boundary:
+
+```ts
+const saved = JSON.stringify({
+  abilities: kit.state(),
+  shield: shield.state(),
+  heat: heat.state(),
+});
+const decoded = JSON.parse(saved);
+if (!kit.restore(decoded.abilities)) throw new Error("ability slot/group ids differ");
+if (!shield.restore(decoded.shield)) throw new Error("external shield pool max differs");
+heat.restore(decoded.heat);
+```
+
+`AbilityKit.state()` contains charges, separate recharge/flash/group timers,
+and retuned cooldowns/costs. `state(slotId, resourceAvailable?)` and `snapshot()`
+remain HUD views. Rebuild with the same slot/group definitions; save any bound
+resource separately. Restore never spends it.
+
+`RegenShield.state()` includes mutable bounds, pool value, grace timing, the
+active delay override, and the last external-pool observation. Restore writes
+the pool value, preserving even damage waiting to be observed on the next tick;
+the caller's pool must already have the saved max. Use `refill(amount)` for
+pickups; numeric `restore(amount)` remains a deprecated compatibility alias.
+
+`EventMeter.state()` and `AccumulatorMeter.state()` contain value, the hold
+latch, and the decay-delay timer. Rebuild with the same meter configuration.
+For caller-owned visibility policy, `heat.tick(dt, !sourceVisible)` pauses both
+decay and its delay while seen; omitting the second argument advances normally.
+
 ## 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,
+JGengine owns the closure convenience methods, state 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
+- Re-supply current tuning such as magazine capacity/reload duration
+  and immutable configuration such as 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

package/skills/jgengine-combat/recipes/portable-weapon-plumbing.md

@@ -123,14 +123,48 @@ exposes `elapsedMs()`/`restore()` for HUD and snapshots:
 ```ts
 const snapshot = {
   cadenceMs: rifle.cadence.elapsedMs(),
-  loaded: rifle.magazine?.loaded() ?? null,
+  magazine: rifle.magazine?.snapshot() ?? null,
 };
 // After load: recreate the runtime from the same config, then:
 rifle.cadence.restore(snapshot.cadenceMs);
+if (snapshot.magazine !== null && !rifle.magazine?.restore(snapshot.magazine)) {
+  throw new Error("magazine reserve configuration differs");
+}
 ```
 
-Recreate the magazine at its saved `loaded` via `MagazineConfig.loaded`. (Full
-magazine snapshot/restore lands with the serializable-runtime-state slice.)
+Restore caller-owned reserve storage first. Recreate with the current equipment
+capacity/reload duration, then restore the full magazine snapshot; see the
+[portable runtime-state recipe](portable-runtime-state.md) for live retuning.
+
+## Scene-backed projectiles and spread
+
+When a project already uses `createProjectileSystem`, keep its
+`fireProjectile(input)` → `settleProjectile(shotId)` call path. Pass authoritative
+seeded randomness as `ProjectileSystemDeps.rng`. A nonzero `Aim.spread` (degrees)
+or item `spread` samples an independent uniform solid-angle cone for each pellet
+(the half angle is clamped to 90 degrees);
+`pellets` chooses the count. Each sampled ray resolves its own nearest eligible
+receiver and cover. An explicit `{ origin, direction }` aim remains an exact ray.
+`willHitProjectile` stays a center-ray preview and consumes no randomness.
+
+GameContext forwards its authoritative RNG to the projectile system. Standalone
+callers must inject one for reproducible shots; the fallback is `Math.random`.
+Aim fields, explicit ray vectors, and the chosen origin-policy vectors are copied
+at fire time before RNG callbacks, so reusing caller input cannot redirect an
+in-flight shot. The default policy is copied for each shot too. World entities
+and colliders remain queried at settlement time.
+Two RNG draws are captured at fire time per nonzero-spread pellet. Settlement
+preserves the selected eye/muzzle/converge origin, named hitboxes, LOS, and
+blocking colliders. Ballistic paths are unchanged. `maxPellets` defaults to 64
+and clamps to [1, 256] to bound per-shot ray work. Zero-spread pellets each hit
+the nearest receiver; they no longer cycle through receivers down one ray.
+
+Scrap Signal is the first adopter: `items/use-handlers.ts` already calls these
+projectile APIs, and its Breacher adds pellet/range/ammo tradeoffs. Its combat
+adapter also needs `Magazine.retune` for live equipment/talent changes without
+reconstructing ammo state. Games remain on published packages until the
+coordinator verifies and unlocks the SDK release; these adoption points do not
+claim native play against unpublished code.
 
 ## Ownership
 

package/skills/jgengine-combat/reference.md

@@ -34,6 +34,8 @@ interceptors). See the [portable damage/effects recipe](recipes/portable-damage-
 
 ## Effects and projectiles
 
+Cold projectile restore requires the receiving owner's pellet limit and radius-aware sweep to support the captured launch. Incompatible or inconsistent pellet, cone-sample and flight counts reject atomically; never truncate saved flights or discard pending settlements.
+
 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
@@ -61,15 +63,35 @@ settleProjectile(shotId)                        // authoritative → { at, hits
 
 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.
 
+`defineGame({ projectileTravel })` accepts `GameProjectileTravelOptions` from
+`@jgengine/core/game/defineGame`: the existing `maxActive`, `maxRetained` and
+`maxTargets` budgets plus `sweep(ctx, from, to, step)`,
+`acceleration(ctx, position, velocity, time, input)` and `targets(ctx)`.
+Each callback receives the live context of that world, including when one
+definition hosts multiple worlds; the authoritative clock remains engine-owned.
+Supply a radius-aware `sweep` for finite-radius travel through authored cover.
+The default cover query supports radius zero and rejects larger radii.
+`targets` selects bounded entity IDs for the default moving-target query;
+omission selects that world's entities, and exceeding `maxTargets` (default
+2048) throws instead of dropping blockers. A custom sweep owns its complete
+collision policy, including cover and receivers.
+Supplied `acceleration` fully replaces the authored sampler; call
+`ctx.environment.accelerationAt(position, time, windResponse, maxAcceleration,
+forceMask)` explicitly when composing authored forces. Omitting it keeps the
+authored sampler. Providers are unsaved world policy; projectile snapshot and
+restore retain launch and motion state and use the receiving world's providers.
+
 ## 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`.
+- `DeathReason = { kind: "player_kill", killerUserId, via? } | { kind: "environment", source } | { kind: "self", source }`. Local players, hosted members and uniquely owned pawns attribute automatically. `ctx.player.possession.ownerOf(entityId)` resolves recorded ownership without inventing an owner; shared ownership is ambiguous and returns `undefined`.
+- `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.runAs` with the resolved killer. XP commands, quest kill events and loot therefore use the same actor identity on a remote host.
 - `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`).
+- Non-player kills suppress runtime loot by default. To opt an item table into environmental or unowned deaths, author `onDeath: { dropMode: "world", drops: [{ table: "salvage", when: { reason: "any" } }] }`. Only explicit `"any"` tables spawn in this case; neighboring ordinary tables stay suppressed. Bag grants and currency still require a resolved player killer, including when the table uses `"any"`.
 - 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.
+- `ctx.hydrate` and `ctx.restore` also revive restored entities whose terminal receive pools are above their minima. Snapshots captured inside `entity.died` still contain the victim before despawn; their depleted terminal pools retain the duplicate-death guard.
 - `quest.bind("entity.died")` credits kill objectives from the same event; leaderboards and kill feeds hang off it too.
 
 ## Damage interception and threshold transitions

package/skills/jgengine-gameplay/SKILL.md

@@ -11,10 +11,47 @@ This skill owns non-combat rules and state: systems, catalogs, inventory/items,
 
 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.
 
+For multi-cell inventory items, use `createShapedGrid`, `canPlace`, and
+`findShapedPlacement` (`inventory/shapedGrid`). The caller owns item footprints,
+rotation policy, saves, and UI; [shaped inventory placement](recipes/shaped-inventory.md)
+shows bounded first-fit search. A stack-slot `InventoryGrid` does not replace
+footprint rotation or spatial packing.
+
 Existing projects can keep player state and saves behind `LevelingStatAccess`.
 Follow the [portable XP/leveling recipe](recipes/portable-xp-leveling.md) for
 custom stat ids, immutable store writes, multiple level events, and JSON resume.
 
+Persist rolled items with `createItemInstanceRegistry` (`item/itemInstanceRegistry`):
+`state()` detaches definitions, runtime ids, prefix, and allocation sequence;
+`restore(state)` replaces the registry and rejects a different prefix. Keep
+definitions structured-cloneable and JSON-compatible for JSON saves. Save the
+inventory's returned runtime ids alongside this state; do not regenerate rolls
+or infer the next id from the surviving items.
+For large collections, inject caller-owned `ItemInstanceStorage` and use
+`statePages(pageSize)` / `restorePages(pages)` to clone one batch at a time.
+Follow the [paged item storage recipe](recipes/paged-item-storage.md) for
+atomic replacement, allocator reattachment, and export consistency.
+
+Generate coherent combinations with `generate` (`item/itemgen`): dependent
+pools and `GenStep.accept` constrain later choices using earlier picks.
+Pins consume no choice RNG and must satisfy the same pool and constraints;
+incompatible pins backtrack earlier unpinned choices or return `unsatisfiable`
+within the configured attempt and pick budgets.
+
+Validate generated quest catalogs with `validateQuestCatalog` (`game/questCatalog`).
+Follow the [quest authoring recipe](recipes/quest-authoring.md) for bounded batches,
+canonical facts, external unlock declarations, and precise repair diagnostics.
+
+For cross-catalog sources and skill gates, compose `validateContentReferences` and
+`validateContentProgression` (`game/contentValidation`) with `validateRecipeCatalog`
+(`crafting/recipeCatalog`). Follow [content validation](reference-content-validation.md).
+Games declare complete sources before treating blocked routes as errors; costs,
+consumption, exclusive choices, story and balance still need game-owned playtests.
+
+For generated chapter dialogue, use the [narrative authoring recipe](recipes/narrative-authoring.md)
+and `npx jgengine recipe narrative-authoring`: freeze reviewed canon, validate
+bounded batches, repair located issues and require explicit semantic approval.
+
 ## Canonical workflow
 
 1. Define plain serializable state and stable ids.
@@ -26,6 +63,16 @@ custom stat ids, immutable store writes, multiple level events, and JSON resume.
 
 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.
 
+For staffed production, use `stationOutputRate` (`work/staffedStation`) to resolve
+caller-owned worker stats and efficiency, then feed the rate to `tickProduction`.
+Keep staffing and production progress in the same serializable store; the
+[staffed production example](reference-systems.md#staffed-production) composes
+the existing scheduler and save/reset boundaries without a separate manager.
+
+For whole-world saves, follow [authoritative state](reference-systems.md#authoritative-state); persistence and client replication use separate context methods.
+Follow [truthful device saves](recipes/device-save-status.md) for denied storage,
+quota errors, checkpoint retry, and save status UI.
+
 ## Design rules
 
 - Caller data owns nouns, formulas, tables, costs, tiers, and content.
@@ -34,6 +81,15 @@ Prefer `defineSystem` and `defineGame({ systems })` for scheduled capabilities.
 - Random selection accepts injected RNG and stable ordering.
 - Large collections use indexes, queues, or bounded reconciliation rather than repeated scans.
 
+Quest journals index active objectives by kill target and collected item. Bind
+`entity.died` and `inventory.added` once and keep the returned unsubscribe handles;
+credit follows catalog order, and quests activated by a credit callback join the
+next event. Register replacement definitions after editing objective targets,
+items, or party-sharing policy. Save hydration rebuilds the active indexes.
+Shared kills query nearby party members for matching objectives active on any
+user, so the killer need not have that quest; direct kills and collection only
+visit the actor's matching active objectives.
+
 ## Part-composed character motion
 
 A character kit-bashed from primitives/`ModelPart`s (no skeleton, no clips) animates procedurally: tag parts with `role` (`leg.l`, `arm.r`, `head`, `tail`, `wing.l`…) and the shell's part-motion rig drives counter-phase limb swing from the entity's live movement speed, idle breathe/sway, hit flinch on `combat.hitReaction`, and a death topple on `entity.died` — no game-side frame loops. Tune with `ModelConfig.partMotion`; curves are pure and deterministic (`@jgengine/core/game/partAnimation`), so crowds de-sync by instance-id phase and replays stay stable. Soft characters (blobs, slimes) opt into volume-conserving squash-and-stretch with `partMotion: { squashAmp }` — footfall squash, jelly idle breathe, flinch pulse — and `deathStyle: "splat"` flattens out on death instead of the default sideways topple. Rigged GLBs keep using `ModelConfig.animation` — roles are only for rig-less compositions.
@@ -55,3 +111,10 @@ A character kit-bashed from primitives/`ModelPart`s (no skeleton, no clips) anim
 - Reset a profile with `initialPlayerState(runtime, userId)` from the same `onNewPlayer` hook used at join; insolvency never deletes a world.
 - `ctx.game.chat.send(userId, text)` targets global chat; `recent({ limit })` returns at most 100 messages. The default is 240 characters and one message per author per channel every two seconds. Rejected messages need visible UI feedback.
 - Hosts reuse `validateChatMessage` and `decideRateWindow`, storing the rate window transactionally with each accepted operation. Preserve chat rate windows when saving/restoring chat state.
+
+For timed away missions, compose the pure transitions in `work/expedition` with
+your existing `defineStore` and clock. The [expedition recipe](recipes/expeditions.md)
+keeps bounded offline catch-up, finite supplies, return/death, capacity and RNG
+continuity in one plain saveable state. Authored encounters, hazard/supply policy,
+loot tables, quality ramps and text remain caller-owned; use `timeScaledRarity`
+(`game/lootModifiers`) for elapsed-time odds with pipeline provenance.