@jgengine/core 0.6.0 → 0.8.0

package/dist/item/modularItem.js

@@ -0,0 +1,75 @@
+export function slotById(def, slotId) {
+    return def.slots.find((s) => s.id === slotId) ?? null;
+}
+export function slotAccepts(slot, category) {
+    return typeof slot.accepts === "string" ? slot.accepts === category : slot.accepts.includes(category);
+}
+export function install(def, installed, slotId, part) {
+    const slot = slotById(def, slotId);
+    if (slot === null)
+        return { status: "rejected", reason: "unknown-slot" };
+    if (!slotAccepts(slot, part.category))
+        return { status: "rejected", reason: "wrong-category" };
+    if (installed.some((i) => i.slotId === slotId))
+        return { status: "rejected", reason: "slot-occupied" };
+    return { status: "ok", installed: [...installed, { slotId, part }] };
+}
+export function uninstall(installed, slotId) {
+    return installed.filter((i) => i.slotId !== slotId);
+}
+export function partInSlot(installed, slotId) {
+    return installed.find((i) => i.slotId === slotId)?.part ?? null;
+}
+export function computeEffectiveStats(def, installed) {
+    const stats = { ...def.baseStats };
+    for (const { part } of installed) {
+        if (part.stats === undefined)
+            continue;
+        for (const [key, value] of Object.entries(part.stats))
+            stats[key] = (stats[key] ?? 0) + value;
+    }
+    for (const { part } of installed) {
+        if (part.multipliers === undefined)
+            continue;
+        for (const [key, factor] of Object.entries(part.multipliers))
+            stats[key] = (stats[key] ?? 0) * factor;
+    }
+    return stats;
+}
+export function missingRequiredSlots(def, installed) {
+    return def.slots.filter((s) => s.required === true && !installed.some((i) => i.slotId === s.id)).map((s) => s.id);
+}
+export function isComplete(def, installed) {
+    return missingRequiredSlots(def, installed).length === 0;
+}
+export function createModularItem(def, initial = []) {
+    let installed = initial;
+    return {
+        def,
+        parts() {
+            return installed;
+        },
+        install(slotId, part) {
+            const result = install(def, installed, slotId, part);
+            if (result.status === "ok")
+                installed = result.installed;
+            return result;
+        },
+        uninstall(slotId) {
+            installed = uninstall(installed, slotId);
+            return installed;
+        },
+        partInSlot(slotId) {
+            return partInSlot(installed, slotId);
+        },
+        effectiveStats() {
+            return computeEffectiveStats(def, installed);
+        },
+        missingRequired() {
+            return missingRequiredSlots(def, installed);
+        },
+        isComplete() {
+            return isComplete(def, installed);
+        },
+    };
+}

package/dist/meta/changelog.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.6.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,75 @@
-export const VERSION = "0.6.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).",
+            "0.7.0 is additive — every 0.6.0 API is unchanged, so no code change is required to upgrade; existing games keep the orbit/first-person camera, single-player-entity control, and every existing primitive exactly as before.",
+            "Opt into any new system by importing it directly: a camera rig via camera.rig; a sensor/* probe with @jgengine/shell/vision renderers; an ai/* director over the nav/ navmesh; turn/* + tactics/* for turn-based games; cards/* + board/* for deckbuilders; crafting/* for recipes/production/farming; survival/* + world/{envField,weather,realm} for survival; combat/{abilityKit,animationState,defensiveWindow} for action feel; physics/{vehicleBody,traversal,structure,ragdoll} for vehicles/destruction; session/* for contested/round/downed/ring/extraction machines; and multiplayer/* for lag-comp/hidden-commit/matchmaking.",
+            "entityStore.update() now also accepts name, so possession/form can retarget an instance's catalog id without despawn/respawn.",
+        ],
+        added: [
+            "Navigation & pointer input — nav/navGrid (A* walkable grid), nav/pathFollow, input/pointer (PointerHit), scene/selection, interaction/contextMenu, and PlayableGame.pointer (worldHit, marquee select, right-click verbs, move/aim commands) in @jgengine/shell.",
+            "Camera rig library — eight rigs on PlayableGame.camera (topDown/iso, rts, shoulder, lockOn, chase + cockpit/hood/rear, orbit, first), a cinematic keyframe path, rig cross-fade, followEntityId: null, and a shared camera-shake/trauma channel (cameraShake / useCameraShake).",
+            "Physics constraints & actors — PhysicsWorld joints (hinge/fixed/distance/spring), onCollision gameplay-event hook, physics/ragdoll, physics/carryable, physics/forceVolume + platformCarry, and physics/spatialGrid broad-phase.",
+            "Vehicles, mounts & racing — physics/vehicleBody (suspension + grip curve), input/axisInput, physics/buoyancy boat, scene/mount multi-seat rideable, physics/damageZones crash stages, and game/race (raceTrack + raceState).",
+            "Traversal & destruction — physics/traversal (grapple/glide), world/carve (voxel carve/deposit + terrain write-back), and physics/structure (integrity graph → debris collapse).",
+            "AI director/behavior/crowds — ai/spawnDirector, ai/threat, ai/jobBoard, ai/crowd flow field, and a scene/behaviors patrol descriptor over the navmesh.",
+            "Abilities, resources & cooldowns — combat/abilityKit (four-state slots), stats/accumulatorMeter + stats/eventMeter (ult/streak), scene/autoTarget, combat/resistance matrix, game/runDraft, and @jgengine/react useAbilitySlots / useEventMeter.",
+            "Character combat feel — combat/animationState, combat/attackTags, combat/defensiveWindow, combat/comboString, combat/breakMeters (stagger/buildup), movement/dash, combat/hitReaction (hitstop + shake), combat/telegraph, and typed float-text styling.",
+            "Item & gear — item/durability, item/affix roller, item/modularItem, and inventory/storageTier (carried vs banked + delivery/insurance/consolation).",
+            "Objective/mode/session machines — session/contestedChannel, session/roundState, combat/downed, session/ring, session/extraction, and runtime/persistenceScope (run-vs-meta split with HostPersistence.resetScenario).",
+            "Turn-based & tactics — turn/turnLoop (+ action-economy pools), turn/commit (immediate/simultaneous/rewind), tactics/tacticalGrid, tactics/predictiveQuery, tactics/snapshot, tactics/surface, and shared combat/effects resolveAreaTargets.",
+            "Card & board stack — cards/cardPile, cards/modifierPipeline, board/laneBoard, board/timelineBoard, inventory/shapedGrid, and @jgengine/react dragLayer.",
+            "Crafting, tech & production — crafting/recipe graph, economy/techTree (prereq-gated unlocks), crafting/production buildings + conveyor/power, and crafting/crop farming state machine.",
+            "Survival & environment — survival/decayMeter, survival/moodle, survival/regionHealth, world/envField, world/weather (+ coarse fire grid), world/realm composition, and @jgengine/shell FireSpreadLayer.",
+            "World items & loot — game/worldItem (third scene bucket), game/lootFilter, onDeath.dropMode world scatter, PlayableGame.worldItem render binding, and @jgengine/react useWorldItems / useNearestWorldItem.",
+            "Placement, building & terraform — world/placementController, world/connectors, world/support, world/walls, world/placedStructureStore, world/terraform (editable terrain write-back), world/buildPermissions, and @jgengine/shell ghost/tint/brush renderers.",
+            "Map, HUD & ping — world/markers, world/fog, world/minimap, game/ping, @jgengine/react Minimap/Compass/WorldMap + useMarkers/useFog, and @jgengine/shell bakeTerrainMap + MapMarkerBeacons.",
+            "Audio & voice — audio/audioFalloff contract, time/beatClock, @jgengine/shell positional emitters (PlayableGame.audio + entitySounds/objectSounds), and @jgengine/ws voiceChannel router.",
+            "Interaction verbs & minigames — interaction/skillCheck, interaction/qte, scene/captureCheck + scene/roster, stats/rollCheck, dialogue skill-check gates, and @jgengine/react SkillCheckBar/QteTrack/CaptureOdds + useRoster.",
+            "Sensors, vision & observer — sensor/revealQuery, sensor/hiddenStateProbe, sensor/frustumSensor, sensor/recordingBuffer, the observer camera rig, and @jgengine/shell vision/replay renderers.",
+            "Player embodiment & expression — scene/possession, scene/form (shapeshift), game/cosmetics loadouts, and social emote broadcast over the presence layer.",
+            "Multiplayer depth — multiplayer/lagCompensation (position history + rewind), multiplayer/simultaneousCommit, multiplayer/combatSnapshot replay, scene/stationClaim shared-vehicle facets, economy/sharedWallet, and multiplayer/matchmaking (browse/filter/join-by-code) with @jgengine/node host support.",
+        ],
+        changed: [],
+        removed: [],
+    },
     "0.6.0": {
         migrate: [
             "Bump every @jgengine/* dependency to ^0.6.0 (the eight packages version in lockstep).",

package/dist/movement/dash.d.ts

@@ -0,0 +1,37 @@
+export interface DashConfig {
+    distance: number;
+    durationMs: number;
+    iframes: {
+        fromMs: number;
+        toMs: number;
+    };
+    staminaCost: number;
+    staminaMax: number;
+    staminaRegenPerSecond: number;
+    cooldownMs: number;
+}
+export interface DashDirection {
+    x: number;
+    z: number;
+}
+export type DashRejection = {
+    reason: "no-stamina" | "cooldown" | "dashing";
+};
+export interface DashBurst {
+    direction: DashDirection;
+    durationMs: number;
+    distance: number;
+}
+export declare function iframeActive(config: DashConfig, elapsedMs: number): boolean;
+export declare function dashEase(t: number): number;
+export declare function dashOffset(config: DashConfig, dir: DashDirection, elapsedMs: number): [number, number, number];
+export interface DashState {
+    tryDash(direction: DashDirection, nowMs: number): DashRejection | DashBurst;
+    tick(dtSeconds: number, nowMs: number): void;
+    stamina(): number;
+    staminaFraction(): number;
+    isDashing(nowMs: number): boolean;
+    isInvulnerable(nowMs: number): boolean;
+    offset(nowMs: number): [number, number, number];
+}
+export declare function createDashState(config: DashConfig): DashState;

package/dist/movement/dash.js

@@ -0,0 +1,65 @@
+export function iframeActive(config, elapsedMs) {
+    return elapsedMs >= config.iframes.fromMs && elapsedMs < config.iframes.toMs;
+}
+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) {
+    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 createDashState(config) {
+    let stamina = config.staminaMax;
+    let dashStartMs = null;
+    let dashDir = { x: 0, z: 0 };
+    let cooldownUntil = 0;
+    function elapsed(nowMs) {
+        if (dashStartMs === null)
+            return null;
+        const dt = nowMs - dashStartMs;
+        return dt >= 0 && dt < config.durationMs ? dt : null;
+    }
+    return {
+        tryDash(direction, nowMs) {
+            if (elapsed(nowMs) !== null)
+                return { reason: "dashing" };
+            if (nowMs < cooldownUntil)
+                return { reason: "cooldown" };
+            if (stamina < config.staminaCost)
+                return { reason: "no-stamina" };
+            stamina -= config.staminaCost;
+            dashStartMs = nowMs;
+            dashDir = direction;
+            cooldownUntil = nowMs + config.cooldownMs;
+            return { direction, durationMs: config.durationMs, distance: config.distance };
+        },
+        tick(dtSeconds, nowMs) {
+            if (dashStartMs !== null && nowMs - dashStartMs >= config.durationMs)
+                dashStartMs = null;
+            stamina = Math.min(config.staminaMax, stamina + config.staminaRegenPerSecond * dtSeconds);
+        },
+        stamina() {
+            return stamina;
+        },
+        staminaFraction() {
+            return config.staminaMax <= 0 ? 0 : stamina / config.staminaMax;
+        },
+        isDashing(nowMs) {
+            return elapsed(nowMs) !== null;
+        },
+        isInvulnerable(nowMs) {
+            const dt = elapsed(nowMs);
+            return dt !== null && iframeActive(config, dt);
+        },
+        offset(nowMs) {
+            const dt = elapsed(nowMs);
+            if (dt === null)
+                return [0, 0, 0];
+            return dashOffset(config, dashDir, dt);
+        },
+    };
+}

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;