alois/OpenFrontIO
1
0
Fork 0
mirror of https://github.com/openfrontio/OpenFrontIO.git synced 2026-06-21 12:20:46 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
7d67c8079893b1aaf34a371f29fb291d1c6800ad
OpenFrontIO/tests/pathfinding/README.md
T
Arkadiusz Sygulski b090f2f624 HPA* Pathfinding (#2815) 
## Pathfinding with HPA*

Hi! The primary objective of this PR is to replace per-tile A* with
hierarchical pathfinding - HPA*. In practice, this means we create an
abstract graph on top of the actual map with far fewer points and use it
to decide on general path structure. Only then we go back to tile-level
and build path between selected waypoints. This speeds up long distance
pathfinding by over 1000x in some cases. To make the review easier, it
comes with a benchmark and visual playground.

## PREPROCESSING

H part of HPA* means "hierarchical" and requires preprocessing.

This PR includes pre-processing as part inside `new Game()` constructor.
It takes about 135ms for `giantworldmap` on my machine, which increases
the effective initialization from ~95ms to ~230ms. This time could be
reduced in different ways, which are **out of scope** for this PR.

After confirming the initialization time is bearable on low-end devices,
I argue merging this PR as-is is acceptable tradeoff. It creates small
lag at the beginning of a round but pays for itself in the first minute
of the match.

## Nerdy details

**Architecture**
- HPA*-style hierarchical pathfinding
- 32×32 sectors on minimap with gateway nodes on borders
- Gateway graph built via BFS during preprocessing
- Water component optimization skips unreachable gateway pairs
- A* on gateway graph → local A* within sectors → Bresenham path
smoothing
- Minimap upscaling identical to currently used in MiniAStar

**Key Optimizations**
- Typed arrays instead of high-level primitives
- Stamp-based visited tracking (no need to recreate buffers, O(1)
clearing)
- Optional - enabled by default - caching of tile paths between gateways
- Line of sight smoothing for the final path

## Review Focus

Play with included tools, benchmark and visualization. Pathfinding
should be safe to merge as a black box - you do not need to understand
the details. Outcomes can be tested empirically in-game. Visualize (and
share!) edge cases with included playground. Confirm the 100x speedup is
real with benchmark.

If you plan to dive into the code, I suggest the following order:
- Pathfinding abstraction in `src/core/pathfinding/`
- Pathfinding tests in `tests/core/pathfinding/`
- NavMesh in `src/core/pathfinding/navmesh/` + integration with
`Game.ts`
- Benchmark in `tests/pathfinding/benchmark/`

Do not look at playground's code, it has been created with a clanker.
The design is 100% mine and I spent way too long polishing it, but I
haven't even once edited the code manually. There is probably no
abstraction whatsoever, just do not look at the code, let it play.

## Core Changes

#### Pathfinding (`src/core/pathfinding/navmesh/`)
- HPA* + refinement -> three phased pathfinding: A* over the graph ->
naive path -> refinement
- comes with A* and BFS optimized for for specific needs

#### Pre-Processing (`src/core/pathfinding/navmesh/`)
- identify water bodies to avoid pathfinding between disconnected nodes
- create high-level graph of gateways on top of tile map

#### Abstraction (`src/core/pathfinding/`)

- common `PathFinder` interface that can return full path and also act
as state machine (`.next()`)
- adapters for both new and legacy algorithm with fallback to legacy if
navigation mesh not available

#### Benchmark (`tests/pathfinding/benchmark/`)

- `npx tsx tests/pathfinding/benchmark/run.ts` - no guesswork, numbers
- `npx tsx tests/pathfinding/benchmark/run.ts --synthetic` - 1000s of
synthetic paths
- `npx tsc tests/pathfinding/benchmark/generate.ts` - generate more as
needed, test new maps
- includes ONE synthetic scenario to avoid PR bloat, generate more
locally / later

#### Playground (`tests/pathfinding/playground/`)

- `npx tsx tests/pathfinding/playground/server.ts` - visualize paths
with both new and legacy algorithm

## Benchmarks

### Compared with legacy in default - hand picked - scenario:
```
Initialization: 95.95ms -> 227.29ms
Pathfinding: 3038.43ms -> 6.45ms
Distance: 26972 -> 26810 tiles
```

### 42,000 synthetic routes across all maps
```
Running 42 synthetic scenarios with hpa.cached adapter...

✅ synthetic/achiran                   | Init:    93.42ms | Path:    139.07ms | Dist: 1481630 tiles | Routes: 1000/1000
✅ synthetic/africa                    | Init:    87.14ms | Path:    155.08ms | Dist: 1829414 tiles | Routes: 1000/1000
✅ synthetic/asia                      | Init:    57.60ms | Path:    112.55ms | Dist: 1204082 tiles | Routes: 1000/1000
✅ synthetic/australia                 | Init:    78.18ms | Path:     77.12ms | Dist:  978375 tiles | Routes: 1000/1000
✅ synthetic/baikal                    | Init:    78.26ms | Path:    152.14ms | Dist: 1600016 tiles | Routes: 1000/1000
✅ synthetic/baikalnukewars            | Init:    81.44ms | Path:    165.90ms | Dist: 1699283 tiles | Routes: 1000/1000
✅ synthetic/betweentwoseas            | Init:    29.29ms | Path:    114.99ms | Dist: 1338075 tiles | Routes: 1000/1000
✅ synthetic/blacksea                  | Init:    30.66ms | Path:     93.14ms | Dist:  949217 tiles | Routes: 1000/1000
✅ synthetic/britannia                 | Init:    74.12ms | Path:     85.62ms | Dist:  866752 tiles | Routes: 1000/1000
✅ synthetic/deglaciatedantarctica     | Init:   105.49ms | Path:    192.93ms | Dist: 1574684 tiles | Routes: 1000/1000
✅ synthetic/didier                    | Init:    81.51ms | Path:    153.70ms | Dist: 1734876 tiles | Routes: 1000/1000
✅ synthetic/eastasia                  | Init:    49.29ms | Path:    128.63ms | Dist: 1410270 tiles | Routes: 1000/1000
✅ synthetic/europe                    | Init:    92.55ms | Path:    178.35ms | Dist: 1525216 tiles | Routes: 1000/1000
✅ synthetic/europeclassic             | Init:    33.50ms | Path:    104.40ms | Dist: 1209759 tiles | Routes: 1000/1000
✅ synthetic/falklandislands           | Init:    63.00ms | Path:    107.41ms | Dist: 1080251 tiles | Routes: 1000/1000
✅ synthetic/faroeislands              | Init:    71.91ms | Path:     49.52ms | Dist:  604613 tiles | Routes: 1000/1000
✅ synthetic/fourislands               | Init:    45.75ms | Path:     78.91ms | Dist:  937439 tiles | Routes: 1000/1000
✅ synthetic/gatewaytotheatlantic      | Init:    81.00ms | Path:    257.06ms | Dist: 2555551 tiles | Routes: 1000/1000
✅ synthetic/giantworldmap             | Init:   214.25ms | Path:    220.42ms | Dist: 1976693 tiles | Routes: 1000/1000
✅ synthetic/gulfofstlawrence          | Init:    45.16ms | Path:     96.05ms | Dist: 1014604 tiles | Routes: 1000/1000
✅ synthetic/halkidiki                 | Init:    74.68ms | Path:    149.39ms | Dist: 1546781 tiles | Routes: 1000/1000
✅ synthetic/iceland                   | Init:    58.72ms | Path:     78.16ms | Dist: 1001554 tiles | Routes: 1000/1000
✅ synthetic/italia                    | Init:    29.78ms | Path:    139.93ms | Dist: 1412024 tiles | Routes: 1000/1000
✅ synthetic/japan                     | Init:   161.07ms | Path:    118.65ms | Dist: 1154393 tiles | Routes: 1000/1000
✅ synthetic/lemnos                    | Init:    52.59ms | Path:    136.69ms | Dist: 1481101 tiles | Routes: 1000/1000
✅ synthetic/lisbon                    | Init:    49.27ms | Path:     86.53ms | Dist: 1032011 tiles | Routes: 1000/1000
✅ synthetic/manicouagan               | Init:    53.74ms | Path:    110.52ms | Dist: 1307630 tiles | Routes: 1000/1000
✅ synthetic/mars                      | Init:    29.39ms | Path:     80.55ms | Dist: 1091702 tiles | Routes: 1000/1000
✅ synthetic/mena                      | Init:    26.37ms | Path:    120.09ms | Dist: 1272751 tiles | Routes: 1000/1000
✅ synthetic/montreal                  | Init:    26.08ms | Path:    106.77ms | Dist: 1187736 tiles | Routes: 1000/1000
✅ synthetic/newyorkcity               | Init:    56.60ms | Path:    181.19ms | Dist: 1753875 tiles | Routes: 1000/1000
✅ synthetic/northamerica              | Init:    96.29ms | Path:    123.02ms | Dist: 1217221 tiles | Routes: 1000/1000
✅ synthetic/oceania                   | Init:    52.81ms | Path:     51.96ms | Dist:  482373 tiles | Routes: 1000/1000
✅ synthetic/pangaea                   | Init:    21.29ms | Path:     56.58ms | Dist:  716189 tiles | Routes: 1000/1000
✅ synthetic/pluto                     | Init:    53.89ms | Path:    141.62ms | Dist: 1304362 tiles | Routes: 1000/1000
✅ synthetic/southamerica              | Init:    85.19ms | Path:    123.03ms | Dist: 1301403 tiles | Routes: 1000/1000
✅ synthetic/straitofgibraltar         | Init:    76.68ms | Path:    108.30ms | Dist: 1304592 tiles | Routes: 1000/1000
✅ synthetic/straitofhormuz            | Init:    38.97ms | Path:     67.78ms | Dist:  754920 tiles | Routes: 1000/1000
✅ synthetic/surrounded                | Init:    95.35ms | Path:     90.18ms | Dist: 1017142 tiles | Routes: 1000/1000
✅ synthetic/svalmel                   | Init:    60.58ms | Path:    104.75ms | Dist: 1235501 tiles | Routes: 1000/1000
✅ synthetic/twolakes                  | Init:    62.05ms | Path:     94.54ms | Dist: 1140807 tiles | Routes: 1000/1000
✅ synthetic/world                     | Init:    41.43ms | Path:     93.42ms | Dist:  873406 tiles | Routes: 1000/1000

Completed 42 scenarios
Total Initialization Time: 2796.32ms
Total Pathfinding Time: 5026.64ms
Total Distance: 53160274 tiles
```

## Playground

**That's the fun part**. Watch NavMesh running circles around legacy
`PathFinder.Mini` in real time. Debug inner workings, test edge cases,
share URLs for debugging.


https://github.com/user-attachments/assets/34e2e3f5-fbc1-4b1f-917d-820766e98d5d

## Discord Tag
`moleole`
2026-01-08 13:34:18 -08:00

4.3 KiB
Raw Blame History

Pathfinding Tests

This directory contains benchmarking tools, scenario generators, and an interactive playground for testing and optimizing pathfinding algorithms in OpenFrontIO.

TLDR

npx tsx tests/pathfinding/benchmark/run.ts --synthetic --all
npx tsx tests/pathfinding/playground/server.ts

Directory Structure

tests/pathfinding/
├── benchmark.ts          # Benchmarking tool
├── scenarios/            # Scenarios for benchmarks
│   ├── default.ts        # Hand-picked scenario
│   └── synthetic/        # Auto-generated synthetic scenarios
└── playground/           # Interactive web-based visualization

Available algorithms

  • NavSat - future implementation - NavigationSatellite (HPA*)
  • PF.Mini - current implementation - PathFinder.Mini (A*)

Benchmarking

Running a Single Scenario

# Run default scenario with default adapter (NavSat)
npx tsx tests/pathfinding/benchmark/run.ts

# Run specific scenario
npx tsx tests/pathfinding/benchmark/run.ts default

# Run with specific adapter
npx tsx tests/pathfinding/benchmark/run.ts default legacy

Running Synthetic Scenarios

Synthetic scenarios are auto-generated from maps with random port selections and routes.

# Run single synthetic scenario
npx tsx tests/pathfinding/benchmark/run.ts --synthetic iceland

# Run single synthetic scenario with specific adapter
npx tsx tests/pathfinding/benchmark/run.ts --synthetic iceland legacy

# Run ALL synthetic scenarios (comprehensive benchmark)
npx tsx tests/pathfinding/benchmark/run.ts --synthetic --all

# Run all with specific adapter
npx tsx tests/pathfinding/benchmark/run.ts --synthetic --all legacy

Benchmark Metrics

The benchmark measures three key metrics:

  1. Initialization Time - How long it takes to preprocess the map
  2. Path Distance - Total distance across all routes (quality metric)
  3. Pathfinding Time - How long it takes to compute paths (performance metric)

Example Output

================================================================================
METRIC 1: INITIALIZATION TIME
================================================================================

Initialization time: 45.32ms

================================================================================
METRIC 2: PATH DISTANCE
================================================================================

Route                                    Path Length
Miami → Boston                           346 tiles
Miami → Houston                          212 tiles
...

Total distance: 52432 tiles
Routes completed: 22 / 22

================================================================================
METRIC 3: PATHFINDING TIME
================================================================================

Route                                    Time
Miami → Boston                           2.45ms
Miami → Houston                          1.82ms
...

Total time: 156.34ms
Average time: 7.11ms
Routes benchmarked: 22 / 22

================================================================================
SUMMARY
================================================================================

Adapter: default
Scenario: default

Scores:
  Initialization: 45.32ms
  Pathfinding: 156.34ms
  Distance: 52432 tiles

Generating Scenarios

Generate Synthetic Scenarios

Synthetic scenarios are generated by:

  1. Finding all water shoreline tiles on a map
  2. Randomly selecting 200 ports
  3. Creating 1000 routes connecting nearby ports
# Generate scenario for a single map
npx tsx tests/pathfinding/benchmark/generate.ts iceland

# Generate scenarios for all maps
npx tsx tests/pathfinding/benchmark/generate.ts --all

# Force overwrite existing scenarios
npx tsx tests/pathfinding/benchmark/generate.ts iceland --force
npx tsx tests/pathfinding/benchmark/generate.ts --all --force

Interactive Playground

The playground provides a web-based UI for visualizing pathfinding results, comparing algorithms, and debugging.

Starting the Playground

# Start with path caching enabled (default)
npx tsx tests/pathfinding/playground/server.ts

# Start without path caching (to measure uncached performance)
npx tsx tests/pathfinding/playground/server.ts --no-cache

Then open http://localhost:5555 in your browser.

Reference in New Issue View Git Blame Copy Permalink