@jgengine/core 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -26,14 +26,60 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.18.0
+
 ### Migrate
 
+- **Bump lockstep SDK packages to `^0.18.0`:** `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.15.0`; `@jgengine/github` is `0.5.0`.
+- **Register the presence reaper and redeploy your schema.** `jgPoses` gains `sessionId` / `kind` / `label` / `revokedAt` (all optional) and a `by_updated` index, and `createPresenceFunctions` now also returns `reapIdlePresence`. Re-export it (`export const { list, sync, leave, reapIdlePresence } = createPresenceFunctions(...)`) and add `crons.interval("jg presence reap", { seconds: 60 }, internal.presence.reapIdlePresence, {})`. Without it nothing deletes the row of a player who closed the tab — `list` filtered stale rows at read time but the table grew forever. `jgengineCronSpecs()` carries the new entry, and every spec now names the `module` (`"runtime"` / `"presence"`) it is exported from.
+- **`presence.sync` returns `{ pose, lastSeenAt, displaced }` instead of `null`,** and `presence.leave` marks the row revoked instead of deleting it (the reaper collects it once idle). A caller that ignored the return value is unaffected.
+
 ### Changed
 
+- **`presence.sync` accepts a call with no `pose` at all,** which holds the stored position and moves only the liveness stamp. `createConvexPresenceSync` sends one itself when the pose gate has suppressed writes for 10s, so a standing player keeps their row alive without a pose write — and without the reaper collecting a live session.
+- **`PresencePoseRow` carries optional `sessionId` / `kind` / `label`,** so a nameplate reads off the presence row instead of joining against users per frame.
+
 ### Added
 
+- **`createPresenceFunctions` gains the policy hooks the pose lane was missing** — `resolveSpawn(ctx, { serverId, userId, kind })` for where a session with no row starts (async and ctx-bearing, so a spawn can read the world, replacing a hardcoded origin), `poseRules` as a function of the actor `kind` so an agent need not obey a human's speed cap, `idleCutoffMs` / `maxReapPerRun` for the reaper, and optional `sessionId` on `sync` / `leave`: a second tab is a second row, syncing revokes the others, and the displaced session learns it on its next call through `displaced: true`.
+
+- **A command declares what it touches, so `runCommand` hydrates that and nothing else.** `CommandDef` gains an optional `scope(input, actorUserId)` returning `{ players?, chunkKeys? }`, evaluated before hydration; the registered `runCommand` mutation also accepts an explicit `scope` argument, which wins over the declared one. A game that never sets either keeps the whole-world default. `ServerLoopHooks.joinScope(userId, isNew)` does the same for `onNewPlayer`.
+- **`GameRuntime.commandScope` / `GameRuntime.joinScope`** expose those declarations to any host, alongside the pure helpers `resolveCommandScope` / `scopeWithActor` / `commandScopeEscape` (`@jgengine/core/runtime/commandRunner`).
+
 ### Fixed
 
+- **`runCommand` no longer reads the whole world on every command.** `LoadSnapshotScope` landed in 0.17 but only `helpers.loadSnapshot` accepted one, so the supported way to run a command — the registered `runCommand` mutation, a one-line delegation to `helpers.runCommand` — hydrated every member profile and every chunk however narrow the command was, and a game could only get bounded hydration by reimplementing the mutation. `runCommand`, `joinServer`, and `leaveServer` now hydrate a scope; a command whose `apply` dirties a player or chunk its scope never named is refused rather than persisted, since writing an unhydrated chunk overwrites the stored one with a blank. `flushSave` / `flushServerIfDue` / `tickActiveServers` / `flushDirtyServers` still hydrate everything, which is correct for what they write.
+
+## 0.17.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.17.0`:** `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.14.0`; `@jgengine/github` is `0.4.0`.
+- **A deleted player profile stays deleted.** When a game persists players (`save.scope` includes `player`), hydrating a member with no `jgPlayerProfiles` row no longer falls back to the copy of their state kept on the server row — that copy was resurrected and then written back as authoritative, so a world reset that cleared profiles but not servers silently restored every player's old balance. A game whose save scope excludes players (`"none"`, `"chunks"`) is unchanged: the server-row copy is still their state. If you seed members onto a server row without going through `joinServer`, write their profile row too.
+- **`slotsPerServer` is capped at 256** (`JG_MAX_MEMBERS_PER_SERVER`). `createGameServerFunctions` now throws at wiring time on a larger value instead of accepting it and failing at the write that overflows the document. One server is one Convex document holding the world row, the roster, and every member's session state; a bigger number was never a bigger world. Shard across servers, or move world state into `jgWorldChunks`.
+- **The tick cron only sweeps games that declare `loop.onTick`.** A game with no tick hook used to pay a full hydrate plus a full persist every second per running server, for a snapshot `runtime.tick` returned unchanged; it now costs nothing while idle. If you relied on the tick cron to autosave a hookless game, the 60s `flushDirtyServers` cron and the `flushSave` mutation still do it.
+
+### Changed
+
+- **Walking NPCs now stop at the geometry that stops the player.** `wander`, `patrol`, and `ctx.scene.entity.moveToward` consulted no obstacles at all, so a pedestrian walked through the building the player cannot enter. All three now slide their step against the scene's blocking physical colliders — the same query `stepPlayerMovement` reads. A patrol's path state still advances on its own clock (an authored route is not rewound by contact), but the entity can no longer end a tick inside a solid. Pass `avoidSolids: false` to `moveToward` for a mover meant to ignore the world (a flier, a camera rig).
+- **`@jgengine/assets` verify fails a model source that contributes no index entries.** A model pack that has never been pulled is a pin nothing has ever checked — that is how a Street Pack archive sat in the catalogue titled "Downtown City MegaKit". Record why a pack is not pulled in the new `AssetSource.unpulled` string; materials and sprites pull on demand and are exempt.
+- **`persistServerSnapshot` returns `boolean` and skips a write that would change nothing.** Every subscriber of a query that read a server row re-receives the whole result when that document changes, so an unconditional write on the 1 Hz tick re-pushed the entire world to every client once a second whether or not anything moved. `ServerPersistPlan` gains `changed` (`serverState` / `sessionPlayers` / `revision` / `any`) for hosts that write field-by-field.
+- **`sessionPlayers` is merged over the stored map, not rebuilt from the snapshot**, and entries for non-members are pruned. This is what makes a partially hydrated snapshot safe to persist.
+- **`tickActiveServers` is bounded** to `maxServersPerTick` (default 32) servers per transaction, oldest tick anchor first, instead of pulling every running server of every game into one transaction. `flushDirtyServers` is bounded the same way.
+
+### Added
+
+- **`solidObstaclesNear` / `resolveWalkerStep` (`@jgengine/core/movement/solidObstacles`)** — the engine's single answer to "what is solid here", now shared rather than re-derived per consumer. `solidObstaclesNear(ctx, position, reachX, reachZ)` returns the blocking physical colliders near a point through a bounded `inBox` broadphase; `resolveWalkerStep(ctx, position, stepX, stepZ)` slides a horizontal step against them with the player's axis-separated sliding. Reach for these instead of deriving obstacles from a game catalog's own solidity flags.
+- **Bounded hydration and a client chunk read** — `loadServerSnapshot(ctx, server, runtime, { players, chunkKeys })` hydrates only the members and chunks a mutation will touch instead of a document read per member plus one per chunk, and the generated `getChunks` query lets a client read chunk state by key (capped at `MAX_CHUNKS_PER_QUERY`). Chunks were the documented escape hatch for world state too large for one row, but reads were unbounded and clients could not see them at all, so moving geometry there made things worse. `getServerMeta` returns lobby state (status, member count, revision) without the world payload.
+- **`@jgengine/core/runtime/worldChunks`** — `chunkKeyAt` / `chunkCoordAt` / `chunkKeyOf` / `parseChunkKey` / `chunkKeysInRadius` at a declared cell size, plus `setChunk` / `updateChunk` / `deleteChunk`, which mark the key dirty so the host actually persists it. `chunkKey` was an opaque game-chosen string and the engine never wrote `dirty.chunks`, so every game reimplemented the coordinate mapping and a game that forgot to push a key silently never saved that chunk.
+- **Placed objects cull to `replication.aoiRadius`.** `objects` is the one large spatial replicated set and had no projector, so a world with a few thousand placements sent all of them to every viewer. It now joins the same area-of-interest policy as `entities` and `stats`. Unset `aoiRadius` still replicates everything.
+- **`createGameServerFunctions({ matchmaking: "singleton" })`** — one shared world per game: auto-match always targets the existing world and a join past capacity fails loudly, instead of quietly creating a second world the player would be alone in. `joinServer` also reconciles a stored `slotsPerServer`/`save` that has drifted from the host options, which previously made raising the option a no-op on worlds that already existed. `selectJoinTarget` (`@jgengine/core/runtime/hostPolicy`) is the pure decision behind it.
+- **`GameRuntime.hasTick`** reports whether a runtime declares `loop.onTick`, so any host's scheduler can skip a server whose tick is a no-op by construction.
+
+### Removed
+
+- **Asset source `quaternius-downtown-city`.** It was titled "Downtown City MegaKit" but pinned at the Street Pack archive, which ships Blends/FBX/OBJ only — a pull found no models. Nothing referenced it.
+
 ## 0.16.0
 
 ### Migrate

package/dist/meta/changelog.d.ts

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

package/dist/meta/changelog.js

@@ -1,7 +1,51 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.16.0";
+export const VERSION = "0.18.0";
 /** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "0.18.0": {
+        migrate: [
+            "Bump lockstep SDK packages to `^0.18.0`: `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.15.0`; `@jgengine/github` is `0.5.0`.",
+            "Register the presence reaper and redeploy your schema. `jgPoses` gains `sessionId` / `kind` / `label` / `revokedAt` (all optional) and a `by_updated` index, and `createPresenceFunctions` now also returns `reapIdlePresence`. Re-export it (`export const { list, sync, leave, reapIdlePresence } = createPresenceFunctions(...)`) and add `crons.interval(\"jg presence reap\", { seconds: 60 }, internal.presence.reapIdlePresence, {})`. Without it nothing deletes the row of a player who closed the tab — `list` filtered stale rows at read time but the table grew forever. `jgengineCronSpecs()` carries the new entry, and every spec now names the `module` (`\"runtime\"` / `\"presence\"`) it is exported from.",
+            "`presence.sync` returns `{ pose, lastSeenAt, displaced }` instead of `null`, and `presence.leave` marks the row revoked instead of deleting it (the reaper collects it once idle). A caller that ignored the return value is unaffected.",
+        ],
+        added: [
+            "`createPresenceFunctions` gains the policy hooks the pose lane was missing — `resolveSpawn(ctx, { serverId, userId, kind })` for where a session with no row starts (async and ctx-bearing, so a spawn can read the world, replacing a hardcoded origin), `poseRules` as a function of the actor `kind` so an agent need not obey a human's speed cap, `idleCutoffMs` / `maxReapPerRun` for the reaper, and optional `sessionId` on `sync` / `leave`: a second tab is a second row, syncing revokes the others, and the displaced session learns it on its next call through `displaced: true`.",
+            "A command declares what it touches, so `runCommand` hydrates that and nothing else. `CommandDef` gains an optional `scope(input, actorUserId)` returning `{ players?, chunkKeys? }`, evaluated before hydration; the registered `runCommand` mutation also accepts an explicit `scope` argument, which wins over the declared one. A game that never sets either keeps the whole-world default. `ServerLoopHooks.joinScope(userId, isNew)` does the same for `onNewPlayer`.",
+            "`GameRuntime.commandScope` / `GameRuntime.joinScope` expose those declarations to any host, alongside the pure helpers `resolveCommandScope` / `scopeWithActor` / `commandScopeEscape` (`@jgengine/core/runtime/commandRunner`).",
+        ],
+        changed: [
+            "`presence.sync` accepts a call with no `pose` at all, which holds the stored position and moves only the liveness stamp. `createConvexPresenceSync` sends one itself when the pose gate has suppressed writes for 10s, so a standing player keeps their row alive without a pose write — and without the reaper collecting a live session.",
+            "`PresencePoseRow` carries optional `sessionId` / `kind` / `label`, so a nameplate reads off the presence row instead of joining against users per frame.",
+            "`runCommand` no longer reads the whole world on every command. `LoadSnapshotScope` landed in 0.17 but only `helpers.loadSnapshot` accepted one, so the supported way to run a command — the registered `runCommand` mutation, a one-line delegation to `helpers.runCommand` — hydrated every member profile and every chunk however narrow the command was, and a game could only get bounded hydration by reimplementing the mutation. `runCommand`, `joinServer`, and `leaveServer` now hydrate a scope; a command whose `apply` dirties a player or chunk its scope never named is refused rather than persisted, since writing an unhydrated chunk overwrites the stored one with a blank. `flushSave` / `flushServerIfDue` / `tickActiveServers` / `flushDirtyServers` still hydrate everything, which is correct for what they write.",
+        ],
+        removed: [],
+    },
+    "0.17.0": {
+        migrate: [
+            "Bump lockstep SDK packages to `^0.17.0`: `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.14.0`; `@jgengine/github` is `0.4.0`.",
+            "A deleted player profile stays deleted. When a game persists players (`save.scope` includes `player`), hydrating a member with no `jgPlayerProfiles` row no longer falls back to the copy of their state kept on the server row \u2014 that copy was resurrected and then written back as authoritative, so a world reset that cleared profiles but not servers silently restored every player's old balance. A game whose save scope excludes players (`\"none\"`, `\"chunks\"`) is unchanged: the server-row copy is still their state. If you seed members onto a server row without going through `joinServer`, write their profile row too.",
+            "`slotsPerServer` is capped at 256 (`JG_MAX_MEMBERS_PER_SERVER`). `createGameServerFunctions` now throws at wiring time on a larger value instead of accepting it and failing at the write that overflows the document. One server is one Convex document holding the world row, the roster, and every member's session state; a bigger number was never a bigger world. Shard across servers, or move world state into `jgWorldChunks`.",
+            "The tick cron only sweeps games that declare `loop.onTick`. A game with no tick hook used to pay a full hydrate plus a full persist every second per running server, for a snapshot `runtime.tick` returned unchanged; it now costs nothing while idle. If you relied on the tick cron to autosave a hookless game, the 60s `flushDirtyServers` cron and the `flushSave` mutation still do it.",
+        ],
+        added: [
+            "`solidObstaclesNear` / `resolveWalkerStep` (`@jgengine/core/movement/solidObstacles`) \u2014 the engine's single answer to \"what is solid here\", now shared rather than re-derived per consumer. `solidObstaclesNear(ctx, position, reachX, reachZ)` returns the blocking physical colliders near a point through a bounded `inBox` broadphase; `resolveWalkerStep(ctx, position, stepX, stepZ)` slides a horizontal step against them with the player's axis-separated sliding. Reach for these instead of deriving obstacles from a game catalog's own solidity flags.",
+            "Bounded hydration and a client chunk read \u2014 `loadServerSnapshot(ctx, server, runtime, { players, chunkKeys })` hydrates only the members and chunks a mutation will touch instead of a document read per member plus one per chunk, and the generated `getChunks` query lets a client read chunk state by key (capped at `MAX_CHUNKS_PER_QUERY`). Chunks were the documented escape hatch for world state too large for one row, but reads were unbounded and clients could not see them at all, so moving geometry there made things worse. `getServerMeta` returns lobby state (status, member count, revision) without the world payload.",
+            "`@jgengine/core/runtime/worldChunks` \u2014 `chunkKeyAt` / `chunkCoordAt` / `chunkKeyOf` / `parseChunkKey` / `chunkKeysInRadius` at a declared cell size, plus `setChunk` / `updateChunk` / `deleteChunk`, which mark the key dirty so the host actually persists it. `chunkKey` was an opaque game-chosen string and the engine never wrote `dirty.chunks`, so every game reimplemented the coordinate mapping and a game that forgot to push a key silently never saved that chunk.",
+            "Placed objects cull to `replication.aoiRadius`. `objects` is the one large spatial replicated set and had no projector, so a world with a few thousand placements sent all of them to every viewer. It now joins the same area-of-interest policy as `entities` and `stats`. Unset `aoiRadius` still replicates everything.",
+            "`createGameServerFunctions({ matchmaking: \"singleton\" })` \u2014 one shared world per game: auto-match always targets the existing world and a join past capacity fails loudly, instead of quietly creating a second world the player would be alone in. `joinServer` also reconciles a stored `slotsPerServer`/`save` that has drifted from the host options, which previously made raising the option a no-op on worlds that already existed. `selectJoinTarget` (`@jgengine/core/runtime/hostPolicy`) is the pure decision behind it.",
+            "`GameRuntime.hasTick` reports whether a runtime declares `loop.onTick`, so any host's scheduler can skip a server whose tick is a no-op by construction.",
+        ],
+        changed: [
+            "Walking NPCs now stop at the geometry that stops the player. `wander`, `patrol`, and `ctx.scene.entity.moveToward` consulted no obstacles at all, so a pedestrian walked through the building the player cannot enter. All three now slide their step against the scene's blocking physical colliders \u2014 the same query `stepPlayerMovement` reads. A patrol's path state still advances on its own clock (an authored route is not rewound by contact), but the entity can no longer end a tick inside a solid. Pass `avoidSolids: false` to `moveToward` for a mover meant to ignore the world (a flier, a camera rig).",
+            "`@jgengine/assets` verify fails a model source that contributes no index entries. A model pack that has never been pulled is a pin nothing has ever checked \u2014 that is how a Street Pack archive sat in the catalogue titled \"Downtown City MegaKit\". Record why a pack is not pulled in the new `AssetSource.unpulled` string; materials and sprites pull on demand and are exempt.",
+            "`persistServerSnapshot` returns `boolean` and skips a write that would change nothing. Every subscriber of a query that read a server row re-receives the whole result when that document changes, so an unconditional write on the 1 Hz tick re-pushed the entire world to every client once a second whether or not anything moved. `ServerPersistPlan` gains `changed` (`serverState` / `sessionPlayers` / `revision` / `any`) for hosts that write field-by-field.",
+            "`sessionPlayers` is merged over the stored map, not rebuilt from the snapshot, and entries for non-members are pruned. This is what makes a partially hydrated snapshot safe to persist.",
+            "`tickActiveServers` is bounded to `maxServersPerTick` (default 32) servers per transaction, oldest tick anchor first, instead of pulling every running server of every game into one transaction. `flushDirtyServers` is bounded the same way.",
+        ],
+        removed: [
+            "Asset source `quaternius-downtown-city`. It was titled \"Downtown City MegaKit\" but pinned at the Street Pack archive, which ships Blends/FBX/OBJ only \u2014 a pull found no models. Nothing referenced it.",
+        ],
+    },
     "0.16.0": {
         migrate: [
             "Bump lockstep SDK packages to `^0.16.0`: `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.13.0`; `@jgengine/github` is `0.3.0`.",

package/dist/movement/playerMovement.js

@@ -1,7 +1,7 @@
 import { applyHorizontalImpulses, applyMotionImpulses } from "../runtime/motionIntents.js";
 import { groundFieldFor, hasEnvironmentTerrain, sampleSlope } from "../world/terrain.js";
-import { resolveColliders } from "../scene/colliders.js";
 import { advancePlayerMotion, constrainStepToAxis, createEmptyMovementKeys, createPlayerMotionState, DEFAULT_OBSTACLE_PLAYER_RADIUS, obstacleSupportHeight, resolveMovementIntent, resolveObstacleStep, snapPositionToGrid, } from "./movementModel.js";
+import { solidObstaclesNear } from "./solidObstacles.js";
 import { approachYaw, steerYaw } from "./steering.js";
 import { advanceVoxelPlayer, createVoxelPlayerBody, } from "./voxelController.js";
 const DEFAULT_TURN_SPEED = 2.4;
@@ -50,10 +50,6 @@ function storeFor(ctx) {
         store = {
             players: new Map(),
             solids: { count: -1, set: new Set() },
-            obstacleReach: {
-                count: -1,
-                value: { horizontal: OBSTACLE_MAX_HALF_EXTENT, vertical: OBSTACLE_VERTICAL_FLOOR },
-            },
         };
         stores.set(ctx, store);
     }
@@ -209,7 +205,7 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading) {
     const stepHeight = tuning.movement?.stepHeight ?? DEFAULT_PLAYER_STEP_HEIGHT;
     let obstacles = null;
     if (tuning.movement?.collideObjects !== false) {
-        obstacles = gatherMovementObstacles(ctx, store, player.position, stepX, stepZ);
+        obstacles = gatherMovementObstacles(ctx, player.position, stepX, stepZ);
         // While grounded, a box the player could simply step onto is a ledge, not a wall.
         const resolved = resolveObstacleStep(player.position, stepX, stepZ, obstacles, DEFAULT_OBSTACLE_PLAYER_RADIUS, airborne ? 0 : stepHeight);
         stepX = resolved.stepX;
@@ -301,172 +297,10 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading) {
         dt,
     });
 }
-/** Feet-to-head span the obstruction test uses; matches `movementModel`'s `OBSTACLE_PLAYER_HEIGHT`. */
-const OBSTACLE_PLAYER_HEIGHT = 1.8;
 /**
- * Broadphase reach floor (XZ): the `inBox` query indexes objects by their center *point*, so the query
- * must extend past the player by at least the largest blocking-collider extent or a wide object's edge
- * is missed. Floored so default unit boxes stay covered.
+ * The player's blocking obstacles for this step, from the shared solid seam. A walking NPC calls
+ * `resolveWalkerStep` against the same query, so "solid" means one thing engine-wide.
  */
-const OBSTACLE_MAX_HALF_EXTENT = 4;
-/**
- * Hard cap on XZ broadphase reach. City lots ~12–17 m footprint need ~17–20 m after yaw expansion;
- * beyond that we refuse to grow the query into a city-wide box (and rely on the outer AABB of each
- * solid still blocking once its *center* is in range).
- */
-const OBSTACLE_HORIZONTAL_CAP = 22;
-/**
- * Vertical broadphase floor/cap. Player only needs nearby ground props / step-ups — never full tower
- * height. Using building height for Y was the Vice Isle pose killer: a 50 m tower turned `inBox` into
- * a 100³ empty cell walk every frame.
- */
-const OBSTACLE_VERTICAL_FLOOR = 3;
-const OBSTACLE_VERTICAL_CAP = 8;
-/**
- * Mesh compound `boxes` under this count are treated as intentional openings (archways). Above it we
- * walk against the outer fitted AABB only — solid city buildings often ship dense box soups that
- * multiply narrowphase cost without changing the blocked footprint.
- */
-const MOVEMENT_MESH_BOX_BUDGET = 12;
-/**
- * Largest blocking reach in the scene, split into horizontal vs vertical and hard-capped. Cached per
- * ctx and recomputed when the object count changes.
- */
-function obstacleReachFor(ctx, store) {
-    const objects = ctx.scene.object.list();
-    const cache = store.obstacleReach;
-    if (cache.count === objects.length)
-        return cache.value;
-    let horizontal = OBSTACLE_MAX_HALF_EXTENT;
-    let vertical = OBSTACLE_VERTICAL_FLOOR;
-    for (const object of objects) {
-        const set = ctx.scene.object.collidersOf(object.instanceId);
-        if (set === null)
-            continue;
-        for (const collider of resolveColliders(set)) {
-            if (!collider.blocks || collider.purpose !== "physical")
-                continue;
-            const shape = collider.shape;
-            const offset = shape.offset;
-            const ox = offset !== undefined ? Math.abs(offset[0]) : 0;
-            const oy = offset !== undefined ? Math.abs(offset[1]) : 0;
-            const oz = offset !== undefined ? Math.abs(offset[2]) : 0;
-            if (shape.kind === "sphere") {
-                horizontal = Math.max(horizontal, ox + oz + shape.radius);
-                vertical = Math.max(vertical, oy + shape.radius);
-            }
-            else {
-                // Horizontal bound sums both axes so any yaw of the box stays covered.
-                const h = shape.halfExtents;
-                horizontal = Math.max(horizontal, ox + oz + h[0] + h[2]);
-                vertical = Math.max(vertical, oy + h[1]);
-            }
-        }
-    }
-    const value = {
-        horizontal: Math.min(horizontal, OBSTACLE_HORIZONTAL_CAP),
-        vertical: Math.min(vertical, OBSTACLE_VERTICAL_CAP),
-    };
-    cache.count = objects.length;
-    cache.value = value;
-    return value;
-}
-/**
- * Gather the player's nearby blocking obstacles from resolved colliders — the mesh-accurate replacement
- * for the old `nearbyObstacles(list(), …)` which emitted a default 1×1×1 box per object. Bounded by an
- * `inBox` broadphase (reach ≥ player radius + the scene's max blocking extent so wide walls can't be
- * missed), then, per candidate, keeps only blocking physical colliders and emits their real
- * half-extents/offset (or, for a mesh collider carrying a small `boxes` set, the compound sub-boxes),
- * conservatively yaw-rotated by the object's `rotationY`. Objects with no resolved collider fall back
- * to the default box; objects whose colliders don't block stop obstructing. Runs for both the shell's
- * local player and a host, so parity is automatic.
- */
-function gatherMovementObstacles(ctx, store, position, stepX, stepZ) {
-    const reach = obstacleReachFor(ctx, store);
-    const reachX = Math.abs(stepX) + DEFAULT_OBSTACLE_PLAYER_RADIUS + reach.horizontal;
-    const reachZ = Math.abs(stepZ) + DEFAULT_OBSTACLE_PLAYER_RADIUS + reach.horizontal;
-    const min = [
-        position[0] - reachX,
-        position[1] - reach.vertical,
-        position[2] - reachZ,
-    ];
-    const max = [
-        position[0] + reachX,
-        position[1] + OBSTACLE_PLAYER_HEIGHT + reach.vertical,
-        position[2] + reachZ,
-    ];
-    const obstacles = [];
-    for (const object of ctx.scene.object.inBox(min, max)) {
-        const set = ctx.scene.object.collidersOf(object.instanceId);
-        if (set === null) {
-            // No resolved collider: preserve today's default 1×1×1 box.
-            obstacles.push({ position: object.position });
-            continue;
-        }
-        for (const collider of resolveColliders(set)) {
-            if (!collider.blocks || collider.purpose !== "physical")
-                continue;
-            obstacles.push(obstacleFromCollider(collider, object.position, object.rotationY));
-        }
-    }
-    return obstacles;
-}
-/** One blocking collider as a {@link CollisionObstacle}: a compound `boxes` obstacle for a mesh collider
- * carrying a small sub-box set (openings), else a single half-extents/offset AABB. Yaw is applied by
- * conservatively expanding each AABB to its rotated extent (mirroring `worldOffset`), so the obstruction
- * never under-covers. */
-function obstacleFromCollider(collider, position, rotationY) {
-    const cos = Math.cos(rotationY);
-    const sin = Math.sin(rotationY);
-    const shape = collider.shape;
-    // Dense compound soups (city buildings) collapse to the outer fitted AABB for movement — openings
-    // only stay mesh-box accurate when the box count is small (arches, doorways).
-    if (shape.kind === "mesh" &&
-        shape.boxes !== undefined &&
-        shape.boxes.length > 0 &&
-        shape.boxes.length <= MOVEMENT_MESH_BOX_BUDGET) {
-        return {
-            position,
-            boxes: shape.boxes.map((b) => yawExpandLocalBox(b.min, b.max, cos, sin)),
-        };
-    }
-    let hx;
-    let hy;
-    let hz;
-    if (shape.kind === "sphere") {
-        hx = hy = hz = shape.radius;
-    }
-    else {
-        hx = shape.halfExtents[0];
-        hy = shape.halfExtents[1];
-        hz = shape.halfExtents[2];
-    }
-    const offset = shape.offset;
-    const ox = offset !== undefined ? offset[0] : 0;
-    const oy = offset !== undefined ? offset[1] : 0;
-    const oz = offset !== undefined ? offset[2] : 0;
-    return {
-        position,
-        // Rotate the offset by yaw (mirror of colliders.worldOffset), expand the extents to the rotated AABB.
-        offset: [ox * cos + oz * sin, oy, -ox * sin + oz * cos],
-        halfExtents: [Math.abs(hx * cos) + Math.abs(hz * sin), hy, Math.abs(hx * sin) + Math.abs(hz * cos)],
-    };
-}
-/** Yaw-rotate an entity-local AABB about the object origin and re-fit it to an axis-aligned box, expressed
- * as `min`/`max` relative to `position`. Conservative: the rotated box is grown to its enclosing AABB. */
-function yawExpandLocalBox(boxMin, boxMax, cos, sin) {
-    const centerX = (boxMin[0] + boxMax[0]) / 2;
-    const centerY = (boxMin[1] + boxMax[1]) / 2;
-    const centerZ = (boxMin[2] + boxMax[2]) / 2;
-    const halfX = (boxMax[0] - boxMin[0]) / 2;
-    const halfY = (boxMax[1] - boxMin[1]) / 2;
-    const halfZ = (boxMax[2] - boxMin[2]) / 2;
-    const rcX = centerX * cos + centerZ * sin;
-    const rcZ = -centerX * sin + centerZ * cos;
-    const rhX = Math.abs(halfX * cos) + Math.abs(halfZ * sin);
-    const rhZ = Math.abs(halfX * sin) + Math.abs(halfZ * cos);
-    return {
-        min: [rcX - rhX, centerY - halfY, rcZ - rhZ],
-        max: [rcX + rhX, centerY + halfY, rcZ + rhZ],
-    };
+function gatherMovementObstacles(ctx, position, stepX, stepZ) {
+    return solidObstaclesNear(ctx, position, Math.abs(stepX) + DEFAULT_OBSTACLE_PLAYER_RADIUS, Math.abs(stepZ) + DEFAULT_OBSTACLE_PLAYER_RADIUS);
 }

package/dist/movement/solidObstacles.d.ts

@@ -0,0 +1,87 @@
+import type { GameContext } from "../runtime/gameContext.js";
+import { resolveColliders, type ResolvedCollider } from "../scene/colliders.js";
+import type { EntityPosition } from "../scene/entityStore.js";
+import { type CollisionObstacle } from "./movementModel.js";
+/** Largest blocking-collider extent in the scene, split so tower height cannot inflate the XZ query. */
+export interface ObstacleReach {
+    /** Max XZ center-to-face distance of any blocking collider (capped). */
+    horizontal: number;
+    /** Max vertical center-to-face distance of any blocking collider (capped, much tighter than H). */
+    vertical: number;
+}
+/**
+ * The slice of the scene's object store this query needs. Narrow on purpose: the scene context wires
+ * its own store here while it is still being constructed, and `ctx.scene.object` satisfies it as-is.
+ * @internal
+ */
+export interface SolidObstacleSource {
+    list(): readonly {
+        instanceId: string;
+        position: EntityPosition;
+        rotationY: number;
+    }[];
+    inBox(min: EntityPosition, max: EntityPosition): readonly {
+        instanceId: string;
+        position: EntityPosition;
+        rotationY: number;
+    }[];
+    collidersOf(instanceId: string): Parameters<typeof resolveColliders>[0] | null;
+}
+/** Mutable reach cache; one per source, invalidated by object count. @internal */
+export interface ObstacleReachCache {
+    count: number;
+    value: ObstacleReach;
+}
+/** A fresh {@link ObstacleReachCache} for a caller that owns its own source. @internal */
+export declare function createObstacleReachCache(): ObstacleReachCache;
+/**
+ * Largest blocking reach in the scene, split into horizontal vs vertical and hard-capped. Cached per
+ * ctx and recomputed when the object count changes — the broadphase box every consumer inflates by, so
+ * a wall wider than the query box can never be missed.
+ * @internal
+ */
+export declare function solidObstacleReach(ctx: GameContext): ObstacleReach;
+/** {@link solidObstacleReach} against a bare source and caller-owned cache. @internal */
+export declare function sourceObstacleReach(source: SolidObstacleSource, cache: ObstacleReachCache): ObstacleReach;
+/** One blocking collider as a {@link CollisionObstacle}: a compound `boxes` obstacle for a mesh collider
+ * carrying a small sub-box set (openings), else a single half-extents/offset AABB. Yaw is applied by
+ * conservatively expanding each AABB to its rotated extent (mirroring `worldOffset`), so the obstruction
+ * never under-covers.
+ * @internal */
+export declare function obstacleFromCollider(collider: ResolvedCollider, position: EntityPosition, rotationY: number): CollisionObstacle;
+/**
+ * Every blocking physical obstacle overlapping the box `position` ± `reachX`/`reachZ`, read from the
+ * scene's resolved colliders.
+ *
+ * This is the engine's single answer to "what is solid here". The player resolver, a walking NPC, and
+ * anything else that has to stop at a wall read it rather than deriving their own set — three
+ * divergent notions of solid (engine colliders / game catalog flags / nothing at all) is what let a
+ * pedestrian stroll through the building the player cannot enter.
+ *
+ * @capability solid-obstacles the one blocking-geometry query the player resolver and NPC movers share
+ */
+export declare function solidObstaclesNear(ctx: GameContext, position: EntityPosition, reachX: number, reachZ: number, height?: number): CollisionObstacle[];
+/** {@link solidObstaclesNear} against a bare source and an already-resolved reach. @internal */
+export declare function sourceObstaclesNear(source: SolidObstacleSource, reach: ObstacleReach, position: EntityPosition, reachX: number, reachZ: number, height?: number): CollisionObstacle[];
+/**
+ * Slide a walker's horizontal step against the same solid geometry that stops the player, returning the
+ * X/Z it may actually take this tick. A step into a wall is cut on the blocked axis and preserved on the
+ * other, exactly as {@link stepPlayerMovement} resolves the player's.
+ *
+ * Bounded by the same broadphase as the player's gather: one `inBox` query sized to this step, never a
+ * full-world scan, so it stays affordable per NPC per tick.
+ *
+ * @capability walker-solid-step slide an NPC's step against the geometry that blocks the player
+ */
+export declare function resolveWalkerStep(ctx: GameContext, position: EntityPosition, stepX: number, stepZ: number, options?: {
+    radius?: number;
+    stepUpHeight?: number;
+}): {
+    stepX: number;
+    stepZ: number;
+};
+/** {@link resolveWalkerStep} against an already-gathered obstacle set. @internal */
+export declare function slideStep(position: EntityPosition, stepX: number, stepZ: number, obstacles: readonly CollisionObstacle[], radius?: number, stepUpHeight?: number): {
+    stepX: number;
+    stepZ: number;
+};

package/dist/movement/solidObstacles.js

@@ -0,0 +1,208 @@
+import { perContext } from "../runtime/perContext.js";
+import { resolveColliders } from "../scene/colliders.js";
+import { DEFAULT_OBSTACLE_PLAYER_RADIUS, resolveObstacleStep, } from "./movementModel.js";
+/**
+ * Broadphase reach floor (XZ): the `inBox` query indexes objects by their center *point*, so the query
+ * must extend past the walker by at least the largest blocking-collider extent or a wide object's edge
+ * is missed. Floored so default unit boxes stay covered.
+ */
+const OBSTACLE_MAX_HALF_EXTENT = 4;
+/**
+ * Hard cap on XZ broadphase reach. City lots ~12-17 m footprint need ~17-20 m after yaw expansion;
+ * beyond that we refuse to grow the query into a city-wide box (and rely on the outer AABB of each
+ * solid still blocking once its *center* is in range).
+ */
+const OBSTACLE_HORIZONTAL_CAP = 22;
+/**
+ * Vertical broadphase floor/cap. A walker only needs nearby ground props / step-ups — never full tower
+ * height. Using building height for Y was the Vice Isle pose killer: a 50 m tower turned `inBox` into
+ * a 100^3 empty cell walk every frame.
+ */
+const OBSTACLE_VERTICAL_FLOOR = 3;
+const OBSTACLE_VERTICAL_CAP = 8;
+/**
+ * Mesh compound `boxes` under this count are treated as intentional openings (archways). Above it we
+ * walk against the outer fitted AABB only — solid city buildings often ship dense box soups that
+ * multiply narrowphase cost without changing the blocked footprint.
+ */
+const MOVEMENT_MESH_BOX_BUDGET = 12;
+/** Feet-to-head span a walker is tested over — matches the player's, so both agree on what a wall is. */
+const WALKER_HEIGHT = 1.8;
+/** A fresh {@link ObstacleReachCache} for a caller that owns its own source. @internal */
+export function createObstacleReachCache() {
+    return { count: -1, value: { horizontal: OBSTACLE_MAX_HALF_EXTENT, vertical: OBSTACLE_VERTICAL_FLOOR } };
+}
+const reachCache = perContext(() => createObstacleReachCache());
+/**
+ * Largest blocking reach in the scene, split into horizontal vs vertical and hard-capped. Cached per
+ * ctx and recomputed when the object count changes — the broadphase box every consumer inflates by, so
+ * a wall wider than the query box can never be missed.
+ * @internal
+ */
+export function solidObstacleReach(ctx) {
+    return sourceObstacleReach(ctx.scene.object, reachCache(ctx));
+}
+/** {@link solidObstacleReach} against a bare source and caller-owned cache. @internal */
+export function sourceObstacleReach(source, cache) {
+    const objects = source.list();
+    if (cache.count === objects.length)
+        return cache.value;
+    let horizontal = OBSTACLE_MAX_HALF_EXTENT;
+    let vertical = OBSTACLE_VERTICAL_FLOOR;
+    for (const object of objects) {
+        const set = source.collidersOf(object.instanceId);
+        if (set === null)
+            continue;
+        for (const collider of resolveColliders(set)) {
+            if (!collider.blocks || collider.purpose !== "physical")
+                continue;
+            const shape = collider.shape;
+            const offset = shape.offset;
+            const ox = offset !== undefined ? Math.abs(offset[0]) : 0;
+            const oy = offset !== undefined ? Math.abs(offset[1]) : 0;
+            const oz = offset !== undefined ? Math.abs(offset[2]) : 0;
+            if (shape.kind === "sphere") {
+                horizontal = Math.max(horizontal, ox + oz + shape.radius);
+                vertical = Math.max(vertical, oy + shape.radius);
+            }
+            else {
+                // Horizontal bound sums both axes so any yaw of the box stays covered.
+                const h = shape.halfExtents;
+                horizontal = Math.max(horizontal, ox + oz + h[0] + h[2]);
+                vertical = Math.max(vertical, oy + h[1]);
+            }
+        }
+    }
+    const value = {
+        horizontal: Math.min(horizontal, OBSTACLE_HORIZONTAL_CAP),
+        vertical: Math.min(vertical, OBSTACLE_VERTICAL_CAP),
+    };
+    cache.count = objects.length;
+    cache.value = value;
+    return value;
+}
+/** Yaw-rotate an entity-local AABB about the object origin and re-fit it to an axis-aligned box, expressed
+ * as `min`/`max` relative to `position`. Conservative: the rotated box is grown to its enclosing AABB. */
+function yawExpandLocalBox(boxMin, boxMax, cos, sin) {
+    const centerX = (boxMin[0] + boxMax[0]) / 2;
+    const centerY = (boxMin[1] + boxMax[1]) / 2;
+    const centerZ = (boxMin[2] + boxMax[2]) / 2;
+    const halfX = (boxMax[0] - boxMin[0]) / 2;
+    const halfY = (boxMax[1] - boxMin[1]) / 2;
+    const halfZ = (boxMax[2] - boxMin[2]) / 2;
+    const rcX = centerX * cos + centerZ * sin;
+    const rcZ = -centerX * sin + centerZ * cos;
+    const rhX = Math.abs(halfX * cos) + Math.abs(halfZ * sin);
+    const rhZ = Math.abs(halfX * sin) + Math.abs(halfZ * cos);
+    return {
+        min: [rcX - rhX, centerY - halfY, rcZ - rhZ],
+        max: [rcX + rhX, centerY + halfY, rcZ + rhZ],
+    };
+}
+/** One blocking collider as a {@link CollisionObstacle}: a compound `boxes` obstacle for a mesh collider
+ * carrying a small sub-box set (openings), else a single half-extents/offset AABB. Yaw is applied by
+ * conservatively expanding each AABB to its rotated extent (mirroring `worldOffset`), so the obstruction
+ * never under-covers.
+ * @internal */
+export function obstacleFromCollider(collider, position, rotationY) {
+    const cos = Math.cos(rotationY);
+    const sin = Math.sin(rotationY);
+    const shape = collider.shape;
+    // Dense compound soups (city buildings) collapse to the outer fitted AABB for movement — openings
+    // only stay mesh-box accurate when the box count is small (arches, doorways).
+    if (shape.kind === "mesh" &&
+        shape.boxes !== undefined &&
+        shape.boxes.length > 0 &&
+        shape.boxes.length <= MOVEMENT_MESH_BOX_BUDGET) {
+        return {
+            position,
+            boxes: shape.boxes.map((b) => yawExpandLocalBox(b.min, b.max, cos, sin)),
+        };
+    }
+    let hx;
+    let hy;
+    let hz;
+    if (shape.kind === "sphere") {
+        hx = hy = hz = shape.radius;
+    }
+    else {
+        hx = shape.halfExtents[0];
+        hy = shape.halfExtents[1];
+        hz = shape.halfExtents[2];
+    }
+    const offset = shape.offset;
+    const ox = offset !== undefined ? offset[0] : 0;
+    const oy = offset !== undefined ? offset[1] : 0;
+    const oz = offset !== undefined ? offset[2] : 0;
+    return {
+        position,
+        // Rotate the offset by yaw (mirror of colliders.worldOffset), expand the extents to the rotated AABB.
+        offset: [ox * cos + oz * sin, oy, -ox * sin + oz * cos],
+        halfExtents: [Math.abs(hx * cos) + Math.abs(hz * sin), hy, Math.abs(hx * sin) + Math.abs(hz * cos)],
+    };
+}
+/**
+ * Every blocking physical obstacle overlapping the box `position` ± `reachX`/`reachZ`, read from the
+ * scene's resolved colliders.
+ *
+ * This is the engine's single answer to "what is solid here". The player resolver, a walking NPC, and
+ * anything else that has to stop at a wall read it rather than deriving their own set — three
+ * divergent notions of solid (engine colliders / game catalog flags / nothing at all) is what let a
+ * pedestrian stroll through the building the player cannot enter.
+ *
+ * @capability solid-obstacles the one blocking-geometry query the player resolver and NPC movers share
+ */
+export function solidObstaclesNear(ctx, position, reachX, reachZ, height = WALKER_HEIGHT) {
+    return sourceObstaclesNear(ctx.scene.object, solidObstacleReach(ctx), position, reachX, reachZ, height);
+}
+/** {@link solidObstaclesNear} against a bare source and an already-resolved reach. @internal */
+export function sourceObstaclesNear(source, reach, position, reachX, reachZ, height = WALKER_HEIGHT) {
+    const min = [
+        position[0] - reachX - reach.horizontal,
+        position[1] - reach.vertical,
+        position[2] - reachZ - reach.horizontal,
+    ];
+    const max = [
+        position[0] + reachX + reach.horizontal,
+        position[1] + height + reach.vertical,
+        position[2] + reachZ + reach.horizontal,
+    ];
+    const obstacles = [];
+    for (const object of source.inBox(min, max)) {
+        const set = source.collidersOf(object.instanceId);
+        if (set === null) {
+            // No resolved collider: preserve the default 1×1×1 box.
+            obstacles.push({ position: object.position });
+            continue;
+        }
+        for (const collider of resolveColliders(set)) {
+            if (!collider.blocks || collider.purpose !== "physical")
+                continue;
+            obstacles.push(obstacleFromCollider(collider, object.position, object.rotationY));
+        }
+    }
+    return obstacles;
+}
+/**
+ * Slide a walker's horizontal step against the same solid geometry that stops the player, returning the
+ * X/Z it may actually take this tick. A step into a wall is cut on the blocked axis and preserved on the
+ * other, exactly as {@link stepPlayerMovement} resolves the player's.
+ *
+ * Bounded by the same broadphase as the player's gather: one `inBox` query sized to this step, never a
+ * full-world scan, so it stays affordable per NPC per tick.
+ *
+ * @capability walker-solid-step slide an NPC's step against the geometry that blocks the player
+ */
+export function resolveWalkerStep(ctx, position, stepX, stepZ, options = {}) {
+    if (stepX === 0 && stepZ === 0)
+        return { stepX, stepZ };
+    const radius = options.radius ?? DEFAULT_OBSTACLE_PLAYER_RADIUS;
+    const obstacles = solidObstaclesNear(ctx, position, Math.abs(stepX) + radius, Math.abs(stepZ) + radius);
+    return slideStep(position, stepX, stepZ, obstacles, radius, options.stepUpHeight ?? 0);
+}
+/** {@link resolveWalkerStep} against an already-gathered obstacle set. @internal */
+export function slideStep(position, stepX, stepZ, obstacles, radius = DEFAULT_OBSTACLE_PLAYER_RADIUS, stepUpHeight = 0) {
+    if (obstacles.length === 0)
+        return { stepX, stepZ };
+    return resolveObstacleStep(position, stepX, stepZ, obstacles, radius, stepUpHeight);
+}