@jgengine/node 0.18.0 → 0.19.0

package/skills/jgengine/capabilities.md

@@ -12,10 +12,30 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `collectAuthoredTriggers` (function) · `import { collectAuthoredTriggers } from "@jgengine/shell/gameKit"`
 
+## chase-view-cycle — cycle a vehicle camera between chase, hood and cockpit views at runtime
+
+- `nextChaseView` (function) · `import { nextChaseView } from "@jgengine/core/runtime/cameraDirector"`
+
+## client-side — input prediction with replay reconciliation
+
+- `createPredictionBuffer` (function) · `import { createPredictionBuffer } from "@jgengine/core/runtime/prediction"`
+
 ## collider-autofit — hitboxes and physical bodies fit each kind's rendered model bounds automatically — no hand-tuned sizes
 
 - `GameContextModels` (interface) · `import { GameContextModels } from "@jgengine/core/runtime/gameContext"`
 
+## command-number — validate finite, bounded numbers and integers at command boundaries
+
+- `readInputNumber` (function) · `import { readInputNumber } from "@jgengine/core/runtime/commandInput"`
+
+## command-parse — parse untrusted command input once so every command stage sees typed, bounded values
+
+- `defineCommand` (function) · `import { defineCommand } from "@jgengine/core/runtime/commandRunner"`
+
+## command-quantity — validate bounded whole-item counts at command boundaries
+
+- `readQuantity` (function) · `import { readQuantity } from "@jgengine/core/runtime/commandInput"`
+
 ## default-walk-codes — stock WASD + jump key codes for the shell walk controller
 
 - `DEFAULT_WALK_CODES` (const) · `import { DEFAULT_WALK_CODES } from "@jgengine/shell/gameKit"`
@@ -32,6 +52,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `EditorCatalogDefinition` (interface) · `import { EditorCatalogDefinition } from "@jgengine/shell/gameKit"`
 
+## 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/authoring"`
+
 ## game-system — declare a composable capability with its own schedule and lifecycle
 
 - `SystemDefinition` (interface) · `import { SystemDefinition } from "@jgengine/shell/gameKit"`
@@ -84,6 +108,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `StatBar` (function) · `import { StatBar } from "@jgengine/shell/gameKit"`
 
+## input-recorder — tick-indexed input log for replay, rollback, and regression tests
+
+- `createInputRecorder` (function) · `import { createInputRecorder } from "@jgengine/core/runtime/inputRecorder"`
+
+## local-players — Couch co-op seats: devices hot-join into slots, each with its own user id and input snapshot.
+
+- `createLocalPlayers` (function) · `import { createLocalPlayers } from "@jgengine/core/runtime/localPlayers"`
+
 ## loot-table — validate a loot table definition for use with the registry
 
 - `lootTable` (function) · `import { lootTable } from "@jgengine/core/authoring"`
@@ -116,6 +148,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `toRuntimeObjectRow` (function) · `import { toRuntimeObjectRow } from "@jgengine/core/runtime/objectRows"`
 
+## pose-interpolation — render entity poses between fixed simulation steps without stutter
+
+- `createPoseHistory` (function) · `import { createPoseHistory } from "@jgengine/core/runtime/poseInterpolation"`
+
 ## render-fallback-diagnostics — Enable/disable the dev-only placeholder-fallback probe.
 
 - `armFallbackSeams` (function) · `import { armFallbackSeams } from "@jgengine/core/devtools/fallbackSeams"`
@@ -126,6 +162,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `resetTextureErrors` (function) · `import { resetTextureErrors } from "@jgengine/core/devtools/textureErrors"`
 - `textureErrorsSnapshot` (function) · `import { textureErrorsSnapshot } from "@jgengine/core/devtools/textureErrors"`
 
+## runtime — snapshot interpolation
+
+- `createSnapshotBuffer` (function) · `import { createSnapshotBuffer } from "@jgengine/core/runtime/snapshotBuffer"`
+
 ## runtime-save — save/load the whole game world through a pluggable backend, autosave or save points
 
 - `createRuntimeSave` (function) · `import { createRuntimeSave } from "@jgengine/core/runtime/runtimeSave"`
@@ -142,6 +182,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `seededRng` (function) · `import { seededRng } from "@jgengine/shell/gameKit"`
 
+## sim-loop — fixed-step or variable simulation stepping with tick count, catch-up cap, and interpolation alpha
+
+- `createSimLoop` (function) · `import { createSimLoop } from "@jgengine/core/runtime/simLoop"`
+
+## sim-snapshot — capture and restore whole-simulation state for replay, rollback, and regression tests
+
+- `createSimSnapshotRegistry` (function) · `import { createSimSnapshotRegistry } from "@jgengine/core/runtime/simSnapshot"`
+
 ## typed-keyed-store — a cast-free typed handle onto a per-owner keyed family of reactive game-store slots, replayable and host-authoritative
 
 - `defineKeyedStore` (function) · `import { defineKeyedStore } from "@jgengine/shell/gameKit"`
@@ -150,6 +198,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `defineStore` (function) · `import { defineStore } from "@jgengine/shell/gameKit"`
 
+## warn-once — emit a dev-only warning a single time per call site
+
+- `warnOnce` (function) · `import { warnOnce } from "@jgengine/core/devtools/warnOnce"`
+
 ## world-chunk-key — map world positions to persisted chunk keys at a declared cell size
 
 - `chunkKeyOf` (function) · `import { chunkKeyOf } from "@jgengine/core/runtime/worldChunks"`
@@ -165,3 +217,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 ## world-environment — compose editor/preset-derived outdoor dressing — terrain, weather, water, structures — into a legacy environment feature
 
 - `environment` (function) · `import { environment } from "@jgengine/shell/gameKit"`
+
+## world-item-pickup — pick up dropped items: ctx.scene.worldItem nearestInRadius → pickup into the player's inventory
+
+- `SceneWorldItemContext` (interface) · `import { SceneWorldItemContext } from "@jgengine/core/runtime/gameContext"`

package/skills/jgengine/recipes/minimal-game.md

@@ -45,6 +45,9 @@ spatial place. When the game *is* a place, declare only substrate + laws with `w
 `@jgengine/core/world/place` (e.g. `{ id, ground: { mode: "flat", size: { x: Infinity, z: Infinity } }, physics: { gravity: -24 } }`,
 or `mode: "board"` for 2D). Never seed, sky, or vegetation in `world` — the engine renders its
 default sky until you author one in the editor, and foliage is editor scatter over the ground.
+A created 3D game instead ships hills as a terrain sculpt in `editor.scene.json` and a `world.ts`
+that consumes it with `environment({ sculpt })` via `environmentContentFromDocument`; the file
+holds only the ground palette. Reshape the hills in the editor, not in code.
 
 
 ```ts

package/skills/jgengine-multiplayer/SKILL.md

@@ -45,3 +45,28 @@ Use [capabilities.md](capabilities.md) for intent-to-import discovery, [api.md](
 - Presence/chat/voice are session channels, not game-state ownership.
 - Do not couple a primitive to WebSocket, Convex, Postgres, or one deployment topology.
 - Reward allocation, inventory mutation, and progression policy remain gameplay/combat concerns.
+
+## Shared-world capacity and persistence
+
+| Topology | Membership and session state | Command reads | Presence fan-out |
+| --- | --- | --- | --- |
+| Rooms | **256 members maximum** in the room document | Declared actor/player and chunk scope | Neighborhood index |
+| Shared | Indexed `jgServerMembers`, separate `jgServerCapacity`, per-user profile session state; no 256-member engine cap | Declared actor/player and chunk scope; player-only writes avoid the world row | Neighborhood index, 10 Hz maximum default pose writes |
+
+Use `createGameServerFunctions({ topology: "shared", runtimes })` for one persistent world. Shared topology defaults to singleton matchmaking. Capacity is not a throughput guarantee; verify the command and subscription read sets under crowd load. Subscribe to `getServerCapacity` for shared membership/status without volatile world revision reads.
+
+Every gameplay command declares `scope(input)`: use `{ players: "actor", chunkKeys: [] }` for player-only work and `chunkKeysAround(position, 1)` for spatial work. The omitted-command default is actor-only with no chunks; an explicit `{}` requests the whole world and needs a justified bounded workload. Hosts use `helpers.runCommand` and its `beforePersist` callback to pair game writes with membership and revision checks in one transaction. Never copy that check/apply/persist loop into a game. Declare commands with `defineCommand({ parse, scope, validate, apply })` and build `parse` from the `readInput*` readers in `@jgengine/core/runtime/commandInput` (finite, bounded numbers and points, capped strings and arrays): the runner refuses malformed input before `scope`, `validate` or `apply` run, so those stages never re-parse or trust raw values. Treat every field of a command's `input` as client-controlled: a command whose input carries facts only the host may decide (unlock state, prices, multipliers, whether a target exists) declares `access: "server"`, so the public `runCommand` and WebSocket clients are refused and only a host mutation calling `helpers.runCommand` (or `host.runCommand({ trusted: true })`) runs it. Read time from the `nowMs` argument, never from `input`.
+
+Every presence query is neighborhood-scoped. Pass `PresenceSession.viewerChunkKey` through `createConvexPresenceTransport`. Hosts with custom authentication, bot ownership, or spawn policy use `createWorldPresenceStore` from `@jgengine/convex/worldPresence`: resolve trusted identities and access first, then call `ensure`, `sync`, `revoke`, `active`, `nearby`, and `reap`. Store rows in `jgPoses`, never a game-owned presence table. Optional snapshot callbacks persist game-owned last-position fields at the store's cadence. Bot identity may differ from its authorized owner; preserve that mapping explicitly. Resident rows implement `PresenceResidentRow.actorExternalId` and `ownerActorId` exactly.
+
+Persist only dirty profiles/chunks. Join/leave are roster writes; they do not dirty or rewrite the world. Reset a player with `helpers.resetPlayerProfile`, which runs the same initializer used by joins, and keep the shared world intact.
+
+## Scheduled work
+
+A cron never collects a whole table. Use presence-gated `forEachOnlinePlayer` with a bounded `batchSize`, an internal batch handler, and a continuation reference: each page schedules its handler and the next page as separate transactions. `OnlinePlayer.homeGameId` carries optional application identity from its pose row. Persist elapsed-time anchors with effects; use `accrueSince` to cap offline catch-up. `allServers` is only for explicitly global systems with a bounded server budget.
+
+Pass runtimes to `jgengineCronSpecs` so no tick cron registers when no runtime declares `onTick`; set per-spec `intervalSeconds` deliberately. Retention sweeps and one-shot backfills are bounded, report `remaining`, and stop at convergence. Delete completed migration crons instead of leaving hourly table scans installed forever.
+
+Join failures return typed `full`, `closed`, or `unauthorized` outcomes. Surface them through a retry gate; returning a rejection without visible UI is unfinished. Browser adapters leave sessions on `pagehide`. Membership is per client session: pass a fresh `sessionId` (`createTransportSessionId`) to each `joinServer` and its matching `leaveServer`, so a closed tab or a disposed mount never evicts a live one. A host mutation acting for a user who may have no live session calls `helpers.ensureJoined` before `helpers.runCommand`.
+
+For the explicit shared-builder composition, `jgengine create "World Name" --shape shared-world-builder` generates the connected Convex shell, runtime scope declarations, claim/accrual examples, chat, indexed presence, and an online batch pipeline. The generated README owns setup; replace the demonstration economy and author buildable world content in the editor.