@jgengine/core 0.17.0 → 0.18.1

package/dist/input/gamepadModel.d.ts

@@ -0,0 +1,45 @@
+import type { ActionCodesMap } from "./actionBindings.js";
+/** A serializable gamepad state sampled from the platform input API. */
+export interface GamepadSnapshot {
+    id: string;
+    axes: number[];
+    buttons: {
+        pressed: boolean;
+        value: number;
+    }[];
+    connected: boolean;
+}
+/** Names of the built-in controller glyph sets. */
+export type GamepadGlyphName = "xbox" | "playstation" | "nintendo" | "generic";
+/** Button labels used by one controller family. */
+export interface GamepadGlyphSet {
+    buttons: readonly string[];
+}
+/** Built-in short labels for the common controller families. */
+export declare const GAMEPAD_GLYPH_SETS: Record<GamepadGlyphName, GamepadGlyphSet>;
+/** Lowercase alias for consumers that prefer data-oriented naming. */
+export declare const gamepadGlyphSets: Record<GamepadGlyphName, GamepadGlyphSet>;
+/** Action bindings whose codes identify gamepad buttons or axes. */
+export type GamepadBindings<TAction extends string = string> = ActionCodesMap<TAction, GamepadCode>;
+/** A gamepad button or signed axis binding code. */
+export type GamepadCode = `pad:${number}` | `padaxis:${number}${"+" | "-"}`;
+/** Deadzone policy applied to gamepad axes. */
+export interface GamepadDeadzone {
+    kind: "radial" | "axial";
+    inner: number;
+    outer: number;
+}
+/** Options for resolving one gamepad snapshot into action state. */
+export interface ResolveGamepadFrameOptions {
+    deadzone: GamepadDeadzone;
+    curve?: number;
+}
+/** The digital and analog action state produced by a gamepad frame. */
+export interface GamepadFrame {
+    held: string[];
+    analog: Record<string, number>;
+}
+/** Resolve one sampled gamepad into held actions and shaped analog action values.
+ * @capability gamepad-input Resolve sampled gamepad input into actions with deadzones and response curves.
+ */
+export declare function resolveGamepadFrame(snapshot: GamepadSnapshot, bindings: GamepadBindings, options: ResolveGamepadFrameOptions): GamepadFrame;

package/dist/input/gamepadModel.js

@@ -0,0 +1,69 @@
+/** Built-in short labels for the common controller families. */
+export const GAMEPAD_GLYPH_SETS = {
+    xbox: { buttons: ["A", "B", "X", "Y", "LB", "RB", "LT", "RT", "View", "Menu", "L3", "R3", "↑", "↓", "←", "→"] },
+    playstation: { buttons: ["Cross", "Circle", "Square", "Triangle", "L1", "R1", "L2", "R2", "Share", "Options", "L3", "R3", "↑", "↓", "←", "→"] },
+    nintendo: { buttons: ["B", "A", "Y", "X", "L", "R", "ZL", "ZR", "−", "+", "L3", "R3", "↑", "↓", "←", "→"] },
+    generic: { buttons: ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "↑", "↓", "←", "→"] },
+};
+/** Lowercase alias for consumers that prefer data-oriented naming. */
+export const gamepadGlyphSets = GAMEPAD_GLYPH_SETS;
+function bindingCodes(codes) {
+    if (Array.isArray(codes))
+        return codes;
+    const modes = codes;
+    return [...(modes.hold ?? []), ...(modes.toggle ?? [])];
+}
+function shape(value, deadzone, curve) {
+    const magnitude = Math.abs(value);
+    if (magnitude <= deadzone.inner)
+        return 0;
+    const normalized = magnitude >= deadzone.outer ? 1 : (magnitude - deadzone.inner) / (deadzone.outer - deadzone.inner);
+    return Math.sign(value) * Math.pow(normalized, curve);
+}
+function readAxis(code) {
+    const match = /^padaxis:(\d+)([+-])$/.exec(code);
+    return match === null ? null : { index: Number(match[1]), sign: match[2] === "+" ? 1 : -1 };
+}
+/** Resolve one sampled gamepad into held actions and shaped analog action values.
+ * @capability gamepad-input Resolve sampled gamepad input into actions with deadzones and response curves.
+ */
+export function resolveGamepadFrame(snapshot, bindings, options) {
+    if (!snapshot.connected)
+        return { held: [], analog: {} };
+    const inner = Math.max(0, options.deadzone.inner);
+    const outer = Math.max(inner + Number.EPSILON, options.deadzone.outer);
+    const curve = options.curve === undefined ? 1 : Math.max(Number.EPSILON, options.curve);
+    const rawAxes = snapshot.axes.map((value) => (Number.isFinite(value) ? Math.max(-1, Math.min(1, value)) : 0));
+    const axes = rawAxes.map((value) => shape(value, { ...options.deadzone, inner, outer }, curve));
+    if (options.deadzone.kind === "radial") {
+        const magnitude = Math.hypot(...rawAxes);
+        const radial = magnitude <= inner ? 0 : Math.min(1, (magnitude - inner) / (outer - inner));
+        const factor = magnitude === 0 ? 0 : (radial * Math.pow(radial, curve - 1)) / magnitude;
+        for (let index = 0; index < axes.length; index += 1)
+            axes[index] = rawAxes[index] * factor;
+    }
+    const held = [];
+    const analog = {};
+    for (const action of Object.keys(bindings)) {
+        let actionAnalog = 0;
+        let isHeld = false;
+        for (const code of bindingCodes(bindings[action])) {
+            if (code.startsWith("pad:")) {
+                const index = Number(code.slice(4));
+                const button = snapshot.buttons[index];
+                if (button?.pressed === true)
+                    isHeld = true;
+                actionAnalog = Math.max(actionAnalog, button?.value ?? 0);
+                continue;
+            }
+            const axis = readAxis(code);
+            if (axis !== null)
+                actionAnalog = Math.max(actionAnalog, Math.max(0, axes[axis.index] * axis.sign));
+        }
+        if (isHeld || actionAnalog > 0)
+            held.push(action);
+        if (actionAnalog !== 0)
+            analog[action] = actionAnalog;
+    }
+    return { held, analog };
+}

package/dist/meta/changelog.d.ts

@@ -1,5 +1,5 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export declare const VERSION = "0.17.0";
+export declare const VERSION = "0.18.1";
 /** One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md). */
 export interface ChangelogEntry {
     migrate: readonly string[];

package/dist/meta/changelog.js

@@ -1,7 +1,109 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.17.0";
+export const VERSION = "0.18.1";
 /** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "0.18.1": {
+        migrate: [
+            "Bump lockstep SDK packages to `^0.18.1`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.15.1`; `@jgengine/github` is `0.5.1`.",
+            "Declare `topology: \"shared\"` on runtime definitions. Shared Convex hosts migrate the bounded legacy roster into indexed membership and per-player session rows; use `getServerCapacity` for stable lobby subscriptions.",
+            "Put every command's read scope on its definition. Omitted scopes now load the actor and no chunks; explicitly request whole-world reads only where needed. Trusted host mutations can compose writes through `helpers.runCommand`.",
+            "Handle typed join outcomes (`ok` and `reason`) or use `useServerSession` and `JoinGate`. Pass runtimes to `jgengineCronSpecs`; tick registration requires an actual tick hook.",
+            "Declare currency precision with `decimals` and remove game-side cent conversions. Public amounts stay in major units and wallet writes round through integer minor units.",
+            "Replace custom presence, chat, territory and tick batching with `createWorldPresenceStore`, chat helpers, chunk territory, and `forEachOnlinePlayer`. Legacy claim backfills must finish before removing their old schema.",
+            "`AudioEngine.setListenerPose` now accepts `{ position, forward, up }`. Bare `Vec3` positions remain compatible for one release and use forward `[0, 0, -1]` with up `[0, 1, 0]`.",
+            "Hosted world stores are asynchronous. Implement `HostedWorldStore.load()` and `save()` as `Promise`-returning methods and construct persisted sessions with `createHostedWorldSessionAsync`; synchronous tests can keep using `memoryWorldStore`.",
+            "Look presets now default to `neutral`. Games that relied on the previous implicit cinematic sky/post stack should set `look: \"photoreal\"` (or keep `look: \"cinematic\"`) explicitly.",
+            "`ServerTickPlan.due` is `{ id, runs }[]` instead of a repeated id list. `planServerTick` repeated a system id once per missed interval, and the obvious way to consume that — `due.includes(id)` or a `Set` — ran the system once while the returned anchor had already advanced by every repeat, silently dropping the catch-up work. A host now reads `runs` (or `tickRunCount(plan, id)`) and loops that many times.",
+            "`CommandDef.validate` / `CommandDef.apply` take a fourth argument, `nowMs`. Existing implementations that ignore it are unaffected. Commands that took a `now` in their `input` should read this instead — the client supplied the old one.",
+        ],
+        added: [
+            "Indexed shared membership and capacity rows, bounded neighborhood poses with 100 ms server/client gates, durable rate limits, authenticated diagnostics and bounded retention.",
+            "Territory footprint planning and atomic placement claims, chat validation and headless chat/join/territory surfaces, elapsed accrual, safe quantities, and player-profile reset through the initializer.",
+            "An explicit `--patch` release option.",
+            "Added smooth interpolation for remote presence player poses.",
+            "WS ping/pong messages and client RTT sampling on the backend object.",
+            "Added skin-backed HUD chrome variables, font loading, and the procedural `HudSkinPreview` fixture.",
+            "Core gamepad snapshot model, deadzone/curve resolver, and controller glyph labels.",
+            "Shell gamepad source polls connected pads, merges analog actions, supports synthetic `?gamepad=1` input, and exposes `ctx.input.rumble`.",
+            "Core action context stacks layer gameplay, menus, and passthrough overlays with snapshot/restore; shell action tracking now respects the active context.",
+            "Shell audio now supports listener orientation and per-sound Web Audio panners. `setListenerPose` accepts `{ position, forward, up }`; bare positions remain supported for one release.",
+            "Core perception tracks deterministic sight, hearing, occlusion, and bounded observation memory for AI.",
+            "`syncWorldColliders` now keeps terrain and static object colliders synchronized with a physics backend.",
+            "Core decision graphs provide deterministic selector, sequence, condition, action, and utility runtimes with snapshot/restore.",
+            "Core behavior descriptors can run registered decision graphs at the interest-scheduler cadence.",
+            "Core navigation meshes provide deterministic polygon routing, off-mesh links, closest-point queries, and nav raycasts.",
+            "WS sessions now issue resume tickets and retain disconnected memberships for a 15-second grace window, allowing reconnects to rejoin without replacing player state.",
+            "Shell entity sprites can play atlas-backed sprite clips while preserving raw texture sprites.",
+            "Tilemap layers can render atlas-backed textured tiles as one instanced quad mesh with parallax.",
+            "Core pixel-perfect orthographic frustum and pixel-grid camera snapping are available to shell cameras.",
+            "Core sprite atlas adapters and deterministic 2D sprite clip playback primitives.",
+            "`src/art-direction.md` scaffold and `check-art-direction` gate for created games.",
+            "Host-authoritative shell sessions now expose each accepted world frame to the local prediction buffer, reconciling and snapping the possessed pose only when drift exceeds its threshold.",
+            "Shared GLTF loader configuration for Draco and KTX2-compressed assets, with CDN defaults and renderer capability detection.",
+            "Material map overrides now support metalness, emissive, and height maps on standard and physical materials.",
+            "Presentation and editor documents now accept gradient, HDRI/EXR, and cube-map environment sources.",
+            "Authored `light` markers now feed bounded point/spot punctual lights with an eight-light default budget and editor warning.",
+            "Graphics profiles now resolve per-tier render scale, shadow budgets, culling distance, particles, cascades, and post stages; games can override them with `defineGame({ graphics })`.",
+            "`defineGame({ physics: { backend } })` now adopts a capsule character controller for shell/headless movement and registers the backend simulation after movement, including floor collision and step-up behavior.",
+            "Added the `physics-probe` dev scene for Rapier crate, ragdoll, and vehicle motion.",
+            "Assets now expose import-spec validation and magic-byte classification for supported source files.",
+            "Hosted WS sessions now support spectator joins, viewer roles, throttled low-priority snapshot modules, and default command rate limits.",
+            "`@jgengine/navbake` bakes deterministic navigation meshes and editor documents can store named bake data.",
+            "Core tactical queries derive cover points and score bounded candidate positions.",
+            "Added createSnapshotBuffer for delayed snapshot interpolation.",
+            "Host-authoritative world replication over WS. Hosted sessions expose revision-cursor pulls, so server subscribers receive compact world diffs and automatically recover with a fresh baseline after missed revisions; viewer-specific projections still receive per-viewer baselines.",
+            "Animation graph — `ModelAnimationConfig.graph` and `@jgengine/core/anim/animGraph`. A serializable, layered animation state machine: `clip`, `blend1D`, and `blend2D` states, transitions as data (parameter comparisons, consumed triggers, exit times, crossfade durations), masked and additive layers, and clip events. `createAnimGraphRuntime` is headless and owns every clip's playback time and weight, so the shell's mixer only seeks and weights actions (`useModelAnimation` takes the graph path when `graph` is set) and a headless host or test advances the same graph without three.js. The shell feeds the entity's smoothed ground speed as `speed`, merges parameters from the entity blackboard key `ANIM_PARAMS_KEY`, arms triggers from `entity.animation` / `combat.hitReaction` / `entity.died`, and emits the new `animation.event` for clip events (foot plants, hit frames). `locomotionGraph()` builds the previous idle/walk/run plus one-shot behavior as one authored graph.",
+            "`PhysicsBackend` — one interface over interchangeable rigid-body solvers. `@jgengine/core/physics/physicsBackend` defines bodies (`BodyDesc` with a box / sphere / capsule / convex / trimesh / heightfield shape union, quaternion rotation, angular velocity, layers and mask, CCD flag), joints, `raycast`, `shapecast`, `overlap`, contact events, and `snapshot`/`restore` with stable handles; `capabilities` says what a backend really does. `createPhysicsWorldBackend` puts the zero-dependency `PhysicsWorld` behind it (translation-only, non-box shapes collide as their bounding box, warned once), and `runPhysicsBackendConformance` is the behavioral contract any adapter runs. `createCharacterController` (`@jgengine/core/movement/characterController`) is the first consumer: a capsule collide-and-slide controller with step-up, slope limit, ceiling test, crouch with headroom check, ground snapping, and moving-platform carry, pure over any backend and retunable during play.",
+            "Fixed-step simulation with render interpolation — `defineGame({ simulation: { hz } })` and `ctx.sim`. Every driver (shell frame, HUD-only, headless runner, authoritative host) now steps through one `SimLoop` (`@jgengine/core/runtime/simLoop`): a fixed `hz` accumulates real time and runs equal-dt steps behind a catch-up cap (`maxCatchUpSteps`, default 5) instead of spiralling; the default stays `\"variable\"` (one step per frame) so existing games are unchanged until they opt in. Under a fixed rate the shell renders entities at `ctx.sim.renderPose(id)` — the pose interpolated between the previous and current step (`@jgengine/core/runtime/poseInterpolation`), with teleports past `snapDistance` snapping — so a 20 Hz sim no longer stutters. `ctx.sim.tick()` counts steps and `InputFrame.tick` carries it over the wire; `ctx.sim.addStage({ phase, run })` inserts per-step work before movement, after movement, or after `onTick` (the hook a physics backend or netcode buffer registers through). System fixed-rate groups gain the same substep cap. For replay and rollback: `seededRng` streams expose `state()`/`restore()` (`rngStateOf`/`restoreRng` for any `ctx.rng`), `createSimSnapshotRegistry`/`createContextSimSnapshot` capture world, clock, loop, and rng cursor together, `createInputRecorder` logs frames by tick, and `HeadlessRunner` gains `snapshot()`/`restore()`/`tick()` — a test proves that replaying recorded input from a snapshot reproduces every entity pose.",
+            "City and street races share one generator. `extractCircuitRoute` lifts a sealed-off race lap from a city street network; city rules, editor baking, playground modes, and the shell renderer carry the same street dials through the resulting race surface and junction dressing.",
+            "`ctx.particles` — the game-reachable particle seam. Game logic queues one-shot bursts (`ctx.particles.burst(config, count)`) and keyed standing emitters (`attach`/`retune`/`detach`, with `follow` to track a scene entity) as plain serializable data (`@jgengine/core/vfx/particleDirector`); the shell auto-mounts a renderer that turns them into pooled GPU point clouds via the existing `createParticleSystem`/`ParticleField`, caps pool sizes by graphics quality (low 128 / medium 256 / high 512 per effect, degrading density instead of dropping effects), and reaps finished bursts. Dust, sparks, exhaust, and debris no longer require forking the shell; headless tests assert the requested effects straight off the director.",
+            "`resolveSourceWalkerStep(source, cache, position, stepX, stepZ, options)` (`@jgengine/core/movement/solidObstacles`) — `resolveWalkerStep` with no `GameContext`, for movement rules that live in a pure package with no React or three.js. `SolidObstacleSource`, `ObstacleReachCache`, `createObstacleReachCache`, `sourceObstacleReach`, `sourceObstaclesNear`, and `slideStep` are public alongside it instead of `@internal`, so a game no longer has to push the resolver up into its app layer and inject it back down. `resolveWalkerStep`'s doc now states that it already resolves X and Z separately, so a caller doing its own axis-split must hand it one axis per call.",
+            "`tickRunCount(plan, id)` (`@jgengine/core/time/serverTick`) — how many runs a plan owes a system, or 0 when it is not due.",
+            "`grass()` exposes the clump/lighting knobs its shader already had. `GrassEnvironmentConfig` gains optional `bladeBend`, `tuftRadius`, `colorVariation`, and `normalLift`, forwarded by the shell's environment renderer — a world descriptor can now author bushy wind-combed scrub instead of the fixed lawn-blade look; defaults unchanged.",
+            "`TerrainDetailConfig.sweeps` — the detail shader's two macro colour sweeps (sun-dried patches, cooler wet pockets) take per-world RGB multipliers instead of hardcoded meadow tints. The old green-leaning \"lush pocket\" default painted moss onto arid/ashen biomes; defaults are unchanged, so a desert world should set warm/neutral `sweeps` explicitly.",
+            "`@jgengine/rapier` — a Rapier-backed `PhysicsBackend` adapter with native capsules, shapecasts, rotation, CCD, joints, and collision queries.",
+        ],
+        changed: [
+            "Hosted game runner queues authoritative inputs by simulation tick and applies the in-force frame each fixed step.",
+            "Create scaffolds now use a 60 Hz simulation with interpolation enabled by default.",
+            "Rigged `ModelConfig` entries can opt into shell foot IK with named thigh/shin/foot bones; the driver raycasts the shared scene terrain, solves each chain, and fades corrections while airborne.",
+            "Animation graph clips may carry root-bone position tracks; states with `rootMotion: true` return the sampled displacement and the shell applies it to the entity while restoring the root bone's bind translation.",
+            "Added renderer-free two-bone, FABRIK, and look-at inverse-kinematics solvers to `@jgengine/core`.",
+            "Shell model animation now routes states and one-shots through the shared animation graph runtime.",
+            "CI now clones the external games repository with `GAMES_CLONE_TOKEN` and runs the game shape, content, front-end, art-direction, and feel gates against it; those gates fail loudly in CI when the checkout is missing while remaining no-ops locally.",
+            "`jgengine create` now accepts `--player`, `--ground`, and `--scene` so generated games can choose their model, terrain ground, and empty or starter scene.",
+            "Directional shadow frustum config actually reaches the GPU. `shadowCameraSize` on a single (non-cascaded) shadow light was silently inert: the shell wrote the bounds through R3F pierced props and nothing refreshed the shadow camera's projection matrix, so three rendered depth with its default ~10-unit box at the world origin — the reason no open-world game had cast shadows away from spawn. The shell now syncs the projection (and reallocates the shadow map when `shadowMapSize` changes). `bloom.threshold`'s doc also now states it measures raw HDR before the exposure stage.",
+            "CSM (`cascades > 1`) no longer over-lights streamed meshes or clobbers material shaders. Cascade scoping is injected per material, but the scan ran every 30 frames, so a model that streamed in rendered lit by every cascade light at once (a cascades× sun) until the next scan — a sub-second flash on desktop, the whole shot on capture rigs. The scan now runs every frame behind a WeakSet, and `setupMaterial` chains with a material's own `onBeforeCompile` (rim light, detail maps) instead of replacing it.",
+            "The host's wall clock reaches the runtime hooks. `RuntimeInitContext` (so `onInit`, `onNewPlayer`, and `onTick` alike) carries `nowMs`, the host timestamp for that call. Anything keyed to real time — a UTC date rollover, a `lastTickAt` anchor read by non-tick code, an RNG seed or `createdAt` stamp — reads it rather than accumulating `dtSeconds` against an epoch persisted in the snapshot, which drifts by whatever the tick loses to stalls and `maxCatchUp` clamping. `GameRuntime.hydrate` takes an optional `nowMs`; `tick`, `joinPlayer`, and `runCommand` take an optional trailing `nowMs`. All default to `Date.now()`, and the shipped WS and Convex hosts pass the timestamp they already computed to plan the tick.",
+            "Imported models cast and receive shadows. `cloneModelScene` never set `castShadow`/`receiveShadow` on a GLB's meshes (only the magenta fallback box had them), so every catalog model in every game rendered shadowless however the lights were configured. Cloned models now default to `ModelConfig.shadows: \"both\"`; set `\"cast\"`, `\"receive\"`, or `\"none\"` per model (foliage cards, decals, viewmodels).",
+            "`jgengine create` installs `game-design` and `jgengine-ui` by default. The minimal skill set was intake, editor, and verify, so a real project never saw the greenfield design contract or the UI art-direction template unless someone ran `jgengine skills --all`; `MINIMAL_GAME_SKILLS` now carries both.",
+        ],
+        removed: [],
+    },
+    "0.18.0": {
+        migrate: [
+            "Bump lockstep SDK packages to `^0.18.0`: `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.15.0`; `@jgengine/github` is `0.5.0`.",
+            "Register the presence reaper and redeploy your schema. `jgPoses` gains `sessionId` / `kind` / `label` / `revokedAt` (all optional) and a `by_updated` index, and `createPresenceFunctions` now also returns `reapIdlePresence`. Re-export it (`export const { list, sync, leave, reapIdlePresence } = createPresenceFunctions(...)`) and add `crons.interval(\"jg presence reap\", { seconds: 60 }, internal.presence.reapIdlePresence, {})`. Without it nothing deletes the row of a player who closed the tab — `list` filtered stale rows at read time but the table grew forever. `jgengineCronSpecs()` carries the new entry, and every spec now names the `module` (`\"runtime\"` / `\"presence\"`) it is exported from.",
+            "`presence.sync` returns `{ pose, lastSeenAt, displaced }` instead of `null`, and `presence.leave` marks the row revoked instead of deleting it (the reaper collects it once idle). A caller that ignored the return value is unaffected.",
+        ],
+        added: [
+            "Polygon navigation meshes — `NavMeshData`, adjacency building, polygon A* paths, closest-point, and nav raycasts (`@jgengine/core/nav/navMesh`).",
+            "`createPerception` (`@jgengine/core/sensor/perception`) tracks sight, sound, and damage stimuli per observer, with cone/range/occlusion checks, linearly decaying memory, retuning, and snapshot/restore.",
+            "`syncWorldColliders(backend, ctx)` mirrors static scene-object colliders and the sampled ground heightfield into a physics backend, updating on object spawn, despawn, and pose changes.",
+            "Physics-backed player movement — `defineGame({ physics: { backend } })` installs the backend's `afterMovement` simulation stage and makes the shell/headless walk controller use a capsule for gravity, shapecast collision, slopes, and step-up, while retaining the existing input and impulse feel.",
+            "`createPresenceFunctions` gains the policy hooks the pose lane was missing — `resolveSpawn(ctx, { serverId, userId, kind })` for where a session with no row starts (async and ctx-bearing, so a spawn can read the world, replacing a hardcoded origin), `poseRules` as a function of the actor `kind` so an agent need not obey a human's speed cap, `idleCutoffMs` / `maxReapPerRun` for the reaper, and optional `sessionId` on `sync` / `leave`: a second tab is a second row, syncing revokes the others, and the displaced session learns it on its next call through `displaced: true`.",
+            "A command declares what it touches, so `runCommand` hydrates that and nothing else. `CommandDef` gains an optional `scope(input, actorUserId)` returning `{ players?, chunkKeys? }`, evaluated before hydration; the registered `runCommand` mutation also accepts an explicit `scope` argument, which wins over the declared one. A game that never sets either keeps the whole-world default. `ServerLoopHooks.joinScope(userId, isNew)` does the same for `onNewPlayer`.",
+            "`GameRuntime.commandScope` / `GameRuntime.joinScope` expose those declarations to any host, alongside the pure helpers `resolveCommandScope` / `scopeWithActor` / `commandScopeEscape` (`@jgengine/core/runtime/commandRunner`).",
+        ],
+        changed: [
+            "Rigged `ModelConfig` entries can opt into shell foot IK with named thigh/shin/foot bones; the driver raycasts the shared scene terrain, solves each chain, and fades corrections while airborne.",
+            "Animation graph clips may carry root-bone position tracks; states with `rootMotion: true` return the sampled displacement and the shell applies it to the entity while restoring the root bone's bind translation.",
+            "`presence.sync` accepts a call with no `pose` at all, which holds the stored position and moves only the liveness stamp. `createConvexPresenceSync` sends one itself when the pose gate has suppressed writes for 10s, so a standing player keeps their row alive without a pose write — and without the reaper collecting a live session.",
+            "`PresencePoseRow` carries optional `sessionId` / `kind` / `label`, so a nameplate reads off the presence row instead of joining against users per frame.",
+            "`runCommand` no longer reads the whole world on every command. `LoadSnapshotScope` landed in 0.17 but only `helpers.loadSnapshot` accepted one, so the supported way to run a command — the registered `runCommand` mutation, a one-line delegation to `helpers.runCommand` — hydrated every member profile and every chunk however narrow the command was, and a game could only get bounded hydration by reimplementing the mutation. `runCommand`, `joinServer`, and `leaveServer` now hydrate a scope; a command whose `apply` dirties a player or chunk its scope never named is refused rather than persisted, since writing an unhydrated chunk overwrites the stored one with a blank. `flushSave` / `flushServerIfDue` / `tickActiveServers` / `flushDirtyServers` still hydrate everything, which is correct for what they write.",
+        ],
+        removed: [],
+    },
     "0.17.0": {
         migrate: [
             "Bump lockstep SDK packages to `^0.17.0`: `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.14.0`; `@jgengine/github` is `0.4.0`.",

package/dist/movement/characterController.d.ts

@@ -0,0 +1,76 @@
+import type { BodyHandle, BodyShape, PhysicsBackend, PhysicsVec3 } from "../physics/physicsBackend.js";
+/** Capsule dimensions and the walk rules a controller applies; every field is retunable during play. */
+export interface CharacterControllerConfig {
+    radius: number;
+    /** Standing height from feet to crown. */
+    height: number;
+    /** Height the feet may pop up to clear a ledge in one move. Default 0.35. */
+    stepHeight?: number;
+    /** Steepest walkable slope in degrees; steeper surfaces are walls to slide along. Default 50. */
+    maxSlopeDeg?: number;
+    /** Gap kept between the capsule and any surface so casts never start inside geometry. Default 0.02. */
+    skinWidth?: number;
+    /** Height while crouched. Default `height * 0.6`. */
+    crouchHeight?: number;
+    /** How far below the feet the ground may be while still counting as grounded (stairs down, small bumps). Default 0.3. */
+    snapDistance?: number;
+    /** Slide iterations per move. Default 4. */
+    maxSlides?: number;
+    /** Collision mask for the controller's casts. Default all layers. */
+    mask?: number;
+}
+/** The controller's serializable state. `position` is the feet point; the capsule stands above it. */
+export interface CharacterControllerState {
+    position: [number, number, number];
+    verticalVelocity: number;
+    grounded: boolean;
+    groundNormal: [number, number, number];
+    groundBody: BodyHandle | null;
+    crouching: boolean;
+}
+/** One step of intent for {@link CharacterController.move}. */
+export interface CharacterMoveInput {
+    /** Desired horizontal displacement this step, world units. */
+    motion: PhysicsVec3;
+    dt: number;
+    /** Downward acceleration applied to `verticalVelocity`. Default 0 (caller integrates vertical motion itself). */
+    gravity?: number;
+    /** Upward velocity to set this step; ignored unless grounded. */
+    jumpVelocity?: number;
+    /** Request crouch (`true`) or stand (`false`); standing waits until there is headroom. */
+    crouch?: boolean;
+    /** Body the controller itself is represented by, excluded from its own casts. */
+    self?: BodyHandle;
+}
+/** What one move did. */
+export interface CharacterMoveResult {
+    moved: [number, number, number];
+    grounded: boolean;
+    groundNormal: [number, number, number];
+    hitWall: boolean;
+    hitCeiling: boolean;
+    steppedUp: boolean;
+    /** Set when a stand request was refused for lack of headroom. */
+    crouchBlocked: boolean;
+}
+/** The controller handle: config, state, and the per-step move. */
+export interface CharacterController {
+    config(): Readonly<Required<CharacterControllerConfig>>;
+    retune(next: Partial<CharacterControllerConfig>): void;
+    state(): CharacterControllerState;
+    snapshot(): CharacterControllerState;
+    restore(next: CharacterControllerState): void;
+    /** Current capsule as a backend shape (crouch-aware). */
+    shape(): BodyShape;
+    /** Capsule center for the current state. */
+    center(): [number, number, number];
+    move(backend: PhysicsBackend, input: CharacterMoveInput): CharacterMoveResult;
+}
+/**
+ * Collide-and-slide capsule controller over any {@link PhysicsBackend}: horizontal slide along walls, step-up over
+ * ledges, slope limit, ceiling test, crouch with headroom check, ground snapping, and moving-platform carry read from
+ * the ground body's velocity. Pure over the backend's `shapecast`/`overlap`; the caller owns input and gravity policy.
+ *
+ * @capability character-controller capsule walk over the physics backend — slide, step-up, slopes, crouch, platforms
+ */
+export declare function createCharacterController(initial: CharacterControllerConfig): CharacterController;

package/dist/movement/characterController.js

@@ -0,0 +1,216 @@
+function resolve(config) {
+    return {
+        radius: config.radius,
+        height: config.height,
+        stepHeight: config.stepHeight ?? 0.35,
+        maxSlopeDeg: config.maxSlopeDeg ?? 50,
+        skinWidth: config.skinWidth ?? 0.02,
+        crouchHeight: config.crouchHeight ?? config.height * 0.6,
+        snapDistance: config.snapDistance ?? 0.3,
+        maxSlides: config.maxSlides ?? 4,
+        mask: config.mask ?? 0xffffffff,
+    };
+}
+/**
+ * Collide-and-slide capsule controller over any {@link PhysicsBackend}: horizontal slide along walls, step-up over
+ * ledges, slope limit, ceiling test, crouch with headroom check, ground snapping, and moving-platform carry read from
+ * the ground body's velocity. Pure over the backend's `shapecast`/`overlap`; the caller owns input and gravity policy.
+ *
+ * @capability character-controller capsule walk over the physics backend — slide, step-up, slopes, crouch, platforms
+ */
+export function createCharacterController(initial) {
+    let cfg = resolve(initial);
+    let state = {
+        position: [0, 0, 0],
+        verticalVelocity: 0,
+        grounded: false,
+        groundNormal: [0, 1, 0],
+        groundBody: null,
+        crouching: false,
+    };
+    function currentHeight() {
+        return state.crouching ? cfg.crouchHeight : cfg.height;
+    }
+    function shapeFor(height) {
+        const halfHeight = Math.max(0, height / 2 - cfg.radius);
+        return { kind: "capsule", radius: cfg.radius, halfHeight };
+    }
+    function centerFor(position, height) {
+        return [position[0], position[1] + height / 2, position[2]];
+    }
+    function walkable(normal) {
+        return normal[1] >= Math.cos((cfg.maxSlopeDeg * Math.PI) / 180);
+    }
+    function cast(backend, from, height, motion, self) {
+        return backend.shapecast({
+            shape: shapeFor(height),
+            position: centerFor(from, height),
+            motion,
+            mask: cfg.mask,
+            ...(self === undefined ? {} : { exclude: self }),
+        });
+    }
+    /** Move along `motion`, stopping `skinWidth` short of the first hit. Returns the fraction travelled and the hit. */
+    function sweep(backend, pos, height, motion, self) {
+        const len = Math.hypot(motion[0], motion[1], motion[2]);
+        if (!(len > 1e-9))
+            return { fraction: 1, hit: null };
+        const hit = cast(backend, pos, height, motion, self);
+        if (hit === null) {
+            pos[0] += motion[0];
+            pos[1] += motion[1];
+            pos[2] += motion[2];
+            return { fraction: 1, hit: null };
+        }
+        const back = cfg.skinWidth / len;
+        const fraction = Math.max(0, hit.toi - back);
+        pos[0] += motion[0] * fraction;
+        pos[1] += motion[1] * fraction;
+        pos[2] += motion[2] * fraction;
+        return { fraction, hit };
+    }
+    return {
+        config: () => cfg,
+        retune(next) {
+            cfg = resolve({ ...cfg, ...next });
+        },
+        state: () => state,
+        snapshot: () => ({
+            position: [state.position[0], state.position[1], state.position[2]],
+            verticalVelocity: state.verticalVelocity,
+            grounded: state.grounded,
+            groundNormal: [state.groundNormal[0], state.groundNormal[1], state.groundNormal[2]],
+            groundBody: state.groundBody,
+            crouching: state.crouching,
+        }),
+        restore(next) {
+            state = {
+                position: [next.position[0], next.position[1], next.position[2]],
+                verticalVelocity: next.verticalVelocity,
+                grounded: next.grounded,
+                groundNormal: [next.groundNormal[0], next.groundNormal[1], next.groundNormal[2]],
+                groundBody: next.groundBody,
+                crouching: next.crouching,
+            };
+        },
+        shape: () => shapeFor(currentHeight()),
+        center: () => centerFor(state.position, currentHeight()),
+        move(backend, input) {
+            const { dt, self } = input;
+            const result = {
+                moved: [0, 0, 0],
+                grounded: false,
+                groundNormal: [0, 1, 0],
+                hitWall: false,
+                hitCeiling: false,
+                steppedUp: false,
+                crouchBlocked: false,
+            };
+            const start = [state.position[0], state.position[1], state.position[2]];
+            const pos = [start[0], start[1], start[2]];
+            if (input.crouch === true && !state.crouching) {
+                state.crouching = true;
+            }
+            else if (input.crouch === false && state.crouching) {
+                const standing = backend.overlap({
+                    shape: shapeFor(cfg.height),
+                    position: centerFor(pos, cfg.height),
+                    mask: cfg.mask,
+                    ...(self === undefined ? {} : { exclude: self }),
+                });
+                if (standing.length === 0)
+                    state.crouching = false;
+                else
+                    result.crouchBlocked = true;
+            }
+            const height = currentHeight();
+            let carry = [0, 0, 0];
+            if (state.grounded && state.groundBody !== null) {
+                const ground = backend.body(state.groundBody);
+                if (ground !== null)
+                    carry = [ground.velocity[0] * dt, ground.velocity[1] * dt, ground.velocity[2] * dt];
+            }
+            let remaining = [input.motion[0] + carry[0], 0, input.motion[2] + carry[2]];
+            for (let i = 0; i < cfg.maxSlides; i += 1) {
+                const { hit, fraction } = sweep(backend, pos, height, remaining, self);
+                if (hit === null)
+                    break;
+                const left = [remaining[0] * (1 - fraction), remaining[1] * (1 - fraction), remaining[2] * (1 - fraction)];
+                const dot = left[0] * hit.normal[0] + left[1] * hit.normal[1] + left[2] * hit.normal[2];
+                const slid = [
+                    left[0] - hit.normal[0] * dot,
+                    left[1] - hit.normal[1] * dot,
+                    left[2] - hit.normal[2] * dot,
+                ];
+                if (!walkable(hit.normal)) {
+                    result.hitWall = true;
+                    slid[1] = 0;
+                    if (cfg.stepHeight > 0 && !result.steppedUp && tryStepUp(backend, pos, height, remaining, self)) {
+                        result.steppedUp = true;
+                        result.hitWall = false;
+                        break;
+                    }
+                }
+                if (Math.hypot(slid[0], slid[1], slid[2]) < 1e-6)
+                    break;
+                remaining = slid;
+            }
+            if (input.gravity !== undefined)
+                state.verticalVelocity -= input.gravity * dt;
+            if (input.jumpVelocity !== undefined && state.grounded) {
+                state.verticalVelocity = input.jumpVelocity;
+                state.grounded = false;
+            }
+            const wasGrounded = state.grounded;
+            let vertical = state.verticalVelocity * dt + carry[1];
+            if (wasGrounded && vertical <= 0)
+                vertical -= cfg.snapDistance;
+            const { hit: verticalHit } = sweep(backend, pos, height, [0, vertical, 0], self);
+            if (verticalHit !== null && vertical > 0) {
+                result.hitCeiling = true;
+                state.verticalVelocity = 0;
+                state.grounded = false;
+                state.groundBody = null;
+            }
+            else if (verticalHit !== null && walkable(verticalHit.normal)) {
+                state.grounded = true;
+                state.groundNormal = [verticalHit.normal[0], verticalHit.normal[1], verticalHit.normal[2]];
+                state.groundBody = verticalHit.body;
+                if (state.verticalVelocity < 0)
+                    state.verticalVelocity = 0;
+                // A contact at t=0 means touching or already inside; lift by the skin so the next casts start clear.
+                if (verticalHit.toi <= 0)
+                    pos[1] += cfg.skinWidth;
+            }
+            else {
+                state.grounded = false;
+                state.groundBody = null;
+                state.groundNormal = [0, 1, 0];
+            }
+            state.position = pos;
+            result.moved = [pos[0] - start[0], pos[1] - start[1], pos[2] - start[2]];
+            result.grounded = state.grounded;
+            result.groundNormal = [state.groundNormal[0], state.groundNormal[1], state.groundNormal[2]];
+            return result;
+        },
+    };
+    function tryStepUp(backend, pos, height, motion, self) {
+        const probe = [pos[0], pos[1], pos[2]];
+        const up = sweep(backend, probe, height, [0, cfg.stepHeight, 0], self);
+        if (up.hit !== null && up.fraction <= 0)
+            return false;
+        const forward = sweep(backend, probe, height, motion, self);
+        if (forward.hit !== null && forward.fraction < 0.05)
+            return false;
+        const drop = -(probe[1] - pos[1]);
+        const down = sweep(backend, probe, height, [0, drop, 0], self);
+        if (down.hit === null || !walkable(down.hit.normal))
+            return false;
+        if (probe[1] <= pos[1] + 1e-6)
+            return false;
+        pos[0] = probe[0];
+        pos[1] = probe[1];
+        pos[2] = probe[2];
+        return true;
+    }
+}