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-06-24 13:52:45 +00:00 · 2026-01-13 21:39:54 +01:00
parent 35b7213c5c
commit 85def73bd9
20 changed files with 963 additions and 713 deletions
@@ -0,0 +1,341 @@
+import { GameMap, TileRef } from "../../game/GameMap";
+import { DebugSpan } from "../../utilities/DebugSpan";
+import {
+  AStarWaterBounded,
+  SearchBounds,
+} from "../algorithms/AStar.WaterBounded";
+import { PathFinder } from "../types";
+
+const ENDPOINT_REFINEMENT_TILES = 50;
+const LOCAL_ASTAR_MAX_AREA = 100 * 100;
+const LOS_MIN_MAGNITUDE = 3;
+const MAGNITUDE_MASK = 0x1f;
+
+/**
+ * Water path smoother transformer with two passes:
+ * 1. Binary search LOS smoothing (avoids shallow water)
+ * 2. Local A* refinement on endpoints (first/last N tiles)
+ */
+export class SmoothingWaterTransformer implements PathFinder<TileRef> {
+  private readonly mapWidth: number;
+  private readonly localAStar: AStarWaterBounded;
+  private readonly terrain: Uint8Array;
+  private readonly isTraversable: (tile: TileRef) => boolean;
+
+  constructor(
+    private inner: PathFinder<TileRef>,
+    private map: GameMap,
+    isTraversable: (tile: TileRef) => boolean = (t) => map.isWater(t),
+  ) {
+    this.mapWidth = map.width();
+    this.localAStar = new AStarWaterBounded(map, LOCAL_ASTAR_MAX_AREA);
+    this.terrain = (map as any).terrain as Uint8Array;
+    this.isTraversable = isTraversable;
+  }
+
+  findPath(from: TileRef | TileRef[], to: TileRef): TileRef[] | null {
+    const path = this.inner.findPath(from, to);
+
+    return DebugSpan.wrap("smoothingTransformer", () =>
+      path ? this.smooth(path) : null,
+    );
+  }
+
+  private smooth(path: TileRef[]): TileRef[] {
+    if (path.length <= 2) {
+      return path;
+    }
+
+    // Pass 1: LOS smoothing with binary search
+    let smoothed = DebugSpan.wrap("smoother:los", () => this.losSmooth(path));
+
+    // Pass 2: Local A* refinement on endpoints
+    smoothed = DebugSpan.wrap("smoother:refine", () =>
+      this.refineEndpoints(smoothed),
+    );
+
+    return smoothed;
+  }
+
+  private losSmooth(path: TileRef[]): TileRef[] {
+    const result: TileRef[] = [path[0]];
+    let current = 0;
+
+    while (current < path.length - 1) {
+      // Binary search for farthest visible waypoint
+      let lo = current + 1;
+      let hi = path.length - 1;
+      let farthest = lo;
+
+      while (lo <= hi) {
+        const mid = (lo + hi) >>> 1;
+        if (this.canSee(path[current], path[mid])) {
+          farthest = mid;
+          lo = mid + 1;
+        } else {
+          hi = mid - 1;
+        }
+      }
+
+      // Trace the path to farthest visible point
+      if (farthest > current + 1) {
+        const trace = this.tracePath(path[current], path[farthest]);
+        if (trace) {
+          // Add all intermediate tiles except the last (will be added in next iteration or at end)
+          for (let i = 1; i < trace.length - 1; i++) {
+            result.push(trace[i]);
+          }
+        }
+      }
+
+      current = farthest;
+      if (current < path.length - 1) {
+        result.push(path[current]);
+      }
+    }
+
+    result.push(path[path.length - 1]);
+    return result;
+  }
+
+  private refineEndpoints(path: TileRef[]): TileRef[] {
+    if (path.length <= 2) {
+      return path;
+    }
+
+    const refineDist = ENDPOINT_REFINEMENT_TILES;
+    let result = path;
+
+    // Find the index where cumulative distance reaches refineDist from start
+    const startEndIdx = this.findTileAtDistance(path, 0, refineDist, true);
+
+    // Refine start segment if it's more than 2 tiles and not already optimal
+    if (startEndIdx > 1) {
+      const startSegment = this.refineSegment(path[0], path[startEndIdx]);
+
+      if (startSegment && startSegment.length > 0) {
+        result = [...startSegment.slice(0, -1), ...result.slice(startEndIdx)];
+      }
+    }
+
+    // Find the index where cumulative distance reaches refineDist from end
+    const endStartIdx = this.findTileAtDistance(
+      result,
+      result.length - 1,
+      refineDist,
+      false,
+    );
+
+    // Refine end segment if it's more than 2 tiles and not already optimal
+    // Search in reverse (from destination backwards) so path approaches target naturally
+    if (endStartIdx < result.length - 2) {
+      const endSegment = this.refineSegment(
+        result[result.length - 1],
+        result[endStartIdx],
+      );
+
+      if (endSegment && endSegment.length > 0) {
+        endSegment.reverse();
+        result = [...result.slice(0, endStartIdx), ...endSegment];
+      }
+    }
+
+    return result;
+  }
+
+  private findTileAtDistance(
+    path: TileRef[],
+    startIdx: number,
+    distance: number,
+    forward: boolean,
+  ): number {
+    let cumDist = 0;
+    let idx = startIdx;
+
+    if (forward) {
+      while (idx < path.length - 1 && cumDist < distance) {
+        cumDist += this.manhattanDist(path[idx], path[idx + 1]);
+        idx++;
+      }
+    } else {
+      while (idx > 0 && cumDist < distance) {
+        cumDist += this.manhattanDist(path[idx], path[idx - 1]);
+        idx--;
+      }
+    }
+
+    return idx;
+  }
+
+  private refineSegment(from: TileRef, to: TileRef): TileRef[] | null {
+    const x0 = this.map.x(from);
+    const y0 = this.map.y(from);
+    const x1 = this.map.x(to);
+    const y1 = this.map.y(to);
+
+    // Calculate bounds with padding
+    const padding = 10;
+    const bounds: SearchBounds = {
+      minX: Math.max(0, Math.min(x0, x1) - padding),
+      maxX: Math.min(this.map.width() - 1, Math.max(x0, x1) + padding),
+      minY: Math.max(0, Math.min(y0, y1) - padding),
+      maxY: Math.min(this.map.height() - 1, Math.max(y0, y1) + padding),
+    };
+
+    return this.localAStar.searchBounded(from, to, bounds);
+  }
+
+  private canSee(from: TileRef, to: TileRef): boolean {
+    const x0 = from % this.mapWidth;
+    const y0 = (from / this.mapWidth) | 0;
+    const x1 = to % this.mapWidth;
+    const y1 = (to / this.mapWidth) | 0;
+
+    const dx = Math.abs(x1 - x0);
+    const dy = Math.abs(y1 - y0);
+    const sx = x0 < x1 ? 1 : -1;
+    const sy = y0 < y1 ? 1 : -1;
+    let err = dx - dy;
+
+    let x = x0;
+    let y = y0;
+
+    const maxTiles = 100000;
+    let iterations = 0;
+
+    while (true) {
+      if (iterations++ > maxTiles) return false;
+
+      const tile = (y * this.mapWidth + x) as TileRef;
+      if (!this.isTraversable(tile)) return false;
+
+      // Check magnitude - avoid shallow water
+      const magnitude = this.terrain[tile] & MAGNITUDE_MASK;
+      if (magnitude < LOS_MIN_MAGNITUDE) return false;
+
+      if (x === x1 && y === y1) return true;
+
+      const e2 = 2 * err;
+      const shouldMoveX = e2 > -dy;
+      const shouldMoveY = e2 < dx;
+
+      if (shouldMoveX && shouldMoveY) {
+        // Diagonal move - check intermediate tile
+        x += sx;
+        err -= dy;
+
+        const intermediateTile = (y * this.mapWidth + x) as TileRef;
+        const intMag = this.terrain[intermediateTile] & MAGNITUDE_MASK;
+        if (
+          !this.isTraversable(intermediateTile) ||
+          intMag < LOS_MIN_MAGNITUDE
+        ) {
+          // Try alternative path
+          x -= sx;
+          err += dy;
+          y += sy;
+          err += dx;
+
+          const altTile = (y * this.mapWidth + x) as TileRef;
+          const altMag = this.terrain[altTile] & MAGNITUDE_MASK;
+          if (!this.isTraversable(altTile) || altMag < LOS_MIN_MAGNITUDE)
+            return false;
+
+          x += sx;
+          err -= dy;
+        } else {
+          y += sy;
+          err += dx;
+        }
+      } else {
+        if (shouldMoveX) {
+          x += sx;
+          err -= dy;
+        }
+        if (shouldMoveY) {
+          y += sy;
+          err += dx;
+        }
+      }
+    }
+  }
+
+  private tracePath(from: TileRef, to: TileRef): TileRef[] | null {
+    const x0 = from % this.mapWidth;
+    const y0 = (from / this.mapWidth) | 0;
+    const x1 = to % this.mapWidth;
+    const y1 = (to / this.mapWidth) | 0;
+
+    const tiles: TileRef[] = [];
+
+    const dx = Math.abs(x1 - x0);
+    const dy = Math.abs(y1 - y0);
+    const sx = x0 < x1 ? 1 : -1;
+    const sy = y0 < y1 ? 1 : -1;
+    let err = dx - dy;
+
+    let x = x0;
+    let y = y0;
+
+    const maxTiles = 100000;
+    let iterations = 0;
+
+    while (true) {
+      if (iterations++ > maxTiles) return null;
+
+      const tile = (y * this.mapWidth + x) as TileRef;
+      if (!this.isTraversable(tile)) return null;
+
+      tiles.push(tile);
+
+      if (x === x1 && y === y1) break;
+
+      const e2 = 2 * err;
+      const shouldMoveX = e2 > -dy;
+      const shouldMoveY = e2 < dx;
+
+      if (shouldMoveX && shouldMoveY) {
+        x += sx;
+        err -= dy;
+
+        const intermediateTile = (y * this.mapWidth + x) as TileRef;
+        if (!this.isTraversable(intermediateTile)) {
+          x -= sx;
+          err += dy;
+          y += sy;
+          err += dx;
+
+          const altTile = (y * this.mapWidth + x) as TileRef;
+          if (!this.isTraversable(altTile)) return null;
+          tiles.push(altTile);
+
+          x += sx;
+          err -= dy;
+        } else {
+          tiles.push(intermediateTile);
+          y += sy;
+          err += dx;
+        }
+      } else {
+        if (shouldMoveX) {
+          x += sx;
+          err -= dy;
+        }
+        if (shouldMoveY) {
+          y += sy;
+          err += dx;
+        }
+      }
+    }
+
+    return tiles;
+  }
+
+  private manhattanDist(a: TileRef, b: TileRef): number {
+    const ax = a % this.mapWidth;
+    const ay = (a / this.mapWidth) | 0;
+    const bx = b % this.mapWidth;
+    const by = (b / this.mapWidth) | 0;
+    return Math.abs(ax - bx) + Math.abs(ay - by);
+  }
+}