@jgengine/core 0.18.1 → 0.21.0

package/dist/movement/poseState.d.ts

@@ -28,6 +28,8 @@ export interface PoseState {
     /** Restore every entity's pose and aim from a {@link snapshotAll} payload. */
     hydrateAll(state: PoseSnapshot): void;
 }
+/** Restore one owned pose on synchronous failure; external implementations retain their semantic setter policy. @internal */
+export declare function withPoseRollback<T>(state: PoseState, instanceId: string, operation: () => T): T;
 /**
  * Stance/pose transitions — stand, crouch, prone — that change the hitbox and movement.
  *

package/dist/movement/poseState.js

@@ -23,6 +23,32 @@ export const POSE_HITBOX = {
         speedMultiplier: MOVEMENT_TUNING.runSpeedMultiplier,
     },
 };
+const ownedPoses = new WeakMap();
+/** Restore one owned pose on synchronous failure; external implementations retain their semantic setter policy. @internal */
+export function withPoseRollback(state, instanceId, operation) {
+    const poses = ownedPoses.get(state.getPose);
+    const previous = poses === undefined ? state.getPose(instanceId) : poses.get(instanceId);
+    try {
+        return operation();
+    }
+    catch (error) {
+        if (poses !== undefined) {
+            if (previous === undefined)
+                poses.delete(instanceId);
+            else
+                poses.set(instanceId, previous);
+        }
+        else {
+            try {
+                state.setPose(instanceId, previous);
+            }
+            finally {
+                throw error;
+            }
+        }
+        throw error;
+    }
+}
 /**
  * Stance/pose transitions — stand, crouch, prone — that change the hitbox and movement.
  *
@@ -37,7 +63,7 @@ export function createPoseState(resolveAllowed) {
     function allowedAims(instanceId) {
         return resolveAllowed(instanceId)?.aim ?? ["hip"];
     }
-    return {
+    const state = {
         getPose(instanceId) {
             return poses.get(instanceId) ?? "standing";
         },
@@ -74,4 +100,6 @@ export function createPoseState(resolveAllowed) {
                 aims.set(id, aim);
         },
     };
+    ownedPoses.set(state.getPose, poses);
+    return state;
 }

package/dist/movement/solidObstacles.d.ts

@@ -1,6 +1,7 @@
 import type { GameContext } from "../runtime/gameContext.js";
 import { resolveColliders, type ResolvedCollider } from "../scene/colliders.js";
 import type { EntityPosition } from "../scene/entityStore.js";
+import type { WorldSolid, WorldSolids } from "../world/worldSolids.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 {
@@ -15,6 +16,8 @@ export interface ObstacleReach {
  * pure rules package with no `GameContext` to import can satisfy it from its own object list.
  */
 export interface SolidObstacleSource {
+    /** Optional indexed world geometry that is not represented by scene objects. */
+    solids?: Pick<WorldSolids, "count" | "inBox">;
     list(): readonly {
         instanceId: string;
         position: EntityPosition;
@@ -49,9 +52,16 @@ export declare function sourceObstacleReach(source: SolidObstacleSource, cache:
  * never under-covers.
  * @internal */
 export declare function obstacleFromCollider(collider: ResolvedCollider, position: EntityPosition, rotationY: number): CollisionObstacle;
+/**
+ * A {@link WorldSolid} as a {@link CollisionObstacle}. Axis-aligned solids are one box; a yawed solid is
+ * cut into strips along its long axis, each fitted with an AABB, so a turned building does not block
+ * the street beside it the way a single enclosing box would.
+ * @capability solid-obstacles the one blocking-geometry query the player resolver and NPC movers share
+ */
+export declare function obstacleFromSolid(solid: WorldSolid): CollisionObstacle;
 /**
  * Every blocking physical obstacle overlapping the box `position` ± `reachX`/`reachZ`, read from the
- * scene's resolved colliders.
+ * scene's resolved colliders and `ctx.world.solids`.
  *
  * 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

package/dist/movement/solidObstacles.js

@@ -15,7 +15,7 @@ const OBSTACLE_MAX_HALF_EXTENT = 4;
 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
+ * height. Using building height for Y was the Harbor Heat pose killer: a 50 m tower turned `inBox` into
  * a 100^3 empty cell walk every frame.
  */
 const OBSTACLE_VERTICAL_FLOOR = 3;
@@ -26,6 +26,10 @@ const OBSTACLE_VERTICAL_CAP = 8;
  * multiply narrowphase cost without changing the blocked footprint.
  */
 const MOVEMENT_MESH_BOX_BUDGET = 12;
+/** Most AABB strips an oriented world solid is sliced into, bounding the corner overhang a yawed box leaves. */
+const SOLID_MAX_STRIPS = 8;
+/** Yaw within this of a quarter turn is treated as axis-aligned (radians). */
+const AXIS_ALIGNED_EPSILON = 1e-4;
 /** 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. */
@@ -141,9 +145,40 @@ export function obstacleFromCollider(collider, position, rotationY) {
         halfExtents: [Math.abs(hx * cos) + Math.abs(hz * sin), hy, Math.abs(hx * sin) + Math.abs(hz * cos)],
     };
 }
+/**
+ * A {@link WorldSolid} as a {@link CollisionObstacle}. Axis-aligned solids are one box; a yawed solid is
+ * cut into strips along its long axis, each fitted with an AABB, so a turned building does not block
+ * the street beside it the way a single enclosing box would.
+ * @capability solid-obstacles the one blocking-geometry query the player resolver and NPC movers share
+ */
+export function obstacleFromSolid(solid) {
+    const [hx, hy, hz] = solid.halfExtents;
+    const yaw = solid.rotationY ?? 0;
+    const quarter = yaw / (Math.PI / 2);
+    const nearest = Math.round(quarter);
+    if (Math.abs(quarter - nearest) < AXIS_ALIGNED_EPSILON) {
+        const swapped = Math.abs(nearest) % 2 === 1;
+        return { position: solid.center, halfExtents: swapped ? [hz, hy, hx] : [hx, hy, hz] };
+    }
+    const alongX = hx >= hz;
+    const long = alongX ? hx : hz;
+    const short = Math.max(alongX ? hz : hx, 1e-6);
+    const strips = Math.min(SOLID_MAX_STRIPS, Math.max(1, Math.ceil(long / short)));
+    const cos = Math.cos(yaw);
+    const sin = Math.sin(yaw);
+    const boxes = [];
+    for (let i = 0; i < strips; i += 1) {
+        const from = -long + (2 * long * i) / strips;
+        const to = from + (2 * long) / strips;
+        const boxMin = alongX ? [from, -hy, -hz] : [-hx, -hy, from];
+        const boxMax = alongX ? [to, hy, hz] : [hx, hy, to];
+        boxes.push(yawExpandLocalBox(boxMin, boxMax, cos, sin));
+    }
+    return { position: solid.center, boxes };
+}
 /**
  * Every blocking physical obstacle overlapping the box `position` ± `reachX`/`reachZ`, read from the
- * scene's resolved colliders.
+ * scene's resolved colliders and `ctx.world.solids`.
  *
  * 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
@@ -153,7 +188,16 @@ export function obstacleFromCollider(collider, position, rotationY) {
  * @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);
+    const obstacles = sourceObstaclesNear(ctx.scene.object, solidObstacleReach(ctx), position, reachX, reachZ, height);
+    appendWorldSolidObstacles(obstacles, ctx.world.solids, position, reachX, reachZ, height);
+    return obstacles;
+}
+function appendWorldSolidObstacles(obstacles, solids, position, reachX, reachZ, height) {
+    if (solids === undefined || solids.count() === 0)
+        return;
+    for (const solid of solids.inBox([position[0] - reachX, position[1] - height, position[2] - reachZ], [position[0] + reachX, position[1] + 2 * height, position[2] + reachZ])) {
+        obstacles.push(obstacleFromSolid(solid));
+    }
 }
 /** {@link solidObstaclesNear} against a bare source and an already-resolved reach. */
 export function sourceObstaclesNear(source, reach, position, reachX, reachZ, height = WALKER_HEIGHT) {
@@ -181,6 +225,7 @@ export function sourceObstaclesNear(source, reach, position, reachX, reachZ, hei
             obstacles.push(obstacleFromCollider(collider, object.position, object.rotationY));
         }
     }
+    appendWorldSolidObstacles(obstacles, source.solids, position, reachX, reachZ, height);
     return obstacles;
 }
 /**

package/dist/movement/terrainGrade.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Constrain an uphill heightfield step by its sampled rise/run grade. Try the full step, then
+ * X-only, then Z-only, preserving downhill travel and sliding along a traversable axis.
+ * The sampler can represent a game's terrain policy independently of the ground used for feet.
+ * This endpoint test also applies while jumping; it is not continuous terrain collision.
+ * @capability uphill-grade-step constrain sampled heightfield ascent with axis sliding and a configurable terrain-policy sampler
+ */
+export declare function resolveTerrainGradeStep(sampler: {
+    sampleHeight(x: number, z: number): number;
+} | ((x: number, z: number) => number), position: readonly [number, number, number], stepX: number, stepZ: number, maxClimbGrade: number): {
+    stepX: number;
+    stepZ: number;
+};

package/dist/movement/terrainGrade.js

@@ -0,0 +1,33 @@
+/**
+ * Constrain an uphill heightfield step by its sampled rise/run grade. Try the full step, then
+ * X-only, then Z-only, preserving downhill travel and sliding along a traversable axis.
+ * The sampler can represent a game's terrain policy independently of the ground used for feet.
+ * This endpoint test also applies while jumping; it is not continuous terrain collision.
+ * @capability uphill-grade-step constrain sampled heightfield ascent with axis sliding and a configurable terrain-policy sampler
+ */
+export function resolveTerrainGradeStep(sampler, position, stepX, stepZ, maxClimbGrade) {
+    if (!Number.isFinite(maxClimbGrade) || maxClimbGrade < 0) {
+        throw new RangeError("maxClimbGrade must be finite and nonnegative.");
+    }
+    const startX = position[0];
+    const startZ = position[2];
+    const sampleHeight = (x, z) => {
+        const height = typeof sampler === "function" ? sampler(x, z) : sampler.sampleHeight(x, z);
+        if (!Number.isFinite(height)) {
+            throw new RangeError(`climbGradeHeight/sampleHeight must return a finite height at (${x}, ${z}); received ${height}.`);
+        }
+        return height;
+    };
+    const height = sampleHeight(startX, startZ);
+    const allowed = (dx, dz) => {
+        const distance = Math.hypot(dx, dz);
+        return distance < 0.0001 || (sampleHeight(startX + dx, startZ + dz) - height) / distance <= maxClimbGrade;
+    };
+    if (allowed(stepX, stepZ))
+        return { stepX, stepZ };
+    if (allowed(stepX, 0))
+        return { stepX, stepZ: 0 };
+    if (allowed(0, stepZ))
+        return { stepX: 0, stepZ };
+    return { stepX: 0, stepZ: 0 };
+}

package/dist/movement/voxelController.d.ts

@@ -19,7 +19,7 @@
  * 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";
+import { type MovementIntent, type MovementTuningOverrides, type MotionFrameOptions } 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 {
@@ -58,4 +58,4 @@ export type GroundHeightQuery = (x: number, z: number) => number;
  * 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;
+export declare function advanceVoxelPlayer(body: VoxelPlayerBody, intent: MovementIntent, forwardX: number, forwardZ: number, baseSpeed: number, rawDeltaSeconds: number, isSolid: SolidQuery, dims?: VoxelPlayerDims, tuning?: MovementTuningOverrides, groundHeight?: GroundHeightQuery, options?: Pick<MotionFrameOptions, "authoritativeStep">): void;

package/dist/movement/voxelController.js

@@ -19,7 +19,7 @@
  * 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 { MOVEMENT_TUNING } from "./movementModel.js";
+import { MOVEMENT_TUNING, motionStepSeconds } from "./movementModel.js";
 export const DEFAULT_VOXEL_DIMS = {
     halfWidth: 0.3,
     height: 1.8,
@@ -97,7 +97,7 @@ function supportTopWithin(x, z, fromY, toY, isSolid, dims) {
     }
     return best;
 }
-function targetHorizontalVelocity(intent, forwardX, forwardZ, baseSpeed) {
+function targetHorizontalVelocity(intent, forwardX, forwardZ, baseSpeed, tuning) {
     if (!intent.moving)
         return { x: 0, z: 0 };
     let fx = forwardX;
@@ -120,9 +120,9 @@ function targetHorizontalVelocity(intent, forwardX, forwardZ, baseSpeed) {
     if (magSq < 1e-6)
         return { x: 0, z: 0 };
     const speedMultiplier = intent.crouching
-        ? MOVEMENT_TUNING.crouchSpeedMultiplier
+        ? (tuning?.crouchSpeedMultiplier ?? MOVEMENT_TUNING.crouchSpeedMultiplier)
         : intent.running
-            ? MOVEMENT_TUNING.runSpeedMultiplier
+            ? (tuning?.runSpeedMultiplier ?? MOVEMENT_TUNING.runSpeedMultiplier)
             : 1;
     const targetSpeed = baseSpeed * MOVEMENT_TUNING.walkSpeedMultiplier * speedMultiplier;
     const scale = targetSpeed / Math.sqrt(magSq);
@@ -172,19 +172,19 @@ function moveAxis(body, axis, delta, isSolid, dims) {
  * 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 function advanceVoxelPlayer(body, intent, forwardX, forwardZ, baseSpeed, rawDeltaSeconds, isSolid, dims = DEFAULT_VOXEL_DIMS, tuning, groundHeight) {
-    const dt = Math.min(rawDeltaSeconds, MOVEMENT_TUNING.maxFrameSeconds);
+export function advanceVoxelPlayer(body, intent, forwardX, forwardZ, baseSpeed, rawDeltaSeconds, isSolid, dims = DEFAULT_VOXEL_DIMS, tuning, groundHeight, options) {
+    const dt = motionStepSeconds(rawDeltaSeconds, options?.authoritativeStep);
     const gravityAcceleration = tuning?.gravityAcceleration ?? MOVEMENT_TUNING.gravityAcceleration;
     const jumpVelocity = tuning?.jumpVelocity ?? MOVEMENT_TUNING.jumpVelocity;
-    const target = targetHorizontalVelocity(intent, forwardX, forwardZ, baseSpeed);
+    const target = targetHorizontalVelocity(intent, forwardX, forwardZ, baseSpeed, tuning);
     const acceleration = body.grounded
-        ? MOVEMENT_TUNING.groundAcceleration
-        : MOVEMENT_TUNING.airAcceleration;
+        ? (tuning?.groundAcceleration ?? MOVEMENT_TUNING.groundAcceleration)
+        : (tuning?.airAcceleration ?? MOVEMENT_TUNING.airAcceleration);
     const accelerationBlend = 1 - Math.exp(-acceleration * dt);
     body.velocityX += (target.x - body.velocityX) * accelerationBlend;
     body.velocityZ += (target.z - body.velocityZ) * accelerationBlend;
     if (!intent.moving && body.grounded) {
-        const friction = Math.exp(-MOVEMENT_TUNING.groundFriction * dt);
+        const friction = Math.exp(-(tuning?.groundFriction ?? MOVEMENT_TUNING.groundFriction) * dt);
         body.velocityX *= friction;
         body.velocityZ *= friction;
     }

package/dist/nav/navFromEnvironment.d.ts

@@ -1,11 +1,17 @@
 import type { EnvironmentWorldFeature } from "../world/features.js";
 import type { Aabb } from "../world/geometry.js";
+import { type WorldSolids } from "../world/worldSolids.js";
 export interface NavObstacleGrid {
     blockAabb(aabb: Aabb): void;
 }
 /**
- * Expands every structure descriptor on an environment world feature into its
- * generated buildings and blocks their footprints on `grid`. Returns the
- * number of buildings blocked.
+ * Blocks the footprint of every solid building an environment feature's `structures` generate — the
+ * same set `ctx.world.solids` holds for it. Returns the number of buildings blocked.
  */
 export declare function populateNavGridFromEnvironment(grid: NavObstacleGrid, world: EnvironmentWorldFeature): number;
+/**
+ * Blocks the XZ footprint of every solid in `solids` (usually `ctx.world.solids`) on `grid`, so NPC
+ * paths avoid exactly what movement and physics collide with. Returns the number of solids blocked.
+ * @capability nav-from-solids block world solids on a nav grid
+ */
+export declare function populateNavGridFromSolids(grid: NavObstacleGrid, solids: Pick<WorldSolids, "all">): number;

package/dist/nav/navFromEnvironment.js

@@ -1,16 +1,22 @@
-import { resolveStructureBuildings } from "../world/environmentSummary.js";
+import { structureSolids, worldSolidFootprint } from "../world/worldSolids.js";
 /**
- * Expands every structure descriptor on an environment world feature into its
- * generated buildings and blocks their footprints on `grid`. Returns the
- * number of buildings blocked.
+ * Blocks the footprint of every solid building an environment feature's `structures` generate — the
+ * same set `ctx.world.solids` holds for it. Returns the number of buildings blocked.
  */
 export function populateNavGridFromEnvironment(grid, world) {
-    let blocked = 0;
-    for (const descriptor of world.structures ?? []) {
-        for (const building of resolveStructureBuildings(descriptor)) {
-            grid.blockAabb(building.bounds);
-            blocked += 1;
-        }
-    }
-    return blocked;
+    const solids = structureSolids(world);
+    for (const solid of solids)
+        grid.blockAabb(worldSolidFootprint(solid));
+    return solids.length;
+}
+/**
+ * Blocks the XZ footprint of every solid in `solids` (usually `ctx.world.solids`) on `grid`, so NPC
+ * paths avoid exactly what movement and physics collide with. Returns the number of solids blocked.
+ * @capability nav-from-solids block world solids on a nav grid
+ */
+export function populateNavGridFromSolids(grid, solids) {
+    const all = solids.all();
+    for (const solid of all)
+        grid.blockAabb(worldSolidFootprint(solid));
+    return all.length;
 }

package/dist/nav/navGrid.d.ts

@@ -17,6 +17,10 @@ export interface FindPathOptions {
     clearance?: number;
     /** Multiplier (>=1) applied to the base cost of stepping from one cell center to a neighbour's. Use to penalize slopes, terrain, etc. */
     stepCost?: (from: NavPoint, to: NavPoint) => number;
+    /** Additional edge/shortcut policy. Called after grid occupancy checks. */
+    canTraverse?: (from: NavPoint, to: NavPoint) => boolean;
+    /** Maximum expanded cells. Omit for the legacy whole-grid search. */
+    maxNodes?: number;
 }
 export interface NavGrid {
     readonly cols: number;
@@ -44,6 +48,20 @@ export declare function createNavGrid(config: NavGridConfig): NavGrid;
  * the nearest walkable cell so a click on an obstacle still routes to its edge.
  */
 export declare function findPath(grid: NavGrid, from: NavPoint, to: NavPoint, options?: FindPathOptions): NavPoint[] | null;
+/** Bounded grid search distinguishes exhausted work from a proven unreachable goal. */
+export type FindPathResult = {
+    status: "path";
+    points: NavPoint[];
+    visited: number;
+} | {
+    status: "no-path" | "budget";
+    visited: number;
+};
+/**
+ * Same endpoint snapping as {@link findPath}, with explicit search-budget exhaustion.
+ * @capability bounded-grid-route distinguish no path from exhausted grid search work
+ */
+export declare function findPathResult(grid: NavGrid, from: NavPoint, to: NavPoint, options?: FindPathOptions): FindPathResult;
 /**
  * `FindPathOptions.stepCost` factory that penalizes steep terrain: cost is
  * `1 + weight * |Δheight| / horizontalDistance`, so with the default weight a
@@ -53,4 +71,4 @@ export declare function slopeStepCost(field: {
     sampleHeight(x: number, z: number): number;
 }, weight?: number): (from: NavPoint, to: NavPoint) => number;
 /** Remove waypoints the mover can skip because it has clear line-of-sight past them. */
-export declare function smoothPath(grid: NavGrid, points: readonly NavPoint[]): NavPoint[];
+export declare function smoothPath(grid: NavGrid, points: readonly NavPoint[], canTraverse?: (from: NavPoint, to: NavPoint) => boolean): NavPoint[];

package/dist/nav/navGrid.js

@@ -174,14 +174,27 @@ function nearestPassable(grid, point, passable) {
  * the nearest walkable cell so a click on an obstacle still routes to its edge.
  */
 export function findPath(grid, from, to, options = {}) {
+    const result = findPathResult(grid, from, to, options);
+    return result.status === "path" ? result.points : null;
+}
+/**
+ * Same endpoint snapping as {@link findPath}, with explicit search-budget exhaustion.
+ * @capability bounded-grid-route distinguish no path from exhausted grid search work
+ */
+export function findPathResult(grid, from, to, options = {}) {
+    const maxNodes = options.maxNodes ?? Number.POSITIVE_INFINITY;
+    if (!(maxNodes >= 0))
+        throw new Error("navGrid maxNodes must be nonnegative.");
     const passable = withClearance(grid, options.clearance ?? 0);
     const stepCost = options.stepCost;
     const startCell = grid.cellAt(from);
     const goalCell = grid.cellAt(to);
     const start = passable(startCell.col, startCell.row) ? startCell : nearestPassable(grid, from, passable);
-    const goal = passable(goalCell.col, goalCell.row) ? goalCell : nearestPassable(grid, to, passable);
+    const exactGoal = passable(goalCell.col, goalCell.row);
+    const goal = exactGoal ? goalCell : nearestPassable(grid, to, passable);
     if (start === null || goal === null)
-        return null;
+        return { status: "no-path", visited: 0 };
+    const pointAt = (col, row) => exactGoal && col === goal.col && row === goal.row ? to : grid.center(col, row);
     const cols = grid.cols;
     const keyOf = (col, row) => row * cols + col;
     const startKey = keyOf(start.col, start.row);
@@ -222,6 +235,8 @@ export function findPath(grid, from, to, options = {}) {
             found = true;
             break;
         }
+        if (closed.size >= maxNodes)
+            return { status: "budget", visited: closed.size };
         closed.add(current.key);
         const col = current.key % cols;
         const row = (current.key - col) / cols;
@@ -236,7 +251,9 @@ export function findPath(grid, from, to, options = {}) {
             const nKey = keyOf(nc, nr);
             if (closed.has(nKey))
                 continue;
-            const multiplier = stepCost === undefined ? 1 : Math.max(1, stepCost(grid.center(col, row), grid.center(nc, nr)));
+            if (options.canTraverse !== undefined && !options.canTraverse(pointAt(col, row), pointAt(nc, nr)))
+                continue;
+            const multiplier = stepCost === undefined ? 1 : Math.max(1, stepCost(pointAt(col, row), pointAt(nc, nr)));
             const tentative = g + step * multiplier;
             if (tentative < (gScore.get(nKey) ?? Number.POSITIVE_INFINITY)) {
                 gScore.set(nKey, tentative);
@@ -246,7 +263,7 @@ export function findPath(grid, from, to, options = {}) {
         }
     }
     if (!found)
-        return null;
+        return { status: "no-path", visited: closed.size };
     const cells = [];
     let cursor = goalKey;
     while (cursor !== undefined) {
@@ -254,10 +271,9 @@ export function findPath(grid, from, to, options = {}) {
         cells.unshift({ col, row: (cursor - col) / cols });
         cursor = cameFrom.get(cursor);
     }
-    const raw = cells.map((cell) => grid.center(cell.col, cell.row));
-    if (passable(goalCell.col, goalCell.row))
-        raw[raw.length - 1] = [to[0], to[1]];
-    return options.smooth === false ? raw : smoothPath(grid, raw);
+    const raw = cells.map((cell) => [...pointAt(cell.col, cell.row)]);
+    const points = options.smooth === false ? raw : smoothPath(grid, raw, options.canTraverse);
+    return { status: "path", points, visited: closed.size };
 }
 const DEFAULT_SLOPE_STEP_WEIGHT = 1;
 /**
@@ -275,13 +291,13 @@ export function slopeStepCost(field, weight = DEFAULT_SLOPE_STEP_WEIGHT) {
     };
 }
 /** Remove waypoints the mover can skip because it has clear line-of-sight past them. */
-export function smoothPath(grid, points) {
+export function smoothPath(grid, points, canTraverse) {
     if (points.length <= 2)
         return points.slice();
     const result = [points[0]];
     let anchor = 0;
     for (let i = 2; i < points.length; i += 1) {
-        if (!grid.lineOfSight(points[anchor], points[i])) {
+        if (!grid.lineOfSight(points[anchor], points[i]) || (canTraverse !== undefined && !canTraverse(points[anchor], points[i]))) {
             result.push(points[i - 1]);
             anchor = i - 1;
         }

package/dist/nav/navMesh.d.ts

@@ -4,13 +4,19 @@ export interface NavMeshLink {
     from: number;
     to: number;
     cost?: number;
+    /** Where the link leaves `from`; defaults to that polygon's center. */
+    start?: Vec3;
+    /** Where the link lands in `to`; defaults to that polygon's center. */
+    end?: Vec3;
 }
-/** Serializable polygon navigation mesh data. */
+/** Serializable polygon navigation mesh data. Treat it as immutable once queried; queries cache derived geometry per object. */
 export interface NavMeshData {
     /** Flat xyz vertex coordinates. Polygon indices refer to triples in this array. */
     verts: number[];
+    /** Convex polygons as vertex index lists. */
     polys: number[][];
     links: NavMeshLink[];
+    /** Area id per polygon, priced by {@link NavMeshQueryOptions.areaCosts}. */
     areas?: number[];
 }
 /** Neighbor relationship for one navigation polygon. */
@@ -22,12 +28,47 @@ export interface NavMeshAdjacency {
 export interface NavMeshPath {
     points: Vec3[];
     polys: number[];
+    /** True when the search budget ran out and the route ends at the polygon nearest the goal. */
+    partial?: boolean;
+}
+/** Tunable pricing and bounds for a {@link NavMeshQuery}. */
+export interface NavMeshQueryOptions {
+    /** Cost multiplier per area id; unlisted areas cost 1, and a negative or non-finite cost blocks the area. */
+    areaCosts?: Readonly<Record<number, number>>;
+    /** Most polygons one path search may expand before returning a partial path. Default 2048. */
+    maxNodes?: number;
+}
+/** Serializable tuning of a {@link NavMeshQuery}. */
+export interface NavMeshQuerySnapshot {
+    areaCosts: Record<number, number>;
+    maxNodes: number;
+}
+/** Cached, allocation-light queries over one {@link NavMeshData}. */
+export interface NavMeshQuery {
+    readonly mesh: NavMeshData;
+    /** Polygon nearest the point in 3D, so stacked floors resolve by height; null for an empty mesh. */
+    findPolygon(point: Vec3): number | null;
+    /** Closest point on the mesh surface, or null for an empty mesh. */
+    closestPoint(point: Vec3): Vec3 | null;
+    /** Cheapest polygon corridor by A*, straightened with a portal funnel. */
+    findPath(from: Vec3, to: Vec3): NavMeshPath | null;
+    /** True when the straight segment stays on walkable, unblocked polygons. */
+    raycast(from: Vec3, to: Vec3): boolean;
+    retune(patch: NavMeshQueryOptions): void;
+    snapshot(): NavMeshQuerySnapshot;
+    restore(next: NavMeshQuerySnapshot): void;
 }
 /** Build polygon adjacency from shared edges and explicit off-mesh links. */
 export declare function buildNavAdjacency(mesh: NavMeshData): NavMeshAdjacency[];
+/**
+ * Create a cached query over a nav mesh: height-aware polygon lookup through a uniform grid, binary-heap A*
+ * priced by area costs and bounded by `maxNodes`, portal-funnel path straightening, and edge-walking raycasts.
+ * @capability navmesh-query route, snap, and raycast on a polygon navmesh with retunable area costs and a bounded search
+ */
+export declare function createNavMeshQuery(mesh: NavMeshData, options?: NavMeshQueryOptions): NavMeshQuery;
 /** Return the closest point on the mesh surface, or null for an empty mesh. */
 export declare function closestPoint(mesh: NavMeshData, point: Vec3): Vec3 | null;
-/** A* over polygon centers, followed by deterministic visibility string-pulling. */
+/** A* over polygon portals with default area costs, straightened by a portal funnel. Use {@link createNavMeshQuery} to price areas. */
 export declare function findPath(mesh: NavMeshData, from: Vec3, to: Vec3): NavMeshPath | null;
 /** True when the segment remains over walkable polygons. */
 export declare function raycastNav(mesh: NavMeshData, from: Vec3, to: Vec3): boolean;