@jgengine/core 0.18.1 → 0.19.0

package/dist/movement/playerMovement.d.ts

@@ -2,11 +2,14 @@ import type { PhysicsConfig } from "../game/defineGame.js";
 import type { PlayerMovementConfig, VoxelCollisionConfig } from "../game/playableGame.js";
 import type { GameContext } from "../runtime/gameContext.js";
 import type { InputFrame } from "../runtime/inputSnapshot.js";
-import { type CharacterControllerConfig } from "./characterController.js";
+import { type InputBufferSnapshot } from "../input/inputBuffer.js";
+import { type CharacterControllerConfig, type CharacterControllerState } from "./characterController.js";
 import { type TerrainField } from "../world/terrain.js";
 import type { WorldFeature } from "../world/features.js";
 import type { PhysicsBackend } from "../physics/physicsBackend.js";
-import { type MovementTuningOverrides } from "./movementModel.js";
+import { type MovementTuningOverrides, type PlayerMotionState } from "./movementModel.js";
+import { type FreeFlightState } from "./freeFlight.js";
+import { type VoxelPlayerBody } from "./voxelController.js";
 /** The resolved, per-world movement configuration {@link stepPlayerMovement} integrates against — the same inputs the shell FrameDriver used to read piecemeal, gathered into one struct so single-player and host movement run identical math. */
 export interface PlayerMovementTuning {
     collision?: VoxelCollisionConfig;
@@ -35,6 +38,22 @@ export declare function resolvePlayerMovementTuning(opts: {
 }): PlayerMovementTuning;
 /** One player's current heading (radians), integrated by {@link stepPlayerMovement} — the shell reads it back into its camera/aim yaw. */
 export declare function playerMovementHeading(ctx: GameContext, userId: string): number;
+/** One player's serializable movement state: heading, facing, velocities, jump latch and controller capsule. The entity pose lives in the entity store. */
+export interface PlayerMovementSnapshot {
+    heading: number;
+    facing: number | null;
+    voxelBody: VoxelPlayerBody | null;
+    motion: PlayerMotionState | null;
+    flight: FreeFlightState | null;
+    controller: CharacterControllerState | null;
+    controllerJumpHeld: boolean;
+    /** Buffered jump presses; absent in snapshots taken before jump buffering existed. */
+    jumpBuffer?: InputBufferSnapshot | null;
+}
+/** Copy one player's movement state for prediction, rollback or a save; `null` when the player has not moved yet. */
+export declare function snapshotPlayerMovement(ctx: GameContext, userId: string): PlayerMovementSnapshot | null;
+/** Put a player's movement state back to a {@link snapshotPlayerMovement} copy, so the next {@link stepPlayerMovement} replays from there. */
+export declare function restorePlayerMovement(ctx: GameContext, userId: string, snapshot: PlayerMovementSnapshot): void;
 /** Drop a player's retained movement state (heading + kinematic body) — call on leave so a rejoin starts fresh instead of resuming stale velocity. */
 export declare function forgetPlayerMovement(ctx: GameContext, userId: string): void;
 /**

package/dist/movement/playerMovement.js

@@ -1,5 +1,6 @@
+import { createInputBuffer } from "../input/inputBuffer.js";
 import { applyHorizontalImpulses, applyMotionImpulses } from "../runtime/motionIntents.js";
-import { createCharacterController } from "./characterController.js";
+import { createCharacterController, } from "./characterController.js";
 import { groundFieldFor, hasEnvironmentTerrain, sampleSlope } from "../world/terrain.js";
 import { advancePlayerMotion, constrainStepToAxis, createEmptyMovementKeys, createPlayerMotionState, DEFAULT_OBSTACLE_PLAYER_RADIUS, obstacleSupportHeight, resolveMovementIntent, resolveObstacleStep, snapPositionToGrid, MOVEMENT_TUNING, } from "./movementModel.js";
 import { advanceFreeFlight, createFreeFlightState, resolveFlightStep, resolveFreeFlightIntentFromInput, } from "./freeFlight.js";
@@ -36,7 +37,24 @@ export function resolvePhysicsTuning(physics) {
 export function resolvePlayerMovementTuning(opts) {
     const physics = resolvePhysicsTuning(opts.physics);
     const backpedal = opts.movement?.backpedalMult;
-    const overrides = backpedal === undefined ? physics : { ...(physics ?? {}), backpedalSpeedMultiplier: backpedal };
+    const feel = opts.movement?.feel;
+    const feelOverrides = {
+        ...(backpedal === undefined ? {} : { backpedalSpeedMultiplier: backpedal }),
+        ...(feel?.groundAcceleration === undefined ? {} : { groundAcceleration: feel.groundAcceleration }),
+        ...(feel?.airAcceleration === undefined ? {} : { airAcceleration: feel.airAcceleration }),
+        ...(feel?.groundFriction === undefined ? {} : { groundFriction: feel.groundFriction }),
+        ...(feel?.runMultiplier === undefined ? {} : { runSpeedMultiplier: feel.runMultiplier }),
+        ...(feel?.crouchMultiplier === undefined ? {} : { crouchSpeedMultiplier: feel.crouchMultiplier }),
+        ...(feel?.jumpBufferMs === undefined ? {} : { jumpBufferMs: feel.jumpBufferMs }),
+        ...(feel?.coyoteMs === undefined ? {} : { coyoteMs: feel.coyoteMs }),
+        ...(feel?.jumpCutFactor === undefined ? {} : { jumpCutFactor: feel.jumpCutFactor }),
+        ...(feel?.apexGravityScale === undefined ? {} : { apexGravityScale: feel.apexGravityScale }),
+        ...(feel?.apexSpeed === undefined ? {} : { apexSpeed: feel.apexSpeed }),
+        ...(feel?.fallGravityScale === undefined ? {} : { fallGravityScale: feel.fallGravityScale }),
+        ...(feel?.landingRecoveryMs === undefined ? {} : { landingRecoveryMs: feel.landingRecoveryMs }),
+        ...(feel?.landingSpeedScale === undefined ? {} : { landingSpeedScale: feel.landingSpeedScale }),
+    };
+    const overrides = Object.keys(feelOverrides).length === 0 ? physics : { ...(physics ?? {}), ...feelOverrides };
     return {
         ...(opts.collision === undefined ? {} : { collision: opts.collision }),
         ...(opts.movement === undefined ? {} : { movement: opts.movement }),
@@ -72,7 +90,17 @@ function storeFor(ctx) {
 function stateFor(store, userId) {
     let state = store.players.get(userId);
     if (state === undefined) {
-        state = { heading: 0, facing: null, voxelBody: null, motion: null, flight: null, controller: null, controllerJumpHeld: false };
+        state = {
+            heading: 0,
+            facing: null,
+            voxelBody: null,
+            motion: null,
+            flight: null,
+            controller: null,
+            controllerJumpHeld: false,
+            jumpBuffer: null,
+            pendingController: null,
+        };
         store.players.set(userId, state);
     }
     return state;
@@ -81,6 +109,54 @@ function stateFor(store, userId) {
 export function playerMovementHeading(ctx, userId) {
     return stores.get(ctx)?.players.get(userId)?.heading ?? 0;
 }
+function copyController(state) {
+    return { ...state, position: [...state.position], groundNormal: [...state.groundNormal] };
+}
+/** Copy one player's movement state for prediction, rollback or a save; `null` when the player has not moved yet. */
+export function snapshotPlayerMovement(ctx, userId) {
+    const state = stores.get(ctx)?.players.get(userId);
+    if (state === undefined)
+        return null;
+    const controller = state.controller?.snapshot() ?? state.pendingController;
+    return {
+        heading: state.heading,
+        facing: state.facing,
+        voxelBody: state.voxelBody === null ? null : { ...state.voxelBody },
+        motion: state.motion === null ? null : { ...state.motion },
+        flight: state.flight === null ? null : { ...state.flight },
+        controller: controller === null ? null : copyController(controller),
+        controllerJumpHeld: state.controllerJumpHeld,
+        jumpBuffer: state.jumpBuffer?.snapshot() ?? null,
+    };
+}
+/** Put a player's movement state back to a {@link snapshotPlayerMovement} copy, so the next {@link stepPlayerMovement} replays from there. */
+export function restorePlayerMovement(ctx, userId, snapshot) {
+    const state = stateFor(storeFor(ctx), userId);
+    state.heading = snapshot.heading;
+    state.facing = snapshot.facing;
+    state.voxelBody = snapshot.voxelBody === null ? null : { ...snapshot.voxelBody };
+    state.motion = snapshot.motion === null ? null : { ...snapshot.motion };
+    state.flight = snapshot.flight === null ? null : { ...snapshot.flight };
+    state.controllerJumpHeld = snapshot.controllerJumpHeld;
+    const jumpBuffer = snapshot.jumpBuffer ?? null;
+    if (jumpBuffer === null) {
+        state.jumpBuffer = null;
+    }
+    else {
+        state.jumpBuffer ??= createInputBuffer({ windowMs: jumpBuffer.windowMs });
+        state.jumpBuffer.restore(jumpBuffer);
+    }
+    const controller = snapshot.controller === null ? null : copyController(snapshot.controller);
+    if (state.controller !== null && controller !== null) {
+        state.controller.restore(controller);
+        state.pendingController = null;
+    }
+    else {
+        if (controller === null)
+            state.controller = null;
+        state.pendingController = controller;
+    }
+}
 /** Drop a player's retained movement state (heading + kinematic body) — call on leave so a rejoin starts fresh instead of resuming stale velocity. */
 export function forgetPlayerMovement(ctx, userId) {
     stores.get(ctx)?.players.delete(userId);
@@ -275,7 +351,7 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitc
         if (controller === null) {
             controller = createCharacterController(tuning.controller.capsule);
             state.controller = controller;
-            controller.restore({
+            controller.restore(state.pendingController ?? {
                 position: [player.position[0], player.position[1], player.position[2]],
                 verticalVelocity: 0,
                 grounded: true,
@@ -283,6 +359,7 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitc
                 groundBody: null,
                 crouching: false,
             });
+            state.pendingController = null;
         }
         const controllerState = controller.state();
         if (Math.hypot(controllerState.position[0] - player.position[0], controllerState.position[1] - player.position[1], controllerState.position[2] - player.position[2]) > 1e-6) {
@@ -401,9 +478,15 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitc
     const submerged = swimEnabled &&
         waterLevel !== undefined &&
         tuning.ground.sampleHeight(player.position[0], player.position[2]) < waterLevel;
+    const jumpBufferMs = tuning.physics?.jumpBufferMs ?? 0;
+    let jumpBuffer = state.jumpBuffer;
+    if (jumpBuffer === null) {
+        jumpBuffer = createInputBuffer({ windowMs: jumpBufferMs });
+        state.jumpBuffer = jumpBuffer;
+    }
     const motionOptions = submerged
-        ? { speedScale: swimSpeedMultiplier, floating: true }
-        : undefined;
+        ? { speedScale: swimSpeedMultiplier, floating: true, buffer: jumpBuffer }
+        : { buffer: jumpBuffer };
     const prevJumpOffset = motion.jumpOffset;
     const step = advancePlayerMotion(motion, intent, forwardX, forwardZ, walkSpeed, dt, tuning.physics, motionOptions);
     // Airborne means "not resting on the surface below": any jump/impulse height before or after this

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 } 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 {
@@ -49,9 +50,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

@@ -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,14 @@ 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);
+    const solids = ctx.world.solids;
+    if (solids.count() === 0)
+        return obstacles;
+    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) {

package/dist/movement/voxelController.js

@@ -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);
@@ -176,15 +176,15 @@ export function advanceVoxelPlayer(body, intent, forwardX, forwardZ, baseSpeed,
     const dt = Math.min(rawDeltaSeconds, MOVEMENT_TUNING.maxFrameSeconds);
     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/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;