@jgengine/core 0.7.0 → 0.9.0

package/dist/item/affix.js

@@ -1,23 +1,5 @@
 import { pickWeighted } from "../world/scatterItems.js";
-function hashSeed(seed) {
-    const text = typeof seed === "number" ? seed.toString() : seed;
-    let h = 2166136261 >>> 0;
-    for (let i = 0; i < text.length; i++) {
-        h ^= text.charCodeAt(i);
-        h = Math.imul(h, 16777619);
-    }
-    return h >>> 0;
-}
-export function seededRng(seed) {
-    let a = hashSeed(seed) >>> 0;
-    return () => {
-        a = (a + 0x6d2b79f5) >>> 0;
-        let t = a;
-        t = Math.imul(t ^ (t >>> 15), t | 1);
-        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-    };
-}
+export { seededRng } from "../random/rng.js";
 function resolveRoll(roll, rng) {
     if (typeof roll === "number")
         return roll;

package/dist/meta/changelog.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.7.0";
+export declare const VERSION = "0.9.0";
 export interface ChangelogEntry {
     migrate: readonly string[];
     added: readonly string[];

package/dist/meta/changelog.js

@@ -1,5 +1,63 @@
-export const VERSION = "0.7.0";
+export const VERSION = "0.9.0";
 export const CHANGELOG = {
+    "0.9.0": {
+        migrate: [
+            "Bump every @jgengine/* dependency to ^0.9.0 (the eight packages version in lockstep).",
+            "Mobile HUD fit is now on by default: design-resolution HUD scaling applies to every game with no config change. A desktop-only game that must keep the legacy fixed 0.85 compact zoom declares platforms: [\"web\"] (without \"mobile\").",
+            "Everything else is additive — VisibilitySystem defaults are enabled automatically but only affect renderers that read the policy, and existing games keep every 0.8.0 API unchanged.",
+            "Assets now resolve from this repo's self-hosted mirror (DEFAULT_RELEASE_BASE); games that pinned the previous base can override releaseBase if they need the old host.",
+        ],
+        added: [
+            "Mobile HUD fit — design-resolution UI scaling applies to every game by default: HudCanvas scales the whole HUD from PlayableGame.hudFit.designSize (default 1600×900, clamps minScale/maxScale 0.4–1) so desktop-authored layouts shrink to fit a phone; pure math in @jgengine/core/ui/hudScale (hudScaleForViewport, resolveHudFit, rectOverflow, overflowingPanels), wired by @jgengine/react's HudViewportProvider.",
+            "Graphics → UI scale — a player-facing graphics.uiScale slider (0.5–1.5, default 1) multiplies the computed HUD scale on every platform.",
+            "HUD overflow gate — HudCanvas reports panels that escape the viewport on a data-hud-overflow attribute; bun run shoot <game> --device mobile|both exits non-zero naming the offenders.",
+            "Automatic visibility & streaming defaults — VisibilitySystem (exported from @jgengine/core) gives every scene renderer-agnostic culling and asset-streaming policy with no per-object wiring: distance culling, preload margins, hysteresis, delayed unloading, multi-camera awareness, and per-object overrides.",
+            "Self-hosted asset mirror — DEFAULT_RELEASE_BASE points at this repo's rolling packs release; a catalog-driven mirror-assets workflow (weekly cron + dispatch) keeps it in sync.",
+        ],
+        changed: [
+            "Mobile HUD fit is on by default — design-resolution HUD scaling now applies to every game with no config change (was opt-in via platforms: [\"web\", \"mobile\"]); a desktop-only game keeps the legacy fixed 0.85 compact zoom via platforms: [\"web\"].",
+        ],
+        removed: [],
+    },
+    "0.8.0": {
+        migrate: [
+            "Bump every @jgengine/* dependency to ^0.8.0 (the eight packages version in lockstep).",
+            "Additive only, except for gameui — every other 0.7.0 API is unchanged; opt into any of the below by importing it directly.",
+            "Breaking: replace any @jgengine/react/gameui import with the equivalent registry component (npx shadcn@latest add https://jgengine.com/r/<name>.json), and swap GameUiThemeProvider for --jg-* CSS variables on a wrapper element. GameIcon and friends moved to @jgengine/react/gameIcons.",
+            "leveling({ thresholdMode: 'cumulative' }) is opt-in; the default 'perLevel' behavior is unchanged.",
+            "defineGame.physics.gravity/jumpVelocity are now read by the built-in kinematics controller every frame — if a game already set them expecting a no-op, jump/fall now actually reflects them; omit both to keep the previous defaults.",
+        ],
+        added: [
+            "Transport pipe seam (@jgengine/ws/pipe) — createWsBackend runs over any bidirectional string channel, not just a raw WebSocket, via TransportPipe/TransportPipeHandlers/TransportPipeFactory, with webSocketPipe as the default.",
+            "Browser-safe authoritative host — createGameHost and memoryPersistence moved from @jgengine/node to @jgengine/ws/host (zero Node dependencies; @jgengine/node re-exports both unchanged). @jgengine/ws/hostRouter's createHostRouter extracts the ws wire-protocol session logic into a transport-agnostic HostRouter; @jgengine/node's createGameWsServer is now a thin binding of this router onto the ws npm package. loopbackPipe connects a createWsBackend straight into an in-process router.",
+            "Socket.IO transport — @jgengine/ws/socketIoPipe (socketIoPipe, createSocketIoBackend) and @jgengine/node/socketIoServer (attachGameSocketIoServer) ride the existing ws JSON protocol over socket.io's send/message frames, no socket.io dependency in either package's types. New socketIo() adapter in @jgengine/core/runtime/adapter.",
+            "WebRTC peer-to-peer (@jgengine/ws/peer) — one browser tab hosts authoritatively with no server process: createPeerHost/createPeerGuest, encodePeerSignal/decodePeerSignal for copy-pasteable signaling codes, broadcastChannelSignaling for same-origin multi-tab play. New p2p() adapter.",
+            "LAN adapter + Fly sugar — lan() in @jgengine/core/runtime/adapter resolves to the page's own hostname over ws, no URL configuration; fly() is ws sugar for a Fly.io deploy. apps/dev's Vite server listens on the network and exposes ?p2p=host/join query params.",
+            "ws() (@jgengine/core/runtime/adapter) gained an optional url field, carried through by resolveShellMultiplayer.",
+            "Cumulative leveling — leveling({ thresholdMode: 'cumulative' }) tracks xp as a lifetime total that resolves upward across levels and clamps at the max-level threshold once capped (#12).",
+            "Direction-aware pool depletion — EffectSystem.canReceive(instanceId, effect, magnitude?) takes an optional signed magnitude; negative checks the opposite direction and returns 'pools-depleted' only when every stat in the receive order is already at max, so heals reach fully-depleted targets (#168).",
+            "Puzzle primitives — puzzle/cellGrid (uniform-cell boards: line-clear, match-3 cascade, run detection) and puzzle/fallingPiece (rotation-state shapes, ghost drop, lock delay, classic gravity/level/score curves) for Tetris/match-3 games (#166).",
+            "Voxel field — world/voxelField (createVoxelField, chunked block lattice, neighbors/exposedFaces, 3D DDA raycast, dirty-tracked chunkVersion) for voxel games and instanced renderers; assert on field.summary() the way environment worlds assert on summarizeEnvironment (#166).",
+            "defineGame games may omit assets (an empty catalog is injected); PlayableGame.presentation: 'hud' mounts no 3D canvas/camera/pointer for board/card/menu games; an environment() world auto-renders as the shell's backdrop when PlayableGame.environment is unset (#166).",
+            "Declared-action intent board — turn/intent createIntentBoard for one-turn-ahead intents (Slay-the-Spire style): declare/peek/all/consume/clear (#168).",
+            "turnLoop lifecycle hooks — config.onTurnStart/onTurnEnd fire on every advanceTurn(); ctx.game.turn.loop(id, config) lazily creates/returns a notify-wrapped TurnLoop so every mutation (advanceTurn/advancePhase/advanceRound/spend/gain/refill/setOrder/...) auto-bumps ctx.version() with no manual wiring (#163/#168).",
+            "ctx.game.store — a reactive per-game keyed store (set/delete/get/has/subscribe/mapSnapshot/arraySnapshot) plus @jgengine/react's useGameStore selector hook, replacing hand-rolled module-level stores for ad-hoc reactive game state; ctx.game.cards.pile(id, config?) lazily creates/returns a notify-wrapped CardPile the same way; createCardPile gained an onChange hook for headless use; CommandDefinition.apply may return void for side-effect-only commands (#163).",
+            "Camera — sideScroll rig (fixed lateral follow for 2.5D platformers/beat-'em-ups), a none rig (no camera mounted; pairs with PlayableGame.presentation: 'hud'), rts.pan: false (static backdrop camera: no pan/edge-scroll/rotate/zoom, still re-centers on the follow target), and the observer rig now defaults to the local player when bind is unset (#167).",
+            "Sensors + session — sensor/concealment (colorDistance/concealmentScore/createConcealmentSensor), sensor/freezeMonitor (createFreezeMonitor), session/roles (assignRoles); createRoundState's RoundConfig.teams accepts per-team roles and an optional winCondition that evaluate() checks each tick, and takes an optional phaseOrder for arbitrary named phase cycles (concludeRound/evaluate settle only while the current phase is neither the first nor the last entry) (#151).",
+            "Appearance replication — presence rows carry an optional per-slot appearance channel (cosmetic ids, hex tints, model keys) alongside pose, riding the existing pose message with no protocol bump; wire ctx.player.cosmetics.get(userId) into the outgoing pose (#151).",
+            "ctx.input — a per-frame held-action snapshot (publish(held)/isDown(action)/held()) without bumping ctx.version(); action bindings gained repeatMs (repeat-fire while held); every command resolved from a bound action now carries aim; pointer.secondaryCommand runs a command on right-click off the same raycast as move/ping (#164).",
+            "Object spatial queries + entity patching — ctx.scene.object.at/inBox/raycast/raycastAll over unit-box objects; ctx.scene.entity.update(id, patch) for name/position/rotation/role/movement/behaviors/meta; per-instance renderObject/objectStyles overrides; pointerService.worldHitCenter() + pointer-lock center-ray aiming (#165).",
+            "Controller movement config — PlayerMovementConfig (mode: free/axis/grid, axis, cellSize, collideObjects, beforeCommit pre-commit hook) for the shell-driven walk controller; defineGame.physics.gravity/jumpVelocity are honored by the built-in walk controller (distinct from the standalone physics/physicsWorld rigid-body sim); ctx.player.motion.impulse/setVerticalVelocity/setY/takePending (MotionIntents); entity.spawnPoseOf/resetToSpawn/resetAllToSpawn (#162).",
+            "Model material/animation + paint — ModelConfig.tint/metalness/roughness/animation (GLTF clip playback, paused pose holds); PointerHit.uv + pointerService.sampleSurface() for material-aware picking; ctx.scene.entity.paint runtime paint layer, auto-rendered via a per-instance canvas texture with no per-game wiring; remote-player appearance tint recolors the shell's default capsule (#151).",
+            "Factions & reputation — faction/factions (createFactionGraph faction-vs-faction relation matrix, createFactionRoster entity membership + relationBetweenEntities/isHostile/hostilesOf) turns 'who is my enemy' into a data lookup feeding scene/targeting and ai/threat instead of a per-game role-string check; faction/reputation (createReputationLedger, DEFAULT_REPUTATION_TIERS Hated→Exalted, tierForStanding, effectiveRelation) tracks per-actor standing and overlays it on the base faction relation for at-war reputation grinds.",
+            "Threat taunt — ai/threat gained taunt(source, durationSeconds)/forcedTarget(): a taunt forces the mob onto a tank for its window (overriding highest) and lifts the taunter to the current top threat so aggro holds afterward; decay(dt) counts the window down.",
+            "Devtools discovery covers every game variable — discover.scanTable recurses nested plain objects and arrays into dotted paths (camera.chase.distance, waves.0.speed; 5 levels, 512 entries per scan, dedupes a value reachable through two tables), tunableDiscoveryPlugin rewrites annotated and derived single-line export consts (Math.sqrt(...), PLAYER_HEIGHT - 0.15) not just literals, DevtoolsOverlay self-scans the PlayableGame and core MOVEMENT_TUNING so physics/camera/movement/world config tune with zero exports in any host, resolvePhysicsTuning reads gravity/jumpVelocity live per frame, and the Tune tab gained a filter box.",
+        ],
+        changed: [],
+        removed: [
+            "The gameui component kit (@jgengine/react/gameui) — the themed HUD kit and its GameUiThemeProvider/useGameUiTheme theming. Breaking for anyone importing @jgengine/react/gameui. Now ships as installable shadcn registry items at https://jgengine.com/r/<name>.json, styled with Tailwind + --jg-* CSS variables. GameIcon and friends moved to @jgengine/react/gameIcons.",
+        ],
+    },
     "0.7.0": {
         migrate: [
             "Bump every @jgengine/* dependency to ^0.7.0 (the eight packages version in lockstep).",

package/dist/movement/dash.d.ts

@@ -24,7 +24,9 @@ export interface DashBurst {
 }
 export declare function iframeActive(config: DashConfig, elapsedMs: number): boolean;
 export declare function dashEase(t: number): number;
+export declare function dashDisplacement(config: DashConfig, dir: DashDirection, elapsedMs: number): [number, number, number];
 export declare function dashOffset(config: DashConfig, dir: DashDirection, elapsedMs: number): [number, number, number];
+export declare function dashFrameDelta(config: DashConfig, dir: DashDirection, previousElapsedMs: number, elapsedMs: number): [number, number, number];
 export interface DashState {
     tryDash(direction: DashDirection, nowMs: number): DashRejection | DashBurst;
     tick(dtSeconds: number, nowMs: number): void;
@@ -32,6 +34,7 @@ export interface DashState {
     staminaFraction(): number;
     isDashing(nowMs: number): boolean;
     isInvulnerable(nowMs: number): boolean;
+    displacement(nowMs: number): [number, number, number];
     offset(nowMs: number): [number, number, number];
 }
 export declare function createDashState(config: DashConfig): DashState;

package/dist/movement/dash.js

@@ -5,13 +5,21 @@ export function dashEase(t) {
     const clamped = Math.max(0, Math.min(1, t));
     return 1 - (1 - clamped) * (1 - clamped);
 }
-export function dashOffset(config, dir, elapsedMs) {
+export function dashDisplacement(config, dir, elapsedMs) {
     const traveled = dashEase(elapsedMs / config.durationMs) * config.distance;
     const len = Math.hypot(dir.x, dir.z);
     if (len === 0)
         return [0, 0, 0];
     return [(dir.x / len) * traveled, 0, (dir.z / len) * traveled];
 }
+export function dashOffset(config, dir, elapsedMs) {
+    return dashDisplacement(config, dir, elapsedMs);
+}
+export function dashFrameDelta(config, dir, previousElapsedMs, elapsedMs) {
+    const previous = dashDisplacement(config, dir, previousElapsedMs);
+    const current = dashDisplacement(config, dir, elapsedMs);
+    return [current[0] - previous[0], current[1] - previous[1], current[2] - previous[2]];
+}
 export function createDashState(config) {
     let stamina = config.staminaMax;
     let dashStartMs = null;
@@ -23,6 +31,12 @@ export function createDashState(config) {
         const dt = nowMs - dashStartMs;
         return dt >= 0 && dt < config.durationMs ? dt : null;
     }
+    function displacementAt(nowMs) {
+        const dt = elapsed(nowMs);
+        if (dt === null)
+            return [0, 0, 0];
+        return dashDisplacement(config, dashDir, dt);
+    }
     return {
         tryDash(direction, nowMs) {
             if (elapsed(nowMs) !== null)
@@ -55,11 +69,11 @@ export function createDashState(config) {
             const dt = elapsed(nowMs);
             return dt !== null && iframeActive(config, dt);
         },
+        displacement(nowMs) {
+            return displacementAt(nowMs);
+        },
         offset(nowMs) {
-            const dt = elapsed(nowMs);
-            if (dt === null)
-                return [0, 0, 0];
-            return dashOffset(config, dashDir, dt);
+            return displacementAt(nowMs);
         },
     };
 }

package/dist/movement/glideModel.d.ts

@@ -0,0 +1,44 @@
+export type GlideVec3 = readonly [number, number, number];
+export interface GlideModelConfig {
+    /** Fraction of gravity felt while gliding; default `0.25`. */
+    gravityScale?: number;
+    /** Gravity used before scaling; default `20`. */
+    gravity?: number;
+    /** Forward cruise acceleration toward `forwardSpeed`; default `10`. */
+    thrustAccel?: number;
+    /** Cruise speed the glider settles toward along its heading; default `12`. */
+    forwardSpeed?: number;
+    /** Yaw radians/s at full steer input; default `1.6`. */
+    yawRate?: number;
+    /** Vertical thrust (units/s²) at full throttle — powered climb; default `0` (unpowered glide). */
+    climbAccel?: number;
+    /** Terminal fall speed; default `8`. */
+    maxFallSpeed?: number;
+    /** Control softness in `[0, 1]` — `1` full authority, lower values (turbulence) blunt steering and thrust; default `1`. */
+    control?: number;
+}
+export interface GlideInput {
+    /** Steering in `[-1, 1]` (positive turns toward +x when facing +z). */
+    yaw?: number;
+    /** Powered climb in `[0, 1]` (needs `climbAccel`). */
+    throttle?: number;
+    /** Runtime control-authority override in `[0, 1]` — schedule-varying turbulence; overrides the config `control`. */
+    control?: number;
+}
+export interface GlideStep {
+    position: GlideVec3;
+    velocity: GlideVec3;
+    heading: number;
+}
+/**
+ * A kinematic glider (#282.6) — the walk-controller-compatible sibling of `physics/traversal`'s
+ * rigid-body `Glide`, with the yaw and powered-climb authority that one lacks. External flows —
+ * `physics/flowTube` corridors, `world/windZones` schedules — compose per tick through
+ * `externalVelocity`, and turbulence degrades control through the `control` scalar.
+ */
+export interface GlideModel {
+    step(dt: number, input?: GlideInput, externalVelocity?: GlideVec3): GlideStep;
+    pose(): GlideStep;
+    launch(position: GlideVec3, heading: number, initialSpeed?: number): void;
+}
+export declare function createGlideModel(config?: GlideModelConfig): GlideModel;

package/dist/movement/glideModel.js

@@ -0,0 +1,54 @@
+export function createGlideModel(config = {}) {
+    const gravity = (config.gravity ?? 20) * (config.gravityScale ?? 0.25);
+    const thrustAccel = config.thrustAccel ?? 10;
+    const forwardSpeed = config.forwardSpeed ?? 12;
+    const yawRate = config.yawRate ?? 1.6;
+    const climbAccel = config.climbAccel ?? 0;
+    const maxFallSpeed = config.maxFallSpeed ?? 8;
+    const baseControl = config.control ?? 1;
+    let x = 0;
+    let y = 0;
+    let z = 0;
+    let heading = 0;
+    let vx = 0;
+    let vy = 0;
+    let vz = 0;
+    function snapshot() {
+        return { position: [x, y, z], velocity: [vx, vy, vz], heading };
+    }
+    return {
+        launch(position, nextHeading, initialSpeed = forwardSpeed) {
+            x = position[0];
+            y = position[1];
+            z = position[2];
+            heading = nextHeading;
+            vx = Math.sin(heading) * initialSpeed;
+            vy = 0;
+            vz = Math.cos(heading) * initialSpeed;
+        },
+        pose: snapshot,
+        step(dt, input = {}, externalVelocity) {
+            if (dt <= 0)
+                return snapshot();
+            const control = Math.max(0, Math.min(1, input.control ?? baseControl));
+            heading += (input.yaw ?? 0) * yawRate * control * dt;
+            const fx = Math.sin(heading);
+            const fz = Math.cos(heading);
+            const along = vx * fx + vz * fz;
+            const cruise = (forwardSpeed - along) * Math.min(1, (thrustAccel / Math.max(1, forwardSpeed)) * dt);
+            vx += fx * cruise * control;
+            vz += fz * cruise * control;
+            vy -= gravity * dt;
+            const throttle = Math.max(0, Math.min(1, input.throttle ?? 0));
+            if (climbAccel > 0 && throttle > 0)
+                vy += climbAccel * throttle * control * dt;
+            if (vy < -maxFallSpeed)
+                vy = -maxFallSpeed;
+            const [ex, ey, ez] = externalVelocity ?? [0, 0, 0];
+            x += (vx + ex) * dt;
+            y += (vy + ey) * dt;
+            z += (vz + ez) * dt;
+            return snapshot();
+        },
+    };
+}

package/dist/movement/grappleSwing.d.ts

@@ -0,0 +1,34 @@
+export type SwingVec3 = readonly [number, number, number];
+export interface GrappleSwingConfig {
+    /** Rope shortens by this many units/s while `reeling`. Default `0` (fixed length). */
+    reelSpeed?: number;
+    minLength?: number;
+    /** Extra spring pull toward the anchor when the rope is taut (elastic feel); default `0` (hard constraint only). */
+    stiffness?: number;
+    /** Velocity damping per second while attached; default `0.1`. */
+    damping?: number;
+}
+export interface GrappleSwingState {
+    attached: boolean;
+    anchor: SwingVec3 | null;
+    ropeLength: number;
+}
+export interface GrappleSwingStep {
+    position: SwingVec3;
+    velocity: SwingVec3;
+}
+/**
+ * A rope-swing constraint for kinematic controllers (#282.5) — the walk-controller-compatible
+ * sibling of `physics/traversal`'s rigid-body `Grapple`. Fire at an anchor, feed each frame's
+ * integrated position/velocity through `step`, and commit what comes back (via `beforeCommit`
+ * or `setPose`): positions beyond the rope clamp to its sphere and velocity loses its outward
+ * radial component, which is exactly a pendulum swing.
+ */
+export interface GrappleSwing {
+    fire(anchor: SwingVec3, from: SwingVec3): void;
+    release(): void;
+    state(): GrappleSwingState;
+    /** Constrain one frame. `reeling` shortens the rope; returns the corrected position/velocity. */
+    step(position: SwingVec3, velocity: SwingVec3, dt: number, reeling?: boolean): GrappleSwingStep;
+}
+export declare function createGrappleSwing(config?: GrappleSwingConfig): GrappleSwing;

package/dist/movement/grappleSwing.js

@@ -0,0 +1,56 @@
+export function createGrappleSwing(config = {}) {
+    const reelSpeed = config.reelSpeed ?? 0;
+    const minLength = config.minLength ?? 1;
+    const stiffness = config.stiffness ?? 0;
+    const damping = config.damping ?? 0.1;
+    let anchor = null;
+    let ropeLength = 0;
+    return {
+        fire(nextAnchor, from) {
+            anchor = nextAnchor;
+            ropeLength = Math.max(minLength, Math.hypot(from[0] - nextAnchor[0], from[1] - nextAnchor[1], from[2] - nextAnchor[2]));
+        },
+        release() {
+            anchor = null;
+        },
+        state: () => ({ attached: anchor !== null, anchor, ropeLength }),
+        step(position, velocity, dt, reeling = false) {
+            if (anchor === null || dt <= 0)
+                return { position, velocity };
+            if (reeling && reelSpeed > 0)
+                ropeLength = Math.max(minLength, ropeLength - reelSpeed * dt);
+            let px = position[0];
+            let py = position[1];
+            let pz = position[2];
+            let vx = velocity[0];
+            let vy = velocity[1];
+            let vz = velocity[2];
+            const dx = px - anchor[0];
+            const dy = py - anchor[1];
+            const dz = pz - anchor[2];
+            const distance = Math.hypot(dx, dy, dz);
+            if (distance > ropeLength && distance > 1e-9) {
+                const nx = dx / distance;
+                const ny = dy / distance;
+                const nz = dz / distance;
+                px = anchor[0] + nx * ropeLength;
+                py = anchor[1] + ny * ropeLength;
+                pz = anchor[2] + nz * ropeLength;
+                const radial = vx * nx + vy * ny + vz * nz;
+                if (radial > 0) {
+                    vx -= nx * radial;
+                    vy -= ny * radial;
+                    vz -= nz * radial;
+                }
+                if (stiffness > 0) {
+                    const pull = (distance - ropeLength) * stiffness * dt;
+                    vx -= nx * pull;
+                    vy -= ny * pull;
+                    vz -= nz * pull;
+                }
+            }
+            const damp = Math.max(0, 1 - damping * dt);
+            return { position: [px, py, pz], velocity: [vx * damp, vy * damp, vz * damp] };
+        },
+    };
+}

package/dist/movement/leaderTrail.d.ts

@@ -0,0 +1,29 @@
+export type TrailPoint = readonly [number, number, number];
+export interface LeaderTrailConfig {
+    /** Arc-length gap between consecutive followers. */
+    spacing: number;
+    /** Followers the trail must be able to serve; history is capped to cover them. Default `16`. */
+    maxFollowers?: number;
+    /** Minimum leader movement before a new trail sample is recorded; default `spacing / 8`. */
+    sampleDistance?: number;
+}
+export interface TrailPose {
+    position: TrailPoint;
+    /** Yaw (radians) of the trail direction at this point, matching engine `rotationY`. */
+    heading: number;
+}
+/**
+ * A live breadcrumb trail recorded from a moving leader, with followers placed by arc-length
+ * behind the head — conga lines, convoys, duckling chains, snake bodies. Call `record` with the
+ * leader's position every tick; read `followerAt(i)` for the pose `spacing * (i + 1)` behind.
+ */
+export interface LeaderTrail {
+    record(position: TrailPoint): void;
+    /** Pose for follower `index` (0 = closest behind the leader); `null` until enough trail exists. */
+    followerAt(index: number): TrailPose | null;
+    /** Recorded arc length available behind the leader. */
+    length(): number;
+    /** Drop all history (teleport, respawn) and optionally restart from a position. */
+    reset(position?: TrailPoint): void;
+}
+export declare function createLeaderTrail(config: LeaderTrailConfig): LeaderTrail;

package/dist/movement/leaderTrail.js

@@ -0,0 +1,67 @@
+export function createLeaderTrail(config) {
+    if (!(config.spacing > 0))
+        throw new Error(`leader trail spacing must be positive, got ${config.spacing}`);
+    const spacing = config.spacing;
+    const maxFollowers = Math.max(1, config.maxFollowers ?? 16);
+    const sampleDistance = config.sampleDistance ?? spacing / 8;
+    const capacity = spacing * (maxFollowers + 1);
+    let points = [];
+    let lengths = [];
+    let total = 0;
+    function trim() {
+        while (total > capacity && lengths.length > 0) {
+            const tailSegment = lengths[0];
+            if (total - tailSegment < capacity)
+                break;
+            lengths.shift();
+            points.shift();
+            total -= tailSegment;
+        }
+    }
+    return {
+        record(position) {
+            const head = points[points.length - 1];
+            if (head === undefined) {
+                points.push(position);
+                return;
+            }
+            const step = Math.hypot(position[0] - head[0], position[1] - head[1], position[2] - head[2]);
+            if (step < sampleDistance)
+                return;
+            points.push(position);
+            lengths.push(step);
+            total += step;
+            trim();
+        },
+        followerAt(index) {
+            const behind = spacing * (index + 1);
+            if (behind > total)
+                return null;
+            let remaining = behind;
+            for (let i = lengths.length - 1; i >= 0; i -= 1) {
+                const segment = lengths[i];
+                const to = points[i + 1];
+                const from = points[i];
+                if (remaining <= segment) {
+                    const fraction = segment <= 1e-9 ? 0 : remaining / segment;
+                    return {
+                        position: [
+                            to[0] + (from[0] - to[0]) * fraction,
+                            to[1] + (from[1] - to[1]) * fraction,
+                            to[2] + (from[2] - to[2]) * fraction,
+                        ],
+                        heading: Math.atan2(to[0] - from[0], to[2] - from[2]),
+                    };
+                }
+                remaining -= segment;
+            }
+            return null;
+        },
+        length: () => total,
+        reset(position) {
+            points = position === undefined ? [] : [position];
+            lengths = [];
+            total = 0;
+        },
+    };
+}

package/dist/movement/movementModel.d.ts

@@ -6,8 +6,9 @@
  * integration. Keeping it framework-free means the kinematics controller,
  * the keyboard handler and the on-screen touch D-pad all speak the same
  * vocabulary, and the translation is unit testable without a renderer.
- * DOM capture, pointer lock, and the per-frame look channel live in
- * movementInput.ts.
+ * DOM capture lives in `@jgengine/shell`'s GamePlayerShell (keyboard and
+ * touch controls) and its camera rigs (pointer lock, the per-frame look
+ * channel).
  */
 export type MovementKey = "w" | "a" | "s" | "d" | "shift" | "control" | "c" | "space";
 export type MovementKeysState = Record<MovementKey, boolean>;
@@ -79,6 +80,14 @@ export interface MovementFrameStep {
     stepX: number;
     stepZ: number;
 }
+/**
+ * Per-game overrides for the gravity/jump feel, sourced from
+ * `GameDefinition.physics`. Omitted fields fall back to {@link MOVEMENT_TUNING}.
+ */
+export interface MovementTuningOverrides {
+    gravityAcceleration?: number;
+    jumpVelocity?: number;
+}
 /**
  * Advance one frame of avatar kinematics. Mutates `motion` (velocity, jump,
  * gravity, grounded) and returns the horizontal step to commit through the
@@ -89,7 +98,31 @@ export interface MovementFrameStep {
  * this out of the render loop is what lets us assert "held forward for N frames
  * crosses the room" in a unit test instead of only in the live game.
  */
-export declare function advancePlayerMotion(motion: PlayerMotionState, intent: MovementIntent, forwardX: number, forwardZ: number, baseSpeed: number, rawDeltaSeconds: number): MovementFrameStep;
+export declare function advancePlayerMotion(motion: PlayerMotionState, intent: MovementIntent, forwardX: number, forwardZ: number, baseSpeed: number, rawDeltaSeconds: number, tuning?: MovementTuningOverrides): MovementFrameStep;
+/** A placed scene object the walking player collides against as a circle-vs-AABB obstacle. */
+export interface CollisionObstacle {
+    position: readonly [number, number, number];
+    /** Box half-size on each axis. Default `[0.5, 0.5, 0.5]` (unit-box scene objects). */
+    halfExtents?: readonly [number, number, number];
+}
+/**
+ * Resolve a horizontal step against nearby placed objects with classic
+ * axis-separated sliding (try X, then Z against the post-X position) so
+ * walking into a wall stops the blocked axis but keeps sliding along the
+ * other. Obstacles are treated as circle-vs-AABB in the X/Z plane, inflated
+ * by `playerRadius`; an obstacle whose vertical span misses the player's
+ * feet-to-head span is skipped entirely. Callers should pre-filter to nearby
+ * objects — this also early-exits per obstacle on horizontal distance.
+ */
+export declare function resolveObstacleStep(current: readonly [number, number, number], stepX: number, stepZ: number, obstacles: readonly CollisionObstacle[], playerRadius?: number): MovementFrameStep;
+/** Zeroes the off-axis component so travel is locked to a single world axis (`PlayerMovementConfig.mode: "axis"`). */
+export declare function constrainStepToAxis(stepX: number, stepZ: number, axis: "x" | "z"): MovementFrameStep;
+/**
+ * Snap a world position to its containing cell's center, matching the
+ * bounds-free form of `navGrid`'s and `tacticalGrid`'s `floor` + half-cell
+ * convention (`PlayerMovementConfig.mode: "grid"`).
+ */
+export declare function snapPositionToGrid(x: number, z: number, cellSize: number): [number, number];
 /** Peak jump height from MOVEMENT_TUNING.jumpVelocity + gravity, with small buffer. */
 export declare const MAX_JUMP_OFFSET = 1.15;
 /** Camera yaw looks along -Z; character mesh faces +Z at body rotation.y = 0. */

package/dist/movement/movementModel.js

@@ -6,8 +6,9 @@
  * integration. Keeping it framework-free means the kinematics controller,
  * the keyboard handler and the on-screen touch D-pad all speak the same
  * vocabulary, and the translation is unit testable without a renderer.
- * DOM capture, pointer lock, and the per-frame look channel live in
- * movementInput.ts.
+ * DOM capture lives in `@jgengine/shell`'s GamePlayerShell (keyboard and
+ * touch controls) and its camera rigs (pointer lock, the per-frame look
+ * channel).
  */
 export function createEmptyMovementKeys() {
     return { w: false, a: false, s: false, d: false, shift: false, control: false, c: false, space: false };
@@ -98,9 +99,11 @@ export function createPlayerMotionState() {
  * this out of the render loop is what lets us assert "held forward for N frames
  * crosses the room" in a unit test instead of only in the live game.
  */
-export function advancePlayerMotion(motion, intent, forwardX, forwardZ, baseSpeed, rawDeltaSeconds) {
+export function advancePlayerMotion(motion, intent, forwardX, forwardZ, baseSpeed, rawDeltaSeconds, tuning) {
     const deltaSeconds = Math.min(rawDeltaSeconds, MOVEMENT_TUNING.maxFrameSeconds);
     const targetSpeed = resolveTargetSpeed(intent, baseSpeed);
+    const gravityAcceleration = tuning?.gravityAcceleration ?? MOVEMENT_TUNING.gravityAcceleration;
+    const jumpVelocity = tuning?.jumpVelocity ?? MOVEMENT_TUNING.jumpVelocity;
     let targetVelocityX = 0;
     let targetVelocityZ = 0;
     if (intent.moving) {
@@ -145,12 +148,12 @@ export function advancePlayerMotion(motion, intent, forwardX, forwardZ, baseSpee
     }
     const jumpPressed = intent.jumping;
     if (jumpPressed && !motion.jumpHeld && motion.grounded && !intent.crouching) {
-        motion.verticalVelocity = MOVEMENT_TUNING.jumpVelocity;
+        motion.verticalVelocity = jumpVelocity;
         motion.grounded = false;
     }
     motion.jumpHeld = jumpPressed;
     if (!motion.grounded || motion.verticalVelocity > 0) {
-        motion.verticalVelocity -= MOVEMENT_TUNING.gravityAcceleration * deltaSeconds;
+        motion.verticalVelocity -= gravityAcceleration * deltaSeconds;
         motion.jumpOffset += motion.verticalVelocity * deltaSeconds;
         if (motion.jumpOffset <= 0) {
             motion.jumpOffset = 0;
@@ -163,6 +166,79 @@ export function advancePlayerMotion(motion, intent, forwardX, forwardZ, baseSpee
         stepZ: motion.horizontalVelocityZ * deltaSeconds,
     };
 }
+const DEFAULT_OBSTACLE_HALF_EXTENTS = [0.5, 0.5, 0.5];
+const DEFAULT_OBSTACLE_PLAYER_RADIUS = 0.3;
+/** Feet-to-head span used for the obstacle's vertical overlap test; matches DEFAULT_VOXEL_DIMS.height. */
+const OBSTACLE_PLAYER_HEIGHT = 1.8;
+function clampAxisStep(originalCoord, step, min, max) {
+    if (step === 0)
+        return 0;
+    const target = originalCoord + step;
+    if (target <= min || target >= max)
+        return step;
+    if (step > 0)
+        return originalCoord <= min ? min - originalCoord : 0;
+    return originalCoord >= max ? max - originalCoord : 0;
+}
+/**
+ * Resolve a horizontal step against nearby placed objects with classic
+ * axis-separated sliding (try X, then Z against the post-X position) so
+ * walking into a wall stops the blocked axis but keeps sliding along the
+ * other. Obstacles are treated as circle-vs-AABB in the X/Z plane, inflated
+ * by `playerRadius`; an obstacle whose vertical span misses the player's
+ * feet-to-head span is skipped entirely. Callers should pre-filter to nearby
+ * objects — this also early-exits per obstacle on horizontal distance.
+ */
+export function resolveObstacleStep(current, stepX, stepZ, obstacles, playerRadius = DEFAULT_OBSTACLE_PLAYER_RADIUS) {
+    const feetY = current[1];
+    const headY = feetY + OBSTACLE_PLAYER_HEIGHT;
+    const reachX = Math.abs(stepX) + playerRadius;
+    const reachZ = Math.abs(stepZ) + playerRadius;
+    const nearby = [];
+    for (const obstacle of obstacles) {
+        const halfExtents = obstacle.halfExtents ?? DEFAULT_OBSTACLE_HALF_EXTENTS;
+        const obstacleBottom = obstacle.position[1] - halfExtents[1];
+        const obstacleTop = obstacle.position[1] + halfExtents[1];
+        if (obstacleTop <= feetY || obstacleBottom >= headY)
+            continue;
+        const dx = obstacle.position[0] - current[0];
+        const dz = obstacle.position[2] - current[2];
+        if (Math.abs(dx) > halfExtents[0] + reachX || Math.abs(dz) > halfExtents[2] + reachZ)
+            continue;
+        nearby.push({
+            minX: obstacle.position[0] - halfExtents[0] - playerRadius,
+            maxX: obstacle.position[0] + halfExtents[0] + playerRadius,
+            minZ: obstacle.position[2] - halfExtents[2] - playerRadius,
+            maxZ: obstacle.position[2] + halfExtents[2] + playerRadius,
+        });
+    }
+    let resultX = stepX;
+    for (const box of nearby) {
+        if (current[2] <= box.minZ || current[2] >= box.maxZ)
+            continue;
+        resultX = clampAxisStep(current[0], resultX, box.minX, box.maxX);
+    }
+    const nextX = current[0] + resultX;
+    let resultZ = stepZ;
+    for (const box of nearby) {
+        if (nextX <= box.minX || nextX >= box.maxX)
+            continue;
+        resultZ = clampAxisStep(current[2], resultZ, box.minZ, box.maxZ);
+    }
+    return { stepX: resultX, stepZ: resultZ };
+}
+/** Zeroes the off-axis component so travel is locked to a single world axis (`PlayerMovementConfig.mode: "axis"`). */
+export function constrainStepToAxis(stepX, stepZ, axis) {
+    return axis === "x" ? { stepX, stepZ: 0 } : { stepX: 0, stepZ };
+}
+/**
+ * Snap a world position to its containing cell's center, matching the
+ * bounds-free form of `navGrid`'s and `tacticalGrid`'s `floor` + half-cell
+ * convention (`PlayerMovementConfig.mode: "grid"`).
+ */
+export function snapPositionToGrid(x, z, cellSize) {
+    return [(Math.floor(x / cellSize) + 0.5) * cellSize, (Math.floor(z / cellSize) + 0.5) * cellSize];
+}
 /** Peak jump height from MOVEMENT_TUNING.jumpVelocity + gravity, with small buffer. */
 export const MAX_JUMP_OFFSET = 1.15;
 /** Camera yaw looks along -Z; character mesh faces +Z at body rotation.y = 0. */