@aethervtt/shard-nav 0.0.1

package/dist/methods.d.ts

@@ -0,0 +1,97 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+import type { AppMethod } from '@aethervtt/shard-runtime';
+/** Grids, navmeshes, and agents as data (the `nav.describe` method). */
+export declare function describeNav(world: World): {
+    recast: boolean;
+    grids: {
+        entity: number;
+        path: string | null;
+        source: "colliders" | "data" | "tilemap";
+        size: number[] | null;
+        cellSize: number[];
+        origin: number[];
+        diagonal: "always" | "never" | "no-corners" | undefined;
+        walkableCells: number;
+        problem: string | null;
+    }[];
+    meshes: ({
+        entity: number;
+        path: string | null;
+        problem: string;
+        settings?: undefined;
+        tiles?: undefined;
+        emptyTiles?: undefined;
+        polygons?: undefined;
+        bounds?: undefined;
+        lastBake?: undefined;
+        bakes?: undefined;
+        tilesBuilt?: undefined;
+        cacheHits?: undefined;
+        waitingForMeshes?: undefined;
+        crowd?: undefined;
+    } | {
+        entity: number;
+        path: string | null;
+        settings: import("./recast.js").BakeSettings;
+        tiles: number;
+        emptyTiles: number;
+        polygons: number;
+        bounds: {
+            min: number[];
+            max: number[];
+        } | null;
+        lastBake: {
+            ms: number;
+            built: number;
+            fromCache: number;
+            kept: number;
+            removed: number;
+        };
+        bakes: number;
+        tilesBuilt: number;
+        cacheHits: number;
+        waitingForMeshes: number;
+        crowd: {
+            agents: number;
+            capacity: number;
+        } | null;
+        problem: string | null;
+    })[];
+    sources: {
+        triangles: number;
+        links: number;
+        skipped: {
+            entity: Entity;
+            reason: string;
+            path: string | null;
+        }[];
+    };
+    cache: {
+        tiles: number;
+        loadedFromDisk: number;
+        file: string | null;
+    };
+    agents: {
+        entity: number;
+        path: string | null;
+        on: {
+            entity: number;
+            path: string | null;
+            kind: "grid" | "mesh" | "none";
+        } | null;
+        status: "arrived" | "idle" | "moving" | "unreachable";
+        remaining: number;
+        corners: number;
+        velocity: number[];
+        destination: number[] | null;
+        target: {
+            entity: number;
+            path: string | null;
+        } | null;
+        drive: "character" | "transform" | "velocity" | undefined;
+        problem?: string | undefined;
+        route: number[][];
+    }[];
+    statuses: readonly ["idle", "moving", "arrived", "unreachable"];
+};
+export declare const navMethods: AppMethod[];

package/dist/methods.js

@@ -0,0 +1,179 @@
+import { defineSchema, findComponent, t } from "@aethervtt/shard-core";
+import { liveTileKeys, NO_RECAST, updateNavigation } from "./bake.js";
+import { NavCache, saveNavCache } from "./cache.js";
+import { AGENT_STATUSES, DRIVES, NavAgent, NavAgentState, NavMesh } from "./components.js";
+import { DIAGONAL_MODES } from "./grid.js";
+import { findPath } from "./query.js";
+import { navState } from "./state.js";
+const round = (x, digits = 3) => Math.round(x * 10 ** digits) / 10 ** digits;
+const r3 = (v) => [round(v[0]), round(v[1]), round(v[2])];
+function scenePath(world, entity) {
+  if (entity === null || entity < 0) return null;
+  const member = findComponent("scene/SceneMember");
+  if (!member || !world.isAlive(entity)) return null;
+  return world.tryGet(entity, member)?.path || null;
+}
+function describeNav(world) {
+  const nav = navState(world);
+  const cache = world.tryResource(NavCache);
+  const meshEntities = world.query({ with: [NavMesh] }).entities();
+  return {
+    recast: nav.R !== null,
+    grids: [...nav.grids.values()].map((g) => {
+      let walkable = 0;
+      if (g.grid) {
+        for (let i = 0; i < g.grid.costs.length; i++) if (g.grid.costs[i] > 0) walkable++;
+      }
+      return {
+        entity: g.entity,
+        path: scenePath(world, g.entity),
+        source: g.source,
+        size: g.grid ? [g.grid.width, g.grid.height] : null,
+        cellSize: [round(g.csx), round(g.csy)],
+        origin: [round(g.ox), round(g.oy)],
+        diagonal: DIAGONAL_MODES[g.diagonal],
+        walkableCells: walkable,
+        problem: g.problem
+      };
+    }),
+    meshes: meshEntities.map((entity) => {
+      const rt = nav.meshes.get(entity);
+      if (!rt)
+        return {
+          entity,
+          path: scenePath(world, entity),
+          problem: nav.R ? "not baked yet" : NO_RECAST
+        };
+      const walkable = [...rt.tiles.values()].filter((tile) => tile.ref);
+      return {
+        entity,
+        path: scenePath(world, entity),
+        settings: rt.settings,
+        tiles: walkable.length,
+        emptyTiles: rt.tiles.size - walkable.length,
+        polygons: rt.polygons(),
+        bounds: walkable.length > 0 ? { min: r3(rt.min), max: r3(rt.max) } : null,
+        lastBake: {
+          ms: round(rt.stats.ms, 2),
+          built: rt.stats.built,
+          fromCache: rt.stats.cached,
+          kept: rt.stats.kept,
+          removed: rt.stats.removed
+        },
+        bakes: rt.stats.bakes,
+        tilesBuilt: rt.stats.totalBuilt,
+        cacheHits: rt.stats.totalCached,
+        waitingForMeshes: rt.pending,
+        crowd: rt.crowd ? { agents: rt.crowd.getActiveAgentCount(), capacity: rt.crowdCapacity } : null,
+        problem: rt.problem
+      };
+    }),
+    sources: {
+      triangles: nav.soup.count,
+      links: nav.links.length,
+      skipped: nav.skipped.map((s) => ({ ...s, path: scenePath(world, s.entity) }))
+    },
+    cache: {
+      tiles: cache?.tiles.size ?? 0,
+      loadedFromDisk: cache?.loaded ?? 0,
+      file: cache?.fs ? cache.path : null
+    },
+    agents: [...nav.agents.values()].filter((a) => world.isAlive(a.entity) && world.has(a.entity, NavAgent)).map((a) => {
+      const agent = world.get(a.entity, NavAgent);
+      const state = world.get(a.entity, NavAgentState);
+      return {
+        entity: a.entity,
+        path: scenePath(world, a.entity),
+        on: a.nav >= 0 ? { entity: a.nav, path: scenePath(world, a.nav), kind: a.kind } : null,
+        status: state.status,
+        remaining: round(state.remaining),
+        corners: state.corners,
+        velocity: r3(state.velocity),
+        destination: agent.target === null ? r3(agent.destination) : null,
+        target: agent.target === null ? null : { entity: agent.target, path: scenePath(world, agent.target) },
+        drive: DRIVES[a.drive],
+        ...DRIVES[a.drive] !== agent.drive ? {
+          problem: `drive ${agent.drive} needs a ${agent.drive === "character" ? "CharacterController" : "Velocity"}; moving the Transform`
+        } : {},
+        route: Array.from(
+          { length: a.count },
+          (_, i) => r3(a.corners.subarray(i * 3, i * 3 + 3))
+        )
+      };
+    }),
+    statuses: AGENT_STATUSES
+  };
+}
+const navMethods = [
+  {
+    name: "nav.path",
+    description: "A path between two world points on the NavGrid or NavMesh containing `from` (or `nav`): status (complete, partial: ends at the closest reachable point, none), corners, and length. Errors nav/no-navmesh and nav/out-of-bounds say why there is none.",
+    params: defineSchema("nav/PathParams", {
+      from: t.vec3({ required: true }),
+      to: t.vec3({ required: true }),
+      nav: t.entity({ description: "The NavGrid or NavMesh entity (default: the one at from)." }),
+      areas: t.json({ description: 'Area costs for this query: { "1": 10 } (0 excludes).' })
+    }),
+    handler: ({ world }, p) => {
+      const path = findPath(world, p.from, p.to, {
+        nav: p.nav ?? null,
+        areas: p.areas ?? void 0
+      });
+      return {
+        status: path.status,
+        length: round(path.length),
+        corners: Array.from(
+          { length: path.count },
+          (_, i) => r3(path.corners.subarray(i * 3, i * 3 + 3))
+        ),
+        nav: path.nav,
+        navPath: scenePath(world, path.nav)
+      };
+    }
+  },
+  {
+    name: "nav.describe",
+    description: "Navigation state: every NavGrid (source, size, cell size, walkable cells, problem), NavMesh (tiles, polygons, bounds, last bake: ms, tiles built by Recast, from cache, kept; totals, meshes still loading), the triangles and off-mesh links baked from, the tile cache, and every NavAgent (status, remaining distance, velocity, destination or target, drive, route corners).",
+    params: defineSchema("nav/DescribeParams", {}),
+    handler: ({ world }) => describeNav(world)
+  },
+  {
+    name: "nav.bake",
+    description: "Rebakes every NavMesh now and reports tiles built by Recast and loaded from the cache; with save (default) writes the tiles to .shard/cache/nav so the next load skips Recast. force rebuilds every tile.",
+    params: defineSchema("nav/BakeParams", {
+      save: t.bool({ default: true, description: "Write the tile cache to disk." }),
+      force: t.bool({ description: "Ignore cached and current tiles: Recast rebuilds all." })
+    }),
+    handler: async ({ world }, p) => {
+      const nav = navState(world);
+      const cache = world.initResource(NavCache);
+      if (p.force) {
+        for (const rt of nav.meshes.values()) {
+          for (const tile of rt.tiles.values()) cache.tiles.delete(tile.key);
+          for (const tile of [...rt.tiles.values()]) rt.removeTile(tile.tx, tile.ty);
+        }
+      }
+      nav.dirty = true;
+      updateNavigation(world, 0);
+      const saved = p.save === false ? 0 : await saveNavCache(world, liveTileKeys(nav));
+      return {
+        meshes: [...nav.meshes.values()].map((rt) => ({
+          entity: rt.entity,
+          path: scenePath(world, rt.entity),
+          tiles: [...rt.tiles.values()].filter((tile) => tile.ref).length,
+          polygons: rt.polygons(),
+          built: rt.stats.built,
+          fromCache: rt.stats.cached,
+          kept: rt.stats.kept,
+          ms: round(rt.stats.ms, 2),
+          problem: rt.problem
+        })),
+        saved: saved > 0 ? { file: cache.path, bytes: saved } : null
+      };
+    }
+  }
+];
+export {
+  describeNav,
+  navMethods
+};

package/dist/navmesh.d.ts

@@ -0,0 +1,101 @@
+import type { Entity } from '@aethervtt/shard-core';
+import { TriangleSoup } from './geometry.js';
+import { type BakeSettings, type Recast } from './recast.js';
+type RNavMesh = InstanceType<Recast['NavMesh']>;
+type RQuery = InstanceType<Recast['NavMeshQuery']>;
+type RCrowd = InstanceType<Recast['Crowd']>;
+type RFilter = InstanceType<Recast['QueryFilter']>;
+/** A tile the navmesh holds: where, the key of the geometry that built it, and its Detour ref. */
+export interface TileEntry {
+    tx: number;
+    ty: number;
+    key: string;
+    /** Detour tile data, or null for a tile with nothing walkable (not added). */
+    bytes: Uint8Array | null;
+    ref: number;
+    polys: number;
+}
+export declare const packTile: (tx: number, ty: number) => number;
+export interface BakeStats {
+    /** Tiles Recast built in the last bake. */
+    built: number;
+    /** Tiles loaded from the cache in the last bake. */
+    cached: number;
+    /** Tiles kept because their geometry didn't change. */
+    kept: number;
+    /** Tiles dropped (their geometry went away). */
+    removed: number;
+    /** Milliseconds the last bake took. */
+    ms: number;
+    /** Bakes since the navmesh appeared. */
+    bakes: number;
+    /** Tiles Recast built since the navmesh appeared. */
+    totalBuilt: number;
+    /** Tiles taken from the cache since the navmesh appeared. */
+    totalCached: number;
+}
+/**
+ * A NavMesh entity's Detour navmesh: tiles on a world-aligned grid (tile (0, 0) starts at the
+ * origin, so moving geometry never shifts other tiles), a query object, and the crowd its agents
+ * walk in.
+ */
+export declare class NavMeshRuntime {
+    readonly R: Recast;
+    readonly entity: Entity;
+    readonly settings: BakeSettings;
+    readonly tileWorld: number;
+    navMesh: RNavMesh;
+    query: RQuery;
+    filter: RFilter;
+    crowd: RCrowd | null;
+    crowdCapacity: number;
+    crowdRadius: number;
+    maxTiles: number;
+    readonly tiles: Map<number, TileEntry>;
+    /** Bumps whenever tiles change: agents and cached paths revalidate. */
+    version: number;
+    readonly stats: BakeStats;
+    /** Bounds of the walkable tiles, for "which navmesh contains this point". */
+    readonly min: Float64Array<ArrayBuffer>;
+    readonly max: Float64Array<ArrayBuffer>;
+    /** Why the last bake didn't finish, if it didn't. */
+    problem: string | null;
+    /** Source meshes still loading; the bake reruns when they arrive. */
+    pending: number;
+    /** Bakes and queries happen in this entity's local space (null: world space). */
+    frame: Entity | null;
+    /** World → navmesh space and back (affine 3×4, row by row). */
+    readonly toLocal: Float64Array<ArrayBuffer>;
+    readonly toWorld: Float64Array<ArrayBuffer>;
+    /** Framed bakes: the world soup moved into navmesh space, with its hash lanes. */
+    readonly local: TriangleSoup;
+    localHashes: Uint32Array<ArrayBuffer>;
+    /** A world point into navmesh space (identity without a frame). */
+    pointIn(x: number, y: number, z: number, out: {
+        [i: number]: number;
+    }): void;
+    /** A navmesh-space point into world space. */
+    pointOut(x: number, y: number, z: number, out: {
+        [i: number]: number;
+    }): void;
+    /** A navmesh-space direction into world space. */
+    vectorOut(x: number, y: number, z: number, out: {
+        [i: number]: number;
+    }): void;
+    constructor(R: Recast, entity: Entity, settings: BakeSettings, maxTiles?: number);
+    private createNavMesh;
+    /** Grows the tile capacity, moving every tile into a new Detour navmesh. */
+    reserve(tiles: number): boolean;
+    private add;
+    /** Puts a tile's data in (null: removes it). */
+    setTile(tx: number, ty: number, key: string, bytes: Uint8Array | null): void;
+    removeTile(tx: number, ty: number): void;
+    /** Recomputes `min`/`max` from the tiles' headers. */
+    updateBounds(): void;
+    polygons(): number;
+    /** Applies area costs (0 excludes an area) to queries and the crowd. */
+    applyAreas(areas: Record<number, number>): void;
+    destroyCrowd(): void;
+    destroy(): void;
+}
+export {};

package/dist/navmesh.js

@@ -0,0 +1,194 @@
+import { TriangleSoup } from "./geometry.js";
+import { areaFlags, voxelSettings } from "./recast.js";
+const packTile = (tx, ty) => (tx + 32768) * 65536 + (ty + 32768);
+class NavMeshRuntime {
+  R;
+  entity;
+  settings;
+  tileWorld;
+  navMesh;
+  query;
+  filter;
+  crowd = null;
+  crowdCapacity = 0;
+  crowdRadius = 0;
+  maxTiles;
+  tiles = /* @__PURE__ */ new Map();
+  /** Bumps whenever tiles change: agents and cached paths revalidate. */
+  version = 0;
+  stats = {
+    built: 0,
+    cached: 0,
+    kept: 0,
+    removed: 0,
+    ms: 0,
+    bakes: 0,
+    totalBuilt: 0,
+    totalCached: 0
+  };
+  /** Bounds of the walkable tiles, for "which navmesh contains this point". */
+  min = new Float64Array([Infinity, Infinity, Infinity]);
+  max = new Float64Array([-Infinity, -Infinity, -Infinity]);
+  /** Why the last bake didn't finish, if it didn't. */
+  problem = null;
+  /** Source meshes still loading; the bake reruns when they arrive. */
+  pending = 0;
+  /** Bakes and queries happen in this entity's local space (null: world space). */
+  frame = null;
+  /** World → navmesh space and back (affine 3×4, row by row). */
+  toLocal = new Float64Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0]);
+  toWorld = new Float64Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0]);
+  /** Framed bakes: the world soup moved into navmesh space, with its hash lanes. */
+  local = new TriangleSoup();
+  localHashes = new Uint32Array(0);
+  /** A world point into navmesh space (identity without a frame). */
+  pointIn(x, y, z, out) {
+    const m = this.toLocal;
+    out[0] = m[0] * x + m[1] * y + m[2] * z + m[3];
+    out[1] = m[4] * x + m[5] * y + m[6] * z + m[7];
+    out[2] = m[8] * x + m[9] * y + m[10] * z + m[11];
+  }
+  /** A navmesh-space point into world space. */
+  pointOut(x, y, z, out) {
+    const m = this.toWorld;
+    out[0] = m[0] * x + m[1] * y + m[2] * z + m[3];
+    out[1] = m[4] * x + m[5] * y + m[6] * z + m[7];
+    out[2] = m[8] * x + m[9] * y + m[10] * z + m[11];
+  }
+  /** A navmesh-space direction into world space. */
+  vectorOut(x, y, z, out) {
+    const m = this.toWorld;
+    out[0] = m[0] * x + m[1] * y + m[2] * z;
+    out[1] = m[4] * x + m[5] * y + m[6] * z;
+    out[2] = m[8] * x + m[9] * y + m[10] * z;
+  }
+  constructor(R, entity, settings, maxTiles = 256) {
+    this.R = R;
+    this.entity = entity;
+    this.settings = { ...settings };
+    this.tileWorld = voxelSettings(settings).tileWorld;
+    this.maxTiles = maxTiles;
+    this.navMesh = this.createNavMesh(maxTiles);
+    this.query = new R.NavMeshQuery(this.navMesh, { maxNodes: 4096 });
+    this.filter = this.query.defaultFilter;
+  }
+  createNavMesh(maxTiles) {
+    const R = this.R;
+    const tileBits = Math.min(14, Math.max(1, Math.ceil(Math.log2(maxTiles))));
+    const navMesh = new R.NavMesh();
+    navMesh.initTiled(
+      R.NavMeshParams.create({
+        orig: { x: 0, y: 0, z: 0 },
+        tileWidth: this.tileWorld,
+        tileHeight: this.tileWorld,
+        maxTiles: 1 << tileBits,
+        maxPolys: 1 << 22 - tileBits
+      })
+    );
+    return navMesh;
+  }
+  /** Grows the tile capacity, moving every tile into a new Detour navmesh. */
+  reserve(tiles) {
+    if (tiles <= this.maxTiles) return false;
+    let cap = this.maxTiles;
+    while (cap < tiles) cap *= 2;
+    const old = this.navMesh;
+    this.maxTiles = cap;
+    this.navMesh = this.createNavMesh(cap);
+    this.query.destroy();
+    this.query = new this.R.NavMeshQuery(this.navMesh, { maxNodes: 4096 });
+    this.filter = this.query.defaultFilter;
+    for (const t of this.tiles.values()) {
+      t.ref = 0;
+      if (t.bytes) this.add(t);
+    }
+    old.destroy();
+    this.destroyCrowd();
+    this.version++;
+    return true;
+  }
+  add(t) {
+    const R = this.R;
+    const data = new R.UnsignedCharArray();
+    data.copy(t.bytes);
+    const res = this.navMesh.addTile(data, R.Detour.DT_TILE_FREE_DATA, 0);
+    if (R.statusFailed(res.status)) {
+      data.destroy();
+      t.ref = 0;
+      t.polys = 0;
+      return;
+    }
+    t.ref = res.tileRef;
+    const tile = this.navMesh.getTileByRef(res.tileRef);
+    t.polys = tile ? tile.header()?.polyCount() ?? 0 : 0;
+  }
+  /** Puts a tile's data in (null: removes it). */
+  setTile(tx, ty, key, bytes) {
+    const k = packTile(tx, ty);
+    const old = this.tiles.get(k);
+    if (old?.ref) this.navMesh.removeTile(old.ref);
+    const t = { tx, ty, key, bytes, ref: 0, polys: 0 };
+    this.tiles.set(k, t);
+    if (bytes) this.add(t);
+    this.version++;
+  }
+  removeTile(tx, ty) {
+    const k = packTile(tx, ty);
+    const old = this.tiles.get(k);
+    if (!old) return;
+    if (old.ref) this.navMesh.removeTile(old.ref);
+    this.tiles.delete(k);
+    this.version++;
+  }
+  /** Recomputes `min`/`max` from the tiles' headers. */
+  updateBounds() {
+    this.min.fill(Infinity);
+    this.max.fill(-Infinity);
+    for (const t of this.tiles.values()) {
+      if (!t.ref) continue;
+      const header = this.navMesh.getTileByRef(t.ref)?.header();
+      if (!header) continue;
+      for (let i = 0; i < 3; i++) {
+        this.min[i] = Math.min(this.min[i], header.bmin(i));
+        this.max[i] = Math.max(this.max[i], header.bmax(i));
+      }
+    }
+  }
+  polygons() {
+    let n = 0;
+    for (const t of this.tiles.values()) n += t.polys;
+    return n;
+  }
+  /** Applies area costs (0 excludes an area) to queries and the crowd. */
+  applyAreas(areas) {
+    let exclude = 0;
+    const filters = [this.filter];
+    if (this.crowd) filters.push(this.crowd.getFilter(0));
+    for (const f of filters) {
+      for (let a = 0; a < 63; a++) f.setAreaCost(a, 1);
+      for (const key of Object.keys(areas)) {
+        const area = Number(key);
+        const cost = areas[area];
+        if (!(area >= 0 && area < 63)) continue;
+        if (cost <= 0) exclude |= area < 15 ? areaFlags(area) : 0;
+        else f.setAreaCost(area, cost);
+      }
+      f.includeFlags = 65535 & ~exclude;
+      f.excludeFlags = 0;
+    }
+  }
+  destroyCrowd() {
+    this.crowd?.destroy();
+    this.crowd = null;
+    this.crowdCapacity = 0;
+  }
+  destroy() {
+    this.destroyCrowd();
+    this.query.destroy();
+    this.navMesh.destroy();
+  }
+}
+export {
+  NavMeshRuntime,
+  packTile
+};

package/dist/overlay.d.ts

@@ -0,0 +1 @@
+export declare const navOverlay: import("@aethervtt/shard-render").OverlayDef;