# Navmesh Placement Policy - Guide and Use Cases

### Overview

`NavMeshPlacementPolicy` lets each **Spawn Entry** decide how tightly it should align to the NavMesh. It removes common pitfalls like off-mesh walkers, and supports streaming/late-baked NavMeshes without stalling gameplay.

#### The three modes:

1. **Require**\
   Spawns only after a valid NavMesh point is found. If none is available, the spawner defers the request and retries (exponential backoff) up to **Max Deferred Retries**.
2. **Prefer**\
   Spawns immediately and becomes “live” visually, but navigation waits. A lightweight helper enables the `NavMeshAgent` once the NavMesh becomes available.
3. **Ignore**\
   Spawns without NavMesh constraints. Great for fliers, physics props, ambient fauna, or scripted placements.

### Key fields (per entry)

* **Search Radius** - how far from the intended position to look for a NavMesh point.
* **Area Mask** - which NavMesh areas are allowed.
* **Max Attempts & Jitter** - resiliency knobs while sampling.
* **Max Deferred Retries** *(Require only)* - how many backoff cycles to tolerate.

> **Performance note:** sampling is lightweight and gated by attempts/jitter; deferred jobs run on a short tick with a cap to avoid spam.

### Interaction with other systems

* **Spawn Hints**:\
  If a hint has `requireNavMesh` or `overrideAreaMask`, those are applied *before* the entry’s policy kicks in. With **Hint Only** mode, spawns are skipped if no valid hint qualifies.\
  If your **Global Min Spawn Range** exceeds a hint’s `MaxPlayerDistance`, enable **Ignore Global Min Distance** in Hint Settings or adjust the distances; the locator will warn you in the console.
* **Global / Region / Wave**:\
  All flows honor the same policy. Waves inherit `WaveSpawnPoint` anchor tags; the locator prefers hints that match those tags first.

### Common scenarios

* **Open-world streaming**: walkers set to **Prefer** so enemies appear instantly; their agents enable as tiles stream in. Bosses set to **Require** to avoid off-mesh intro glitches.
* **Procedural arenas**: during a rebake, use **Require** to keep grounded AI off until the mesh stabilizes.
* **Flying/swimming units**: set to **Ignore**; no NavMesh dependency.
* **Road/bridge areas**: use **Require** with an **Area Mask** limited to “Road” to keep vehicles from snapping onto sidewalks.

### Migration checklist

1. Open each **Spawn Entry** and choose a **NavMesh Placement Policy**.
2. For grounded AI, start with **Require**: Search Radius = 10–20m, Max Attempts = 4–8, Jitter = 0.5–1.5m.
3. If you stream/bake late, consider **Prefer** for fodder enemies.
4. If using **Spawn Hints**, verify hint distances vs. your **Global Min Spawn Range** and enable **Ignore Global Min Distance** if needed.

### FAQ

**Q: My walkers never spawn with Require.**\
A: Increase Search Radius, loosen Area Mask, or raise Max Deferred Retries. Ensure a NavMesh actually exists in that area.

**Q: Prefer spawns appear but don’t move.**\
A: That’s expected until a valid NavMesh is present; the helper will enable the `NavMeshAgent` once projection succeeds.

**Q: Do waves/regions behave differently?**\
A: No - policy is per entry and applies the same way everywhere. Wave entries simply get their candidate positions from the trigger/anchor.