@jgengine/core 0.7.0 → 0.8.0

package/dist/input/touchScheme.js

@@ -0,0 +1,115 @@
+/**
+ * Touch control scheme derived from a game's existing action bindings: the
+ * capture layer renders a virtual joystick, on-screen buttons, and a gesture
+ * surface, and feeds synthetic `touch:<action>` codes into the same
+ * ActionStateTracker the keyboard uses, so games gain touch play without any
+ * per-game input code. Games refine the derived defaults through
+ * TouchControlsConfig (gesture bindings, button curation) or opt out entirely
+ * with `touch: false`.
+ */
+import { isHotbarSlotAction } from "./actionBindings.js";
+export const TOUCH_CODE_PREFIX = "touch:";
+export function touchCode(action) {
+    return `${TOUCH_CODE_PREFIX}${action}`;
+}
+/** Every action gains a synthetic touch code alongside its physical codes. */
+export function withTouchCodes(map) {
+    const result = {};
+    for (const action of Object.keys(map ?? {})) {
+        const codes = map[action];
+        const synthetic = touchCode(action);
+        if (Array.isArray(codes)) {
+            result[action] = [...codes, synthetic];
+        }
+        else {
+            const modes = codes;
+            const toggleOnly = (modes.toggle?.length ?? 0) > 0 && (modes.hold?.length ?? 0) === 0;
+            result[action] = toggleOnly
+                ? { hold: modes.hold, toggle: [...(modes.toggle ?? []), synthetic] }
+                : { hold: [...(modes.hold ?? []), synthetic], toggle: modes.toggle };
+        }
+    }
+    return result;
+}
+const DEFAULT_LOOK_SENSITIVITY = 0.005;
+const JOYSTICK_AXES = {
+    up: ["moveForward"],
+    down: ["moveBack"],
+    left: ["moveLeft", "turnLeft"],
+    right: ["moveRight", "turnRight"],
+};
+const BUTTONABLE_RESERVED = new Set(["jump", "sprint", "interact", "useAbility"]);
+export function touchActionLabel(action) {
+    const spaced = action.replace(/([a-z0-9])([A-Z])/g, "$1 $2");
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+function gestureActions(gestures) {
+    const used = new Set();
+    if (gestures === undefined)
+        return used;
+    for (const action of [gestures.tap, gestures.swipeUp, gestures.swipeDown, gestures.swipeLeft, gestures.swipeRight]) {
+        if (action !== undefined)
+            used.add(action);
+    }
+    const drag = gestures.drag;
+    for (const action of [drag?.left, drag?.right, drag?.up, drag?.down]) {
+        if (action !== undefined)
+            used.add(action);
+    }
+    return used;
+}
+/**
+ * Null means "render no touch controls" — either the game opted out or there
+ * is nothing to synthesize.
+ */
+export function deriveTouchScheme(input, { reserved, firstPerson, config }) {
+    if (config === false)
+        return null;
+    const actions = Object.keys(input ?? {});
+    const bound = new Set(actions);
+    const joystickMapped = new Set();
+    let joystick = null;
+    if (config?.movement !== false) {
+        const resolveAxis = (candidates) => {
+            const action = candidates.find((candidate) => bound.has(candidate)) ?? null;
+            if (action !== null)
+                joystickMapped.add(action);
+            return action;
+        };
+        const axes = {
+            up: resolveAxis(JOYSTICK_AXES.up),
+            down: resolveAxis(JOYSTICK_AXES.down),
+            left: resolveAxis(JOYSTICK_AXES.left),
+            right: resolveAxis(JOYSTICK_AXES.right),
+        };
+        joystick = axes.up === null && axes.down === null && axes.left === null && axes.right === null ? null : axes;
+    }
+    const gestures = config?.gestures ?? null;
+    const consumedByGestures = gestureActions(config?.gestures);
+    const hidden = new Set(config?.hidden ?? []);
+    let buttons;
+    if (config?.buttons !== undefined) {
+        buttons = config.buttons.map((spec) => typeof spec === "string"
+            ? { action: spec, label: touchActionLabel(spec), icon: null }
+            : { action: spec.action, label: spec.label ?? touchActionLabel(spec.action), icon: spec.icon ?? null });
+    }
+    else {
+        buttons = actions
+            .filter((action) => !joystickMapped.has(action))
+            .filter((action) => !isHotbarSlotAction(action))
+            .filter((action) => !consumedByGestures.has(action))
+            .filter((action) => !hidden.has(action))
+            .filter((action) => !reserved.has(action) || BUTTONABLE_RESERVED.has(action))
+            .map((action) => ({ action, label: touchActionLabel(action), icon: null }));
+    }
+    const look = config?.look ?? firstPerson;
+    if (joystick === null && buttons.length === 0 && gestures === null && !look)
+        return null;
+    return {
+        joystick,
+        buttons,
+        gestures,
+        look,
+        lookSensitivity: config?.lookSensitivity ?? DEFAULT_LOOK_SENSITIVITY,
+    };
+}

package/dist/item/affix.d.ts

@@ -45,7 +45,7 @@ export interface RolledItem {
     affixes: readonly RolledAffix[];
     stats: Record<string, number>;
 }
-export declare function seededRng(seed: string | number): () => number;
+export { seededRng } from "../random/rng.js";
 export interface AffixRoller {
     rollRarity(rng: () => number): RarityTier;
     roll(base: ItemBaseDef, rarityId: string, rng: () => number): RolledItem;

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.8.0";
 export interface ChangelogEntry {
     migrate: readonly string[];
     added: readonly string[];

package/dist/meta/changelog.js

@@ -1,5 +1,41 @@
-export const VERSION = "0.7.0";
+export const VERSION = "0.8.0";
 export const CHANGELOG = {
+    "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).",
+        ],
+        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/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. */

package/dist/movement/voxelController.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Voxel character controller (pure model).
+ *
+ * The base first-person controller in `movementModel.ts` assumes flat ground at
+ * y=0 — it integrates gravity into a `jumpOffset` and never asks the world how
+ * tall the ground is. That is fine for a plaza demo but wrong for any game where
+ * the player walks on placed blocks and digs down into the world: they float on
+ * an invisible floor, clip through walls, and can never descend.
+ *
+ * This module resolves the player as an axis-aligned box against a set of solid
+ * unit cells (a `SolidQuery`), so the same held-keys → intent pipeline drives a
+ * body that stands on blocks, falls into holes, is stopped by walls, and steps
+ * up single-block ledges. Keeping it renderer-free means the shell can drive it
+ * from live scene objects while the descent/landing/step-up behaviour stays unit
+ * testable without three.js.
+ *
+ * Cell convention matches the shell's object rendering and the voxel raycast:
+ * cell (x,y,z) is the solid box X∈[x-0.5,x+0.5], Y∈[y,y+1], Z∈[z-0.5,z+0.5]. A
+ * block at cell y therefore has its top face at world y+1, so a player standing
+ * on the surface layer (cell y=-1) rests with their feet at y=0.
+ */
+import { type MovementIntent, type MovementTuningOverrides } from "./movementModel.js";
+export type SolidQuery = (x: number, y: number, z: number) => boolean;
+/** Footprint + height of the player box, in world units. */
+export interface VoxelPlayerDims {
+    /** Half the box width on both horizontal axes. */
+    halfWidth: number;
+    /** Box height measured up from the feet. */
+    height: number;
+    /** Tallest ledge the player walks up without jumping. */
+    stepHeight: number;
+}
+export declare const DEFAULT_VOXEL_DIMS: VoxelPlayerDims;
+/** Mutable kinematic state carried between frames by the voxel controller. */
+export interface VoxelPlayerBody {
+    x: number;
+    y: number;
+    z: number;
+    velocityX: number;
+    velocityY: number;
+    velocityZ: number;
+    grounded: boolean;
+    jumpHeld: boolean;
+}
+export declare function createVoxelPlayerBody(x: number, y: number, z: number): VoxelPlayerBody;
+/** Samples the terrain floor height at a point; unset means flat ground plays no part in support. */
+export type GroundHeightQuery = (x: number, z: number) => number;
+/**
+ * Advance one frame of voxel-collided player kinematics. Mutates `body`
+ * (position, velocity, grounded) in place.
+ *
+ * `forwardX`/`forwardZ` are the camera heading projected onto the ground plane
+ * (need not be normalized). Pulling this out of the render loop is what lets us
+ * assert "dig the block underfoot and the player drops a level" in a unit test.
+ *
+ * `groundHeight`, when supplied, is an additional solid floor sampled at the
+ * body's (x, z): the player never sinks below it and standing on it counts as
+ * supported (resets jump state like landing on a solid cell). Where terrain and
+ * a solid cell's top disagree, the higher of the two wins.
+ */
+export declare function advanceVoxelPlayer(body: VoxelPlayerBody, intent: MovementIntent, forwardX: number, forwardZ: number, baseSpeed: number, rawDeltaSeconds: number, isSolid: SolidQuery, dims?: VoxelPlayerDims, tuning?: MovementTuningOverrides, groundHeight?: GroundHeightQuery): void;