@jgengine/core 0.25.0 → 0.26.0

package/dist/nav/navCrowd.js

@@ -0,0 +1,412 @@
+import { devtools } from "../devtools/devtools.js";
+import { createRvoCrowd } from "../ai/rvo.js";
+import { spreadOffset } from "../ai/crowd.js";
+const EPSILON = 1e-9;
+function sameVec(a, b) {
+    return a[0] === b[0] && a[1] === b[1] && a[2] === b[2];
+}
+/**
+ * Compose {@link createNavRuntime} and {@link createRvoCrowd} into a moving crowd: plan on the mesh,
+ * follow the smoothed corridor, avoid each other. Deterministic — agents advance in insertion order
+ * and the avoidance solve breaks ties by slot, not chance.
+ *
+ * @capability nav-crowd move many agents across an editor-baked nav mesh with avoidance
+ */
+export function createNavCrowd(options) {
+    const nav = options.nav;
+    let speed = Math.max(0, options.speed ?? 3);
+    let radius = Math.max(0, options.radius ?? 0.4);
+    let goalRadius = Math.max(0, options.goalRadius ?? 0.5);
+    let spread = Math.max(0, options.spread ?? 0);
+    let waypointRadius = Math.max(0, options.waypointRadius ?? 0.6);
+    let replanBudget = Math.max(1, Math.floor(options.replanBudget ?? 8));
+    let replanMs = Math.max(0, options.replanMs ?? 1.5);
+    const agents = [];
+    const agentOf = new Map();
+    const avoid = createRvoCrowd({ devtoolsName: undefined, ...options.avoid });
+    let ticks = 0;
+    let plans = 0;
+    let unroutable = 0;
+    let slowestTickMs = 0;
+    const motion = { x: 0, z: 0, vx: 0, vz: 0 };
+    let cachedBounds = [0, 0, 0, 0];
+    let cachedRebuilds = -1;
+    /** Whole-mesh XZ bounds, recomputed only after the runtime exchanged the mesh. */
+    function meshBounds() {
+        const rebuilds = nav.rebuilds();
+        if (rebuilds === cachedRebuilds)
+            return cachedBounds;
+        const verts = nav.mesh.verts;
+        let minX = Infinity;
+        let minZ = Infinity;
+        let maxX = -Infinity;
+        let maxZ = -Infinity;
+        for (let i = 0; i < verts.length; i += 3) {
+            const x = verts[i];
+            const z = verts[i + 2];
+            if (x < minX)
+                minX = x;
+            if (x > maxX)
+                maxX = x;
+            if (z < minZ)
+                minZ = z;
+            if (z > maxZ)
+                maxZ = z;
+        }
+        cachedBounds = Number.isFinite(minX) ? [minX, minZ, maxX, maxZ] : [0, 0, 0, 0];
+        cachedRebuilds = rebuilds;
+        return cachedBounds;
+    }
+    function probeLine() {
+        let arrived = 0;
+        let waiting = 0;
+        for (const agent of agents) {
+            if (agent.arrived)
+                arrived += 1;
+            if (agent.waitingForPlan)
+                waiting += 1;
+        }
+        return `${agents.length} agents ${arrived} arrived ${waiting} waiting ${plans} plans ${unroutable} unroutable ${ticks} ticks ${slowestTickMs.toFixed(2)} ms slowest`;
+    }
+    const unregister = options.devtoolsName === undefined ? null : devtools.probes.register(options.devtoolsName, () => probeLine());
+    function applyPath(agent, path) {
+        plans += 1;
+        if (path === null || path.points.length === 0) {
+            agent.waypoints = [];
+            agent.waypoint = 0;
+            agent.polys = [];
+            agent.arrived = false;
+            agent.waitingForPlan = false;
+            unroutable += 1;
+            return false;
+        }
+        agent.waypoints = path.points.map((point) => [point[0], point[1], point[2]]);
+        agent.waypoint = agent.waypoints.length > 1 ? 1 : 0;
+        agent.polys = [...path.polys];
+        agent.arrived = false;
+        agent.waitingForPlan = false;
+        return true;
+    }
+    function aim(agent) {
+        return [agent.goal[0] + agent.offsetX, agent.goal[1], agent.goal[2] + agent.offsetZ];
+    }
+    function replan(agent) {
+        return applyPath(agent, nav.plan([agent.x, agent.y, agent.z], aim(agent)));
+    }
+    function index(id) {
+        return agentOf.get(id);
+    }
+    return {
+        add(id, spec) {
+            if (agentOf.has(id))
+                return false;
+            const [offsetX, offsetZ] = spread > 0 ? spreadOffset(id, spread) : [0, 0];
+            const agent = {
+                id,
+                goal: spec.goal,
+                offsetX,
+                offsetZ,
+                speed: Math.max(0, spec.speed ?? speed),
+                radius: Math.max(0, spec.radius ?? radius),
+                waypoints: [],
+                waypoint: 0,
+                polys: [],
+                arrived: false,
+                waitingForPlan: false,
+                x: spec.position[0],
+                y: spec.position[1],
+                z: spec.position[2],
+                velocity: [0, 0],
+            };
+            agents.push(agent);
+            agentOf.set(id, agents.length - 1);
+            avoid.add(id, { x: spec.position[0], z: spec.position[2], radius: agent.radius, maxSpeed: agent.speed });
+            replan(agent);
+            return true;
+        },
+        remove(id) {
+            const at = index(id);
+            if (at === undefined)
+                return false;
+            const last = agents.pop();
+            agentOf.delete(id);
+            if (at < agents.length) {
+                agents[at] = last;
+                agentOf.set(last.id, at);
+            }
+            avoid.remove(id);
+            return true;
+        },
+        has: (id) => agentOf.has(id),
+        count: () => agents.length,
+        ids: () => agents.map((agent) => agent.id),
+        setGoal(id, goal) {
+            const at = index(id);
+            if (at === undefined)
+                return false;
+            const agent = agents[at];
+            if (agent.arrived && sameVec(agent.goal, goal))
+                return true;
+            agent.goal = goal;
+            agent.arrived = false;
+            agent.waitingForPlan = true;
+            return true;
+        },
+        plan(id) {
+            const at = index(id);
+            if (at === undefined)
+                return false;
+            return replan(agents[at]);
+        },
+        agent(id) {
+            const at = index(id);
+            if (at === undefined)
+                return null;
+            const agent = agents[at];
+            return {
+                id: agent.id,
+                position: [agent.x, agent.y, agent.z],
+                velocity: agent.velocity,
+                goal: agent.goal,
+                waypoint: agent.waypoint,
+                waypoints: agent.waypoints.length,
+                arrived: agent.arrived,
+                waitingForPlan: agent.waitingForPlan,
+            };
+        },
+        tick(dt) {
+            if (!(dt > 0) || agents.length === 0)
+                return;
+            const started = performance.now();
+            let budget = replanBudget;
+            const replanDeadline = started + replanMs;
+            for (const agent of agents) {
+                if (!agent.waitingForPlan)
+                    continue;
+                if (budget <= 0)
+                    break;
+                if (performance.now() > replanDeadline)
+                    break;
+                budget -= 1;
+                replan(agent);
+            }
+            for (const agent of agents) {
+                const target = agent.arrived ? null : agent.waypoints[agent.waypoint];
+                if (target === null || target === undefined) {
+                    // A route that ended short of the goal (congestion pushed it away) needs a new plan, or the
+                    // agent would stand there with no target forever.
+                    if (!agent.arrived && !agent.waitingForPlan && agent.waypoints.length > 0)
+                        agent.waitingForPlan = true;
+                    avoid.setPreferredVelocity(agent.id, 0, 0);
+                    continue;
+                }
+                const dx = target[0] - agent.x;
+                const dz = target[2] - agent.z;
+                const distance = Math.hypot(dx, dz);
+                if (distance <= EPSILON) {
+                    avoid.setPreferredVelocity(agent.id, 0, 0);
+                    continue;
+                }
+                const want = Math.min(agent.speed, distance / dt);
+                avoid.setPreferredVelocity(agent.id, (dx / distance) * want, (dz / distance) * want);
+            }
+            avoid.step(dt);
+            const bounds = meshBounds();
+            for (const agent of agents) {
+                if (!avoid.readInto(agent.id, motion))
+                    continue;
+                agent.velocity[0] = motion.vx;
+                agent.velocity[1] = motion.vz;
+                let x = motion.x;
+                let z = motion.z;
+                let y = agent.y;
+                // Avoidance pushes agents apart with no idea where the walls are; keep each one inside the
+                // baked mesh's bounds so a shove cannot walk it off the walkable surface. Interior walls stay
+                // the game's collision layer: this seam has the outer bound, not a baked obstacle field.
+                if (x < bounds[0] - 0.01 || x > bounds[2] + 0.01 || z < bounds[1] - 0.01 || z > bounds[3] + 0.01) {
+                    const snapped = nav.closestPoint([x, y, z]);
+                    if (snapped !== null) {
+                        x = snapped[0];
+                        y = snapped[1];
+                        z = snapped[2];
+                        avoid.setKinematics(agent.id, { x, z });
+                    }
+                }
+                let advanced = true;
+                for (let guard = agent.waypoints.length + 1; advanced && guard > 0; guard -= 1) {
+                    advanced = false;
+                    const target = agent.waypoints[agent.waypoint];
+                    if (target === undefined)
+                        break;
+                    if (Math.hypot(target[0] - x, target[2] - z) <= waypointRadius) {
+                        y = target[1];
+                        agent.waypoint += 1;
+                        advanced = true;
+                    }
+                }
+                agent.x = x;
+                agent.y = y;
+                agent.z = z;
+                const goalDistance = Math.hypot(agent.goal[0] + agent.offsetX - x, agent.goal[2] + agent.offsetZ - z);
+                if (agent.waypoint >= agent.waypoints.length && goalDistance <= Math.max(goalRadius, waypointRadius)) {
+                    agent.arrived = true;
+                    agent.waypoints = [];
+                    agent.waypoint = 0;
+                    agent.polys = [];
+                }
+                else if (agent.arrived && goalDistance > Math.max(goalRadius, waypointRadius)) {
+                    agent.arrived = false;
+                    agent.waitingForPlan = true;
+                }
+            }
+            ticks += 1;
+            slowestTickMs = Math.max(slowestTickMs, performance.now() - started);
+        },
+        revalidate(stats, region) {
+            let queued = 0;
+            let untouched = 0;
+            for (const agent of agents) {
+                if (agent.waitingForPlan) {
+                    queued += 1;
+                    continue;
+                }
+                if (agent.waypoints.length === 0) {
+                    untouched += 1;
+                    continue;
+                }
+                let crossed = false;
+                for (const poly of agent.polys) {
+                    if (poly < 0 || poly >= stats.remap.length || stats.remap[poly] === -1) {
+                        crossed = true;
+                        break;
+                    }
+                }
+                if (!crossed && region !== undefined) {
+                    for (let i = agent.waypoint; i < agent.waypoints.length && !crossed; i += 1) {
+                        const point = agent.waypoints[i];
+                        crossed = point[0] >= region.min[0] && point[0] <= region.max[0] && point[2] >= region.min[1] && point[2] <= region.max[1];
+                    }
+                }
+                if (crossed) {
+                    agent.waitingForPlan = true;
+                    queued += 1;
+                }
+                else {
+                    untouched += 1;
+                }
+            }
+            return { queued, untouched };
+        },
+        stats() {
+            let arrived = 0;
+            let waiting = 0;
+            for (const agent of agents) {
+                if (agent.arrived)
+                    arrived += 1;
+                if (agent.waitingForPlan)
+                    waiting += 1;
+            }
+            return { agents: agents.length, arrived, waitingForPlan: waiting, plans, unroutable, ticks, slowestTickMs };
+        },
+        retune(patch) {
+            if (patch.speed !== undefined)
+                speed = Math.max(0, patch.speed);
+            if (patch.radius !== undefined)
+                radius = Math.max(0, patch.radius);
+            if (patch.goalRadius !== undefined)
+                goalRadius = Math.max(0, patch.goalRadius);
+            if (patch.spread !== undefined) {
+                spread = Math.max(0, patch.spread);
+                for (const agent of agents) {
+                    const [offsetX, offsetZ] = spread > 0 ? spreadOffset(agent.id, spread) : [0, 0];
+                    agent.offsetX = offsetX;
+                    agent.offsetZ = offsetZ;
+                    agent.arrived = false;
+                    agent.waitingForPlan = true;
+                }
+            }
+            if (patch.waypointRadius !== undefined)
+                waypointRadius = Math.max(0, patch.waypointRadius);
+            if (patch.replanBudget !== undefined)
+                replanBudget = Math.max(1, Math.floor(patch.replanBudget));
+            if (patch.replanMs !== undefined)
+                replanMs = Math.max(0, patch.replanMs);
+            if (patch.avoid !== undefined)
+                avoid.retune(patch.avoid);
+        },
+        snapshot() {
+            const avoidState = avoid.snapshot();
+            return {
+                tunables: {
+                    speed,
+                    radius,
+                    goalRadius,
+                    spread,
+                    waypointRadius,
+                    replanBudget,
+                    replanMs,
+                    avoid: { ...avoidState.tunables },
+                },
+                agents: agents.map((agent) => ({
+                    id: agent.id,
+                    position: [agent.x, agent.y, agent.z],
+                    velocity: [agent.velocity[0], agent.velocity[1]],
+                    goal: agent.goal,
+                    offsetX: agent.offsetX,
+                    offsetZ: agent.offsetZ,
+                    speed: agent.speed,
+                    radius: agent.radius,
+                    waypoints: agent.waypoints.map((point) => [point[0], point[1], point[2]]),
+                    waypoint: agent.waypoint,
+                    arrived: agent.arrived,
+                    polys: [...agent.polys],
+                    waitingForPlan: agent.waitingForPlan,
+                })),
+            };
+        },
+        restore(next) {
+            agents.length = 0;
+            agentOf.clear();
+            speed = next.tunables.speed;
+            radius = next.tunables.radius;
+            goalRadius = next.tunables.goalRadius;
+            spread = Math.max(0, next.tunables.spread ?? 0);
+            waypointRadius = next.tunables.waypointRadius;
+            replanBudget = next.tunables.replanBudget;
+            replanMs = next.tunables.replanMs ?? 1.5;
+            avoid.restore({ tunables: { ...next.tunables.avoid }, agents: [] });
+            for (const saved of next.agents) {
+                const agent = {
+                    id: saved.id,
+                    goal: saved.goal,
+                    offsetX: saved.offsetX,
+                    offsetZ: saved.offsetZ,
+                    speed: saved.speed,
+                    radius: saved.radius,
+                    waypoints: saved.waypoints.map((point) => [point[0], point[1], point[2]]),
+                    waypoint: saved.waypoint,
+                    polys: [...saved.polys],
+                    arrived: saved.arrived,
+                    waitingForPlan: saved.waitingForPlan,
+                    x: saved.position[0],
+                    y: saved.position[1],
+                    z: saved.position[2],
+                    velocity: [saved.velocity[0], saved.velocity[1]],
+                };
+                agents.push(agent);
+                agentOf.set(agent.id, agents.length - 1);
+                avoid.add(agent.id, {
+                    x: saved.position[0],
+                    z: saved.position[2],
+                    radius: saved.radius,
+                    maxSpeed: saved.speed,
+                    vx: saved.velocity[0],
+                    vz: saved.velocity[1],
+                });
+            }
+        },
+        dispose() {
+            unregister?.();
+        },
+    };
+}

package/dist/nav/navRuntime.d.ts

@@ -0,0 +1,108 @@
+import type { Vec3 } from "../world/geometry.js";
+import { type NavMeshData, type NavMeshLink, type NavMeshPath, type NavMeshQueryOptions } from "./navMesh.js";
+/** What an authored off-mesh connection crosses; the runtime prices it by kind unless the author sets a cost. */
+export type NavLinkKind = "door" | "ladder" | "jump" | "link";
+/**
+ * A connection the scene author places between two spots — a door through a wall, a ladder to a
+ * deck, a jump across a gap. Authored as world points, not polygon ids, so it survives a re-bake:
+ * {@link NavRuntime.applyMesh} resolves each end onto the nearest walkable polygon.
+ */
+export interface AuthoredNavLink {
+    /** Stable authored id; reported by `unresolvedLinks()` when an end no longer touches the mesh. */
+    id: string;
+    /** Traversal kind; prices the link when `cost` is absent. Default `"link"`. */
+    kind?: NavLinkKind;
+    /** World point the agent leaves from. */
+    from: Vec3;
+    /** World point the agent arrives at. */
+    to: Vec3;
+    /** Path cost in world units; overrides the kind's price. Non-finite or negative falls back to the kind. */
+    cost?: number;
+}
+/** An XZ box naming the authored area a scene edit touched, so routing state elsewhere is left alone. */
+export interface NavRegion {
+    min: readonly [number, number];
+    max: readonly [number, number];
+}
+/** How one {@link NavRuntime.applyMesh} exchange changed the mesh. */
+export interface NavRebuildStats {
+    /** Polygons in the new bake that have no predecessor. */
+    added: number;
+    /** Older polygons the new bake no longer contains. */
+    removed: number;
+    /** Older polygons the new bake still contains, matched by geometry — their routes stay valid. */
+    kept: number;
+    /** Old polygon index → its index in the new mesh, or `-1` when that polygon is gone. */
+    remap: Int32Array;
+}
+/** Serializable tuning and authored links of a {@link NavRuntime}; the baked geometry is replaced by `applyMesh`. */
+export interface NavRuntimeSnapshot {
+    areaCosts: Record<number, number>;
+    maxNodes: number;
+    links: AuthoredNavLink[];
+    linkCosts: Partial<Record<NavLinkKind, number>>;
+    linkSnapRadius: number;
+}
+/** Runtime seam over a baked {@link NavMeshData}: route, price areas, resolve authored links, rebuild in place. */
+export interface NavRuntime {
+    /** The mesh currently routed on — a bake plus the resolved links. */
+    readonly mesh: NavMeshData;
+    /** Cheapest polygon corridor between two points, funnel-smoothed by the mesh query. */
+    plan(from: Vec3, to: Vec3): NavMeshPath | null;
+    findPolygon(point: Vec3): number | null;
+    closestPoint(point: Vec3): Vec3 | null;
+    /** True when the straight segment stays on walkable, unblocked polygons. */
+    raycast(from: Vec3, to: Vec3): boolean;
+    /**
+     * Exchange the bake for a newer one. The new geometry is authoritative; polygons that survive the
+     * re-bake keep their identity through `remap`, so routing state over them stays valid and only the
+     * routes crossing changed polygons need re-planning.
+     */
+    applyMesh(next: NavMeshData): NavRebuildStats;
+    /** Resolved links the router is using. */
+    links(): readonly NavMeshLink[];
+    /** Authored ids whose ends no longer reach the mesh. */
+    unresolvedLinks(): readonly string[];
+    /** How many times the mesh was exchanged. */
+    rebuilds(): number;
+    retune(patch: NavRuntimeOptions): void;
+    snapshot(): NavRuntimeSnapshot;
+    restore(next: NavRuntimeSnapshot): void;
+    /** Drop the devtools probe registered by `devtoolsName`. Safe to call twice. */
+    dispose(): void;
+}
+/** Options for {@link createNavRuntime}. */
+export interface NavRuntimeOptions extends NavMeshQueryOptions {
+    /** Authored off-mesh connections resolved onto the current mesh. */
+    links?: readonly AuthoredNavLink[];
+    /** Price per link kind, in path-cost units; defaults `door` 0.5, `jump` 1.5, `ladder` 4, `link` 0. */
+    linkCosts?: Partial<Record<NavLinkKind, number>>;
+    /** How far an authored link end may sit from the mesh before the link is reported unresolved. Default 2. */
+    linkSnapRadius?: number;
+    /** Register a devtools probe under this name so the perf overlay shows mesh and routing counters. */
+    devtoolsName?: string;
+}
+/** A bake stored on an editor scene document, structurally compatible with `EditorBake`. */
+export interface SceneBake {
+    kind: string;
+    id: string;
+    data: unknown;
+}
+/**
+ * Read the named navigation bake an editor wrote onto a scene document. Returns `null` when the
+ * document holds no such bake yet, and throws when the stored bake is not a valid nav mesh — a
+ * corrupt bake should fail at load, not as agents walking through walls.
+ *
+ * @capability navmesh-from-scene read the editor's baked nav mesh off a scene document
+ */
+export declare function navMeshFromBake(bakes: readonly SceneBake[] | undefined, id?: string): NavMeshData | null;
+/**
+ * Route agents over the nav mesh an editor baked. Wraps {@link createNavMeshQuery}, resolves authored
+ * off-mesh links (doors, ladders, jumps) onto the current surface, and exchanges the mesh one scene
+ * region at a time so untouched polygons keep their ids and the agents routing over them keep their paths.
+ *
+ * @capability nav-runtime route agents on an editor-baked nav mesh with authored links and re-bakes that keep polygon identity
+ */
+export declare function createNavRuntime(options: NavRuntimeOptions & {
+    mesh: NavMeshData;
+}): NavRuntime;