@aethervtt/shard-nav 0.0.1

package/dist/overlay.js

@@ -0,0 +1,166 @@
+import { defineOverlay } from "@aethervtt/shard-render";
+import { GlobalTransform } from "@aethervtt/shard-transform";
+import { Nav } from "./state.js";
+function areaColor(area, out) {
+  if (area === 0) {
+    out[0] = 0.2;
+    out[1] = 0.85;
+    out[2] = 0.75;
+  } else {
+    const h = area * 0.618034 % 1;
+    out[0] = 0.5 + 0.5 * Math.cos(6.2832 * h);
+    out[1] = 0.5 + 0.5 * Math.cos(6.2832 * (h - 0.333));
+    out[2] = 0.5 + 0.5 * Math.cos(6.2832 * (h - 0.667));
+  }
+  out[3] = 1;
+  return out;
+}
+const meshLines = /* @__PURE__ */ new WeakMap();
+const gridLines = /* @__PURE__ */ new WeakMap();
+function linesOf(rt) {
+  const cached = meshLines.get(rt);
+  if (cached && cached.version === rt.version) return cached;
+  const lines = [];
+  const areas = [];
+  const links = [];
+  for (const t of rt.tiles.values()) {
+    if (!t.ref) continue;
+    const tile = rt.navMesh.getTileByRef(t.ref);
+    const header = tile?.header();
+    if (!tile || !header) continue;
+    for (let p = 0; p < header.polyCount(); p++) {
+      const poly = tile.polys(p);
+      const n = poly.vertCount();
+      if (poly.getType() === 1) {
+        const a2 = poly.verts(0) * 3;
+        const b2 = poly.verts(1) * 3;
+        links.push(tile.verts(a2), tile.verts(a2 + 1), tile.verts(a2 + 2));
+        links.push(tile.verts(b2), tile.verts(b2 + 1), tile.verts(b2 + 2));
+        continue;
+      }
+      const area = poly.areaAndType() & 63;
+      for (let i = 0; i < n; i++) {
+        const a2 = poly.verts(i) * 3;
+        const b2 = poly.verts((i + 1) % n) * 3;
+        lines.push(tile.verts(a2), tile.verts(a2 + 1) + 0.05, tile.verts(a2 + 2));
+        lines.push(tile.verts(b2), tile.verts(b2 + 1) + 0.05, tile.verts(b2 + 2));
+        areas.push(area);
+      }
+    }
+  }
+  const out = {
+    version: rt.version,
+    lines: Float32Array.from(lines),
+    areas: Uint8Array.from(areas),
+    count: areas.length,
+    links: Float32Array.from(links),
+    linkCount: links.length / 6
+  };
+  meshLines.set(rt, out);
+  return out;
+}
+function gridLinesOf(g) {
+  const cached = gridLines.get(g);
+  if (cached && cached.version === g.version) return cached;
+  const grid = g.grid;
+  const w = grid.width;
+  const h = grid.height;
+  const lines = [];
+  const open = (x, y) => grid.get(x, y) > 0;
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      if (!open(x, y)) continue;
+      if (!open(x - 1, y)) lines.push(x, y, x, y + 1);
+      if (!open(x + 1, y)) lines.push(x + 1, y, x + 1, y + 1);
+      if (!open(x, y - 1)) lines.push(x, y, x + 1, y);
+      if (!open(x, y + 1)) lines.push(x, y + 1, x + 1, y + 1);
+    }
+  }
+  const out = { version: g.version, lines: Float32Array.from(lines), count: lines.length / 4 };
+  gridLines.set(g, out);
+  return out;
+}
+const color = new Float32Array(4);
+const LINK = new Float32Array([1, 0.75, 0.2, 1]);
+const GRID = new Float32Array([0.2, 0.85, 0.75, 1]);
+const PATH = new Float32Array([1, 0.95, 0.3, 1]);
+const UNREACHABLE = new Float32Array([1, 0.35, 0.3, 1]);
+const a = new Float64Array(3);
+const b = new Float64Array(3);
+const mid = new Float64Array(3);
+const MAX_SEGMENTS = 6e4;
+const navOverlay = defineOverlay({
+  name: "navmesh",
+  description: "Navigation: navmesh polygon edges colored by area, off-mesh links as arcs, NavGrid walkable-area outlines, and every NavAgent\u2019s path (yellow; red when unreachable).",
+  draw(world, g, passes) {
+    const nav = world.tryResource(Nav);
+    if (!nav) return;
+    let budget = MAX_SEGMENTS;
+    for (const rt of nav.meshes.values()) {
+      if (!passes(rt.entity)) continue;
+      const m = linesOf(rt);
+      const l = m.lines;
+      for (let i = 0; i < m.count && budget > 0; i++, budget--) {
+        const o = i * 6;
+        a[0] = l[o];
+        a[1] = l[o + 1];
+        a[2] = l[o + 2];
+        b[0] = l[o + 3];
+        b[1] = l[o + 4];
+        b[2] = l[o + 5];
+        g.line(a, b, areaColor(m.areas[i], color));
+      }
+      for (let i = 0; i < m.linkCount; i++) {
+        const o = i * 6;
+        a[0] = m.links[o];
+        a[1] = m.links[o + 1];
+        a[2] = m.links[o + 2];
+        b[0] = m.links[o + 3];
+        b[1] = m.links[o + 4];
+        b[2] = m.links[o + 5];
+        mid[0] = (a[0] + b[0]) / 2;
+        mid[1] = Math.max(a[1], b[1]) + 0.5;
+        mid[2] = (a[2] + b[2]) / 2;
+        g.line(a, mid, LINK);
+        g.line(mid, b, LINK);
+      }
+    }
+    for (const rec of nav.grids.values()) {
+      if (!rec.grid || !passes(rec.entity)) continue;
+      const gl = gridLinesOf(rec);
+      const l = gl.lines;
+      for (let i = 0; i < gl.count && budget > 0; i++, budget--) {
+        const o = i * 4;
+        a[0] = rec.ox + l[o] * rec.csx;
+        a[1] = rec.oy + l[o + 1] * rec.csy;
+        a[2] = rec.z;
+        b[0] = rec.ox + l[o + 2] * rec.csx;
+        b[1] = rec.oy + l[o + 3] * rec.csy;
+        b[2] = rec.z;
+        g.line(a, b, GRID);
+      }
+    }
+    for (const rec of nav.agents.values()) {
+      if (rec.count < 2 || !passes(rec.entity) || !world.isAlive(rec.entity)) continue;
+      if (!world.has(rec.entity, GlobalTransform)) continue;
+      const m = world.get(rec.entity, GlobalTransform).matrix;
+      const c = rec.corners;
+      const col = rec.reachable ? PATH : UNREACHABLE;
+      a[0] = m[3];
+      a[1] = m[7] + (rec.kind === "mesh" ? 0.1 : 0);
+      a[2] = m[11];
+      for (let i = Math.max(1, rec.kind === "grid" ? rec.next : 1); i < rec.count; i++) {
+        b[0] = c[i * 3];
+        b[1] = c[i * 3 + 1] + (rec.kind === "mesh" ? 0.1 : 0);
+        b[2] = c[i * 3 + 2];
+        g.line(a, b, col);
+        a[0] = b[0];
+        a[1] = b[1];
+        a[2] = b[2];
+      }
+    }
+  }
+});
+export {
+  navOverlay
+};

package/dist/plugin.d.ts

@@ -0,0 +1,11 @@
+import { type Plugin } from '@aethervtt/shard-runtime';
+/**
+ * Navigation (spec 0037): NavGrid A* for 2D, Recast navmeshes baked from NavSource geometry with
+ * off-mesh links, path queries, and NavAgents steered by Detour's crowd or grid steering.
+ */
+export declare const navPlugin: Plugin;
+/**
+ * Grids only: NavGrid, path queries on grids, and grid NavAgents, without loading the Recast
+ * WASM. NavMesh entities report `nav/no-navmesh`.
+ */
+export declare const navGridPlugin: Plugin;

package/dist/plugin.js

@@ -0,0 +1,79 @@
+import {
+  ChildOf,
+  FixedUpdate,
+  onAdd,
+  onRemove,
+  onSet,
+  PostUpdate
+} from "@aethervtt/shard-core";
+import { Collider, PhysicsSystems } from "@aethervtt/shard-physics";
+import { Mesh3d } from "@aethervtt/shard-render";
+import { definePlugin } from "@aethervtt/shard-runtime";
+import { TransformSystems } from "@aethervtt/shard-transform";
+import { dropAgent, navAgents } from "./agents.js";
+import { navBake } from "./bake.js";
+import * as cacheModule from "./cache.js";
+import { NavCache } from "./cache.js";
+import * as componentsModule from "./components.js";
+import { NavAgent, NavAreas, NavGridDatas, NavSource, OffMeshLink } from "./components.js";
+import { navMethods } from "./methods.js";
+import * as overlayModule from "./overlay.js";
+import { loadRecast } from "./recast.js";
+import * as stateModule from "./state.js";
+import { Nav } from "./state.js";
+function underSource(world, entity) {
+  for (let e = entity, depth = 0; e !== null && depth < 64; depth++) {
+    if (!world.isAlive(e)) return false;
+    if (world.has(e, NavSource)) return true;
+    e = world.tryGet(e, ChildOf)?.parent ?? null;
+  }
+  return false;
+}
+function observe(world, nav) {
+  const structural = () => {
+    nav.dirty = true;
+  };
+  const shape = ({ entity }) => {
+    if (nav.watched.has(entity) || underSource(world, entity)) nav.dirty = true;
+  };
+  for (const def of [NavSource, OffMeshLink]) {
+    world.observe(onAdd(def), structural);
+    world.observe(onRemove(def), structural);
+  }
+  for (const def of [Collider, Mesh3d, ChildOf]) {
+    world.observe(onAdd(def), shape);
+    world.observe(onRemove(def), shape);
+  }
+  world.observe(onSet(ChildOf), shape);
+  world.observe(onRemove(NavAgent), ({ entity }) => dropAgent(world, entity));
+}
+function build(app) {
+  const w = app.world;
+  const nav = w.initResource(Nav);
+  w.initResource(NavAreas);
+  w.initResource(NavCache);
+  w.initResource(NavGridDatas);
+  observe(w, nav);
+  app.addSystems(FixedUpdate, navAgents.before(PhysicsSystems));
+  app.addSystems(PostUpdate, navBake.after(TransformSystems));
+  app.addMethod(...navMethods);
+}
+const navPlugin = definePlugin({
+  name: "nav",
+  provides: [cacheModule, componentsModule, overlayModule, stateModule],
+  dependencies: ["core/transform"],
+  build,
+  async ready(app) {
+    app.world.resource(Nav).R = await loadRecast();
+  }
+});
+const navGridPlugin = definePlugin({
+  name: "nav/grid",
+  provides: [cacheModule, componentsModule, overlayModule, stateModule],
+  dependencies: ["core/transform"],
+  build
+});
+export {
+  navGridPlugin,
+  navPlugin
+};

package/dist/query.d.ts

@@ -0,0 +1,83 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+import type { NavMeshRuntime } from './navmesh.js';
+import { type GridRecord } from './state.js';
+export declare const PATH_STATUSES: readonly ['complete', 'partial', 'none'];
+export type PathStatus = (typeof PATH_STATUSES)[number];
+/** A path's corners, reused across queries: pass it as `out` and nothing allocates. */
+export interface NavPath {
+    /** x, y, z per corner, start first. */
+    corners: Float32Array;
+    count: number;
+    /** Length along the corners. */
+    length: number;
+    /** complete: reaches `to`. partial: ends at the closest reachable point. none: no path. */
+    status: PathStatus;
+    /** The NavGrid or NavMesh entity the path is on. */
+    nav: Entity | null;
+}
+export declare function createNavPath(capacity?: number): NavPath;
+export interface FindPathOptions {
+    /** Where to write the path (default: a new one). */
+    out?: NavPath;
+    /** Walk on this NavGrid or NavMesh entity instead of the one containing `from`. */
+    nav?: Entity | null;
+    /** Plan as this NavAgent: its `nav`, if set. */
+    agent?: Entity | null;
+    /** Navmesh area costs for this query only, over nav/Areas (0 excludes an area). */
+    areas?: Record<number, number>;
+}
+/** Which grid or navmesh a point is in. */
+export type NavTarget = {
+    kind: 'grid';
+    entity: Entity;
+    grid: GridRecord;
+} | {
+    kind: 'mesh';
+    entity: Entity;
+    mesh: NavMeshRuntime;
+};
+/**
+ * The grid or navmesh containing a point (grids first, then navmeshes), or undefined. `nav`
+ * picks one explicitly.
+ */
+export declare function navAt(world: World, point: ArrayLike<number>, nav?: Entity | null): NavTarget | undefined;
+/**
+ * A path from `from` to `to` (world space), as corners, on the NavGrid or NavMesh containing
+ * `from`. Grid paths are A* pulled straight; mesh paths are Detour's. A goal with no path gives
+ * a partial path to the closest reachable point. Writes into `options.out` when given.
+ */
+export declare function findPath(world: World, from: ArrayLike<number>, to: ArrayLike<number>, options?: FindPathOptions): NavPath;
+/**
+ * A path on a navmesh with every point in its own space (framed navmeshes: the frame's local
+ * space). For agents, which steer in that space.
+ */
+export declare function meshPathLocal(m: NavMeshRuntime, from: ArrayLike<number>, to: ArrayLike<number>, out: NavPath, areas?: Record<number, number>): void;
+/**
+ * The walkable point nearest to `point` on the grid or navmesh containing it, written into
+ * `out` (xyz). Returns false when nothing walkable is near.
+ */
+export declare function nearestPoint(world: World, point: ArrayLike<number>, out: {
+    [i: number]: number;
+}, options?: {
+    nav?: Entity | null;
+}): boolean;
+/** Where `navRaycast` stopped. */
+export interface NavRayHit {
+    /** 0..1 along the segment; 1: clear to `to`. */
+    t: number;
+    point: Float64Array;
+    /** Edge normal of the wall hit (xyz), zero when clear. */
+    normal: Float64Array;
+}
+export declare function createNavRayHit(): NavRayHit;
+/**
+ * Walks along the walkable surface from `from` toward `to` and stops at the first wall or
+ * blocked cell. Returns true when it hit something (`hit.t` < 1); `hit.point` is where it stopped.
+ */
+export declare function navRaycast(world: World, from: ArrayLike<number>, to: ArrayLike<number>, hit?: NavRayHit, options?: {
+    nav?: Entity | null;
+}): boolean;
+/** An entity's world position (xyz) from its GlobalTransform. */
+export declare function worldPos(world: World, e: Entity, out: {
+    [i: number]: number;
+}): void;