Files
Arkadiusz Sygulski 0e3ced3bfa Pathfinding Refactor pt. 2 (#2866)
## Playtest

https://pf-pt-2.openfront.dev/

## Pathfinding Refactor pt. 2

<img width="1536" height="1024" alt="image"
src="https://github.com/user-attachments/assets/9477958e-54b7-4c83-b317-ba789e809e9e"
/>


This is a follow-up to a previous PR introducing pathfinding changes.
This time, it introduces a complete refactor of `pathfinding` directory
and breakdown into composable pieces.

### Unified PathFinder interface

`PathFinder<T>` and `SteppingPathFinder<T>` are introduced to unify
**all** pathfinding across the application. First one exposes complete
path, while stepping variant allows the callee to iterate over the path
by calling `.next`. All pathfinders share this one common interface,
which makes them easy to use in any scenario -
`PathFinding.Water(game).search(from, to)`.

`SteppingPathFinder<T>` extends `PathFinder<T>` with an ability to
iterate over the path. It handles caching, storing current index and
invalidation. This allows the units to not care about the inner workings
of the pathfinder and just call `pf.next(current, target)` and receive
instructions on what to do next.

### Common entry point

All pathfinders are now exposed from common `PathFinding` entrypoint:

- `PathFinding.Water`
- `PathFinding.Rail`
- `PathFinding.Stations`
- `PathFinding.Rail`

Additional entry point is introduced for pathfinders which need to work
both in the worker, but also on the frontend, which lacks `Game`
interface. Currently only `UniversalPathFinding.Parabola` is available.

### Spatial Query

New module has been introduced close to `pathfinding` - `SpatialQuery`.
It aims to resolve any questions game may have about finding tiles
meeting criteria. Currently `SpatialQuery.closestShore(player, target)`
and `SpatialQuery.closestShoreByWater(player, target)` are available -
they help answering questions about naval invasion: "What is the best
landing location from user's click?" and "Which our tile should be used
to launch the transport ship?". Under the hood they use very similar
mechanics to pathfinding, so it felt right to put them close by.

### Modular architecture

Pathfinders now support transformers: `MiniMapTransformer`,
`ShoreCoercingTransformer`, `ComponentCheckTransformer`,
`SmoothingTransformer`. Transformers functions like a middleware in the
pathfinding chain. They wrap around the pathfinder and provide
additional functionality. This allows the pathfinder to focus on
actually finding the path instead of doing unrelated things.

Example chain for simple (A*) water pathfinding:
```ts
static WaterSimple(game: Game): SteppingPathFinder<TileRef> {
  const miniMap = game.miniMap();
  const pf = new AStarWater(miniMap);

  return PathFinderBuilder.create(pf)
    .wrap((pf) => new ShoreCoercingTransformer(pf, miniMap))
    .wrap((pf) => new MiniMapTransformer(pf, game.map(), miniMap))
    .buildWithStepper(tileStepperConfig(game));
}
```

The Pathfinder - here `AStarWater` - does not care about the conversion
between minimap and main map tiles. It also does not care if the source
or destination is a land tile. The transformers take care of that. The
pathfinder gets a set of valid coordinates and produces the path -
that's it.

Modular approach makes working on a particular set of utilities much
easier - for example map upscaling is handled consistently across all
pathfinders. Additionally, the pathfinders are not tied to the
particular map resolution used. Pass them a different map and they will
work the same.

### Algorithms

Algorithms used are neatly organized inside
`src/core/pathfinding/algorithms`. They are prefixed with the algorithm
name and suffixed with the use case. File without suffix exposes generic
version ready to traverse any graph with adapters. Specialized versions
either use an adapter or inline logic when performance is critical -
using adapters leads to 20-30% performance loss.

The directory includes `A*` and `BFS` but also other useful utils, such
as `AbstractGraph` used to generate... an abstract graph on top of the
tile map and `ConnectedComponents` helping to identify whether two tiles
are connected by a path without actually computing the path.

### Playground

The playground have been updated with new algorithms, including tweaked
very greedy `A*`.

<img width="2175" height="1424" alt="image"
src="https://github.com/user-attachments/assets/1f833651-0024-4299-bf86-882f5368358c"
/>

### Tests

Yeah, there are some, a little too many if I say so myself. But there
are no useless tests. I had to ensure refactored code works somehow
reliably. This PR comes with trust me bro guarantee, but I would
appreciate someone confirming **naval invasions, nukes (esp. MIRV) and
warships**.

### Discord
`moleole`

GL & HF
2026-01-11 20:11:14 -08:00

180 lines
4.3 KiB
TypeScript

// Minimal test maps for pathfinding unit tests
import {
Difficulty,
Game,
GameMapSize,
GameMapType,
GameMode,
GameType,
} from "../../../src/core/game/Game";
import { createGame as createGameImpl } from "../../../src/core/game/GameImpl";
import { GameMapImpl } from "../../../src/core/game/GameMap";
import { UserSettings } from "../../../src/core/game/UserSettings";
import { TestConfig } from "../../util/TestConfig";
import { TestServerConfig } from "../../util/TestServerConfig";
export const W = "W"; // Water
export const L = "L"; // Land
// Terrain encoding
const WATER_BIT = 0x20;
const LAND_BIT = 0x80;
const SHORELINE_BIT = 6;
export type TestMapData = {
width: number;
height: number;
grid: string[];
};
// Compute shoreline bit for tiles adjacent to opposite terrain
function computeShoreline(
terrain: Uint8Array,
width: number,
height: number,
): void {
for (let y = 0; y < height; y++) {
for (let x = 0; x < width; x++) {
const idx = y * width + x;
const isLand = (terrain[idx] & LAND_BIT) !== 0;
const neighbors = [
[x - 1, y],
[x + 1, y],
[x, y - 1],
[x, y + 1],
];
for (const [nx, ny] of neighbors) {
if (nx < 0 || nx >= width || ny < 0 || ny >= height) continue;
const neighborIsLand = (terrain[ny * width + nx] & LAND_BIT) !== 0;
if (isLand !== neighborIsLand) {
terrain[idx] |= 1 << SHORELINE_BIT;
break;
}
}
}
}
}
// 5x5 simple island
export function createIslandMap(): TestMapData {
// prettier-ignore
const grid = [
W, W, W, W, W,
W, L, L, L, W,
W, L, L, L, W,
W, L, L, L, W,
W, W, W, W, W,
];
return { width: 5, height: 5, grid };
}
// Create Game from test map data (computes shoreline bits)
export function createGame(data: TestMapData): Game {
const { width, height, grid } = data;
// Convert string grid to terrain bytes
const terrain = new Uint8Array(width * height);
let numLand = 0;
for (let i = 0; i < grid.length; i++) {
if (grid[i] === L) {
terrain[i] = LAND_BIT;
numLand++;
} else {
terrain[i] = WATER_BIT;
}
}
computeShoreline(terrain, width, height);
const gameMap = new GameMapImpl(width, height, terrain, numLand);
// Create miniMap (2x2→1, water if ANY water)
const miniWidth = Math.ceil(width / 2);
const miniHeight = Math.ceil(height / 2);
const miniTerrain = new Uint8Array(miniWidth * miniHeight);
let miniNumLand = 0;
for (let my = 0; my < miniHeight; my++) {
for (let mx = 0; mx < miniWidth; mx++) {
const mIdx = my * miniWidth + mx;
let hasWater = false;
for (let dy = 0; dy < 2; dy++) {
for (let dx = 0; dx < 2; dx++) {
const x = mx * 2 + dx;
const y = my * 2 + dy;
if (x < width && y < height && !(terrain[y * width + x] & LAND_BIT)) {
hasWater = true;
}
}
}
if (hasWater) {
miniTerrain[mIdx] = WATER_BIT;
} else {
miniTerrain[mIdx] = LAND_BIT;
miniNumLand++;
}
}
}
computeShoreline(miniTerrain, miniWidth, miniHeight);
const miniGameMap = new GameMapImpl(
miniWidth,
miniHeight,
miniTerrain,
miniNumLand,
);
const serverConfig = new TestServerConfig();
const gameConfig = {
gameMap: GameMapType.Asia,
gameMapSize: GameMapSize.Normal,
gameMode: GameMode.FFA,
gameType: GameType.Singleplayer,
difficulty: Difficulty.Medium,
disableNations: false,
donateGold: false,
donateTroops: false,
bots: 0,
infiniteGold: false,
infiniteTroops: false,
instantBuild: false,
disableNavMesh: false,
randomSpawn: false,
};
const config = new TestConfig(
serverConfig,
gameConfig,
new UserSettings(),
false,
);
return createGameImpl([], [], gameMap, miniGameMap, config);
}
// Create GameMapImpl from test map data (for map-only tests)
export function createGameMap(data: TestMapData): GameMapImpl {
const { width, height, grid } = data;
const terrain = new Uint8Array(width * height);
let numLand = 0;
for (let i = 0; i < grid.length; i++) {
if (grid[i] === L) {
terrain[i] = LAND_BIT;
numLand++;
} else {
terrain[i] = WATER_BIT;
}
}
computeShoreline(terrain, width, height);
return new GameMapImpl(width, height, terrain, numLand);
}