# Navigation

When you give a group an order, two systems work together: **long-range routing** finds the
way around walls toward the destination, and **local steering** (avoidance + the formation)
handles the last few metres and agent-to-agent spacing. This page is about the long-range
part - the **pathfinding backend**, chosen with the **Navigation → Mode** property.

## The two backends

=== Flow Field
**Per-goal flow field.** For each destination the simulation builds one **flow field**: a
grid where every cell stores the direction to step next toward the goal (a Dijkstra
expansion from the goal, around walls). Every agent heading to that goal just **samples the
field** at its cell - so a thousand units sharing one order share **one** field.

**Best for:** large groups moving to a shared destination - the classic RTS "select army,
right-click" case. Cost is per *goal*, not per *agent*.

![Flow field debug overlay](../assets/concepts/nav-flowfield.png)
===

=== Spatial A\*
**Per-agent grid A\*** with spatial pruning and a cached route per agent. Each agent gets its
own path of waypoints to follow, recomputed only when needed.

**Best for:** units that need individually distinct routes, or scenarios with many small,
separate orders rather than a few big ones.

![Spatial A* paths debug overlay](../assets/concepts/nav-astar.png)
===

::: tip
Default is **Flow Field**. It is the cheaper, smoother choice for the RTS group-movement
case and what most projects should keep.
:::

## Tuning

| Property | What it does |
|---|---|
| **Mode** (`PathfindingMode`) | `None`, `Flow Field`, or `Spatial A*`. `None` skips routing - agents steer straight at their slot, ignoring walls. |
| **Tile Size** (`PathTileSize`) | World units per routing cell. Smaller = finer paths through tight gaps, but more cells to compute. |
| **Smooth Flow** (`bSmoothFlow`) | *Flow Field only.* Gradient flow (continuous heading) vs nearest-of-8-directions. On = smoother diagonal movement. |

`Near Wall Cost` (under [Walls](../get_started/04-wall_generation.md#tuning-how-the-crowd-treats-walls))
also affects routing: it biases paths away from hugging walls.

## How a move order flows through the system

```
SetAgentsTarget(members, point)
        │
        ▼
  Formation: lay out one slot per member behind the point
        │
        ▼
  Navigation: build/sample the route to the shared goal   ◄── Flow Field or Spatial A*
        │
        ▼
  Avoidance + steering: walk each agent to its slot,
  flowing around walls, each other, and settled units
        │
        ▼
  Settle: agent reaches its slot → OnAgentsReachedGoal
```

## Performance

- **Flow field builds are budgeted** - only a couple of new fields are built per tick, so a
  burst of orders can't stall a frame; the rest build over the next ticks.
- Flow fields are **cached and reused** while agents keep heading to the same goal. The cache
  grows with the world region the crowd spans; you can read its size with
  `GetFlowFieldCount()` / `GetFlowFieldBytes()` for diagnostics.
- A single cross-map order still pays for its whole field in one build. **Time-sliced builds**
  are on the roadmap.

::: warning
Routing operates on a **single 2D plane**. Multi-floor / overlapping-geometry maps are not
supported in 1.0 - see [Limitations](./07-limitations.md).
:::