TheDeclineOfWarriors/docs/plans/TASK-0023-runtime-navmesh-implementation-plan.md

# TASK-0023 Runtime NavMesh Implementation Plan

## Goal

Реализовать runtime NavMesh для procedural voxel world без фризов и без camera-driven assumptions, с архитектурой, совместимой с будущей peer-host multiplayer моделью.

## Inputs And Assumptions

- текущая test scene: `Assets/Features/VoxelWorld/Scenes/VoxelWorldTestScene.unity`
- основной runtime: `Assets/Features/VoxelWorld/Runtime/VoxelWorldGenerator.cs`
- текущий world config asset:
  - `chunkSize = 16`
  - `generationRadius = 3`
  - `maxMountainHeight = 6`
  - `renderRegionSizeInChunks = 4`
  - `maxAsyncChunkJobs = 2`
  - `maxChunkBuildsPerFrame = 1`
  - `maxChunkMeshBuildsPerFrame = 1`
  - `maxColliderAppliesPerFrame = 1`
- первая итерация учитывает область вокруг player actor
- долгосрочный контракт остается `players + active NPC`
- один тип агента
- динамические изменения мира пока не реализуются, но точки расширения под них должны быть предусмотрены

## Chosen Technical Direction

### 1. Не использовать `NavMeshSurfaceVolumeUpdater` как основу решения

Причина:
- пример из samples двигает один build volume за tracked agent и не подходит как production-модель для chunk streaming
- он делает слишком coarse-grained rebuild и оставляет мало контроля над budget, dirty queue и multi-region state

### 2. Использовать ручной runtime pipeline через `NavMeshBuilder.UpdateNavMeshDataAsync`

Причина:
- дает прямой контроль над build sources, bounds, lifecycle `NavMeshData` и количеством одновременных rebuild
- позволяет отказаться от scene-wide source collection и собирать только известные chunk sources
- лучше подходит для throttling под WebGL-host

### 3. Строить NavMesh не per-chunk, а по небольшим nav regions

Выбор:
- отдельный `NavMeshData` на nav region
- стартовый размер region рекомендуется сделать `2x2` чанка, configurable отдельно от render regions

Почему выбран region-based подход:
- per-chunk rebuild создает слишком много мелких операций и лишние seam-риски на границах
- один большой sliding volume вокруг interest target слишком дорог для WebGL-host
- небольшой region дает контролируемый компромисс между стоимостью rebuild и связностью навигации

### 4. Источник build sources брать из runtime collider-геометрии чанков

Выбор:
- `GroundCollider` каждого чанка дает box source
- `MountainCollider.sharedMesh` дает mesh source

Почему так:
- не нужно сканировать всю сцену
- не нужно строить отдельную nav-only геометрию на первом этапе
- collider topology уже является ближайшим к gameplay физическим представлением поверхности

### 5. Rebuild делать через dirty queue и budgeted scheduler

Выбор:
- region помечается dirty при `ApplyColliderMesh` и при unload чанка
- scheduler сортирует dirty regions по расстоянию до interest actor
- одновременно идет максимум один nav rebuild
- если region снова стал dirty во время build, версия region увеличивается и после завершения запускается новый rebuild только для актуальной версии

Почему так:
- это bounded и предсказуемо для WebGL-host
- исключает лавинообразные rebuild при быстром перемещении игрока

## Proposed Runtime Structure

### File Placement

- расширить `VoxelWorldGenerator` новыми partial-файлами, а не вводить отдельный service layer на этой стадии
- рекомендуемые файлы:
  - `Assets/Features/VoxelWorld/Runtime/VoxelWorldGenerator.NavMesh.cs`
  - `Assets/Features/VoxelWorld/Runtime/VoxelWorldGenerator.NavMesh.Types.cs`

Причина:
- nav lifecycle напрямую зависит от chunk lifecycle, которым уже владеет `VoxelWorldGenerator`
- это минимальное изменение без раннего DI/refactor

### New Runtime Data

- `NavRegionRuntime`
  - `NavMeshData NavMeshData`
  - `NavMeshDataInstance Instance`
  - `AsyncOperation ActiveBuild`
  - `int Version`
  - `bool IsDirty`
  - `bool BuildRequestedWhileRunning`
  - `Bounds BuildBounds`
  - `List<NavMeshBuildSource>` reusable sources buffer
- `Queue<Vector2Int> dirtyNavRegions`
- `HashSet<Vector2Int> queuedNavRegions`
- `Dictionary<Vector2Int, NavRegionRuntime> navRegions`

### New Config Settings

Добавить в `VoxelWorldConfig` отдельную секцию `NavMesh`:
- `int navRegionSizeInChunks = 2`
- `int maxNavMeshBuildsPerFrame = 1`
- `int maxConcurrentNavMeshBuilds = 1`
- `float navBoundsVerticalPadding`
- `float navBoundsHorizontalPadding`
- `int navWarmupRadiusInRegions`

Примечание:
- `maxConcurrentNavMeshBuilds` для первой итерации должен остаться `1`
- horizontal padding нужен для корректной стыковки границ region data

## Integration With World Lifecycle

### Chunk load / update flow

1. `GenerateChunkData` завершает данные чанка.
2. `RenderChunk` собирает render snapshot и collider mesh.
3. После фактического применения collider mesh chunk помечает свой nav region dirty.
4. Если чанк лежит у границы nav region, дополнительно dirty-mark соседний region, который делит с ним границу.
5. Scheduler позже запускает rebuild региона по budget.

### Chunk unload flow

1. Перед `runtime.Dispose()` определить nav region чанка.
2. Пометить соответствующий region dirty.
3. Если region стал пустым и вышел из active nav range, удалить его `NavMeshDataInstance`.

### Interest target flow

1. Убрать каноническую зависимость от `Camera.main` как источника стриминга/nav interest.
2. Ввести actor-level target semantics.
3. Для сохранения сцены использовать rename с `FormerlySerializedAs`, если будет меняться имя поля.
4. Для первой итерации target задается явно со сцены или от будущего player actor bootstrap.

## Region Build Flow

1. Определить `regionCoord` по координате чанка.
2. Вычислить `Bounds` региона с padding по XZ и по высоте.
3. Собрать build sources только из чанков, попадающих в region и в соседний margin вокруг него.
4. Для каждого активного чанка добавить:
   - `NavMeshBuildSourceShape.Box` из `GroundCollider`
   - `NavMeshBuildSourceShape.Mesh` из `MountainCollider.sharedMesh`, если mesh не пустой
5. Запустить `NavMeshBuilder.UpdateNavMeshDataAsync` для region-local `NavMeshData`.
6. При завершении проверить актуальность версии и либо оставить data, либо сразу перезапустить rebuild актуальной версии.

## Region Granularity And Boundary Rules

### Start choice

- `navRegionSizeInChunks = 2`

Почему не `1`:
- слишком много мелких `NavMeshData`
- больше seam pressure на стыках
- выше scheduler overhead

Почему не `4`:
- rebuild слишком дорогой для частого runtime update на WebGL-host
- это уже заметный кусок от всего active world при `generationRadius = 3`

### Boundary handling

- build bounds должны быть больше чистого region rectangle
- source collection должна захватывать соседние чанки на один region-margin
- region dirty-mark должен учитывать chunk changes на границах

Причина:
- без overlap на границах легко получить cracks и непредсказуемую связность между соседними `NavMeshData`

## Multiplayer And Authority Contract For This Task

- базовый voxel world генерируется локально у каждого peer из одинакового deterministic input
- NavMesh строится локально у каждого peer и не реплицируется по сети
- authoritative gameplay использует host-side NPC simulation
- текущая итерация NavMesh coverage вокруг player actor считается временным MVP simplification
- при переходе к реальной multiplayer-сцене host должен строить priority coverage вокруг `players + active NPC`
- будущие world changes должны приходить как authoritative deltas и маркировать nav regions dirty локально на каждом peer

## Performance Rules

- не делать full-scene bake
- не пересобирать NavMesh синхронно через `BuildNavMesh()` на gameplay path
- не сканировать произвольные scene objects через generic collection APIs, если можно собрать sources из известных chunk runtimes
- держать максимум один активный build
- переиспользовать buffers, где это возможно
- rebuild запускать только после фактического применения collider mesh
- unload и load чанков должны только маркировать region dirty, а не запускать немедленный build вне scheduler

## Verification Plan

### Manual verification

1. Запустить `VoxelWorldTestScene`.
2. Использовать debug `NavMeshAgent` из AI Navigation samples.
3. Проверить, что агент строит путь по поверхности уже загруженных чанков.
4. Быстро перемещать actor target по миру и отслеживать отсутствие заметных фризов.
5. Проверить unload чанков: после ухода области старый NavMesh не должен оставлять висячие walkable islands в уже удаленных регионах.

### Debug instrumentation

- gizmos для region bounds и состояния region build
- лог счетчиков:
  - active nav regions
  - dirty nav regions
  - builds started/completed/cancelled as stale

## Explicit Non-Goals For This Iteration

- NavMeshObstacle carving
- multi-agent bake
- DI integration через VContainer
- Addressables integration
- ownership migration для чанков или NPC
- финальная multiplayer interest model вокруг всех actors

## Execution Order

1. Добавить nav settings в `VoxelWorldConfig` и resolved settings.
2. Добавить runtime структуры nav regions и dirty scheduler в `VoxelWorldGenerator`.
3. Привязать dirty-marking к chunk collider apply и unload.
4. Реализовать source collection из chunk colliders.
5. Реализовать region-local `NavMeshData` lifecycle и async rebuild.
6. Убрать camera-driven fallback из world/nav interest path.
7. Добавить debug visualization и ручную проверку через sample agent.
8. Задокументировать фактические perf observations после первой проверки гипотезы.