@jgengine/core 0.19.0 → 0.22.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,7 +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 } from "../world/worldSolids.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 {
@@ -16,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;

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;
@@ -189,13 +189,15 @@ export function obstacleFromSolid(solid) {
  */
 export function solidObstaclesNear(ctx, position, reachX, reachZ, height = WALKER_HEIGHT) {
     const obstacles = sourceObstaclesNear(ctx.scene.object, solidObstacleReach(ctx), position, reachX, reachZ, height);
-    const solids = ctx.world.solids;
-    if (solids.count() === 0)
-        return obstacles;
+    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));
     }
-    return obstacles;
 }
 /** {@link solidObstaclesNear} against a bare source and an already-resolved reach. */
 export function sourceObstaclesNear(source, reach, position, reachX, reachZ, height = WALKER_HEIGHT) {
@@ -223,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,
@@ -172,8 +172,8 @@ 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, tuning);

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/solidRoute.d.ts

@@ -0,0 +1,50 @@
+import type { CollisionObstacle } from "../movement/movementModel.js";
+import type { Aabb } from "../world/geometry.js";
+import { type NavPoint } from "./navGrid.js";
+import type { Waypoint } from "./pathFollow.js";
+/** Caller-owned local collision query and terrain policy; no movement or perception state. */
+export interface SolidRouteOptions {
+    bounds: Aabb;
+    cellSize: number;
+    /** Query the indexed movement geometry, including mover clearance outside these bounds. */
+    obstaclesInBounds: (bounds: Aabb) => Iterable<CollisionObstacle>;
+    radius?: number;
+    height?: number;
+    /** Intermediate waypoint elevation. Defaults to the start's feet height. */
+    sampleHeight?: (x: number, z: number) => number;
+    /** Terrain/door policy for every edge and smoothing shortcut. */
+    canTraverse?: (from: Waypoint, to: Waypoint) => boolean;
+    /** Cost multiplier >=1. Suppresses smoothing by default to retain the priced route. */
+    stepCost?: (from: NavPoint, to: NavPoint) => number;
+    smooth?: boolean;
+    /** Grid allocation cap. Default 4096. */
+    maxCells?: number;
+    /** Gathered obstacle/sub-box cap. Default 256. */
+    maxBoxes?: number;
+    /** Search expansion cap. Default 1024. */
+    maxNodes?: number;
+    /** Collision-box tests and terrain-policy calls combined. Default 100000. */
+    maxChecks?: number;
+}
+/** Work counters exclude the caller's spatial-query implementation. */
+export interface SolidRouteWork {
+    cells: number;
+    boxes: number;
+    visited: number;
+    checks: number;
+}
+/** Failures never carry a partial or snapped route. */
+export type SolidRouteResult = {
+    status: "path";
+    waypoints: Waypoint[];
+    work: SolidRouteWork;
+} | {
+    status: "no-path" | "budget";
+    work: SolidRouteWork;
+};
+/**
+ * Plan an exact-endpoint local route over indexed movement boxes using the shared nav grid.
+ * Every edge is swept at body width; bounded failure leaves retry/stop policy with the caller.
+ * @capability solid-route bounded local planning over indexed collision geometry
+ */
+export declare function planSolidRoute(from: Waypoint, to: Waypoint, options: SolidRouteOptions): SolidRouteResult;

package/dist/nav/solidRoute.js

@@ -0,0 +1,144 @@
+import { createNavGrid, findPathResult } from "./navGrid.js";
+function intersects(from, to, box, radius, height) {
+    if (box.max[1] <= Math.min(from[1], to[1]) || box.min[1] >= Math.max(from[1], to[1]) + height)
+        return false;
+    let enter = 0;
+    let exit = 1;
+    for (const axis of [0, 2]) {
+        const min = box.min[axis] - radius;
+        const max = box.max[axis] + radius;
+        const delta = to[axis] - from[axis];
+        if (delta === 0) {
+            if (from[axis] <= min || from[axis] >= max)
+                return false;
+        }
+        else {
+            const a = (min - from[axis]) / delta;
+            const b = (max - from[axis]) / delta;
+            enter = Math.max(enter, Math.min(a, b));
+            exit = Math.min(exit, Math.max(a, b));
+            if (enter >= exit)
+                return false;
+        }
+    }
+    return enter < exit;
+}
+/**
+ * Plan an exact-endpoint local route over indexed movement boxes using the shared nav grid.
+ * Every edge is swept at body width; bounded failure leaves retry/stop policy with the caller.
+ * @capability solid-route bounded local planning over indexed collision geometry
+ */
+export function planSolidRoute(from, to, options) {
+    const { bounds, cellSize } = options;
+    const radius = options.radius ?? 0.3;
+    const height = options.height ?? 1.8;
+    const maxCells = options.maxCells ?? 4096;
+    const maxBoxes = options.maxBoxes ?? 256;
+    const maxNodes = options.maxNodes ?? 1024;
+    const maxChecks = options.maxChecks ?? 100000;
+    if (![...from, ...to, bounds.minX, bounds.maxX, bounds.minZ, bounds.maxZ, cellSize, radius, height].every(Number.isFinite) ||
+        cellSize <= 0 || radius < 0 || height <= 0 || bounds.maxX <= bounds.minX || bounds.maxZ <= bounds.minZ ||
+        ![maxCells, maxBoxes, maxNodes, maxChecks].every((value) => Number.isSafeInteger(value) && value >= 0)) {
+        throw new Error("solidRoute requires finite geometry and nonnegative integer budgets.");
+    }
+    const work = { cells: 0, boxes: 0, visited: 0, checks: 0 };
+    const failure = (status) => ({ status, work });
+    const inside = (point) => point[0] >= bounds.minX && point[0] < bounds.maxX && point[2] >= bounds.minZ && point[2] < bounds.maxZ;
+    if (!inside(from) || !inside(to))
+        return failure("no-path");
+    const cells = Math.ceil((bounds.maxX - bounds.minX) / cellSize) * Math.ceil((bounds.maxZ - bounds.minZ) / cellSize);
+    if (cells > maxCells)
+        return failure("budget");
+    const boxes = [];
+    const query = { minX: bounds.minX - radius, maxX: bounds.maxX + radius, minZ: bounds.minZ - radius, maxZ: bounds.maxZ + radius };
+    for (const obstacle of options.obstaclesInBounds(query)) {
+        const half = obstacle.halfExtents ?? [0.5, 0.5, 0.5];
+        const offset = obstacle.offset ?? [0, 0, 0];
+        const local = obstacle.boxes?.length ? obstacle.boxes : [{
+                min: [offset[0] - half[0], offset[1] - half[1], offset[2] - half[2]],
+                max: [offset[0] + half[0], offset[1] + half[1], offset[2] + half[2]],
+            }];
+        for (const box of local) {
+            if (boxes.length >= maxBoxes)
+                return failure("budget");
+            const worldBox = {
+                min: [obstacle.position[0] + box.min[0], obstacle.position[1] + box.min[1], obstacle.position[2] + box.min[2]],
+                max: [obstacle.position[0] + box.max[0], obstacle.position[1] + box.max[1], obstacle.position[2] + box.max[2]],
+            };
+            if (![...worldBox.min, ...worldBox.max].every(Number.isFinite) || worldBox.min.some((value, axis) => value > worldBox.max[axis])) {
+                throw new Error("solidRoute obstacle boxes must be finite and ordered.");
+            }
+            boxes.push(worldBox);
+            work.boxes++;
+        }
+    }
+    let exhausted = false;
+    const spend = () => {
+        if (work.checks >= maxChecks) {
+            exhausted = true;
+            return false;
+        }
+        work.checks++;
+        return true;
+    };
+    const clear = (a, b) => {
+        if (exhausted)
+            return false;
+        for (const box of boxes) {
+            if (!spend() || intersects(a, b, box, radius, height))
+                return false;
+        }
+        return options.canTraverse === undefined || (a[0] === b[0] && a[1] === b[1] && a[2] === b[2]) ||
+            (spend() && options.canTraverse(a, b));
+    };
+    if (!clear(from, from) || !clear(to, to))
+        return failure(exhausted ? "budget" : "no-path");
+    const directClear = clear(from, to);
+    if (options.stepCost === undefined && directClear)
+        return { status: "path", waypoints: [[...from], [...to]], work };
+    if (exhausted)
+        return failure("budget");
+    const grid = createNavGrid({ bounds, cellSize });
+    const start = grid.cellAt([from[0], from[2]]);
+    const goal = grid.cellAt([to[0], to[2]]);
+    if (start.col === goal.col && start.row === goal.row) {
+        return directClear ? { status: "path", waypoints: [[...from], [...to]], work } : failure("no-path");
+    }
+    const center = grid.center;
+    grid.center = (col, row) => col === start.col && row === start.row ? [from[0], from[2]] :
+        col === goal.col && row === goal.row ? [to[0], to[2]] : center(col, row);
+    const waypoint = (point) => {
+        if (point[0] === from[0] && point[1] === from[2])
+            return from;
+        if (point[0] === to[0] && point[1] === to[2])
+            return to;
+        const y = options.sampleHeight?.(point[0], point[1]) ?? from[1];
+        if (!Number.isFinite(y))
+            throw new Error("solidRoute sampleHeight must be finite.");
+        return [point[0], y, point[1]];
+    };
+    for (let row = 0; row < grid.rows; row++) {
+        for (let col = 0; col < grid.cols; col++) {
+            const point = waypoint(grid.center(col, row));
+            grid.setWalkable(col, row, inside(point) && clear(point, point));
+            work.cells++;
+            if (exhausted)
+                return failure("budget");
+        }
+    }
+    const result = findPathResult(grid, [from[0], from[2]], [to[0], to[2]], {
+        maxNodes, stepCost: options.stepCost, smooth: options.smooth ?? options.stepCost === undefined,
+        canTraverse: (a, b) => clear(waypoint(a), waypoint(b)),
+    });
+    work.visited = result.visited;
+    if (exhausted)
+        return failure("budget");
+    if (result.status !== "path")
+        return failure(result.status);
+    const waypoints = result.points.map((point) => [...waypoint(point)]);
+    for (let i = 1; i < waypoints.length; i++) {
+        if (!clear(waypoints[i - 1], waypoints[i]))
+            return failure(exhausted ? "budget" : "no-path");
+    }
+    return { status: "path", waypoints, work };
+}

package/dist/physics/ballisticSweep.d.ts

@@ -11,8 +11,15 @@ export interface BallisticSweepOptions {
     radius?: number;
 }
 /**
- * Marches the closed-form arc (constant gravity, straight lateral) through `world` and reports the
- * first sample inside any live body's AABB — sleeping bodies included — refined by one bisection
- * between the last clear sample and the hit sample. Returns `null` when the whole arc is clear.
+ * Sweeps each short chord of the closed-form arc through live body AABBs, including sleeping bodies.
+ * Thin cover between samples blocks; `step` controls the approximation of the curved path.
  */
 export declare function createBallisticSweep(world: PhysicsWorld, options?: BallisticSweepOptions): BallisticSweep;
+/** Contact fraction for a point segment against a translating axis-aligned box; inflate extents for a projectile radius.
+ * @capability moving-box-sweep detect contact with boxes crossing a projectile segment between simulation poses
+ */
+export declare function sweepMovingBounds(from: readonly [number, number, number], to: readonly [number, number, number], targetFrom: readonly [number, number, number], targetTo: readonly [number, number, number], halfExtents: readonly [number, number, number]): number | null;
+/** Contact fraction for a point segment against a translating sphere; add the projectile radius to `radius`.
+ * @capability moving-sphere-sweep detect contact with spheres crossing a projectile segment between simulation poses
+ */
+export declare function sweepMovingSphere(from: readonly [number, number, number], to: readonly [number, number, number], targetFrom: readonly [number, number, number], targetTo: readonly [number, number, number], radius: number): number | null;

package/dist/physics/ballisticSweep.js

@@ -1,49 +1,73 @@
+import { intersectAabb } from "../scene/objectQuery.js";
 const DEFAULT_SWEEP_STEP = 1 / 60;
 /**
- * Marches the closed-form arc (constant gravity, straight lateral) through `world` and reports the
- * first sample inside any live body's AABB — sleeping bodies included — refined by one bisection
- * between the last clear sample and the hit sample. Returns `null` when the whole arc is clear.
+ * Sweeps each short chord of the closed-form arc through live body AABBs, including sleeping bodies.
+ * Thin cover between samples blocks; `step` controls the approximation of the curved path.
  */
 export function createBallisticSweep(world, options = {}) {
     const step = options.step ?? DEFAULT_SWEEP_STEP;
     const radius = options.radius ?? 0;
-    function overlapsAnyBody(x, y, z) {
-        for (let i = 0; i < world.highWater; i += 1) {
-            if (!world.isAlive(i))
-                continue;
-            if (Math.abs(x - world.posX[i]) > world.halfX[i] + radius)
-                continue;
-            if (Math.abs(y - world.posY[i]) > world.halfY[i] + radius)
-                continue;
-            if (Math.abs(z - world.posZ[i]) > world.halfZ[i] + radius)
-                continue;
-            return true;
-        }
-        return false;
-    }
+    if (!Number.isFinite(step) || step <= 0 || !Number.isFinite(radius) || radius < 0)
+        throw new RangeError("Ballistic sweep requires a finite positive step and nonnegative radius");
     return (origin, velocity, gravity, maxTime) => {
+        if (!origin.every(Number.isFinite) || !velocity.every(Number.isFinite) || !Number.isFinite(gravity) || !Number.isFinite(maxTime) || maxTime < 0 || Math.ceil(maxTime / step) > 100_000)
+            throw new RangeError("Ballistic sweep requires finite inputs within its 100000 segment budget");
         const pointAt = (t) => [
             origin[0] + velocity[0] * t,
             origin[1] + velocity[1] * t - 0.5 * gravity * t * t,
             origin[2] + velocity[2] * t,
         ];
-        let lastClear = 0;
         let t = 0;
         for (;;) {
-            const sample = pointAt(t);
-            if (overlapsAnyBody(sample[0], sample[1], sample[2])) {
-                if (t === 0)
-                    return { point: sample, time: 0 };
-                const mid = (lastClear + t) / 2;
-                const midSample = pointAt(mid);
-                return overlapsAnyBody(midSample[0], midSample[1], midSample[2])
-                    ? { point: midSample, time: mid }
-                    : { point: sample, time: t };
+            const nextTime = Math.min(t + step, maxTime);
+            const from = pointAt(t);
+            const to = pointAt(nextTime);
+            let fraction = null;
+            for (let i = 0; i < world.highWater; i += 1) {
+                if (!world.isAlive(i))
+                    continue;
+                const contact = sweepMovingBounds(from, to, [world.posX[i], world.posY[i], world.posZ[i]], [world.posX[i], world.posY[i], world.posZ[i]], [world.halfX[i] + radius, world.halfY[i] + radius, world.halfZ[i] + radius]);
+                if (contact !== null && (fraction === null || contact < fraction))
+                    fraction = contact;
+            }
+            if (fraction !== null) {
+                const time = t + (nextTime - t) * fraction;
+                return { point: pointAt(time), time };
             }
             if (t >= maxTime)
                 return null;
-            lastClear = t;
-            t = Math.min(t + step, maxTime);
+            t = nextTime;
         }
     };
 }
+/** Contact fraction for a point segment against a translating axis-aligned box; inflate extents for a projectile radius.
+ * @capability moving-box-sweep detect contact with boxes crossing a projectile segment between simulation poses
+ */
+export function sweepMovingBounds(from, to, targetFrom, targetTo, halfExtents) {
+    const origin = [from[0] - targetFrom[0], from[1] - targetFrom[1], from[2] - targetFrom[2]];
+    const motion = [to[0] - targetTo[0] - origin[0], to[1] - targetTo[1] - origin[1], to[2] - targetTo[2] - origin[2]];
+    return intersectAabb(origin, motion, [-halfExtents[0], -halfExtents[1], -halfExtents[2]], halfExtents, 1)?.distance ?? null;
+}
+/** Contact fraction for a point segment against a translating sphere; add the projectile radius to `radius`.
+ * @capability moving-sphere-sweep detect contact with spheres crossing a projectile segment between simulation poses
+ */
+export function sweepMovingSphere(from, to, targetFrom, targetTo, radius) {
+    const ox = from[0] - targetFrom[0];
+    const oy = from[1] - targetFrom[1];
+    const oz = from[2] - targetFrom[2];
+    const dx = to[0] - targetTo[0] - ox;
+    const dy = to[1] - targetTo[1] - oy;
+    const dz = to[2] - targetTo[2] - oz;
+    const c = ox * ox + oy * oy + oz * oz - radius * radius;
+    if (c <= 0)
+        return 0;
+    const a = dx * dx + dy * dy + dz * dz;
+    if (a <= 1e-18)
+        return null;
+    const b = ox * dx + oy * dy + oz * dz;
+    const discriminant = b * b - a * c;
+    if (discriminant < 0)
+        return null;
+    const fraction = (-b - Math.sqrt(discriminant)) / a;
+    return fraction >= 0 && fraction <= 1 ? fraction : null;
+}