OpenFrontIO/docs/MultiSourceAnyTargetBFS.md

# MultiSourceAnyTargetBFS (boats) — design notes

## Goal

Replace the current “guess a landing tile, then pathfind” approach with a single **multi-source, any-target** search that:

- Prefers landings **near the user click** (destination selection stays “near click”).
- Finds the **best source+target pair** in one run (no retries / staged hacks).
- Is fast enough for a hot path by doing **one search per boat launch**, not per tick.

This is the standard “virtual super-source + virtual super-target” idea:

- Imagine a `START` node connected to every source `S` with cost 0.
- Imagine every target `D` connected to an `END` node with cost 0.
- Run shortest-path from `START` to `END`.

We do not build those nodes; we seed the queue with all sources and stop when we pop a target.

## Scope / assumptions

- Boat routing runs on a **water-only graph**.
- For now, all edges are **equal cost**, so we use **BFS**.
- Optional “pretty” modes (diagonals or smoothing) must be behind a toggle so the default stays cheap.

If we later add non-uniform costs (e.g., currents, danger zones, traffic), the same API can switch to
Dijkstra/A* by supplying a cost function; BFS remains the fast-path when cost is constant.

## Inputs and outputs

### Inputs

- `sources`: candidate attacker spawn shores (or their adjacent water tiles).
- `targets`: candidate defender landing shores near click (or their adjacent water tiles).
- `neighbors(node)`: 4-neighbor (or optional 8-neighbor) adjacency function.
- `passable(node)` or `isTraversable(from,to)`: boat constraint (water-only).
- `maxNodes` / `maxRadius` / `maxSteps` (optional): guardrails for worst-case expansions.

### Output

`{ source, target, path } | PathNotFound`

- `source`: which source won.
- `target`: which target was reached first (with correct BFS semantics).
- `path`: full route (list of tiles) to persist on the unit/execution.

## Target selection (“near click”, but bounded)

Keep the “landing near click” behavior by constructing a **small target set**:

- Collect defender shore tiles around the clicked tile and/or on the defender border.
- Sort by Manhattan distance to click.
- Keep the first `K` (cap, e.g. `K=50..200`) or `min(K, floor(shoreCount * 0.05))` with a hard max.
- Preferably filter to the same connected water component as the attacker (ocean vs a specific lake),
  otherwise BFS will waste time exploring an impossible component.

This turns “any destination” into a precise, controllable set.

## Source selection (bounded)

Sources can be large (player border can be huge). For performance:

- Prefer “spawnable shore tiles” (owned + shore + valid spawn rules).
- Cap/summarize: best-by-distance-to-click, extremal tiles, plus uniform sampling.
- If we already know the boat’s actual spawn (e.g. UI precomputes), sources can be a singleton.

## Core algorithm (unweighted)

### Correct early-exit rule

When using BFS:

- Early-exit only when a target node is **dequeued** (popped), not when first discovered.
  Dequeue guarantees minimal distance.

### Multi-source seeding

Initialize BFS frontier with all sources:

- `dist[source] = 0`
- `prev[source] = -1`
- `startOf[source] = source`
- enqueue all sources

When expanding neighbors:

- if unseen, set `prev[neighbor] = node`, set `startOf[neighbor] = startOf[node]`, enqueue.

When dequeuing:

- if `node` is in `targets`, stop and reconstruct by walking `prev[]`.

### Data structures (hot-path friendly)

Avoid maps/sets in the inner loop:

- `visitedStamp: Uint32Array(numTiles)` + `stampCounter` (no clearing per query).
- `prev: Int32Array(numTiles)` (or `Int32Array` only for seen nodes using a compact list).
- `queue: Int32Array(numTiles)` with head/tail indices (ring buffer).
- `targetsStamp: Uint32Array(numTiles)` (mark target membership once per query via stamping).
- `startOf: Int32Array(numTiles)` if we need “which source won” without reconstructing first step.

Allocate these once and reuse.

## Integration points (boat launch only)

- On boat launch (intent/execution init), compute:
  1) `targets` near click
  2) `sources` (spawn candidates)
  3) `path = MultiSourceAnyTargetBFS(sources, targets)`
- Persist `path` and only advance an index in `tick()`.
- Recompute only on meaningful topology changes (rare) or if the current path is invalidated.
  Default: do not “find path… then find path…”.

## Diagonals / smoothing (optional)

Two mutually exclusive options:

1) **8-neighbor BFS** (“king moves”, Chebyshev) with **no corner cutting**:
   - allow diagonal move only if both adjacent orthogonal tiles are water.
   - still unweighted BFS (diagonal cost == orthogonal cost), so the metric becomes Chebyshev.
2) **4-neighbor BFS + smoothing pass**:
   - keep BFS cheap/correct,
   - do a short post-process that removes zigzags if there is line-of-sight over water.

Default recommendation for boats: option (1) enabled, with no-corner-cutting enabled.

## Failure modes and guardrails

- If `targets` is empty → return `PathNotFound` early.
- If `sources` is empty → return `PathNotFound` early.
- If BFS exceeds a configured budget (`maxNodes`) → return `PathNotFound` (and optionally fall back).

## What this intentionally does NOT do

- No staged “find path… then adjust/retry” heuristics.
- No per-tick pathfinding.
- No bidirectional multi-target tricks (too easy to get subtly wrong).