@jgengine/core 0.18.1 → 0.21.0

package/skills/jgengine-combat/capabilities.md

@@ -120,7 +120,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createEncounterState` (function) · `import { createEncounterState } from "@jgengine/core/combat"`
 
-## event-meter — a heat/streak gauge that builds from repeated hits and cools down over time
+## event-meter — a heat/streak/alert gauge (wanted level, rage, combo) that builds from repeated events and cools down over time
 
 - `createEventMeter` (function) · `import { createEventMeter } from "@jgengine/core/combat"`
 
@@ -128,6 +128,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createFireCadence` (function) · `import { createFireCadence } from "@jgengine/core/combat"`
 
+## global-cooldown — share one cooldown across every ability slot (MMO global cooldown) with a cooldown group
+
+- `createAbilityKit` (function) · `import { createAbilityKit } from "@jgengine/core/combat"`
+
+## hitscan-shot — aim a hitscan shot (shoot a gun): resolve origin and direction from the eye or muzzle for a raycast
+
+- `resolveShot` (function) · `import { resolveShot } 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"`
@@ -141,6 +149,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createMagazine` (function) · `import { createMagazine } from "@jgengine/core/combat"`
 
+## on-death-drops — make a killed enemy drop loot on the ground or into the killer's bag via catalog onDeath
+
+- `OnDeathSpec` (interface) · `import { OnDeathSpec } 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"`
@@ -236,6 +248,22 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `vfxPresets` (const) · `import { vfxPresets } from "@jgengine/core/combat"`
 
+## weapon-feedback — turn weapon shots, recoil kick and impacts into per-tick feedback-mixer signals for camera shake, audio and rumble
+
+- `createWeaponFeedbackSignals` (function) · `import { createWeaponFeedbackSignals } from "@jgengine/core/combat/weaponFeedback"`
+
+## weapon-handling — recoil patterns with camera kick and recovery, spread bloom, stance multipliers and ADS as serializable state
+
+- `createWeaponHandling` (function) · `import { createWeaponHandling } from "@jgengine/core/combat/weaponHandling"`
+
+## weapon-metrics — measure a weapon's feel as numbers — spread per shot, climb over a magazine, reset time, ADS time, time-to-kill at a range
+
+- `measureWeapon` (function) · `import { measureWeapon } from "@jgengine/core/combat/weaponHandling"`
+
+## weapon-presentation — per-weapon viewmodel offset, ADS pose, viewmodel FOV, sway, bob and recoil kick from a weapon handling frame
+
+- `createWeaponPresentation` (function) · `import { createWeaponPresentation } from "@jgengine/core/combat/weaponPresentation"`
+
 ## 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-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/recipes/weapon-feel.md

@@ -0,0 +1,50 @@
+# Recipe — weapon feel (feel target → metrics → handling knobs)
+
+**What this wires:** a weapon that handles the way the brief says, from the shot to the camera, sound and rumble. There is no default rifle or shotgun: every weapon is a set of angles in radians and times in seconds that the game picks, checked against numbers it writes down first. A looter shooter's generated guns are the same fields, rolled from the game's own parts tables.
+
+## The seams
+
+- **Cadence and ammo.** `createWeaponRuntime` or `weaponFire` + `magazine`, per the [portable weapon-plumbing recipe](portable-weapon-plumbing.md). Each time the cadence fires, call `handling.fire(stance)`.
+- **Handling.** `createWeaponHandling(tuning, { random: ctx.rng })` from `@jgengine/core/combat/weaponHandling`.
+  - `recoil`: a `pattern` of `[pitch, yaw]` kicks per shot (or a flat `pitch`), `randomCone` from the injected RNG, `cameraShare` (view punch versus aim kick), `recoverRate`/`recoverDelay`, `adsScale`.
+  - `spread`: `base`, `perShot` bloom, `max`, `recoverRate`/`recoverDelay`, and `ads`/`crouching`/`moving`/`airborne` multipliers.
+  - `adsTime`.
+  - Sample the shot direction inside `fire().spread`. Add `tick(dt, stance).aimPitch/aimYaw` to the aim and `cameraPitch/cameraYaw` to the view only.
+  - `snapshot`/`restore` for prediction and replay; `retune` for attachments, parts and upgrades mid-fight.
+- **Presentation.** Return `{ handling: handling.frame(), presentation }` from `camera.weapon(entityId)`, with a `createWeaponPresentation` tuning (`@jgengine/core/combat/weaponPresentation`): `hip`/`ads` viewmodel offsets, `viewmodelFov`, `adsZoom`, `sway`, `bob` and `kick`. The `first` rig poses the viewmodel, adds recoil to the look and zooms with `adsProgress`. The `shoulder` rig takes its ADS framing and recoil from the same frame.
+- **Feedback.** `createWeaponFeedbackSignals()` from `@jgengine/core/combat/weaponFeedback`.
+  - Call `signals.shot(handling.fire(stance))` on each shot and `signals.impact(damage)` when a hit lands.
+  - Each tick, `mixer.update(dt, signals.read(handling.tick(dt, stance)))` on a `createFeedbackMixer` (`@jgengine/core/vfx/feedbackMixer`) the game declares.
+  - `kick`, `shot` and `impact` are one-tick pulses. Route `kick` without smoothing into a trauma target and pass it to `createCameraShake().add(...)` (`@jgengine/core/vfx/cameraShake`), so trauma lands once per shot.
+  - Route `impact` with a `release` into rumble targets for `ctx.input.rumble`, rate-limited to about 10 Hz. A threshold `event` on `impact` gives a hit-confirm one-shot.
+  - Play the gunshot once per `shot` count. `ads` and `spread` suit continuous targets such as a muffled gun tail or a HUD crosshair gap.
+- **Proof.** `measureWeapon(() => createWeaponHandling(tuning), { interval, burst, damage, pellets, targetHealth, range, targetRadius, damageAt, stance })` returns deterministic numbers:
+  - `spreadByShot`, `firstShotSpread` and `tenthShotSpread`.
+  - `burstClimb`: set `burst` to the magazine size for climb over a magazine.
+  - `resetSeconds` and `adsSeconds`.
+  - `shotsToKill` and `timeToKill`: expected damage, where each projectile hits by the share of its cone the target covers at `range`, scaled by the game's `damageAt` falloff.
+
+## Workflow
+
+1. **Write the feel as numbers** on the `WeaponReport` fields. Some examples:
+   - "Laser beam when aimed" is `spreadByShot[29] < 0.01` rad with `stance: { ads: true }`.
+   - "Controllable" is `burstClimb` under about 3° over the magazine and `resetSeconds < 0.5`.
+   - "Close-range only" is `timeToKill` at 5 m near `0` and above 2 s at 30 m.
+   - "Snappy sights" is `adsSeconds < 0.2`.
+2. **Put them in a test** next to the tuning, one `measureWeapon` call per weapon or per rolled part set.
+3. **Move one knob at a time** using the table below, and rerun after each change.
+4. **Fire it** in the game (`bun run drive <game> --record <name>`, per `jgengine-verify`). The tests prove the numbers; the recording proves the kick, shake and sound read right.
+
+## Symptom → knob
+
+| Symptom | Knob (direction) |
+| --- | --- |
+| Muzzle climbs out of control over a magazine | `recoil.pattern` pitch ↓, `recoverRate` ↑, `recoverDelay` ↓ |
+| Kick feels weak but aim stays true | `cameraShare` ↑: more view punch, same aim |
+| Spray is unlearnable | `randomCone` ↓, keep the drift in `pattern` |
+| Accurate forever while held | `spread.perShot` ↑, `max` ↑ |
+| Bloom never settles between bursts | `spread.recoverRate` ↑, `spread.recoverDelay` ↓ |
+| Hip fire too good versus aiming | `spread.ads` ↓, `recoil.adsScale` ↓ |
+| Sights feel sluggish | `adsTime` ↓ |
+| Shotgun kills at sniper range | `spread.base` ↑ or a steeper `damageAt` falloff |
+| Every shot shakes the same | route `kick` through a `curve` so the shake scales with the kick |

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.