Pathfinding Refinement (#2878)

# Pathfinding pt. 3 ## Description: This PR introduces final change to the pathfinding - path refinement. It optimizes Line of Sight refinement by searching with for the best tile with a binary search instead of linearly. And then spends the recovered budget on better refinement of the first and last 50 tiles of the journey - the place where user is most likely to look at. Additionally this PR re-introduces magnitude check and makes the ships prefer sailing close to the coast, but not too close. ## Please complete the following: - [x] I have added screenshots for all UI updates - [x] I process any text displayed to the user through translateText() and I've added it to the en.json file - [x] I have added relevant tests to the test directory - [x] I confirm I have thoroughly tested these changes and take full responsibility for any bugs introduced ## What? | Before | After | | :--- | :--- | | <img width="1097" height="1117" alt="image" src="https://github.com/user-attachments/assets/4a0b300d-10ef-4151-b6dc-33acfb49f992" /> | <img width="1093" height="1119" alt="image" src="https://github.com/user-attachments/assets/cf81c515-c145-40f4-91e5-a4353986907b" /> | | <img width="1096" height="1129" alt="image" src="https://github.com/user-attachments/assets/21b46bce-f961-4259-88f6-fe4a66180270" /> | <img width="1098" height="1126" alt="image" src="https://github.com/user-attachments/assets/d92587d1-e6b6-4353-b4a4-1efe71bca43d" /> | ## Performance There is actually a severe performance impact of these changes. The path initial path takes almost 2x as long to generate - this is because pre processing can only do so much if the initial path is ugly. Luckily in real gameplay we only need to do this calculation once per edge, so the actual observed performance impact should be much smaller. Cache FTW. | | No Cache | Cache | | :--- | :--- | :--- | | Before | 277.04ms | 208.58ms | | After | 498.34ms | 264.27ms | ## DebugSpan Small utility, it allows any code to be easily instrumented for performance. The idea is the same as with [OTEL Spans](https://opentelemetry.io/docs/concepts/signals/traces/). Produce a span, create sub-spans, measure whatever you need. Works only when `globalThis.__DEBUG_SPAN_ENABLED__ === true`, otherwise no-op. Cool stuff, try it out: ```ts // Convenient wrapper, small performance impact return DebugSpan.wrap('add', () => a + b) // Synchronous API, basically free DebugSpan.start('work') work() DebugSpan.end() // Create sub spans DebugSpan.wrap('complex', () => { const aPlusB = DebugSpan.wrap('add', () => a + b) DebugSpan.set('additionResult', () => aPlusB) // Store data return aPlusB * c }) // Access spans, data and timing const span = DebugSpan.getLast() const compelxSpan = DebugSpan.getLast('complex') console.log(complexSpan.duration, complexSpan.data['additionResult']) ``` These are virtually free and can be enabled on-demand **in production** and available in the devtools. Under the hood devtools integration is just a wrapper around [Performance API](https://developer.mozilla.org/en-US/docs/Web/API/Performance_API). For clarity data keys not prefixed by `$` are omitted from the integration. Every key prefixed with `$` must be fully JSON serializable. <img width="977" height="799" alt="image" src="https://github.com/user-attachments/assets/b4d43506-1639-4f78-a611-30e61de12a07" />
2026-07-14 22:37:31 +00:00 · 2026-01-13 12:39:54 -08:00
parent 35b7213c5c
commit 85def73bd9
20 changed files with 963 additions and 713 deletions
@@ -0,0 +1,343 @@
+import { GameMap, TileRef } from "../../game/GameMap";
+import { PathFinder } from "../types";
+import { BucketQueue } from "./PriorityQueue";
+
+const LAND_BIT = 7;
+const MAGNITUDE_MASK = 0x1f;
+const COST_SCALE = 100;
+const BASE_COST = 1 * COST_SCALE;
+
+// Prefer magnitude 3-10 (3-10 tiles from shore)
+function getMagnitudePenalty(magnitude: number): number {
+  if (magnitude < 3) return 3 * COST_SCALE; // too close to shore
+  if (magnitude <= 10) return 0; // sweet spot
+  return 1 * COST_SCALE; // deep water, slight penalty
+}
+
+export interface BoundedAStarConfig {
+  heuristicWeight?: number;
+  maxIterations?: number;
+}
+
+export interface SearchBounds {
+  minX: number;
+  maxX: number;
+  minY: number;
+  maxY: number;
+}
+
+export class AStarWaterBounded implements PathFinder<number> {
+  private stamp = 1;
+
+  private readonly closedStamp: Uint32Array;
+  private readonly gScoreStamp: Uint32Array;
+  private readonly gScore: Uint32Array;
+  private readonly cameFrom: Int32Array;
+  private readonly queue: BucketQueue;
+  private readonly terrain: Uint8Array;
+  private readonly mapWidth: number;
+  private readonly heuristicWeight: number;
+  private readonly maxIterations: number;
+
+  constructor(
+    map: GameMap,
+    maxSearchArea: number,
+    config?: BoundedAStarConfig,
+  ) {
+    this.terrain = (map as any).terrain as Uint8Array;
+    this.mapWidth = map.width();
+    this.heuristicWeight = config?.heuristicWeight ?? 3;
+    this.maxIterations = config?.maxIterations ?? 100_000;
+
+    this.closedStamp = new Uint32Array(maxSearchArea);
+    this.gScoreStamp = new Uint32Array(maxSearchArea);
+    this.gScore = new Uint32Array(maxSearchArea);
+    this.cameFrom = new Int32Array(maxSearchArea);
+
+    const maxDim = Math.ceil(Math.sqrt(maxSearchArea));
+    // Account for scaled costs + tie-breaker headroom
+    const maxF =
+      (this.heuristicWeight + 1) * BASE_COST * maxDim * 2 + COST_SCALE * maxDim;
+    this.queue = new BucketQueue(maxF);
+  }
+
+  findPath(start: number | number[], goal: number): number[] | null {
+    const starts = Array.isArray(start) ? start : [start];
+    const goalX = goal % this.mapWidth;
+    const goalY = (goal / this.mapWidth) | 0;
+
+    let minX = goalX;
+    let maxX = goalX;
+    let minY = goalY;
+    let maxY = goalY;
+
+    for (const s of starts) {
+      const sx = s % this.mapWidth;
+      const sy = (s / this.mapWidth) | 0;
+      minX = Math.min(minX, sx);
+      maxX = Math.max(maxX, sx);
+      minY = Math.min(minY, sy);
+      maxY = Math.max(maxY, sy);
+    }
+
+    return this.searchBounded(starts as TileRef[], goal as TileRef, {
+      minX,
+      maxX,
+      minY,
+      maxY,
+    });
+  }
+
+  searchBounded(
+    start: TileRef | TileRef[],
+    goal: TileRef,
+    bounds: SearchBounds,
+  ): TileRef[] | null {
+    this.stamp++;
+    if (this.stamp > 0xffffffff) {
+      this.closedStamp.fill(0);
+      this.gScoreStamp.fill(0);
+      this.stamp = 1;
+    }
+
+    const stamp = this.stamp;
+    const mapWidth = this.mapWidth;
+    const terrain = this.terrain;
+    const closedStamp = this.closedStamp;
+    const gScoreStamp = this.gScoreStamp;
+    const gScore = this.gScore;
+    const cameFrom = this.cameFrom;
+    const queue = this.queue;
+    const weight = this.heuristicWeight;
+    const landMask = 1 << LAND_BIT;
+
+    const { minX, maxX, minY, maxY } = bounds;
+    const boundsWidth = maxX - minX + 1;
+    const goalX = goal % mapWidth;
+    const goalY = (goal / mapWidth) | 0;
+    const boundsHeight = maxY - minY + 1;
+    const numLocalNodes = boundsWidth * boundsHeight;
+
+    if (numLocalNodes > this.closedStamp.length) {
+      return null;
+    }
+
+    const toLocal = (tile: TileRef, clamp: boolean = false): number => {
+      let x = tile % mapWidth;
+      let y = (tile / mapWidth) | 0;
+      if (clamp) {
+        x = Math.max(minX, Math.min(maxX, x));
+        y = Math.max(minY, Math.min(maxY, y));
+      }
+      return (y - minY) * boundsWidth + (x - minX);
+    };
+
+    const toGlobal = (local: number): TileRef => {
+      const localX = local % boundsWidth;
+      const localY = (local / boundsWidth) | 0;
+      return ((localY + minY) * mapWidth + (localX + minX)) as TileRef;
+    };
+
+    const goalLocal = toLocal(goal, true);
+    if (goalLocal < 0 || goalLocal >= numLocalNodes) {
+      return null;
+    }
+
+    queue.clear();
+    const starts = Array.isArray(start) ? start : [start];
+
+    // For cross-product tie-breaker (prefer diagonal paths)
+    const s0 = starts[0];
+    const startX = s0 % mapWidth;
+    const startY = (s0 / mapWidth) | 0;
+    const dxGoal = goalX - startX;
+    const dyGoal = goalY - startY;
+    // Normalization factor to keep tie-breaker small (< COST_SCALE)
+    const crossNorm = Math.max(1, Math.abs(dxGoal) + Math.abs(dyGoal));
+
+    // Cross-product tie-breaker: measures deviation from start-goal line
+    const crossTieBreaker = (nx: number, ny: number): number => {
+      const dxN = nx - goalX;
+      const dyN = ny - goalY;
+      const cross = Math.abs(dxGoal * dyN - dyGoal * dxN);
+      return Math.floor((cross * (COST_SCALE - 1)) / crossNorm / crossNorm);
+    };
+
+    for (const s of starts) {
+      const startLocal = toLocal(s, true);
+      if (startLocal < 0 || startLocal >= numLocalNodes) {
+        continue;
+      }
+      gScore[startLocal] = 0;
+      gScoreStamp[startLocal] = stamp;
+      cameFrom[startLocal] = -1;
+      const sx = s % mapWidth;
+      const sy = (s / mapWidth) | 0;
+      const h =
+        weight * BASE_COST * (Math.abs(sx - goalX) + Math.abs(sy - goalY));
+      queue.push(startLocal, h);
+    }
+
+    let iterations = this.maxIterations;
+
+    while (!queue.isEmpty()) {
+      if (--iterations <= 0) {
+        return null;
+      }
+
+      const currentLocal = queue.pop();
+
+      if (closedStamp[currentLocal] === stamp) continue;
+      closedStamp[currentLocal] = stamp;
+
+      if (currentLocal === goalLocal) {
+        return this.buildPath(goalLocal, toGlobal, numLocalNodes);
+      }
+
+      const currentG = gScore[currentLocal];
+
+      // Convert to global coords for neighbor calculation
+      const current = toGlobal(currentLocal);
+      const currentX = current % mapWidth;
+      const currentY = (current / mapWidth) | 0;
+
+      if (currentY > minY) {
+        const neighbor = current - mapWidth;
+        const neighborLocal = currentLocal - boundsWidth;
+        const neighborTerrain = terrain[neighbor];
+        if (
+          closedStamp[neighborLocal] !== stamp &&
+          (neighbor === goal || (neighborTerrain & landMask) === 0)
+        ) {
+          const magnitude = neighborTerrain & MAGNITUDE_MASK;
+          const cost = BASE_COST + getMagnitudePenalty(magnitude);
+          const tentativeG = currentG + cost;
+          if (
+            gScoreStamp[neighborLocal] !== stamp ||
+            tentativeG < gScore[neighborLocal]
+          ) {
+            cameFrom[neighborLocal] = currentLocal;
+            gScore[neighborLocal] = tentativeG;
+            gScoreStamp[neighborLocal] = stamp;
+            const ny = currentY - 1;
+            const h =
+              weight *
+              BASE_COST *
+              (Math.abs(currentX - goalX) + Math.abs(ny - goalY));
+            const f = tentativeG + h + crossTieBreaker(currentX, ny);
+            queue.push(neighborLocal, f);
+          }
+        }
+      }
+
+      if (currentY < maxY) {
+        const neighbor = current + mapWidth;
+        const neighborLocal = currentLocal + boundsWidth;
+        const neighborTerrain = terrain[neighbor];
+        if (
+          closedStamp[neighborLocal] !== stamp &&
+          (neighbor === goal || (neighborTerrain & landMask) === 0)
+        ) {
+          const magnitude = neighborTerrain & MAGNITUDE_MASK;
+          const cost = BASE_COST + getMagnitudePenalty(magnitude);
+          const tentativeG = currentG + cost;
+          if (
+            gScoreStamp[neighborLocal] !== stamp ||
+            tentativeG < gScore[neighborLocal]
+          ) {
+            cameFrom[neighborLocal] = currentLocal;
+            gScore[neighborLocal] = tentativeG;
+            gScoreStamp[neighborLocal] = stamp;
+            const ny = currentY + 1;
+            const h =
+              weight *
+              BASE_COST *
+              (Math.abs(currentX - goalX) + Math.abs(ny - goalY));
+            const f = tentativeG + h + crossTieBreaker(currentX, ny);
+            queue.push(neighborLocal, f);
+          }
+        }
+      }
+
+      if (currentX > minX) {
+        const neighbor = current - 1;
+        const neighborLocal = currentLocal - 1;
+        const neighborTerrain = terrain[neighbor];
+        if (
+          closedStamp[neighborLocal] !== stamp &&
+          (neighbor === goal || (neighborTerrain & landMask) === 0)
+        ) {
+          const magnitude = neighborTerrain & MAGNITUDE_MASK;
+          const cost = BASE_COST + getMagnitudePenalty(magnitude);
+          const tentativeG = currentG + cost;
+          if (
+            gScoreStamp[neighborLocal] !== stamp ||
+            tentativeG < gScore[neighborLocal]
+          ) {
+            cameFrom[neighborLocal] = currentLocal;
+            gScore[neighborLocal] = tentativeG;
+            gScoreStamp[neighborLocal] = stamp;
+            const nx = currentX - 1;
+            const h =
+              weight *
+              BASE_COST *
+              (Math.abs(nx - goalX) + Math.abs(currentY - goalY));
+            const f = tentativeG + h + crossTieBreaker(nx, currentY);
+            queue.push(neighborLocal, f);
+          }
+        }
+      }
+
+      if (currentX < maxX) {
+        const neighbor = current + 1;
+        const neighborLocal = currentLocal + 1;
+        const neighborTerrain = terrain[neighbor];
+        if (
+          closedStamp[neighborLocal] !== stamp &&
+          (neighbor === goal || (neighborTerrain & landMask) === 0)
+        ) {
+          const magnitude = neighborTerrain & MAGNITUDE_MASK;
+          const cost = BASE_COST + getMagnitudePenalty(magnitude);
+          const tentativeG = currentG + cost;
+          if (
+            gScoreStamp[neighborLocal] !== stamp ||
+            tentativeG < gScore[neighborLocal]
+          ) {
+            cameFrom[neighborLocal] = currentLocal;
+            gScore[neighborLocal] = tentativeG;
+            gScoreStamp[neighborLocal] = stamp;
+            const nx = currentX + 1;
+            const h =
+              weight *
+              BASE_COST *
+              (Math.abs(nx - goalX) + Math.abs(currentY - goalY));
+            const f = tentativeG + h + crossTieBreaker(nx, currentY);
+            queue.push(neighborLocal, f);
+          }
+        }
+      }
+    }
+
+    return null;
+  }
+
+  private buildPath(
+    goalLocal: number,
+    toGlobal: (local: number) => TileRef,
+    maxPathLength: number,
+  ): TileRef[] {
+    const path: TileRef[] = [];
+    let current = goalLocal;
+
+    // Safety check to prevent infinite loops
+    let iterations = 0;
+    while (current !== -1 && iterations < maxPathLength) {
+      path.push(toGlobal(current));
+      current = this.cameFrom[current];
+      iterations++;
+    }
+
+    path.reverse();
+    return path;
+  }
+}