mirror of https://github.com/openfrontio/OpenFrontIO.git synced 2026-06-21 16:36:36 +00:00

Files

T

Arkadiusz Sygulski 85def73bd9 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-01-13 12:39:54 -08:00

benchmark

Pathfinding Refactor pt. 2 (#2866 )

2026-01-11 20:11:14 -08:00

playground

Pathfinding Refinement (#2878 )

2026-01-13 12:39:54 -08:00

README.md

HPA* Pathfinding (#2815 )

2026-01-08 13:34:18 -08:00

utils.ts

Pathfinding Refinement (#2878 )

2026-01-13 12:39:54 -08:00

README.md

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:

Initialization Time - How long it takes to preprocess the map
Path Distance - Total distance across all routes (quality metric)
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:

Finding all water shoreline tiles on a map
Randomly selecting 200 ports
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.