@jgengine/core 0.18.1 → 0.21.0

package/skills/jgengine-gameplay/reference-content-validation.md

@@ -0,0 +1,74 @@
+# Validate references and declared progression
+
+Run these pure validators during authoring, build or CI, never per frame. Decode
+external JSON into typed definitions first. Preserve authored array order and
+stable ids so repeated validation returns identical located diagnostics. Each
+`ContentIssue` carries `contentId`, a caller document `path`, and a `repair` action.
+For a bounded generated batch, validate its dependency-complete reviewed catalog,
+repair the located fields, then validate again before registration.
+
+`validateContentReferences` (`@jgengine/core/game/contentValidation`) indexes
+`{ kind, id, path }` definitions once and checks located
+`{ kind, id, path, contentId }` references. A namespace can describe a game-owned
+role: referencing a `questgiver` checks the role rather than merely the existence
+of an NPC. Do not derive roles from names or parse dialogue prose. Validate explicit
+dialogue command arguments against the appropriate namespace.
+For relationships stricter than existence, set a reference's `allowedIds` from
+the game's declared rule, such as this giver's quests or this record's key.
+An existing but disallowed id reports `inconsistent-reference`; omitted policy
+does not infer restrictions from names, prose or ordering.
+
+`validateRecipeCatalog` (`@jgengine/core/crafting/recipeCatalog`) checks native
+`RecipeDef` rows and optional item, station and unlock lookups. Build lookup Sets
+once in the adapter. Empty outputs are valid for benefits applied by game code.
+Zero and fractional counts are valid; enforce discrete units in game policy.
+Duplicate input rows reject because crafting checks each row separately; merge
+their counts. Prices, rarity, ingredient scarcity and recipe cycles are game-owned.
+Compose existing `validateQuestCatalog` and `validateDialogueGraph` for their native
+structures; do not replace the quest journal or conversation model.
+
+```ts
+import { validateContentProgression } from "@jgengine/core/game/contentValidation";
+
+const result = validateContentProgression({
+  initial: ["material:wire", "material:seals", "place:home"],
+  rules: [{
+    id: "sealed-tank",
+    path: "/refits/tank",
+    requires: ["material:wire", "material:seals", "place:home"],
+    provides: ["benefit:sealed-tank"],
+  }],
+  required: [{ id: "benefit:sealed-tank", contentId: "tank", path: "/refits/tank" }],
+  closedWorld: true,
+});
+```
+
+Facts are opaque game-owned strings. All facts in one rule are necessary;
+alternative sources are separate rules. An initial fact or a reachable source
+can seed an intentional cycle. Missing seeds block cycles; cycles themselves
+are never forbidden. `closedWorld: true` asserts all possible sources have been
+declared and makes blocked rules/required facts errors. The default leaves them
+warnings. Legitimate external suppliers belong in `initial` or a source rule,
+not a blanket declaration of every catalog item as available.
+
+Translate skill gates into milestone facts in the game adapter. A repeatable
+action requiring skill 0 and training to 50 can provide milestones through 50;
+it cannot provide the next source's skill-100 fact. Derive milestones from actual
+gates and training caps rather than inventing thousands of skill nodes. Bound the
+analysis to the reviewed content and dependency edges. The engine visits each
+rule and dependency edge with an iterative queue rather than rescanning a catalog
+until convergence.
+
+This proves potential availability only. It does not prove affordable quantities,
+repeatability, inventory capacity, consumed prerequisites, exclusive choices,
+chronology, station proximity, story coherence or obtainable rewards in actual play.
+Declare distinct route/branch facts when combining branches would be misleading,
+and drive representative choices through the actual commands with save/reload.
+Keep story facts, terms, assets and economy decisions in the game. Remove older
+generic reference/topology algorithms when adopting these checks; retain custom
+semantic and durable-save policy validators.
+
+Verify built tarball imports and the actual adopter in an isolated scratch copy.
+Keep the candidate on a prepared branch until a verified published package contains
+these APIs, then adopt through the games workspace catalog and lockfile together.
+Never route game imports to engine source or add per-game version pins.

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
@@ -63,3 +110,79 @@ 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

@@ -9,30 +9,42 @@ description: Build spatial runtime, movement, interaction, AI, and environments.
 
 This skill owns runtime spatial behavior: authored-scene consumption, environments, movement, input mapping, interaction, AI, navigation, physics, visibility, time, and spatial audio. Scene creation and placement stay in `jgengine-editor`; presentation stays in `jgengine-ui`.
 
-Search [capabilities.md](capabilities.md) by intent before designing a primitive. Use [api.md](api.md) for exact exports and [reference.md](reference.md) for environment, camera, navigation, physics, audio, and authored-scene recipes.
+Search [capabilities.md](capabilities.md) by intent before designing a primitive. Use [api.md](api.md) for exact exports and [reference.md](reference.md) for environment, camera, navigation, physics, audio, and authored-scene recipes. Culling and streaming overrides are in [visibility.md](visibility.md).
 
 For a *connected* walkthrough that wires several primitives into a running loop, read the goal-oriented recipes under [recipes/](recipes/) — organized by composition seam (what connects to what), never by genre. Start there before reading a game's source to learn how pieces fit; a hybrid game is just a different composition of the same primitives.
 
 - [recipes/commanding-entities.md](recipes/commanding-entities.md) — select → order → tick → resolve: direct command over a group of entities (the command loop behind squad control, base-defense, herding, autobattle, or a mutating game's real-time phase).
+- [recipes/npc-senses.md](recipes/npc-senses.md) — perceive → remember → decide → route: perception memory written into a decision-graph blackboard, with nav-mesh routing (guards, mobs, pedestrians, police response).
 - [recipes/building-kit.md](recipes/building-kit.md) — bind the facade generator's part slots to real models: one massing, swappable art per style, blocks where the kit is silent.
+- [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: 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
 
 ### Declare the place
 
-A world is the place you play in: substrate + laws, via `world()` from `@jgengine/core/world/place` — `{ id, ground: { mode: flat|round|voxel|board, size, surface?, generator? }, physics? }`. Thin is complete: flat with `Infinity` axes for 3D, `board` for 2D, or omit `world` for pure UI/rules games. Never put seed, sky, or vegetation in a world definition — seeds derive from world id + save/run (`seedForPlace`); sky look and foliage scatter are editor-authored scene content, with the engine default sky when the document has none. `ground.surface` carries matter/feel laws (metal vs slime vs felt) that the same rule systems read — swap the surface, not the rules. See [reference.md](reference.md) for the full shape; `environment()` is the legacy consumption path for editor/preset-written scene data, never the starter.
+A world is the place you play in: substrate + laws, via `world()` from `@jgengine/core/world/place` — `{ id, ground: { mode: flat|round|voxel|board, size, surface?, generator? }, physics? }`. Thin is complete: flat with `Infinity` axes for 3D, `board` for 2D, or omit `world` for pure UI/rules games. Never put seed, sky, or vegetation in a world definition — seeds derive from world id + save/run (`seedForPlace`); sky look and foliage scatter are editor-authored scene content, with the engine default sky when the document has none. `ground.surface` carries matter/feel laws (metal vs slime vs felt) that the same rule systems read — swap the surface, not the rules. See [reference.md](reference.md) for the full shape; `environment()` is the consumption path for editor/preset-written scene data: a created 3D game's `world.ts` passes it the document's sculpt, sky, and clearings through `environmentContentFromDocument`, never code-declared noise or coordinates.
 
 ### Authored world
 
 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.
-4. Keep derived caches rebuildable; the document remains authoritative.
+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`. 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
 
 Per-instance state belongs on the placement, not in a game-owned map keyed by `instanceId`. Set `SceneObject.state` (opaque) through `ctx.scene.object.setState`/`patchState`; declare `slotInventory` on the catalog entry and mutate contents through `ctx.scene.object.slots`, which enforces the declared capacity and `accepts`. Both replicate and save with the object through the always-on `objects` snapshot module, and `toRuntimeObjectRow`/`fromRuntimeObjectRow` (`@jgengine/core/multiplayer`) convert to and from the host's persisted rows.
@@ -41,6 +53,14 @@ 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
 
 Render seams fall back to placeholders when content is unauthored: default green ground (no environment), primitive capsule/box actors (no `entityModels`/`objectModels` mapping), stylized proxy foliage (no scatter `resolveItem`). These placeholders are sometimes intended, so runtime never changes — but a dev-only, opt-in probe (`@jgengine/core/devtools/fallbackSeams`) tells "unauthored/misconfigured" apart from "intended". The shell arms it via `armFallbackSeams(devtoolsEnabled)`; each seam reports at its choice site (`reportFallbackSeam`), and counts surface through the devtools `fallbacks` probe. Disarmed (production) it is a pure, allocation-free no-op.
@@ -52,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.