@driftengine/script 3.61.0

package/src/bindings/interface.ts

@@ -0,0 +1,300 @@
+import type { SpriteBatch, UiInput, UiNode } from '@driftengine/ui2d';
+import {
+  createUiInput,
+  drawUiTree,
+  layoutUiTree,
+  routeUiKey,
+  routeUiPointer,
+  setUiFocus,
+  uiNodeNamed,
+} from '@driftengine/ui2d';
+import type { CapabilityDefinition, Effect, OpaqueType } from 'driftscript';
+import { defineCapability } from 'driftscript';
+
+export const INTERFACE_MODULE = 'drift/ui';
+
+/**
+ * `drift/ui` — a retained interface tree, addressed by the names its nodes were given.
+ *
+ * **The linker has refused this module by name since the language shipped**, saying it waits on
+ * Track F. It does not any more.
+ *
+ * **`drift/2d` is the other half of this track**, and it declares `SpriteBatch` — which `draw`
+ * takes. It was uncallable when it was first written: a module's namespace was the last segment of
+ * its path, so a call would have been `2d.sprite(...)`, and `2d` is a number followed by an
+ * identifier. DriftScript 1.11.0 answered it at the import, and `sprites.ts` carries the story.
+ *
+ * ## Names rather than node values, and the reason is the type system
+ *
+ * Every capability here takes the tree and a name. The alternative — a `UiNode` opaque a script
+ * holds — needs a lookup that can fail, and the language has no optional to answer with: a
+ * `uiChild` that returned the root when a name was absent would be a silent wrong answer inside a
+ * frame loop. Names are total. `has` asks whether one exists, every reader answers a defined value
+ * for a name that does not, and a script reads the way it reads: `if ui.hovered(tree, "start")`.
+ *
+ * It also matches what a tree is for. A host builds the tree, gives its nodes names, and hands the
+ * root to a script through `uses` — the way a `Terrain` and a `NavGraph` arrive. The script does not
+ * construct interfaces; it drives one.
+ *
+ * ## The effects, and the line between two of them
+ *
+ * **A layout, a draw and a change to a node are `scene.write`** — the language's own effect for a
+ * thing that draws, and outside `DETERMINISTIC_EFFECTS` for the right reason: an interface is view
+ * state, and a `@deterministic` system has no business moving it.
+ *
+ * **Reading a laid-out box is `scene.read`** and is inside the boundary, because a rect is state
+ * the layout already produced.
+ *
+ * **But `hovered`, `pressed`, `focused` and `activated` are `input.read`**, and that is the one
+ * distinction worth stopping on. Those flags live on the tree and are read like any other field —
+ * so declaring them `scene.read` would type-check and would be a lie, because what they carry is
+ * where the pointer is. `input.read` is outside `DETERMINISTIC_EFFECTS`, so a `@deterministic`
+ * system cannot ask whether the mouse is over a button, which is exactly right and is the property
+ * the annotation exists to guarantee.
+ */
+export const INTERFACE_TYPES: readonly OpaqueType[] = [
+  {
+    module: INTERFACE_MODULE,
+    name: 'UiTree',
+    doc: 'The root of a retained interface tree. Its nodes are addressed by the names they were built with.',
+  },
+];
+
+const define = (
+  name: string,
+  params: readonly { name: string; type: string }[],
+  returns: string,
+  effects: readonly Effect[],
+  doc: string,
+): CapabilityDefinition =>
+  defineCapability({
+    module: INTERFACE_MODULE,
+    name,
+    signature: `fn(${params.map((p) => `${p.name}: ${p.type}`).join(', ')}) -> ${returns}`,
+    params: [...params],
+    returns,
+    effects: [...effects],
+    deterministic: effects.every((effect) => effect === 'scene.read'),
+    doc,
+    implementation: `${INTERFACE_MODULE}.${name}`,
+  });
+
+const NAMED = [
+  { name: 'tree', type: 'UiTree' },
+  { name: 'name', type: 'String' },
+] as const;
+
+export const INTERFACE_CAPABILITIES: readonly CapabilityDefinition[] = [
+  define(
+    'layout',
+    [
+      { name: 'tree', type: 'UiTree' },
+      { name: 'x', type: 'f32' },
+      { name: 'y', type: 'f32' },
+      { name: 'w', type: 'f32' },
+      { name: 'h', type: 'f32' },
+    ],
+    'void',
+    ['scene.write'],
+    'Lay the tree out into a box. The box is what is available: a tree sized by its contents comes to what its contents come to.',
+  ),
+  define(
+    'draw',
+    [
+      { name: 'tree', type: 'UiTree' },
+      { name: 'batch', type: 'SpriteBatch' },
+      { name: 'white', type: 'i32' },
+    ],
+    'i32',
+    ['scene.write'],
+    "Put the tree in a batch and answer how many quads that was. `white` is the sprite pass's own white slot, which is what a background is drawn on.",
+  ),
+  define(
+    'has',
+    NAMED,
+    'bool',
+    ['scene.read'],
+    'Whether the tree holds a node of this name. Every reader below answers a defined value without it, so this is for a script that wants to know rather than one that would crash.',
+  ),
+  define(
+    'left',
+    NAMED,
+    'f32',
+    ['scene.read'],
+    'Where a node ended up, along x. Zero for a name the tree does not hold.',
+  ),
+  define('top', NAMED, 'f32', ['scene.read'], 'The same, along y.'),
+  define('width', NAMED, 'f32', ['scene.read'], 'How wide a node ended up.'),
+  define('height', NAMED, 'f32', ['scene.read'], 'How tall a node ended up.'),
+  define(
+    'visible',
+    NAMED,
+    'bool',
+    ['scene.read'],
+    'Whether a node is shown. A hidden node is out of the layout and out of the hit test, not merely invisible.',
+  ),
+  define(
+    'show',
+    [...NAMED, { name: 'visible', type: 'bool' }],
+    'void',
+    ['scene.write'],
+    'Show or hide a node and everything under it.',
+  ),
+  define(
+    'setText',
+    [...NAMED, { name: 'text', type: 'String' }],
+    'void',
+    ['scene.write'],
+    "Change what a node says. What draws it is the caller's: this package draws quads, and core already draws two kinds of text.",
+  ),
+  define(
+    'tint',
+    [
+      ...NAMED,
+      { name: 'r', type: 'f32' },
+      { name: 'g', type: 'f32' },
+      { name: 'b', type: 'f32' },
+      { name: 'a', type: 'f32' },
+    ],
+    'void',
+    ['scene.write'],
+    "Change a node's background colour. A node with no background gets one.",
+  ),
+  define('hovered', NAMED, 'bool', ['input.read'], 'Whether the pointer is over a node.'),
+  define(
+    'pressed',
+    NAMED,
+    'bool',
+    ['input.read'],
+    'Whether the pointer went down on a node and has not come up.',
+  ),
+  define('focused', NAMED, 'bool', ['input.read'], 'Whether a node has the keyboard.'),
+  /*
+   * **`point` answers whether anything was activated and `activated` asks which**, rather than one
+   * call returning a name. The language has no optional to answer a miss with, and a two-call shape
+   * is what `drift/behavior`'s `doing` already uses for the same reason: ask by the name you have.
+   */
+  define(
+    'point',
+    [
+      { name: 'tree', type: 'UiTree' },
+      { name: 'x', type: 'f32' },
+      { name: 'y', type: 'f32' },
+      { name: 'down', type: 'bool' },
+    ],
+    'bool',
+    ['input.read', 'scene.write'],
+    'Route the pointer, and answer whether this call activated anything. An activation is a press and a release on the same node, so somebody who pressed the wrong button can slide off it.',
+  ),
+  define(
+    'activated',
+    NAMED,
+    'bool',
+    ['input.read'],
+    'Whether the last `point` activated this node. Read it in the same step that called `point`; the next one clears it.',
+  ),
+  define(
+    'key',
+    [
+      { name: 'tree', type: 'UiTree' },
+      { name: 'key', type: 'String' },
+      { name: 'shift', type: 'bool' },
+    ],
+    'bool',
+    ['input.read', 'scene.write'],
+    'Route a key, and answer whether it activated what has focus. Tab moves focus, Enter and space activate, and everything else is reported unhandled so the caller can have it.',
+  ),
+  define(
+    'focus',
+    NAMED,
+    'void',
+    ['scene.write'],
+    'Give a node the keyboard. A name the tree does not hold focuses nothing.',
+  ),
+];
+
+/**
+ * **The router's state is kept here, per tree, which is the shape `drift/navigation` set.**
+ *
+ * A `UiInput` is hover, press and focus between one call and the next, and a script has nowhere to
+ * put one — the same position a script routing an agent was in before `navigation.path` started
+ * keeping a route per agent. So the host keeps one per tree, in a map keyed weakly so a tree going
+ * away takes its router with it.
+ *
+ * **No services**, for the reason `drift/terrain` gives: every capability takes the tree it acts on,
+ * so this is registered unconditionally and a script that never receives one never calls it.
+ */
+export function interfaceImplementation(): Record<string, unknown> {
+  const routers = new WeakMap<UiNode, UiInput>();
+  /* What the last `point` or `key` activated, so `activated` can be asked by name. */
+  const activations = new WeakMap<UiNode, UiNode | null>();
+
+  const routerOf = (tree: UiNode): UiInput => {
+    let input = routers.get(tree);
+    if (input === undefined) {
+      input = createUiInput();
+      routers.set(tree, input);
+    }
+    return input;
+  };
+
+  const nodeOf = (tree: UiNode, name: string): UiNode | null => uiNodeNamed(tree, name);
+
+  return {
+    layout: (tree: UiNode, x: number, y: number, w: number, h: number) => {
+      layoutUiTree(tree, x, y, w, h);
+    },
+    draw: (tree: UiNode, batch: SpriteBatch, white: number) => drawUiTree(batch, tree, white, null),
+    has: (tree: UiNode, name: string) => nodeOf(tree, name) !== null,
+    left: (tree: UiNode, name: string) => nodeOf(tree, name)?.rect.x ?? 0,
+    top: (tree: UiNode, name: string) => nodeOf(tree, name)?.rect.y ?? 0,
+    width: (tree: UiNode, name: string) => nodeOf(tree, name)?.rect.w ?? 0,
+    height: (tree: UiNode, name: string) => nodeOf(tree, name)?.rect.h ?? 0,
+    visible: (tree: UiNode, name: string) => {
+      const node = nodeOf(tree, name);
+      return node !== null && !node.hidden;
+    },
+    show: (tree: UiNode, name: string, visible: boolean) => {
+      const node = nodeOf(tree, name);
+      if (node !== null) node.hidden = !visible;
+    },
+    setText: (tree: UiNode, name: string, text: string) => {
+      const node = nodeOf(tree, name);
+      if (node !== null) node.text = text;
+    },
+    tint: (tree: UiNode, name: string, r: number, g: number, b: number, a: number) => {
+      const node = nodeOf(tree, name);
+      if (node === null) return;
+      /* A node with no background gets one, which is the only allocation in this module and
+         happens once per node rather than per frame. */
+      if (node.background === null) node.background = new Float32Array(4);
+      node.background[0] = r;
+      node.background[1] = g;
+      node.background[2] = b;
+      node.background[3] = a;
+    },
+    hovered: (tree: UiNode, name: string) => nodeOf(tree, name)?.hovered === true,
+    pressed: (tree: UiNode, name: string) => nodeOf(tree, name)?.pressed === true,
+    focused: (tree: UiNode, name: string) => {
+      const node = nodeOf(tree, name);
+      return node !== null && routerOf(tree).focused === node;
+    },
+    point: (tree: UiNode, x: number, y: number, down: boolean) => {
+      const hit = routeUiPointer(routerOf(tree), tree, x, y, down);
+      activations.set(tree, hit);
+      return hit !== null;
+    },
+    activated: (tree: UiNode, name: string) => {
+      const node = nodeOf(tree, name);
+      return node !== null && activations.get(tree) === node;
+    },
+    key: (tree: UiNode, key: string, shift: boolean) => {
+      const hit = routeUiKey(routerOf(tree), tree, key, shift);
+      activations.set(tree, hit);
+      return hit !== null;
+    },
+    focus: (tree: UiNode, name: string) => {
+      setUiFocus(routerOf(tree), nodeOf(tree, name));
+    },
+  };
+}

package/src/bindings/navigation.ts

@@ -0,0 +1,367 @@
+import { NavPath, NavSearch, createNavSteer, nearestNavNode } from '@driftengine/core';
+import type { NavGraph, NavSteer } from '@driftengine/core';
+import { type Entity, entityGeneration, entityIndex } from '@driftengine/entities';
+import type { CapabilityDefinition, OpaqueType } from 'driftscript';
+import { defineCapability } from 'driftscript';
+
+export const NAVIGATION_MODULE = 'drift/navigation';
+
+/**
+ * `drift/navigation` — a graph, a route over it, and a point to steer at.
+ *
+ * **The linker has refused this module by name since the language shipped**, and the reason given
+ * was that nothing here paths. That was true and it was never a blocker: it was the row. A consumer
+ * reported what its absence costs them — twelve agents that walk straight at whatever they are
+ * going to and wedge against a building on the way, about once every two minutes of play — and
+ * noted that they already extract a road graph from their world, which is the half of the work that
+ * is usually the awkward half.
+ *
+ * **A graph and not a mesh**, and the header of `navGraph.ts` argues that where the decision is:
+ * these consumers arrive with a network already, and open ground crossed by two nodes is crossed in
+ * a straight line.
+ *
+ * **`navigation.read` is a deterministic effect**, which the language decided before this existed
+ * and this has to keep true: a route is a function of the graph and its two endpoints and of
+ * nothing else, ties included. `navSearch.ts` is where that is held. A `@deterministic` system may
+ * therefore path, which is the point — deciding where to walk is exactly the kind of thing that
+ * belongs inside the fixed step.
+ */
+export const NAVIGATION_TYPES: readonly OpaqueType[] = [
+  {
+    module: NAVIGATION_MODULE,
+    name: 'NavGraph',
+    doc: 'A network of places and the ways between them.',
+  },
+  {
+    module: NAVIGATION_MODULE,
+    name: 'NavPath',
+    doc: 'A route being walked, and how far along it the walker is. Ask it where to steer.',
+  },
+];
+
+const define = (
+  name: string,
+  params: readonly { name: string; type: string }[],
+  returns: string,
+  effects: readonly string[],
+  doc: string,
+  deterministic = true,
+  allocates = false,
+): CapabilityDefinition =>
+  defineCapability({
+    module: NAVIGATION_MODULE,
+    name,
+    signature: `fn(${params.map((p) => `${p.name}: ${p.type}`).join(', ')}) -> ${returns}`,
+    params: [...params],
+    returns,
+    ...(allocates ? { allocates: true } : {}),
+    effects: effects as CapabilityDefinition['effects'],
+    /*
+     * **Writing a route is deterministic too, as of DriftScript 1.12.0**, and this paragraph used
+     * to say the opposite. `navigation.read` was in `DETERMINISTIC_EFFECTS` and `navigation.write`
+     * was not, so a `@deterministic` system could steer along a route and could not compute one —
+     * an agent re-pathing inside the fixed step, because a bridge dropped or because it was pushed
+     * off the network, had to path from an ordinary system and hand the result in.
+     *
+     * **It reversed on exactly the argument this comment named**, which is the whole reason the
+     * condition was written down rather than the limitation merely stated: a route is a function of
+     * the graph and two endpoints, `navSearch.ts` breaks ties on the node index so two runs agree,
+     * and the `NavPath` written into is simulation state rather than a host's. The language's own
+     * deferral said the track that builds an effect is the one that can answer for its replay
+     * behaviour; this track shipped, so it answered.
+     *
+     * Every capability here is deterministic now, so the parameter keeps its default and the three
+     * writers stopped passing `false`.
+     */
+    deterministic,
+    doc,
+    implementation: `${NAVIGATION_MODULE}.${name}`,
+  });
+
+export const NAVIGATION_CAPABILITIES: readonly CapabilityDefinition[] = [
+  define(
+    'nearest',
+    [
+      { name: 'graph', type: 'NavGraph' },
+      { name: 'x', type: 'float' },
+      { name: 'y', type: 'float' },
+      { name: 'z', type: 'float' },
+    ],
+    'i32',
+    ['navigation.read'],
+    'The node nearest a place, or -1 where the graph has none. How an agent gets onto the network.',
+  ),
+  define(
+    'nearestWithin',
+    [
+      { name: 'graph', type: 'NavGraph' },
+      { name: 'x', type: 'float' },
+      { name: 'y', type: 'float' },
+      { name: 'z', type: 'float' },
+      { name: 'maxDistance', type: 'float' },
+    ],
+    'i32',
+    ['navigation.read'],
+    'The nearest node within a distance, or -1. Use it so an agent that has walked off the network is not snapped to the far side of the map.',
+  ),
+  /*
+   * **`route` takes places and not node indices**, which is the whole difference between a binding
+   * a script author can use and one they have to learn a data model for first. Getting onto a graph
+   * is `nearest` twice, and a script that had to write that would write it identically every time
+   * and get the out-of-reach case wrong once.
+   */
+  define(
+    'route',
+    [
+      { name: 'path', type: 'NavPath' },
+      { name: 'graph', type: 'NavGraph' },
+      { name: 'fromX', type: 'float' },
+      { name: 'fromY', type: 'float' },
+      { name: 'fromZ', type: 'float' },
+      { name: 'toX', type: 'float' },
+      { name: 'toY', type: 'float' },
+      { name: 'toZ', type: 'float' },
+    ],
+    'bool',
+    ['navigation.write'],
+    'Path from one place to another, storing the route. False where there is no way through, which is an answer and not a failure.',
+  ),
+  define(
+    'routeBetween',
+    [
+      { name: 'path', type: 'NavPath' },
+      { name: 'graph', type: 'NavGraph' },
+      { name: 'from', type: 'i32' },
+      { name: 'to', type: 'i32' },
+    ],
+    'bool',
+    ['navigation.write'],
+    'The same, between two nodes you already have. For a consumer with their own spatial index.',
+  ),
+  /*
+   * **A route per agent, because a script had nowhere to keep one.**
+   *
+   * Every capability above takes a `NavPath` and nothing here made one, so a consumer kept a path
+   * per agent in TypeScript and called a script function once per agent per step — which is the
+   * report DriftScript 1.8.0's `uses` clause answers half of. `uses` hands a system the *graph*, one
+   * per world; a route is one per walker, and a resource is one per type, so the other half has to
+   * arrive as a value a script can ask for by entity. This is it, and with it the loop over agents
+   * goes back into the `system` where it can be reloaded.
+   *
+   * **Kept per entity *index*, with the generation beside it.** A map keyed by the handle would grow
+   * for the life of the world — every agent that ever pathed, long after it was destroyed, with no
+   * moment at which anything could know to drop one. An index is bounded by the world's ceiling, and
+   * a reused index arriving with a different generation is a different agent, so the route is
+   * cleared rather than inherited. That is the failure worth naming: without the check a freshly
+   * spawned walker would set off along the route of whatever died in its slot.
+   *
+   * **It allocates the first time it is asked about an agent** and never again, which `allocates`
+   * says so a `@hot` function is told. There is no way around it — a route is a buffer — and the
+   * alternative, making a script pass its own, is the thing this exists to remove.
+   */
+  define(
+    'path',
+    [{ name: 'agent', type: 'Entity' }],
+    'NavPath',
+    ['navigation.read'],
+    "The route this agent is following, kept by the host between steps. Empty until something routes it, and empty again if the agent's handle is reused.",
+    true,
+    true,
+  ),
+  define(
+    'clear',
+    [{ name: 'path', type: 'NavPath' }],
+    'void',
+    ['navigation.write'],
+    'Forget the route. The walker is then arrived, wherever it is.',
+  ),
+  define(
+    'following',
+    [{ name: 'path', type: 'NavPath' }],
+    'bool',
+    ['navigation.read'],
+    'Whether there is a route to follow.',
+  ),
+  /*
+   * **The steer is read back through four accessors**, which is the shape `input.axisX` and
+   * `animation.hitX` already have and the reason is the same: the language has no way to return a
+   * record by value into a caller's own storage, and an opaque handle for a three-float answer
+   * would be a lifetime a script author has to think about to read a direction.
+   *
+   * The implementation answers all four from one computation — see `navigationImplementation`,
+   * where the reason it can is that the arguments say what the answer depends on.
+   */
+  define(
+    'steerX',
+    [
+      { name: 'path', type: 'NavPath' },
+      { name: 'x', type: 'float' },
+      { name: 'y', type: 'float' },
+      { name: 'z', type: 'float' },
+    ],
+    'float',
+    ['navigation.read'],
+    'Where a walker at this place should aim, along x. A point ahead on the path rather than the next node, so corners are cut smoothly instead of snapped at.',
+  ),
+  define(
+    'steerY',
+    [
+      { name: 'path', type: 'NavPath' },
+      { name: 'x', type: 'float' },
+      { name: 'y', type: 'float' },
+      { name: 'z', type: 'float' },
+    ],
+    'float',
+    ['navigation.read'],
+    'The same aim point, along y.',
+  ),
+  define(
+    'steerZ',
+    [
+      { name: 'path', type: 'NavPath' },
+      { name: 'x', type: 'float' },
+      { name: 'y', type: 'float' },
+      { name: 'z', type: 'float' },
+    ],
+    'float',
+    ['navigation.read'],
+    'The same aim point, along z.',
+  ),
+  define(
+    'remaining',
+    [
+      { name: 'path', type: 'NavPath' },
+      { name: 'x', type: 'float' },
+      { name: 'y', type: 'float' },
+      { name: 'z', type: 'float' },
+    ],
+    'float',
+    ['navigation.read'],
+    'How far is left, following the path rather than as the crow flies.',
+  ),
+  define(
+    'arrived',
+    [
+      { name: 'path', type: 'NavPath' },
+      { name: 'x', type: 'float' },
+      { name: 'y', type: 'float' },
+      { name: 'z', type: 'float' },
+    ],
+    'bool',
+    ['navigation.read'],
+    'Whether the walker is there. True with no route at all, so one check covers both.',
+  ),
+];
+
+/** What a consumer hands the host so scripts can path over their world. */
+export interface NavigationServices {
+  /** The network. One graph; a consumer with several composes them into one before handing it over. */
+  readonly graph: NavGraph;
+  /** A search over that graph, reused across every agent. */
+  readonly search: NavSearch;
+  /** How many nodes a route may have. Longer routes are refused rather than truncated. */
+  readonly maxRouteNodes?: number;
+}
+
+export function navigationImplementation(services: NavigationServices): Record<string, unknown> {
+  const buffer = new Uint32Array(services.maxRouteNodes ?? 256);
+  const steer: NavSteer = createNavSteer();
+  /*
+   * The last place a steer was computed for, so `steerX`, `steerY`, `steerZ`, `remaining` and
+   * `arrived` at one position cost one walk of the path rather than five. Correct rather than
+   * merely fast: the answer is a function of the path and the place, and the path cannot change
+   * between two reads inside a script's own statement.
+   */
+  let cachedPath: NavPath | null = null;
+  let cachedX = NaN;
+  let cachedY = NaN;
+  let cachedZ = NaN;
+
+  /*
+   * One route per agent, by entity **index**, with the generation beside it.
+   *
+   * Two sparse arrays rather than a `Map` keyed by the handle: a map grows for the life of the
+   * world, one entry per agent that ever pathed, and nothing is in a position to know when to drop
+   * one. An index is bounded by the world's ceiling. The generation is what makes a reused index
+   * safe — a slot arriving with a different one is a different agent, and its route is cleared
+   * rather than inherited, which would otherwise send a freshly spawned walker off along the route
+   * of whatever died in its place.
+   */
+  const routes: (NavPath | undefined)[] = [];
+  const owners: number[] = [];
+
+  const at = (path: NavPath, x: number, y: number, z: number): NavSteer => {
+    if (path !== cachedPath || x !== cachedX || y !== cachedY || z !== cachedZ) {
+      path.steer(x, y, z, steer);
+      cachedPath = path;
+      cachedX = x;
+      cachedY = y;
+      cachedZ = z;
+    }
+    return steer;
+  };
+  /** Any write to a path invalidates the cache, since the answer depends on the route. */
+  const invalidate = (): void => {
+    cachedPath = null;
+  };
+
+  return {
+    path(agent: Entity): NavPath {
+      const index = entityIndex(agent);
+      const generation = entityGeneration(agent);
+      let route = routes[index];
+      if (route === undefined) {
+        route = new NavPath(services.graph, services.maxRouteNodes ?? 256);
+        routes[index] = route;
+      } else if (owners[index] !== generation) {
+        /* The slot was somebody else's. Clearing rather than replacing keeps the allocation this
+           agent is about to need and leaves nothing of the last one's route. */
+        route.clear();
+        invalidate();
+      }
+      owners[index] = generation;
+      return route;
+    },
+    nearest: (graph: NavGraph, x: number, y: number, z: number) => nearestNavNode(graph, x, y, z),
+    nearestWithin: (graph: NavGraph, x: number, y: number, z: number, maxDistance: number) =>
+      nearestNavNode(graph, x, y, z, maxDistance),
+    route(
+      path: NavPath,
+      graph: NavGraph,
+      fromX: number,
+      fromY: number,
+      fromZ: number,
+      toX: number,
+      toY: number,
+      toZ: number,
+    ): boolean {
+      invalidate();
+      const from = nearestNavNode(graph, fromX, fromY, fromZ);
+      const to = nearestNavNode(graph, toX, toY, toZ);
+      if (from < 0 || to < 0) {
+        path.clear();
+        return false;
+      }
+      const count = services.search.find(from, to, buffer);
+      path.set(buffer, count);
+      return count > 1;
+    },
+    routeBetween(path: NavPath, graph: NavGraph, from: number, to: number): boolean {
+      invalidate();
+      void graph;
+      const count = services.search.find(from, to, buffer);
+      path.set(buffer, count);
+      return count > 1;
+    },
+    clear(path: NavPath): void {
+      invalidate();
+      path.clear();
+    },
+    following: (path: NavPath) => path.active,
+    steerX: (path: NavPath, x: number, y: number, z: number) => at(path, x, y, z).x,
+    steerY: (path: NavPath, x: number, y: number, z: number) => at(path, x, y, z).y,
+    steerZ: (path: NavPath, x: number, y: number, z: number) => at(path, x, y, z).z,
+    remaining: (path: NavPath, x: number, y: number, z: number) => at(path, x, y, z).remainingM,
+    arrived: (path: NavPath, x: number, y: number, z: number) => at(path, x, y, z).arrived,
+  };
+}