@driftengine/core 3.61.0

package/src/nav/navSearch.ts

@@ -0,0 +1,200 @@
+import type { NavGraph } from './navGraph.ts';
+
+/**
+ * A* over a `NavGraph`, allocating nothing per query and answering the same route every time.
+ *
+ * **Reused rather than constructed per search**, because the scratch is proportional to the graph
+ * and a world with a dozen agents re-pathing on a schedule would otherwise allocate a dozen arrays
+ * the size of the map every time somebody changed their mind. One of these per thread of control;
+ * a search is not re-entrant and says so.
+ *
+ * **The route is a function of the graph and the two endpoints, and of nothing else.** Two runs, two
+ * machines, a replay: same nodes out. That takes more than avoiding randomness — a heap pops ties in
+ * whatever order it happens to hold them, and two equally good routes through a symmetric world are
+ * exactly the case a road network produces constantly. So ties break on the node index, which is
+ * arbitrary but *stable*, and the sequence is frozen the same way the engine's RNG is.
+ *
+ * **The heuristic is straight-line distance**, which is admissible precisely because
+ * `buildNavGraph` refuses an edge cheaper than its own span. That refusal is what makes the first
+ * route this returns the cheapest one rather than merely a good one, and it is why it is a build
+ * error rather than a note.
+ */
+export class NavSearch {
+  private readonly graph: NavGraph;
+  private readonly gScore: Float64Array;
+  private readonly fScore: Float64Array;
+  private readonly cameFrom: Int32Array;
+  /** 0 unseen, 1 open, 2 closed. */
+  private readonly state: Uint8Array;
+  /**
+   * A binary heap of node indices, ordered by `fScore` then by index.
+   *
+   * **Sized by edges and not by nodes**, from an argument rather than from a measurement: a push
+   * happens at most once per directed edge — a node goes on when it is first reached and again only
+   * when an edge improves it — so an array of that length cannot overflow. A node count is *not* a
+   * bound on that, and the failure it would allow is the quiet kind: a dropped push is not a slower
+   * search, it is a node marked open that nothing will ever pop, so a route that exists comes back
+   * as none.
+   *
+   * **No test here exhibits that**, and `nav.test.ts` says so where the dense graph is: occupancy
+   * in practice sits far below either bound, so a graph that could tell the two sizings apart is
+   * larger than a suite should carry. The argument is what the sizing rests on and the guard in
+   * `push` is what stands behind the argument.
+   */
+  private readonly heap: Uint32Array;
+  private heapSize = 0;
+  /** How many nodes the last search took off the heap. Useful for a budget, and for a test. */
+  private lastExpanded = 0;
+
+  constructor(graph: NavGraph) {
+    this.graph = graph;
+    this.gScore = new Float64Array(graph.nodeCount);
+    this.fScore = new Float64Array(graph.nodeCount);
+    this.cameFrom = new Int32Array(graph.nodeCount);
+    this.state = new Uint8Array(graph.nodeCount);
+    this.heap = new Uint32Array(graph.edgeTarget.length + 1);
+  }
+
+  /** Nodes taken off the heap by the last `find`. */
+  get expanded(): number {
+    return this.lastExpanded;
+  }
+
+  /**
+   * Fill `outPath` with the node indices from `from` to `to`, and return how many there are.
+   *
+   * Zero means there is no route, which is a real answer and not an error: a road network with a
+   * bridge out is a graph with two components, and an agent that asks for the other side has to be
+   * told rather than thrown at inside a frame.
+   *
+   * A path longer than `outPath` is refused by returning zero rather than by writing a prefix,
+   * because half a route is worse than none — an agent would follow it confidently into the middle
+   * of nowhere and stop.
+   */
+  find(from: number, to: number, outPath: Uint32Array): number {
+    const { graph } = this;
+    if (from < 0 || from >= graph.nodeCount || to < 0 || to >= graph.nodeCount) return 0;
+    this.state.fill(0);
+    this.heapSize = 0;
+    this.lastExpanded = 0;
+
+    this.gScore[from] = 0;
+    this.fScore[from] = this.straightLine(from, to);
+    this.cameFrom[from] = -1;
+    this.state[from] = 1;
+    this.push(from);
+
+    while (this.heapSize > 0) {
+      const current = this.pop();
+      if (current === to) return this.unwind(from, to, outPath);
+      /* A duplicate of a node already expanded, left behind by pushing instead of decreasing a
+         key. Its cost is already final, so re-walking its edges would find nothing. */
+      if (this.state[current] === 2) continue;
+      this.state[current] = 2;
+      this.lastExpanded++;
+
+      const end = graph.edgeStart[current + 1] ?? 0;
+      for (let e = graph.edgeStart[current] ?? 0; e < end; e++) {
+        const next = graph.edgeTarget[e] ?? 0;
+        if (this.state[next] === 2) continue;
+        const tentative = (this.gScore[current] ?? 0) + (graph.edgeCost[e] ?? 0);
+        if (this.state[next] === 1 && tentative >= (this.gScore[next] ?? 0)) continue;
+        this.gScore[next] = tentative;
+        this.fScore[next] = tentative + this.straightLine(next, to);
+        this.cameFrom[next] = current;
+        /*
+         * Pushed again rather than decreased in place. A decrease-key needs every node's position
+         * in the heap maintained on every swap, which is a second array and a write per sift step
+         * for a graph where a node is rarely improved twice; the duplicate is popped later, found
+         * closed, and skipped. The heap is sized for that: a node can be open once per edge into
+         * it, and the loop below tolerates a full heap by dropping the worse copy.
+         */
+        this.state[next] = 1;
+        this.push(next);
+      }
+    }
+    return 0;
+  }
+
+  /**
+   * Straight-line distance, the heuristic.
+   *
+   * Never an overestimate, because no edge may cost less than its own span — `buildNavGraph`
+   * enforces it — so the first time the goal comes off the heap its cost is final.
+   */
+  private straightLine(a: number, b: number): number {
+    const p = this.graph.positions;
+    const dx = (p[a * 3] ?? 0) - (p[b * 3] ?? 0);
+    const dy = (p[a * 3 + 1] ?? 0) - (p[b * 3 + 1] ?? 0);
+    const dz = (p[a * 3 + 2] ?? 0) - (p[b * 3 + 2] ?? 0);
+    return Math.sqrt(dx * dx + dy * dy + dz * dz);
+  }
+
+  /** Walk `cameFrom` back from the goal, then reverse it in place. */
+  private unwind(from: number, to: number, outPath: Uint32Array): number {
+    let length = 0;
+    for (let node = to; node !== -1; node = this.cameFrom[node] ?? -1) {
+      if (length >= outPath.length) return 0;
+      outPath[length++] = node;
+      if (node === from) break;
+    }
+    for (let i = 0, j = length - 1; i < j; i++, j--) {
+      const swap = outPath[i] ?? 0;
+      outPath[i] = outPath[j] ?? 0;
+      outPath[j] = swap;
+    }
+    return length;
+  }
+
+  private better(a: number, b: number): boolean {
+    const fa = this.fScore[a] ?? 0;
+    const fb = this.fScore[b] ?? 0;
+    if (fa !== fb) return fa < fb;
+    /* The tie-break that makes a route reproducible. See the class note. */
+    return a < b;
+  }
+
+  private push(node: number): void {
+    /*
+     * Unreachable with the heap sized by edges above, and kept because the alternative to a guard
+     * here is writing past the end of the array in a frame. If it ever fires, the sizing argument
+     * is wrong and a route will be missed rather than a crash reported — which is why the sizing
+     * argument is written out where the array is declared.
+     */
+    if (this.heapSize >= this.heap.length) return;
+    let at = this.heapSize++;
+    this.heap[at] = node;
+    while (at > 0) {
+      const parent = (at - 1) >> 1;
+      if (!this.better(this.heap[at] ?? 0, this.heap[parent] ?? 0)) break;
+      const swap = this.heap[at] ?? 0;
+      this.heap[at] = this.heap[parent] ?? 0;
+      this.heap[parent] = swap;
+      at = parent;
+    }
+  }
+
+  private pop(): number {
+    const top = this.heap[0] ?? 0;
+    this.heapSize--;
+    if (this.heapSize > 0) {
+      this.heap[0] = this.heap[this.heapSize] ?? 0;
+      let at = 0;
+      for (;;) {
+        const left = at * 2 + 1;
+        const right = left + 1;
+        let best = at;
+        if (left < this.heapSize && this.better(this.heap[left] ?? 0, this.heap[best] ?? 0))
+          best = left;
+        if (right < this.heapSize && this.better(this.heap[right] ?? 0, this.heap[best] ?? 0))
+          best = right;
+        if (best === at) break;
+        const swap = this.heap[at] ?? 0;
+        this.heap[at] = this.heap[best] ?? 0;
+        this.heap[best] = swap;
+        at = best;
+      }
+    }
+    return top;
+  }
+}

package/src/physics/boxSurface.ts

@@ -0,0 +1,96 @@
+import type { GroundSurface, SurfaceHit } from './ribbonSurface.ts';
+
+/**
+ * The tops of a set of flat, axis-aligned pads, answering as a ground surface.
+ *
+ * For the parts of a route that are *platforms* rather than ribbon — a flight of
+ * steps, a run of pads with gaps between them. Those are still the route, and
+ * that is the whole reason this exists rather than letting the collision boxes
+ * carry them: a character on ordinary geometry is off the route as far as anything
+ * asking the surface is concerned, and the route is what decides top speed, what
+ * the camera leans on, and how far along the run somebody is.
+ *
+ * Deliberately flat. A pad is an AABB, its top is level, and pretending
+ * otherwise would mean inventing a normal that the collider it shares a shape
+ * with does not have.
+ */
+export interface SurfaceBox {
+  minX: number;
+  maxX: number;
+  minZ: number;
+  maxZ: number;
+  /** Height of the walkable face. */
+  topY: number;
+  /** How far along the route this pad sits, metres. */
+  distanceM: number;
+  /** Direction of travel across it, for the camera and the pose. */
+  tangentX: number;
+  tangentZ: number;
+}
+
+export class BoxSurface implements GroundSurface {
+  constructor(private readonly boxes: readonly SurfaceBox[]) {}
+
+  get count(): number {
+    return this.boxes.length;
+  }
+
+  /**
+   * The highest pad whose footprint contains the column.
+   *
+   * Highest rather than nearest, because pads never overlap in a way where the
+   * lower one is the answer — a flight of steps is monotone — and "highest"
+   * needs no reference height, which keeps this usable from a plain
+   * `GroundSurface` call.
+   *
+   * A linear scan: a day's route carries a few dozen pads, and a scan over
+   * thirty boxes inside a fixed tick costs less than the branch needed to skip
+   * it. Allocation-free either way.
+   */
+  sample(x: number, z: number, out: SurfaceHit, atY = Infinity): boolean {
+    let best: SurfaceBox | null = null;
+    for (const box of this.boxes) {
+      if (x < box.minX || x > box.maxX || z < box.minZ || z > box.maxZ) continue;
+      // Highest pad at or below the asker, so a run of pads under a flyover
+      // does not hand a character the deck above them.
+      if (box.topY > atY + 1.2) continue;
+      if (best === null || box.topY > best.topY) best = box;
+    }
+    if (best === null) return false;
+    describe(best, out);
+    return true;
+  }
+
+  /** See `GroundSurface.sampleBand`: the highest pad whose top is in the band. */
+  sampleBand(x: number, z: number, out: SurfaceHit, loY: number, hiY: number): boolean {
+    let best: SurfaceBox | null = null;
+    for (const box of this.boxes) {
+      if (x < box.minX || x > box.maxX || z < box.minZ || z > box.maxZ) continue;
+      if (box.topY < loY || box.topY >= hiY) continue;
+      if (best === null || box.topY > best.topY) best = box;
+    }
+    if (best === null) return false;
+    describe(best, out);
+    return true;
+  }
+}
+
+function describe(box: SurfaceBox, out: SurfaceHit): void {
+  out.y = box.topY;
+  out.normalX = 0;
+  out.normalY = 1;
+  // A lid is flat, so it looks exactly as it collides. See `SurfaceHit.tilt`.
+  out.tiltX = 0;
+  out.tiltY = 1;
+  out.tiltZ = 0;
+  out.normalZ = 0;
+  out.tangentX = box.tangentX;
+  out.tangentY = 0;
+  out.tangentZ = box.tangentZ;
+  out.distanceM = box.distanceM;
+  out.lateralM = 0;
+  // Half the smaller footprint axis: the honest answer to "how much room is
+  // left", which is what a caller uses it for.
+  out.halfWidthM = Math.min(box.maxX - box.minX, box.maxZ - box.minZ) * 0.5;
+  out.bankRad = 0;
+}

package/src/physics/colliderSurface.ts

@@ -0,0 +1,213 @@
+import type { Collider, ColliderSet } from '@driftengine/physics';
+import { ColliderSet as ColliderSetClass } from '@driftengine/physics';
+
+import type { GroundSurface, SurfaceHit } from './ribbonSurface.ts';
+
+/**
+ * A `ColliderSet` answering "where is the ground here?", so a solid holds a body up.
+ *
+ * **Because a collider was solid to walk into and not to stand on.** The kinematic sweep resolves a
+ * body against a collider set laterally, and `CharacterController` senses ground through
+ * `PhysicsWorld` bodies and through a `GroundSurface` — a collider set is neither, so nothing ever
+ * asked it what was under your feet. Measured before this existed: a character dropped over a
+ * `ColliderSet` slab whose top face is at 5.5 m falls to −84 m in three seconds, which is exactly
+ * what it does with no slab at all.
+ *
+ * Reported by a consumer building flyovers, who could express a sloped deck as a hull already and
+ * found that standing on one did not hold them up. The alternative available to them was to add
+ * every deck to a `PhysicsWorld` as a static body as well — the same geometry twice, in two
+ * structures that can disagree.
+ *
+ * **It is a `GroundSurface` and not a new seam, which is what makes it worth having.** Everything
+ * that stands on ground already takes one: the character controller, the raycast vehicle, the
+ * third-person camera boom, the rain field. And because `heightSurface` takes a list of surfaces,
+ * a world can be terrain *and* slabs without either knowing about the other:
+ *
+ * ```ts
+ * const ground = new CompositeSurface([
+ *   heightSurface((x, z) => terrainAt(x, z)),
+ *   colliderSurface(decks, { minY: -10, maxY: 60 }),
+ * ]);
+ * ```
+ *
+ * **What it is not.** It is not a replacement for the sweep: the sweep is what stops a body walking
+ * *into* a collider, and this is what stops it falling *through* one. A consumer wants both, and
+ * they read the same set.
+ */
+export interface ColliderSurfaceOptions {
+  /**
+   * The vertical extent to look through, metres.
+   *
+   * **Required, and guessing would be worse than asking.** A ground query is a column, and the
+   * spatial hash walks every cell in it — an unbounded column over a 4 m grid is half a million
+   * cells and a frozen frame. A consumer knows how tall their world is; the engine does not, and a
+   * default would be wrong quietly.
+   */
+  readonly minY: number;
+  readonly maxY: number;
+}
+
+/** How much a face above the asker is penalised when two are equally near. */
+const TIE_BREAK = 0.4;
+/** Below this a face is treated as vertical: a wall, which is not something to stand on. */
+const VERTICAL_EPSILON = 1e-6;
+/** The column has a width, because a query with none falls between two cells of the hash. */
+const COLUMN_EPSILON = 1e-4;
+
+export function colliderSurface(set: ColliderSet, options: ColliderSurfaceOptions): GroundSurface {
+  const { minY, maxY } = options;
+  if (!(maxY > minY)) {
+    throw new Error(
+      `colliderSurface: maxY must be above minY, got minY=${minY} maxY=${maxY}. This is the ` +
+        'vertical extent the column search walks, and an empty one finds no ground anywhere.',
+    );
+  }
+
+  /* Allocation-free: a ground query runs every tick for everything that stands on something. */
+  const found = new Int32Array(ColliderSetClass.MAX_HITS);
+  const box: Collider = { minX: 0, minY: 0, minZ: 0, maxX: 0, maxY: 0, maxZ: 0 };
+  const top = { y: 0, nx: 0, ny: 1, nz: 0 };
+
+  /**
+   * The highest surface of collider `index` in this column, or false where the column misses it.
+   *
+   * **A shaped collider is solved against its own face planes, not its box.** The box is the broad
+   * phase; treating it as the answer is what would put a body standing on thin air over the corner
+   * of every ramp, which is the same mistake the segment query documents having made. For a convex
+   * solid the vertical line at `(x, z)` enters through the downward-facing planes and leaves
+   * through the upward-facing ones, so the exit is the lowest of the upward ones and the entry is
+   * the highest of the downward ones — and the column misses the solid entirely when the exit is
+   * below the entry.
+   */
+  const columnTop = (index: number, x: number, z: number): boolean => {
+    set.bounds(index, box);
+    if (x < box.minX || x > box.maxX || z < box.minZ || z > box.maxZ) return false;
+
+    const shape = set.shapeAt(index);
+    const planes = shape?.facePlanes;
+    if (shape === undefined || planes === undefined || planes.length < 16) {
+      /* A collider that is its box: the lid is flat and its normal is up. */
+      top.y = box.maxY;
+      top.nx = 0;
+      top.ny = 1;
+      top.nz = 0;
+      return true;
+    }
+
+    let exit = Infinity;
+    let entry = -Infinity;
+    let nx = 0;
+    let ny = 1;
+    let nz = 0;
+    for (let p = 0; p < planes.length; p += 4) {
+      const pnx = planes[p] as number;
+      const pny = planes[p + 1] as number;
+      const pnz = planes[p + 2] as number;
+      const d = planes[p + 3] as number;
+      const lateral = pnx * x + pnz * z;
+      if (pny > -VERTICAL_EPSILON && pny < VERTICAL_EPSILON) {
+        /* A vertical face bounds the column rather than the height: outside it, there is no solid
+           over this point at any height. */
+        if (lateral > d) return false;
+        continue;
+      }
+      const y = (d - lateral) / pny;
+      if (pny > 0) {
+        if (y < exit) {
+          exit = y;
+          nx = pnx;
+          ny = pny;
+          nz = pnz;
+        }
+      } else if (y > entry) {
+        entry = y;
+      }
+    }
+    if (!Number.isFinite(exit) || exit < entry) return false;
+
+    /* Rounding grows the solid outward along the face normal, so the lid rises by it. `sideRadius`
+       grows a cylinder's side and not its caps, which is why only `radius` is here. */
+    top.y = exit + shape.radius;
+    top.nx = nx;
+    top.ny = ny;
+    top.nz = nz;
+    return true;
+  };
+
+  const fill = (out: SurfaceHit): void => {
+    out.y = top.y;
+    out.normalX = top.nx;
+    out.normalY = top.ny;
+    out.normalZ = top.nz;
+    /* A solid has no route, so the fields that describe one say nothing rather than something
+       invented. `tilt` follows the face, for the reason `heightSurface` gives: the surface collides
+       exactly as it looks. */
+    out.tiltX = top.nx;
+    out.tiltY = top.ny;
+    out.tiltZ = top.nz;
+    out.tangentX = 1;
+    out.tangentY = 0;
+    out.tangentZ = 0;
+    out.distanceM = 0;
+    out.lateralM = 0;
+    out.bankRad = 0;
+    out.halfWidthM = Infinity;
+  };
+
+  return {
+    /**
+     * The face nearest the asker's feet, ties broken toward the one below.
+     *
+     * The same rule `CompositeSurface` uses between its parts and `RibbonSurface` between its own
+     * passes, and for the same reason: what you are standing on is the thing under your feet, and
+     * "highest wins" teleports a body under a deck up onto it.
+     */
+    sample(x: number, z: number, out: SurfaceHit, atY = Infinity): boolean {
+      const count = set.query(
+        x - COLUMN_EPSILON,
+        minY,
+        z - COLUMN_EPSILON,
+        x + COLUMN_EPSILON,
+        maxY,
+        z + COLUMN_EPSILON,
+        found,
+      );
+      const located = Number.isFinite(atY);
+      let best = Infinity;
+      let hit = false;
+      for (let i = 0; i < count; i++) {
+        if (!columnTop(found[i] as number, x, z)) continue;
+        const score = located ? Math.abs(top.y - atY) + (top.y > atY ? TIE_BREAK : 0) : -top.y;
+        if (score >= best) continue;
+        best = score;
+        fill(out);
+        hit = true;
+      }
+      return hit;
+    },
+
+    /** See `GroundSurface.sampleBand`: the highest face in the band, and nothing outside it. */
+    sampleBand(x: number, z: number, out: SurfaceHit, loY: number, hiY: number): boolean {
+      const count = set.query(
+        x - COLUMN_EPSILON,
+        Math.max(minY, loY),
+        z - COLUMN_EPSILON,
+        x + COLUMN_EPSILON,
+        Math.min(maxY, hiY),
+        z + COLUMN_EPSILON,
+        found,
+      );
+      let bestY = -Infinity;
+      let hit = false;
+      for (let i = 0; i < count; i++) {
+        if (!columnTop(found[i] as number, x, z)) continue;
+        /* Half-open, as the interface says: a face at head height is one a body passes under. */
+        if (top.y < loY || top.y >= hiY || top.y <= bestY) continue;
+        bestY = top.y;
+        fill(out);
+        hit = true;
+      }
+      return hit;
+    },
+  };
+}

package/src/physics/compositeSurface.ts

@@ -0,0 +1,111 @@
+import { createSurfaceHit } from './ribbonSurface.ts';
+import type { GroundSurface, SurfaceHit } from './ribbonSurface.ts';
+
+/**
+ * Several surfaces answering as one.
+ *
+ * A route that forks has two floors in the same column, and a query has to pick
+ * one. It picks the **highest surface at or below the asking height**, which is
+ * the same rule a lift shaft or a flyover needs: what you are standing on is
+ * the nearest thing under your feet, not the nearest thing full stop.
+ *
+ * Falling back to the highest surface overall when nothing is below keeps a
+ * character who has dropped beneath everything from reporting no ground at all —
+ * they are still over the track, just under it, and the caller decides what
+ * that means.
+ */
+/** How much a surface above the asker is penalised when two are equally near. */
+const TIE_BREAK = 0.4;
+
+export class CompositeSurface implements GroundSurface {
+  private readonly candidate = createSurfaceHit();
+
+  constructor(private readonly surfaces: readonly GroundSurface[]) {}
+
+  /**
+   * The floors this is made of.
+   *
+   * Exposed because "two of my floors are in the same column" is a question only
+   * the parts can answer, and it is one a consumer has to be able to ask. Two
+   * walkable surfaces overlapping with millimetres between them is invisible to
+   * every gameplay check — `sample` picks one and both readings look sane — while
+   * on screen the depth buffer cannot separate them and the pair flickers against
+   * each other as the camera turns. Composed, that information is gone.
+   */
+  get parts(): readonly GroundSurface[] {
+    return this.surfaces;
+  }
+
+  /**
+   * Ask every part and keep the best answer.
+   *
+   * `atY` is what makes this correct rather than arbitrary. Without a reference
+   * height the only available rule is "highest wins", which teleports a character
+   * on the low line of a split up onto the high one the moment the two overlap.
+   */
+  sample(x: number, z: number, out: SurfaceHit, atY = Infinity): boolean {
+    // See `RibbonSurface`: without a height to measure from, the highest wins.
+    const located = Number.isFinite(atY);
+    let best = Infinity;
+    let found = false;
+
+    for (const part of this.surfaces) {
+      if (!part.sample(x, z, this.candidate, atY)) continue;
+      /*
+       * Nearest to the asker's height, ties broken toward the surface below.
+       *
+       * The same rule `RibbonSurface` uses between its own passes, and for the
+       * same reason: "highest at or below" is written for a flyover and wrong for
+       * two decks at similar heights, where it can hand a character a surface just
+       * far enough beneath their feet that they cannot snap to it and fall
+       * through ground that is directly under them.
+       */
+      const score = located
+        ? Math.abs(this.candidate.y - atY) + (this.candidate.y > atY ? TIE_BREAK : 0)
+        : -this.candidate.y;
+      if (score < best) {
+        best = score;
+        copyHit(this.candidate, out);
+        found = true;
+      }
+    }
+    return found;
+  }
+
+  /**
+   * See `GroundSurface.sampleBand`: the highest floor any part puts in the band.
+   *
+   * The one query where composing surfaces costs nothing in fidelity — a band is
+   * a filter, so asking every part and keeping the highest answer is the same
+   * answer a single surface holding all of them would give.
+   */
+  sampleBand(x: number, z: number, out: SurfaceHit, loY: number, hiY: number): boolean {
+    let bestY = -Infinity;
+    let found = false;
+    for (const part of this.surfaces) {
+      if (!part.sampleBand(x, z, this.candidate, loY, hiY)) continue;
+      if (this.candidate.y <= bestY) continue;
+      bestY = this.candidate.y;
+      copyHit(this.candidate, out);
+      found = true;
+    }
+    return found;
+  }
+}
+
+function copyHit(from: SurfaceHit, to: SurfaceHit): void {
+  to.y = from.y;
+  to.normalX = from.normalX;
+  to.normalY = from.normalY;
+  to.normalZ = from.normalZ;
+  to.tangentX = from.tangentX;
+  to.tangentY = from.tangentY;
+  to.tangentZ = from.tangentZ;
+  to.distanceM = from.distanceM;
+  to.lateralM = from.lateralM;
+  to.halfWidthM = from.halfWidthM;
+  to.bankRad = from.bankRad;
+  to.tiltX = from.tiltX;
+  to.tiltY = from.tiltY;
+  to.tiltZ = from.tiltZ;
+}