@jgengine/core 0.19.0 → 0.22.0

package/skills/jgengine-gameplay/reference-systems.md

@@ -2,6 +2,23 @@
 
 Single public authoring path: `defineGame({ systems, loop?, … })` from `@jgengine/shell/defineGame`. Systems are meaningful capabilities — not micro-ticks.
 
+## Authoritative state
+
+Use `ctx.state()` / `ctx.restore(state)` for detached whole-world persistence, including economy, clock, movement pose, possession, progression and registered system saves. These work without `persist` or a save backend. `ctx.snapshot()` / `ctx.hydrate()` remain client replication and omit save-only modules. `createRuntimeSave({ target: ctx, backend })` selects the authoritative pair automatically; existing snapshot-only targets still work.
+
+Restore after initialization has registered every system. Missing keys in older saves retain initialized values; unavailable historical economy/progression cannot be recovered by the engine. Keep a game's legacy migration until its older saves have been converted. Simulation tick and pose-buffer state persist, but callbacks, timers and game-owned closures must be registered/reconstructed at boot or exposed through a system save module.
+
+Declare `persist: { version, migrate(data, fromVersion) }` to convert incompatible
+older whole-world saves before restoration. Raw payloads use version 0; matching
+versions bypass the hook. Throw to reject a missing historical runtime module:
+load returns false, leaving the initialized world and stored
+save untouched. A version number alone preserves compatible mismatch loading;
+it is not a rejection gate. Migration exceptions retain the save store's existing
+decode fallback to initial data with idle status; they are not backend errors.
+Explicit context `save` options override `persist`.
+
+`ctx.sim.advance(realDt, (stepDt, tick, gameDt) => ...)` owns advancement of `ctx.time` once per simulation step. Use the third argument for scaled gameplay time and `stepDt` for movement; remove manual `ctx.time.advance` calls inside simulation callbacks. Movement prediction opts out with `{ advanceTime: false }` and must not run authoritative gameplay stages. Standalone clocks retain their explicit `advance` API.
+
 ## Portable XP and leveling
 
 `leveling` (`@jgengine/core/game/progression`) is usable without a scheduled
@@ -11,6 +28,36 @@ and level state, then emits every reached level in ascending order. State stays
 in the caller's save format and round-trips as ordinary JSON. See the
 [portable XP/leveling recipe](recipes/portable-xp-leveling.md).
 
+## Coherent authored content
+
+Keep stable ids and canonical facts for characters, factions, places, and world rules in the game's authored data. Record each chapter's prerequisites, consequences, and which facts it may introduce or change. The game's creative pillars, story voice, content palette, and desired player experience come from its author; generated prose, items, art, and assets must serve those constraints. Reuse constrained generation and validation code across games while each game owns its content and visual identity; do not fill catalogs from default genre kits or mass generic content.
+
+Generate bounded chapter or catalog batches against those facts and existing definitions. Validate references and dependencies before merging each batch, giving humans and agents precise repair locations early to reduce failed retries and speed up game creation. Preserve reviewed facts across batches instead of asking a model to recreate the world from memory. `QuestDef.requires` accepts completed quest ids or unlock ids, so dependency checks must include the game's declared unlocks rather than treating every requirement as a quest. Check reward quest ids and objective/item references against their owning catalogs too.
+
+Use `validateQuestCatalog` (`@jgengine/core/game/questCatalog`) before registering quest batches. Declare unlocks supplied by other systems with `externalUnlocks`, and quest grants that bypass acceptance with `externallyStartedQuests`. Catalog reward unlocks are recognized automatically. `hasReference` optionally checks item, target, inventory, and currency ids against caller catalogs. Duplicate ids, missing references, and invalid quantities are errors; blocked prerequisites and dependency cycles are warnings under a model where any eligible quest may be accepted and its objectives completed. External grants can change actual reachability. Follow the [quest authoring recipe](recipes/quest-authoring.md) and `npx jgengine recipe quest-authoring` for SDK-typechecked bounded generation and repair locations.
+
+For repeated authoring and repair, follow the [narrative authoring recipe](recipes/narrative-authoring.md). It freezes a reviewed canon revision, bounds dialogue batches and checks explicit character/fact/event-order claims before an injected semantic reviewer approves. New canon is a separate author decision.
+
+Validate dialogue structure before opening a conversation:
+
+```ts
+import { validateDialogueGraph, type DialogueGraph } from "@jgengine/core/game/dialogueGraph";
+
+function reviewDialogue(graph: DialogueGraph) {
+  const issues = validateDialogueGraph(graph);
+  const errors = issues.filter((issue) => issue.severity === "error");
+  return { publishable: errors.length === 0, issues };
+}
+```
+
+The validator locates duplicate ids, missing start/choice targets, unreachable nodes, and nodes without a route to an ending in linear time without recursive traversal. Loops with an exit are valid. Review warnings against intended entry points and conversation behavior; unreachable nodes may be entered with `goTo`, and closed loops may be deliberate. Run validation on authored batches, outside the frame loop.
+
+Structural validity cannot establish story coherence. Review generated content for contradictions with canonical facts, character motivations, chronology, and meaningful consequences; play representative paths and check that choices support the intended experience. Large item counts need useful distinctions, economy balance, discoverability, and bounded runtime lookup. Counting generated items or passing reference checks alone does not establish those qualities.
+
+Quest item rewards use a whole-batch grant before XP, currency, and unlocks. `ctx.game.quest` stages every item against the declared inventories and commits only when all fit, including cumulative capacity in one bag. Capacity/kind/unknown-inventory rejections leave inventories and quest status unchanged, so the player can make room and retry. Inventory commits still notify subscribers synchronously; this does not roll back thrown observer exceptions or arbitrary callback side effects.
+
+Custom `createQuestJournal` dependencies and `applyQuestRewards` appliers must supply `grantItems` for multiple item rewards. The callback grants the entire batch or returns a rejection without writes; implement staging or a transaction in the owning store. Legacy `grantItem` remains supported for a single reward. Multiple rewards without `grantItems` reject before any grant. Keep callbacks nonthrowing; external stores own exception handling and durable transaction boundaries.
+
 ## API
 
 ```ts
@@ -64,6 +111,78 @@ Default stages: fixed `input → movement → combat → ai → activities → c
 - **Save / replicate** — system modules register via `ctx.game.registerSave` / `registerReplicate` at install.
 - **Reset / dispose** — `loop.onReset` / `loop.onDispose` (composed) run system hooks.
 
+Each context owns its installed schedules and listeners, even when worlds share
+one game definition. Retirement removes listeners, disposes systems in reverse
+install order, then invokes the classic loop's disposal hook (including shell
+environment cleanup). Every cleanup is attempted; the first thrown value is
+rethrown afterward. Reentrant or repeated disposal does not invoke hooks again.
+Retired installed handles ignore tick, reset and manual work. `onInit` after
+retirement starts a fresh schedule/listener lifecycle; `onReset` resets an active
+lifecycle and does not reinstall it. Failed installation retires every entered
+system, including one whose `create` throws, and acquired listeners before
+rethrowing the startup error. The caller still retires the classic loop (the
+shell does so on initialization failure). Save/replication registrations are not
+transactional or withdrawn by disposal; discard a failed context, and use a fresh
+context when rebooting systems with registered modules.
+
 ## Snapshot and restore on stateful handles
 
 These handles hand back a plain JSON `snapshot()` that later ticks do not mutate, and take it back with `restore(next)`, so a host, save file or replay can rewind them bit-exactly: `game/lootTable` `createLootRegistry` (registered tables; not JSON when an entry uses `generate`), `game/toasts` `createToastQueue`, `game/vfxInstance` `createVfxInstanceStore` (restore emits `stop` then `upsert` so the renderer follows), `session/roundState` `createRoundState` (`RoundSnapshot` now carries `pendingWinner`), `input/lookChannel` `createLookChannel`, and `input/pointer` `createDragCapture` (`state()` out, `restore(state | null)` in).
+
+## Staffed production
+
+`stationOutputRate` (`@jgengine/core/work/staffedStation`) converts a plain staffing
+snapshot to cycles per game-second: `(base + perStat * sum(worker.stat)) * efficiency`.
+Only the first `floor(slots)` workers contribute, in caller order. Empty staffing
+keeps base output; set `base: 0` to require workers. Efficiency defaults to one and
+clamps to 0…1. Negative/nonfinite contributions are zero, nonfinite slots admit no
+workers, and nonfinite efficiency or an overflowing result returns zero.
+
+The caller owns unique worker ids, assignment/release policy, stat selection,
+modifiers, happiness, and tuning. Resolve numeric contributions from your stat
+store before writing staffing: one station might read `stats.get("strength")`,
+another `stats.get("agility")` with equipment modifiers. Invalid contributions
+still occupy their ordered slot; the function does not promote overflow workers,
+allocate collections, or mutate saved staffing.
+
+```ts
+import { stationOutputRate, type StaffedStation } from "@jgengine/core/work/staffedStation";
+import { createProductionState, productionBuilding, tickProduction, type ProductionState } from "@jgengine/core/crafting/production";
+import { defineStore } from "@jgengine/core/store/defineStore";
+import { defineSystem } from "@jgengine/core/game/defineSystem";
+
+const room = defineStore<{
+  staffing: StaffedStation;
+  efficiency: number;
+  production: ProductionState;
+}>("workshop", () => ({
+  staffing: { stationId: "workshop", slots: 2, workers: [] },
+  efficiency: 1,
+  production: createProductionState(),
+}));
+const recipe = productionBuilding({
+  id: "workshop", outputs: [{ itemId: "supplies", count: 1 }], rate: 0,
+});
+export const staffedProduction = defineSystem({
+  id: "staffed-production",
+  tick: { type: "fixed", rate: 4 },
+  update(ctx, dt) {
+    room.update(ctx, previous => ({ ...previous,
+      production: tickProduction({ ...recipe,
+        rate: stationOutputRate(previous.staffing, {
+          base: 0, perStat: 0.5, efficiency: previous.efficiency,
+        }),
+      }, previous.production, { dt }),
+    }));
+  },
+  reset(ctx) { room.clear(ctx); },
+});
+```
+
+Install the system via `defineGame({ systems: [staffedProduction] })`; write the
+caller-resolved worker snapshot with `room.update`. Production input buffers,
+output counts, partial-cycle seconds, staffing, and efficiency remain plain data
+in the same store. `ctx.state()`/`ctx.restore()` save and replace that data; reset
+restores the declared initial room. Persist progress, not just staffing, to avoid
+restarting an in-flight batch. Input reservation and power gating continue to use
+`feedProduction` and `tickProduction({ ...recipe, rate }, state, { dt, powered })`.

package/skills/jgengine-world/SKILL.md

@@ -19,7 +19,7 @@ For a *connected* walkthrough that wires several primitives into a running loop,
 - [recipes/vehicle-feel.md](recipes/vehicle-feel.md) — feel target → handling metrics → physical knobs for a ground vehicle, plus the camera, sound and rumble hooks that hang off its telemetry.
 - [recipes/flight-feel.md](recipes/flight-feel.md) — an aircraft as physical numbers: surfaces, inertia and engine, with the symptom → knob table for how it flies.
 - [recipes/controls.md](recipes/controls.md) — actions → layered contexts that rebind live → keyboard, touch and gamepad on the same actions → per-axis feel.
-- [recipes/character-animation.md](recipes/character-animation.md) — clips → graph → rig → ground: data-driven state machines, triggers and clip events, root motion, foot IK that keeps feet on slopes, and instanced crowds.
+- [recipes/character-animation.md](recipes/character-animation.md) — clips → graph → rig → ground: modular instance visibility, data-driven state machines, triggers and clip events, root motion, foot IK that keeps feet on slopes, and instanced crowds.
 
 ## Canonical workflows
 
@@ -31,15 +31,19 @@ A world is the place you play in: substrate + laws, via `world()` from `@jgengin
 
 1. Load the scene document through the shared authored-scene feature.
 2. Render objects, paths, terrain, foliage, and markers generically.
-3. Query the same ids/layers for spawns, routes, plots, and interaction.
+3. Query the same ids/layers for spawns, routes, plots, and interaction. The shell batches compatible static catalog props above eight placements per 24 m cell, preserving chosen models, material groups, shadows, measured colliders and object ids for picking. Interactive/custom props, per-object visual/style overrides, and animated, rigged, composed, transparent or mirrored models keep individual renderers. Runtime compatibility changes return a placement to its individual renderer. Visibility compacts each batch to the current visible placements.
 4. Collision for generated and studio content comes from its data through `ctx.world.solids`; never hand-place invisible blockers for it (see reference.md, World solids).
 5. Keep derived caches rebuildable; the document remains authoritative.
 
+For existing `environment()` consumers, `defineGame` overlays only defined editor sky fields on the legacy sky, retaining settings the editor cannot represent; an explicit `backdrop.sky` remains authoritative.
+
+For environment-driven surface appearance, sample only selected targets through `material/appearanceSignals`; wetness already includes shelter. Capture the assigned material's dry baseline, apply explicit wet endpoints, and restore it on unbinding. Keep wind in geometry/simulation consumers and local card backlighting separate from scene exposure. See [reference.md](reference.md#environment-fields-weather-hooks--realm-composition).
+
 ### Movement and interaction
 
 Choose input intent, controller/motor, collision/navigation, and camera as separate seams. Commands express game intent; world systems resolve motion. Interaction targets come from bounded spatial/sensor queries, not full-world scans.
 
-Walk feel is data, not code. `movement.feel` sets `groundAcceleration`, `airAcceleration` and `groundFriction` (response rates, 1/s) plus `runMultiplier`, `crouchMultiplier`, jump forgiveness (`jumpBufferMs`, `coyoteMs`) and jump shape (`jumpCutFactor`, `apexGravityScale`, `fallGravityScale`, `landingRecoveryMs`), and `physics` sets `gravity` and `jumpVelocity`. A floaty platformer and a weighty shooter differ only in these numbers; pin them with `measureMovement` (`movement/movementProbe`) in a test.
+Walk feel is data, not code. `movement.feel` sets `groundAcceleration`, `airAcceleration` and `groundFriction` (response rates, 1/s) plus `runMultiplier`, `crouchMultiplier`, jump forgiveness (`jumpBufferMs`, `coyoteMs`) and jump shape (`jumpCutFactor`, `apexGravityScale`, `fallGravityScale`, `landingRecoveryMs`), and `physics` sets `gravity` and `jumpVelocity`. The heightfield and capsule paths share these feel controls; voxel jumping retains its press-frame policy. Crouch follows supported catalog poses, and capsule standing requires headroom. Pin numeric movement behavior with `measureMovement` (`movement/movementProbe`) in a test.
 
 ### Stateful placed objects
 
@@ -49,8 +53,12 @@ Per-instance state belongs on the placement, not in a game-owned map keyed by `i
 
 Compose perception, selection, planning/behavior, movement, and lifecycle independently. Inject randomness and scheduling. Use spatial indexes, interest tiers, or bounded candidate sets for scale.
 
+For chase-to-reach and cooldown effects, attach `pursue({ aggroRadius, reach, leashRange, speed, attack })` as behavior data. The host schedules acquisition and solid-aware movement; `behaviorControl` exposes pause/reset and optional threat. Pursuit progress survives GameContext save/replication without a game-local home/cooldown map. For allies or neutral players, configure `defineGame({ pursuit: { eligible(ctx, selfId, candidateId) { /* bounded caller policy */ } } })`; the predicate receives the current world and constrains nearest, held, explicit and forced targets. Bind the receiving world's policy data before advancing after a cold restore. Omission keeps the all-player default; see the reference for faction composition. Use a decision graph and navigation actions when a route or richer perception policy is required.
+
 NPC decisions are a `decisionGraph` behavior: the graph and its blackboard are data, actions are registered by name, and perception or game systems write facts into `behaviorControl(ctx).blackboard(id)` rather than actions querying the world. Set `thinkInterval` so crowds think a few times a second, not every frame, and release movement or claims in `onAbort`.
 
+For a bounded local detour over movement collision geometry, use `planSolidRoute` (`nav/solidRoute`) with an indexed `solidObstaclesNear` or `sourceObstaclesNear` query. Handle `no-path` and `budget` separately; retain caller movement, goals, terrain and retry policy. See [reference.md](reference.md#local-collision-routes) for limits.
+
 Route on a polygon nav mesh through one `createNavMeshQuery(mesh)` per mesh; price terrain and gate doors with `areaCosts` via `retune`, and keep `maxNodes` bounded so a long request returns a `partial` route instead of stalling a frame.
 
 ### Fallback-seam diagnostics
@@ -64,6 +72,7 @@ Render seams fall back to placeholders when content is unauthored: default green
 - Do not duplicate editor coordinates in runtime state.
 - Public APIs accept semantic policies and caller data, not renderer mechanics or internal tuning rolls.
 - Generated environments still need deterministic data assertions; authored environments need scene-document assertions.
+- Bound SFX through `PlayableGame.audio.maxVoices` and game-owned `SoundDef.priority`/`maxVoices`; choose reject or deterministic stealing with `voiceOverflow`. See the spatial audio reference for custom hosts and cleanup.
 - Audio files and licensing belong to `jgengine-assets`; spatial playback policy belongs here.