@jgengine/core 0.18.0 → 0.19.0

package/skills/jgengine-gameplay/capabilities.md

@@ -12,6 +12,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `advanceLedger` (function) · `import { advanceLedger } from "@jgengine/core/gameplay"`
 
+## affix-roller — roll randomized gear (guns, armor, loot) with rarity tiers, stat scaling and prefix/suffix affixes from a seed
+
+- `createAffixRoller` (function) · `import { createAffixRoller } from "@jgengine/core/gameplay"`
+
 ## auction-book — timed bid auctions with escrowed bids, buyout, anti-snipe close extension, and collection-box settlement
 
 - `createAuctionBook` (function) · `import { createAuctionBook } from "@jgengine/core/gameplay"`
@@ -40,6 +44,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `totalLoad` (function) · `import { totalLoad } from "@jgengine/core/inventory/encumbrance"`
 
+## cell-grid — immutable 2D board of cells with row clears, gravity collapse, and match runs
+
+- `createCellGrid` (function) · `import { createCellGrid } from "@jgengine/core/puzzle/cellGrid"`
+
 ## clip-roles — map a rigged asset's pack-specific clip name to its semantic animation role
 
 - `classifyClip` (function) · `import { classifyClip } from "@jgengine/core/game/clipRoles"`
@@ -65,6 +73,18 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `breedOffspring` (function) · `import { breedOffspring } from "@jgengine/core/game/breeding"`
 
+## currency-major-units — convert safe minor-unit integers into currency amounts
+
+- `fromMinorUnits` (function) · `import { fromMinorUnits } from "@jgengine/core/economy/currency"`
+
+## currency-minor-units — round decimal currency into safe integer minor units
+
+- `toMinorUnits` (function) · `import { toMinorUnits } from "@jgengine/core/economy/currency"`
+
+## currency-precision-format — display a currency using its declared decimal precision
+
+- `formatCurrency` (function) · `import { formatCurrency } from "@jgengine/core/economy/currency"`
+
 ## decay-meter — survival meters that drain/refill over game time (hunger, water, oxygen, stamina)
 
 - `createDecayMeterSet` (function) · `import { createDecayMeterSet } from "@jgengine/core/gameplay"`
@@ -124,6 +144,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createEventTicker` (function) · `import { createEventTicker } from "@jgengine/core/gameplay"`
 
+## fire-input — bind a key or mouse button to a named action that runs the same-named command with the aim; repeatMs auto-fires while held
+
+- `ActionCodesMap` (type) · `import { ActionCodesMap } from "@jgengine/core/gameplay"`
+
 ## game-save — save/load game state with a pluggable backend, autosave, slots, and migration
 
 - `createSaveStore` (function) · `import { createSaveStore } from "@jgengine/core/gameplay"`
@@ -227,6 +251,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `localSaveBackend` (function) · `import { localSaveBackend } from "@jgengine/core/gameplay"`
 
+## loot-beams — rarity-colored loot beams and labels on dropped items via defineGame({ worldItem: { rarityStyle, beamHeight } })
+
+- `RarityStyle` (interface) · `import { RarityStyle } from "@jgengine/core/gameplay"`
+
 ## loot-filter — filter and highlight drops by rarity/name rules
 
 - `evaluateLootFilter` (function) · `import { evaluateLootFilter } from "@jgengine/core/gameplay"`
@@ -300,6 +328,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createPingSystem` (function) · `import { createPingSystem } from "@jgengine/core/gameplay"`
 
+## pointer-commands — click an entity or the ground to run a command (click-to-target, click-to-move, grab loot, marquee select)
+
+- `PointerConfig` (interface) · `import { PointerConfig } from "@jgengine/core/gameplay"`
+
 ## policy-annotate — tag a scheduled transaction's provenance without changing its value
 
 - `annotate` (function) · `import { annotate } from "@jgengine/core/gameplay"`
@@ -423,6 +455,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createSpawnPoints` (function) · `import { createSpawnPoints } from "@jgengine/core/gameplay"`
 
+## split-screen — Split the screen into one viewport per local seat, each with its own follow camera.
+
+- `splitViewports` (function) · `import { splitViewports } from "@jgengine/core/game/viewports"`
+
 ## stat-graph — derive game-defined stats from named inputs with provenance and preview
 
 - `createStatGraph` (function) · `import { createStatGraph } from "@jgengine/core/gameplay"`

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

@@ -63,3 +63,7 @@ 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.
+
+## 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).

package/skills/jgengine-world/SKILL.md

@@ -9,30 +9,38 @@ 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: 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.
+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.
 
 ### 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.
+
 ### 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 +49,10 @@ 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.
 
+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`.
+
+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.
@@ -54,3 +66,9 @@ Render seams fall back to placeholders when content is unauthored: default green
 - Generated environments still need deterministic data assertions; authored environments need scene-document assertions.
 - Audio files and licensing belong to `jgengine-assets`; spatial playback policy belongs here.
 
+
+### Territory and placement
+
+Use `world/territory` for chunk-backed ownership: `planFootprintClaims` prices previews, `placeWithTerritory` commits claims and object placement atomically, and `createTerritory` binds host-owned snapshot storage to `ctx.game.territory`. Use `territoryChunkKeys` to load every footprint and gap-neighbor chunk before planning; never interpret an unloaded neighborhood as vacant. Claims persist in `RuntimeChunkRow.territory`; `RuntimePlayerRow.territoryOwnedCount` preserves the price curve and `ownedTerritoryChunkKeys` bounds owner queries. Convex hosts use `loadTerritoryState`/`persistTerritoryState` from `@jgengine/convex/territory` to commit dirty claim chunks/profiles without a shared-server write. Grant `starterBlock` before the first placement verb. Placement previews must show the claim cost and affordability on the placement surface.
+
+Use `chunkKeysAround(position, rings)` for bounded command/presence reads; declare `commands[name].scope(input)` for every hosted command. Missing scopes load only the actor and no chunks. A whole-world command must opt in explicitly with `scope: () => ({})` and justify its read budget.