@aethervtt/shard-nav 0.0.1

package/dist/state.d.ts

@@ -0,0 +1,119 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+import type { TileLayer } from '@aethervtt/shard-sprite';
+import type { GridSource } from './components.js';
+import { TriangleSoup } from './geometry.js';
+import { GridSearch, type NavGridData } from './grid.js';
+import type { NavMeshRuntime } from './navmesh.js';
+import type { OffMeshLinkParams, Recast } from './recast.js';
+/** A NavGrid entity's effective grid: its cells and where they sit in the world. */
+export interface GridRecord {
+    entity: Entity;
+    source: GridSource;
+    /** The cells. Built from the tilemap or colliders, or the data asset itself. */
+    grid: NavGridData | null;
+    /** World XY of cell (0, 0)'s lower-left corner, and cell size. */
+    ox: number;
+    oy: number;
+    csx: number;
+    csy: number;
+    /** The entity's world z: grid corners get it. */
+    z: number;
+    diagonal: number;
+    /** Why the grid is empty, if it is. */
+    problem: string | null;
+    /** The component's fields when last built, to rebuild on edits. */
+    stamp: string;
+    /** tilemap: the layer and how far into its edit log the grid has read. */
+    layer: TileLayer | null;
+    editBase: number;
+    editCursor: number;
+    tilemapVersion: number;
+    /** tilemap: tile number → blocks (1). Empty: every non-empty tile blocks. */
+    blocking: Uint8Array | null;
+    /** colliders: physics collider count and tick when last rasterized. */
+    colliderStamp: string;
+    /** Bumps when cells change, so agents on the grid repath. */
+    version: number;
+    /** The grid's `version` last seen (data grids change underneath). */
+    seen: number;
+}
+/** A NavAgent's runtime side: its path, crowd slot, and repath bookkeeping. */
+export interface AgentRecord {
+    entity: Entity;
+    /** The NavGrid or NavMesh entity it walks on, or -1. */
+    nav: Entity;
+    kind: 'grid' | 'mesh' | 'none';
+    /** Crowd agent index on a mesh, or -1. */
+    crowdIndex: number;
+    /** Corners of the current path (xyz), and how many; grid agents walk them. */
+    corners: Float32Array;
+    count: number;
+    /** Next corner to walk to (grid agents). */
+    next: number;
+    /** Where the current path goes. */
+    goal: Float64Array;
+    /** Navigation version the path was made on. */
+    navVersion: number;
+    sinceRepath: number;
+    /** The path reaches the goal (false: partial, heading for the closest point). */
+    reachable: boolean;
+    /** Last status sent, for events on changes. */
+    status: number;
+    /** The NavAgent tick the path was made for: writing NavAgent repaths. */
+    agentTick: number;
+    /** The drive actually used (character without a CharacterController drives the transform). */
+    drive: number;
+    /** On a framed navmesh: steering happens in its space, from this position (set each step). */
+    framed: boolean;
+    lpos: Float64Array;
+    /**
+     * Crossing an off-mesh link: where it started (x, z), the link's near and far surface
+     * heights and far end (x, z), how high the entity sits above the surface (a character's capsule
+     * center), and the height of the jump arc.
+     */
+    link: {
+        active: boolean;
+        lift: number;
+        x0: number;
+        z0: number;
+        y0: number;
+        x1: number;
+        z1: number;
+        y1: number;
+        arc: number;
+    };
+}
+export declare class NavState {
+    /** Recast and Detour, once loaded (the nav plugin loads them; nav/grid doesn't). */
+    R: Recast | null;
+    readonly grids: Map<number, GridRecord>;
+    readonly meshes: Map<number, NavMeshRuntime>;
+    readonly agents: Map<number, AgentRecord>;
+    /** `grids` and `meshes` as arrays, for per-frame loops (Map iteration allocates). */
+    gridList: GridRecord[];
+    meshList: NavMeshRuntime[];
+    readonly search: GridSearch;
+    readonly soup: TriangleSoup;
+    links: OffMeshLinkParams[];
+    /** Entities whose changes rebake navmeshes: sources, their descendants, and link ends. */
+    readonly watched: Set<number>;
+    /** `watched` as an array, for the per-frame change check. */
+    watchedList: Entity[];
+    /** Two 32-bit hash lanes per soup triangle, combined into tile keys. */
+    triHashes: Uint32Array<ArrayBuffer>;
+    /** Something structural changed (a source added or removed): gather and bake. */
+    dirty: boolean;
+    /** Signature of the nav/Areas costs last applied (NaN: none yet). */
+    areas: number;
+    /** Colliders: count and tick of the last change seen (grids rasterized from them rebuild). */
+    colliderCount: number;
+    colliderTick: number;
+    /** Source entities skipped by the last gather, with why. */
+    skipped: {
+        entity: Entity;
+        reason: string;
+    }[];
+}
+export declare const Nav: import("@aethervtt/shard-core").ResourceDef<NavState>;
+/** The navigation state, or `nav/not-ready` without a nav plugin. */
+export declare function navState(world: World): NavState;

package/dist/state.js

@@ -0,0 +1,49 @@
+import { defineResource, ShardError } from "@aethervtt/shard-core";
+import { TriangleSoup } from "./geometry.js";
+import { GridSearch } from "./grid.js";
+class NavState {
+  /** Recast and Detour, once loaded (the nav plugin loads them; nav/grid doesn't). */
+  R = null;
+  grids = /* @__PURE__ */ new Map();
+  meshes = /* @__PURE__ */ new Map();
+  agents = /* @__PURE__ */ new Map();
+  /** `grids` and `meshes` as arrays, for per-frame loops (Map iteration allocates). */
+  gridList = [];
+  meshList = [];
+  search = new GridSearch();
+  soup = new TriangleSoup();
+  links = [];
+  /** Entities whose changes rebake navmeshes: sources, their descendants, and link ends. */
+  watched = /* @__PURE__ */ new Set();
+  /** `watched` as an array, for the per-frame change check. */
+  watchedList = [];
+  /** Two 32-bit hash lanes per soup triangle, combined into tile keys. */
+  triHashes = new Uint32Array(0);
+  /** Something structural changed (a source added or removed): gather and bake. */
+  dirty = true;
+  /** Signature of the nav/Areas costs last applied (NaN: none yet). */
+  areas = Number.NaN;
+  /** Colliders: count and tick of the last change seen (grids rasterized from them rebuild). */
+  colliderCount = -1;
+  colliderTick = 0;
+  /** Source entities skipped by the last gather, with why. */
+  skipped = [];
+}
+const Nav = defineResource("nav/State", {
+  description: "Navigation runtime: grids, navmeshes, agents.",
+  init: () => new NavState()
+});
+function navState(world) {
+  const s = world.tryResource(Nav);
+  if (!s) {
+    throw new ShardError("nav/not-ready", "Navigation is not set up", {
+      hint: "Add the nav plugin (or nav/grid for grids only) and await app.init()."
+    });
+  }
+  return s;
+}
+export {
+  Nav,
+  NavState,
+  navState
+};

package/dist/test-level.d.ts

@@ -0,0 +1,19 @@
+import type { Entity, World } from '@aethervtt/shard-core';
+import { App, type Plugin } from '@aethervtt/shard-runtime';
+export declare function navApp(...plugins: Plugin[]): Promise<App>;
+export declare function frames(a: App, n: number): void;
+/** A box whose top face is at `top`, centered on (x, z). */
+export declare function slab(world: World, x: number, z: number, hx: number, hz: number, top: number, area?: number): Entity;
+/**
+ * A ramp `width` wide rising toward -z from (x, 0, z0) at `degrees`, until it reaches `rise`.
+ * Its top surface passes through (x, 0, z0).
+ */
+export declare function ramp(world: World, x: number, z0: number, degrees: number, rise: number, width?: number): Entity;
+/**
+ * Two floors: ground (40 × 40, top y = 0) and an upper floor (top y = 3) north of it, joined by a
+ * 27° ramp. A second platform (also y = 3) is only reachable by a 60° ramp.
+ */
+export declare function level(world: World): {
+    upper: [number, number, number];
+    steep: [number, number, number];
+};

package/dist/test-level.js

@@ -0,0 +1,55 @@
+import { Collider } from "@aethervtt/shard-physics";
+import { App } from "@aethervtt/shard-runtime";
+import { Transform, TransformPlugin } from "@aethervtt/shard-transform";
+import { NavSource } from "./components.js";
+import { navPlugin } from "./plugin.js";
+const DT = 1 / 60;
+async function navApp(...plugins) {
+  const a = new App().addPlugin(TransformPlugin, navPlugin, ...plugins);
+  await a.init();
+  return a;
+}
+function frames(a, n) {
+  for (let i = 0; i < n; i++) a.update(DT);
+}
+function slab(world, x, z, hx, hz, top, area = 0) {
+  return world.spawn(
+    [NavSource, { area }],
+    [Collider, { shape: "cuboid", halfExtents: [hx, 0.5, hz] }],
+    [Transform, { translation: [x, top - 0.5, z] }]
+  );
+}
+function ramp(world, x, z0, degrees, rise, width = 3) {
+  const a = degrees * Math.PI / 180;
+  const half = rise / Math.sin(a) / 2;
+  return world.spawn(
+    [NavSource, {}],
+    [Collider, { shape: "cuboid", halfExtents: [width / 2, 0.25, half] }],
+    [
+      Transform,
+      {
+        translation: [
+          x,
+          Math.sin(a) * half - Math.cos(a) * 0.25,
+          z0 - Math.cos(a) * half - Math.sin(a) * 0.25
+        ],
+        rotation: [Math.sin(a / 2), 0, 0, Math.cos(a / 2)]
+      }
+    ]
+  );
+}
+function level(world) {
+  slab(world, 0, 0, 20, 20, 0);
+  slab(world, 6, -12, 4, 4, 3);
+  ramp(world, 6, -2, 26.57, 3);
+  slab(world, -8, -12, 3, 3, 3);
+  ramp(world, -8, -6, 60, 3);
+  return { upper: [6, 3, -12], steep: [-8, 3, -12] };
+}
+export {
+  frames,
+  level,
+  navApp,
+  ramp,
+  slab
+};

package/dist/test-maze.d.ts

@@ -0,0 +1,8 @@
+import { NavGridData } from './grid.js';
+/** A small deterministic PRNG (mulberry32). */
+export declare function rng(seed: number): () => number;
+/**
+ * A size × size maze: rooms on odd cells, carved by a randomized depth-first search, then
+ * `loops` extra walls knocked out so there's more than one way through. Some corridors cost 3.
+ */
+export declare function maze(size: number, seed: number, loops?: number): NavGridData;

package/dist/test-maze.js

@@ -0,0 +1,56 @@
+import { NavGridData } from "./grid.js";
+function rng(seed) {
+  let s = seed >>> 0;
+  return () => {
+    s = s + 1831565813 >>> 0;
+    let x = s;
+    x = Math.imul(x ^ x >>> 15, x | 1);
+    x ^= x + Math.imul(x ^ x >>> 7, x | 61);
+    return ((x ^ x >>> 14) >>> 0) / 4294967296;
+  };
+}
+function maze(size, seed, loops = 0.08) {
+  const grid = new NavGridData(size, size, new Uint8Array(size * size));
+  const random = rng(seed);
+  const stack = [1 + size];
+  grid.costs[1 + size] = 1;
+  while (stack.length > 0) {
+    const cur = stack[stack.length - 1];
+    const x = cur % size;
+    const y = (cur - x) / size;
+    const options = [];
+    for (const [dx2, dy2] of [
+      [2, 0],
+      [-2, 0],
+      [0, 2],
+      [0, -2]
+    ]) {
+      const nx = x + dx2;
+      const ny = y + dy2;
+      if (nx > 0 && ny > 0 && nx < size - 1 && ny < size - 1 && grid.costs[ny * size + nx] === 0)
+        options.push(dx2, dy2);
+    }
+    if (options.length === 0) {
+      stack.pop();
+      continue;
+    }
+    const k = Math.floor(random() * (options.length / 2)) * 2;
+    const dx = options[k];
+    const dy = options[k + 1];
+    const cost = random() < 0.1 ? 3 : 1;
+    grid.costs[(y + dy / 2) * size + x + dx / 2] = cost;
+    grid.costs[(y + dy) * size + x + dx] = cost;
+    stack.push((y + dy) * size + x + dx);
+  }
+  for (let y = 1; y < size - 1; y++) {
+    for (let x = 1; x < size - 1; x++) {
+      if (grid.costs[y * size + x] === 0 && (x + y) % 2 === 1 && random() < loops)
+        grid.costs[y * size + x] = 1;
+    }
+  }
+  return grid;
+}
+export {
+  maze,
+  rng
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@aethervtt/shard-nav",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@aethervtt/shard-assets": "0.0.1",
+    "@aethervtt/shard-core": "0.0.1",
+    "@aethervtt/shard-mesh": "0.0.1",
+    "@aethervtt/shard-physics": "0.0.1",
+    "@aethervtt/shard-platform": "0.0.1",
+    "@aethervtt/shard-render": "0.0.1",
+    "@aethervtt/shard-runtime": "0.0.1",
+    "@aethervtt/shard-sprite": "0.0.1",
+    "@aethervtt/shard-transform": "0.0.1",
+    "recast-navigation": "0.43.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aethervtt/shard.git",
+    "directory": "packages/nav"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "shard": {
+    "buildSha": "d6c5c6aef4675575c878b02cf2c8f738b4190229"
+  }
+}