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

# TASK-0023 Runtime NavMesh Implementation Plan

## Goal

Реализовать runtime NavMesh для procedural voxel world как подключаемый sidecar-модуль в отдельной assembly, без camera-driven assumptions, с совместимостью с будущей peer-host multiplayer моделью и уже внедренными `VContainer` + `MessagePipe`.

## Inputs And Assumptions

- текущая test scene: `Assets/Features/VoxelWorld/Scenes/VoxelWorldTestScene.unity`
- основной runtime генерации мира: `Assets/Features/VoxelWorld/Runtime/VoxelWorldGenerator.cs`
- в проекте уже есть `ApplicationLifetimeScope` с `MessagePipe` registration
- первая итерация scheduler может начинать приоритизацию от одного player actor
- внешний interest-контракт сразу остается actor-level interest set: `players + active NPC`
- один тип агента
- динамические изменения мира пока не реализуются, но контракты под них должны быть предусмотрены
- WebGL-host остается целевой платформой, поэтому базовый pipeline не зависит от потоков

## Chosen Technical Direction

### 1. NavMesh не внедряется в `VoxelWorldGenerator` как internal partial-логика

Решение:
- `VoxelWorldGenerator` остается producer world state и chunk geometry
- runtime NavMesh живет в отдельном модуле и подписывается на world contracts

Почему:
- это соответствует целевой модели feature-модулей как подключаемых подсистем
- модуль можно будет реально отключить
- world feature не будет знать детали nav scheduling и `NavMeshData` lifecycle

### 2. Модуль использует `MessagePipe` для событий, но не опирается только на сообщения

Решение:
- `MessagePipe` используется для lifecycle/invalidation notifications
- reader-интерфейсы используются для чтения текущего состояния world geometry и interest points

Почему:
- message-only подход ломается на late subscription и startup ordering
- NavMesh service должен уметь стартовать позже publisher-а и восстановить актуальное состояние

### 3. Runtime pipeline строится через `NavMeshBuilder.UpdateNavMeshDataAsync`

Почему:
- это дает контроль над `NavMeshData`, `Bounds`, build sources и budget
- лучше подходит для region-based rebuild под WebGL-host, чем sample-подход с одним sliding volume

### 4. NavMesh строится по nav regions, а не per-chunk и не full-volume вокруг target

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

Почему:
- per-chunk ведет к слишком большому числу мелких build operations
- один большой moving volume слишком дорог и плохо контролируется по бюджету
- region-based rebuild дает лучший компромисс между стоимостью и связностью

### 5. Целью считается эквивалентная walkable topology, а не bit-identical NavMesh artifact

Почему:
- runtime NavMesh остается derived cache, а не canonical network state
- gameplay correctness не должен опираться на клиентский NavMesh как на источник authority
- это не создает ложного требования к protocol-grade детерминизму там, где он не нужен для MVP

### 6. Источники build sources публикуются world feature как узкие source descriptors

Выбор:
- world feature отдает snapshot nav sources чанка через стабильный reader contract
- текущая реализация `VoxelWorld` может внутри строить эти sources из `GroundCollider` и `MountainCollider`, но эта деталь не протекает в API sidecar-модуля

Почему:
- не нужен scene-wide scanning
- не требуется отдельная nav-only геометрия на первом этапе
- sidecar-модуль не цементируется на конкретных `Collider`-компонентах и scene hierarchy мира

## Target Module Boundaries

### Assembly Layout

- `Assets/Features/VoxelWorld/Contracts/VoxelWorld.Contracts.asmdef`
- `Assets/Features/VoxelWorld/Runtime/VoxelWorld.Runtime.asmdef`
- `Assets/Features/VoxelWorldNavMesh/Runtime/VoxelWorld.NavMesh.Runtime.asmdef`

Почему так:
- `Contracts` фиксируют стабильную внешнюю границу
- `Runtime` реализует мир и публикует contracts
- `VoxelWorld.NavMesh.Runtime` остается optional consumer-модулем

## Contracts To Add

### Reader Interfaces

- `IChunkNavSourceReader`
- `IWorldInterestReader`

Минимальная ответственность:
- `IChunkNavSourceReader` умеет вернуть текущие nav build sources чанка и список уже загруженных чанков
- `IWorldInterestReader` умеет вернуть текущий actor-level interest set

### DTO / Contracts

- `ChunkNavSourceSnapshot`
- `ChunkNavBuildSourceDescriptor`
- `WorldInterestPoint`

Состав DTO:
- `ChunkNavSourceSnapshot`
- `Vector2Int Coord`
- `int Version`
- `ChunkNavBuildSourceDescriptor[] Sources`

- `ChunkNavBuildSourceDescriptor`
- `NavMeshBuildSourceShape Shape`
- `Matrix4x4 Transform`
- `Vector3 Size` для box-source
- `Mesh Mesh` для mesh-source
- `int Area`

- `WorldInterestPoint`
- `Vector3 Position`
- `float Priority`
- `WorldInterestKind Kind`

Примечание:
- DTO должен содержать только то, что реально нужно для NavMesh source collection и build prioritization
- private nested types `VoxelWorldGenerator` не должны утекать наружу
- `Transform`, `MeshCollider` и `BoxCollider` не должны становиться каноническим внешним состоянием NavMesh integration, если достаточно source descriptors

### Message Types

- `ChunkNavGeometryReadyMessage`
- `ChunkNavGeometryRemovedMessage`
- `WorldInterestChangedMessage`
- позже: `ChunkWalkabilityChangedMessage` или аналогичный delta-invalidating message

Правило:
- сообщения несут ключ и минимальные данные invalidation
- тяжелое актуальное состояние читается через reader interfaces

## Required Changes In `VoxelWorldGenerator`

### 1. Перестать быть единственной точкой nav logic

`VoxelWorldGenerator` должен только:
- генерировать и стримить чанки
- создавать/apply collider mesh
- публиковать world contracts

Он не должен:
- владеть dirty nav region queue
- владеть `NavMeshData`
- напрямую запускать `NavMeshBuilder`

### 2. Реализовать reader interfaces

- `IChunkNavSourceReader`
- `IWorldInterestReader`

### 3. Публиковать сообщения после world lifecycle changes

Нужно публиковать:
- `ChunkNavGeometryReadyMessage` после фактического применения collider mesh
- `ChunkNavGeometryRemovedMessage` перед уничтожением чанка
- `WorldInterestChangedMessage` при изменении actor-level interest set

### 4. Убрать каноническую зависимость от `Camera.main`

Для первой итерации допускается scene wiring через explicit target reference, но не через runtime fallback на `Camera.main` как на архитектурную норму.

## NavMesh Module Structure

Рекомендуемые файлы:
- `Assets/Features/VoxelWorldNavMesh/Runtime/VoxelWorldNavMeshService.cs`
- `Assets/Features/VoxelWorldNavMesh/Runtime/VoxelWorldNavMeshTypes.cs`
- `Assets/Features/VoxelWorldNavMesh/Runtime/VoxelWorldNavMeshConfig.cs`
- `Assets/Features/VoxelWorldNavMesh/Runtime/VoxelWorldNavMeshModule.cs`

Дополнительно, если нужен bridge для scene binding на переходном этапе:
- `Assets/Features/VoxelWorldNavMesh/Runtime/VoxelWorldNavMeshEntry.cs`

## DI Composition

### Registration Model

`VoxelWorld` регистрирует:
- `VoxelWorldGenerator` как реализацию reader interfaces
- publishers соответствующих world messages

`VoxelWorldNavMesh` регистрирует:
- `VoxelWorldNavMeshService`
- его subscribers
- config instance

### Important Rule

- feature-код не должен использовать `GlobalMessagePipe` как основную integration point
- `IPublisher<T>` и `ISubscriber<T>` должны приходить через DI

Почему:
- это сохраняет тестируемость
- не создает скрытых runtime-зависимостей
- лучше соответствует модульному подключению через `LifetimeScope`

## NavMesh Service Responsibilities

- подписаться на world lifecycle messages
- на старте получить snapshot уже загруженных чанков через `IChunkNavSourceReader`
- построить initial set dirty regions
- поддерживать `NavMeshData` по регионам
- собирать `NavMeshBuildSource` из source descriptors, а не через прямой доступ к world colliders
- запускать throttled `UpdateNavMeshDataAsync`
- переоценивать build priority относительно current interest set
- удалять region data, когда она выходит из активного диапазона и становится пустой

## Region Runtime Data

- `Dictionary<Vector2Int, NavRegionRuntime> navRegions`
- `Queue<Vector2Int> dirtyNavRegions`
- `HashSet<Vector2Int> queuedNavRegions`

`NavRegionRuntime` должен хранить:
- `NavMeshData NavMeshData`
- `NavMeshDataInstance Instance`
- `AsyncOperation ActiveBuild`
- `int Version`
- `bool BuildRequestedWhileRunning`
- `Bounds BuildBounds`

## New Config Settings

Добавить в NavMesh module config:
- `int navRegionSizeInChunks = 2`
- `int maxConcurrentNavMeshBuilds = 1`
- `int maxNavMeshBuildsPerFrame = 1`
- `float navBoundsHorizontalPadding`
- `float navBoundsVerticalPadding`
- `int navWarmupRadiusInRegions`

Примечание:
- для первой итерации `maxConcurrentNavMeshBuilds` должен оставаться `1`

## Build Flow

### Initial Sync

1. Сервис стартует.
2. Через `IChunkNavSourceReader` получает список уже загруженных чанков.
3. Помечает соответствующие nav regions dirty.
4. Через `IWorldInterestReader` получает текущий interest set.
5. Запускает scheduler.

### Incremental Update

1. Приходит `ChunkNavGeometryReadyMessage`.
2. Сервис читает актуальные sources через `IChunkNavSourceReader`.
3. Помечает nav region dirty.
4. Если chunk расположен на границе region, дополнительно маркирует соседний region.

### Removal

1. Приходит `ChunkNavGeometryRemovedMessage`.
2. Сервис помечает соответствующий region dirty.
3. Если region опустел и вышел из активной зоны, удаляет `NavMeshDataInstance`.

### Interest Update

1. Приходит `WorldInterestChangedMessage`.
2. Сервис обновляет current interest set.
3. Scheduler пересчитывает порядок rebuild и warmup regions.

## Source Collection Rules

Для каждого затронутого region:
- собрать build sources только из чанков региона и соседнего margin
- использовать только известные source snapshots из reader interface
- не сканировать произвольные объекты сцены

Для каждого chunk snapshot:
- добавить sources из `ChunkNavBuildSourceDescriptor`
- если текущий `VoxelWorld` строит эти descriptors из `GroundCollider` и `MountainCollider`, это остается его внутренней деталью и не становится contract-level зависимостью NavMesh-модуля

## Performance Rules

- не делать full-scene bake
- не пересобирать NavMesh синхронно через `BuildNavMesh()` на gameplay path
- не строить систему в расчете на обязательный background threading
- держать максимум один активный region build
- rebuild запускать только после фактического применения collider mesh
- события из `MessagePipe` не должны тащить heavy geometry payload, только invalidation keys
- scheduler должен быть bounded и deterministic по budget

## Verification Plan

### Functional

1. Запустить `VoxelWorldTestScene`.
2. Убедиться, что NavMesh module можно отключить и world generation продолжает работать.
3. Подключить NavMesh module и проверить появление walkable NavMesh на уже загруженных чанках.
4. Проверить, что agent из AI Navigation samples строит путь по поверхности.
5. Проверить unload чанков: старый NavMesh не должен оставлять висячие walkable islands.

### Integration

1. Проверить старт сервиса после world generator: missed events не должны ломать initial sync.
2. Проверить, что модуль работает только через DI-injected `MessagePipe` и reader interfaces.
3. Проверить, что отключение регистрации `VoxelWorldNavMesh` не ломает world feature.
4. Проверить, что внешний interest contract допускает один или несколько interest points, даже если первая scene wiring пока подает только одного player actor.

### Performance

1. Быстро перемещать actor target по миру.
2. Снять показатели:
   - active nav regions
   - queued dirty regions
   - builds started
   - stale rebuilds dropped
   - worst-frame rebuild spikes

## Explicit Non-Goals For This Iteration

- `NavMeshObstacle` carving
- multi-agent bake
- networked NavMesh replication
- ownership migration для чанков или NPC
- финальная multiplayer interest model вокруг всех actors
- прямые зависимости NavMesh feature от `VoxelWorldGenerator` internals

## Execution Order

1. Добавить contracts assembly для world-to-navmesh integration.
2. Добавить message types и reader interfaces.
3. Адаптировать `VoxelWorldGenerator` под публикацию world contracts и messages.
4. Создать отдельную assembly и runtime module `VoxelWorld.NavMesh.Runtime`.
5. Реализовать `VoxelWorldNavMeshService` с initial sync через readers и incremental updates через `MessagePipe`.
6. Реализовать region scheduler и `NavMeshBuilder.UpdateNavMeshDataAsync`.
7. Подключить модуль через DI registration.
8. Провести ручную проверку и зафиксировать фактические perf observations.