---
id: TASK-0027
title: Host-authoritative player navigation с shared debug path preview
summary: Перевести player movement на host-authoritative NavMesh pipeline с server-side path planning, authoritative path following и общим debug path preview для всех клиентов.
priority: Highest
area: gameplay-core
owner: unassigned
created: 2026-04-08
updated: 2026-04-08
execution_time: 3d
depends_on:
  - TASK-0002
  - TASK-0023
canonical_docs:
  - docs/tasks/Index.md
  - docs/architecture/mvp-world-authority-navmesh.md
  - docs/plans/TASK-0023-runtime-navmesh-implementation-plan.md
related_files:
  - Assets/Scripts/Players/PlayerMoving.cs
  - Assets/Features/VoxelWorld/Prefabs/TestPlayer.prefab
  - Assets/Features/VoxelWorld/Scenes/VoxelWorldTestScene.unity
  - Assets/Features/VoxelWorld/Runtime/VoxelWorldGenerator.cs
  - Assets/Features/VoxelWorld/Contracts/NavMeshWorldContracts.cs
  - Assets/Features/VoxelWorldNavMesh/Runtime/VoxelWorldNavMeshService.cs
---

# TASK-0027 - Host-authoritative player navigation с shared debug path preview

## Status

Статус задачи ведется в `docs/tasks/Index.md` и является каноническим там.

## Why

Если игрок тоже должен двигаться по NavMesh, текущий local/client-authoritative movement pipeline становится архитектурно слабым для multiplayer:

- клиент не должен быть источником канонического movement outcome;
- локальный `NavMeshAgent` не должен быть authoritative mover для player actor;
- path planning и path following должны принадлежать хосту;
- shared debug path preview для движущихся игроков должен отображать именно authoritative path, который принят хостом, а не локальную клиентскую догадку.

Без этого возрастает риск:

- desync между client local movement и host state;
- race-condition между player spawn и nav coverage readiness;
- неотлаживаемых расхождений path preview между peers;
- ошибок вроде `Failed to create agent because it is not close enough to the NavMesh`, если movement pipeline завязан на lifecycle локального `NavMeshAgent`.

## Expected Outcome

- Игрок отправляет только команду перемещения, а не итог движения.
- Хост валидирует destination на своем NavMesh, строит authoritative path и двигает actor канонически.
- Клиенты получают authoritative movement state и сглаживают presentation.
- Для каждого движущегося игрока существует authoritative debug path preview, который видят все клиенты.
- Player spawn и first move command не зависят от hidden scene hacks и не требуют client-authoritative `NavMeshAgent`.

## Current Context

В проекте уже зафиксированы и частично реализованы базовые решения по миру и runtime NavMesh:

- `TASK-0023` ввел runtime NavMesh как sidecar-модуль поверх voxel world.
- `VoxelWorldGenerator` уже публикует nav source snapshots и world interest.
- `VoxelWorldNavMeshService` строит NavMesh локально на каждом peer по region-based схеме.

При этом current player flow пока не соответствует целевой модели:

- `Assets/Scripts/Players/PlayerMoving.cs` ориентирован на локальное movement execution;
- `Assets/Features/VoxelWorld/Prefabs/TestPlayer.prefab` все еще держит player movement в client-oriented конфигурации;
- spawn/nav readiness для player-on-navmesh еще не оформлены как отдельный контракт;
- shared debug path preview для player movement отсутствует.

## Source Of Truth

- `docs/architecture/mvp-world-authority-navmesh.md`
- `docs/plans/TASK-0023-runtime-navmesh-implementation-plan.md`
- фактический player/network/world flow в текущем коде проекта

## Read First

- `Assets/Scripts/Players/PlayerMoving.cs`
- `Assets/Scripts/Players/CameraFollow.cs`
- `Assets/Features/VoxelWorld/Prefabs/TestPlayer.prefab`
- `Assets/Features/VoxelWorld/Scenes/VoxelWorldTestScene.unity`
- `Assets/Features/VoxelWorld/Runtime/VoxelWorldGenerator.cs`
- `Assets/Features/VoxelWorld/Contracts/NavMeshWorldContracts.cs`
- `Assets/Features/VoxelWorldNavMesh/Runtime/VoxelWorldNavMeshService.cs`
- `Assets/Scripts/VoxelWorld/VoxelWorldNavMeshLifetimeScope.cs`

## Fixed Decisions

### 1. Player movement outcome is host-authoritative

Клиент отправляет только move intent. Канонические:

- target acceptance/rejection;
- path corners;
- progress по path;
- итоговая позиция;
- movement completion/cancel.

Все это вычисляется и хранится на хосте.

### 2. Player uses NavMesh for movement, but client NavMesh is not authoritative

Клиент может использовать локальный NavMesh только для optional preview/query UX, но не как source of truth для gameplay movement state.

### 3. Do not use client-local `NavMeshAgent` as canonical player mover

Нельзя строить player movement correctness на `NavMeshAgent`, который локально двигает owner-клиента.

Предпочтительный путь:

- host-side `NavMesh.SamplePosition`;
- host-side `NavMesh.CalculatePath`;
- host-side explicit path follower;
- movement execution через контролируемый mover, предпочтительно `CharacterController.Move` или эквивалентный deterministic-ish explicit mover.

### 4. Client does not send path corners or final movement outcome

Клиенту нельзя отправлять:

- path corners;
- velocity как authoritative instruction;
- final position;
- movement completion.

Клиент отправляет только request:

- sequence id;
- requested destination;
- при необходимости легкий UX/debug metadata, не влияющий на authority.

### 5. Shared debug path preview must be authoritative-path-based

Обязательный debug preview, который видят все клиенты, должен строиться из authoritative path, рассчитанного хостом.

Допустим временный local provisional preview у инициирующего клиента, но он:

- не считается каноническим;
- должен визуально отличаться;
- должен исчезать или заменяться после host accept/reject.

### 6. Spawn/nav readiness must be explicit

Нельзя строить pipeline по модели:

- player actor spawned;
- NavMesh может быть еще не готов;
- movement runtime надеется, что agent потом сам корректно «встанет» на NavMesh.

Нужен явный readiness contract или equivalent bootstrap policy для spawn regions / first move command.

## Scope In

- host-authoritative player movement по NavMesh;
- client command pipeline для выбора destination;
- host-side destination validation;
- host-side path planning;
- host-side path following;
- replication authoritative movement state на клиентов;
- shared debug path preview для каждого движущегося игрока на всех клиентах;
- optional local provisional preview для owner-клиента;
- nav-aware spawn/bootstrap и первый move command;
- интеграция через contracts + DI + MessagePipe, совместимая с `TASK-0023`.

## Scope Out

- NPC navigation system;
- crowd simulation;
- сложная prediction/reconciliation система для player nav movement;
- production UI polish path markers;
- ownership migration;
- репликация NavMesh data blob;
- multi-agent support beyond current single-agent MVP;
- сохранение movement path через reconnect/persistence beyond current runtime session.

## Required Architecture

### Movement flow

#### Client

1. Игрок выбирает destination.
2. Input layer определяет world point.
3. Optional: строит provisional local preview path для UX owner-клиента.
4. Отправляет host command с sequence id и requested destination.

#### Host

1. Проверяет ownership и допустимость команды.
2. Проверяет movement lock/state.
3. Проверяет nav readiness для области.
4. Делает `NavMesh.SamplePosition`.
5. Делает `NavMesh.CalculatePath`.
6. Если путь валиден, обновляет canonical movement state.
7. Публикует/реплицирует accepted authoritative path и path preview.
8. Если путь невалиден, отправляет reject reason.

#### Host tick

1. Берет текущий active path.
2. Вычисляет движение к текущему corner.
3. Двигает player actor через explicit mover.
4. Продвигает current corner index.
5. По завершении очищает active path preview и переводит actor в `Idle`.

#### Clients

1. Получают authoritative movement state.
2. Сглаживают presentation.
3. Отображают authoritative debug path preview для всех moving players.

### Assembly boundaries

Рекомендуется отдельный feature-модуль:

- `Assets/Features/PlayerNavigation/Contracts/PlayerNavigation.Contracts.asmdef`
- `Assets/Features/PlayerNavigation/Runtime/PlayerNavigation.Runtime.asmdef`

Нельзя вшивать player navigation hardwired внутрь `VoxelWorldGenerator` или `VoxelWorldNavMeshService`.

### DI and integration model

Использовать:

- contracts;
- DI через `VContainer`;
- typed `MessagePipe` publishers/subscribers;
- reader interfaces для текущего snapshot state.

Не использовать `GlobalMessagePipe`.

### Message vs reader split

Через MessagePipe:

- lifecycle movement events;
- accept/reject events;
- preview invalidation/update events.

Через reader contracts:

- текущее состояние movement state;
- текущее состояние authoritative path preview;
- nav readiness / spawn readiness snapshot, если требуется queryable access.

## Required New Contracts

### Reader interfaces

Нужны как минимум:

- `IPlayerMovementStateReader`
- `IPlayerPathPreviewReader`
- `ISpawnNavReadinessReader` или эквивалентный узкий readiness contract

Минимальная ответственность:

- `IPlayerMovementStateReader` умеет вернуть current movement snapshot игрока;
- `IPlayerPathPreviewReader` умеет вернуть active authoritative preview для игрока или списка игроков;
- `ISpawnNavReadinessReader` умеет ответить, готова ли nav coverage для spawn/first-move области.

### DTO / snapshots

Ожидаются как минимум:

- `PlayerMovementStateSnapshot`
- `PlayerPathPreviewSnapshot`
- `PlayerMoveRequest`
- `PlayerMoveCommandResult`

Минимальный состав `PlayerMovementStateSnapshot`:

- player network id;
- status;
- command sequence;
- current position;
- target position;
- move speed;
- current corner index;
- authoritative path corners;
- updated timestamp/network tick.

Минимальный состав `PlayerPathPreviewSnapshot`:

- player network id;
- command sequence;
- corners;
- `IsAuthoritative`;
- `IsActive`.

### Enums

Нужны как минимум:

- `PlayerMovementStatus`
- `PlayerMoveRejectReason`

Примерные состояния:

- `Idle`
- `AwaitingPath`
- `Moving`
- `Blocked`
- `Completed`
- `Cancelled`
- `Rejected`

Примерные reject reasons:

- `NoNavCoverage`
- `DestinationNotOnNavMesh`
- `PathInvalid`
- `PathPartial`
- `MovementLocked`
- `NotOwner`

## Required Messages

Нужны typed MessagePipe messages для:

- `PlayerMoveRequestedMessage`
- `PlayerMoveAcceptedMessage`
- `PlayerMoveRejectedMessage`
- `PlayerMoveStateChangedMessage`
- `PlayerPathPreviewChangedMessage`
- `PlayerMovementStoppedMessage`

Если для spawn/bootstrap это необходимо, допустим дополнительный readiness message, но только как supplement к reader contract, а не как единственный источник истины.

## Required Runtime Responsibilities

### 1. Client input sender

Должен:

- собирать local click-to-move input;
- вычислять world destination;
- отправлять network command хосту;
- optional: запускать provisional local preview.

Не должен:

- канонически двигать actor;
- принимать final authoritative решения по path validity.

### 2. Host command validator / planner

Должен:

- валидировать ownership;
- валидировать destination;
- делать `NavMesh.SamplePosition`;
- делать `NavMesh.CalculatePath`;
- обновлять canonical movement state;
- публиковать accepted/rejected results.

### 3. Host path follower

Должен:

- исполнять movement по accepted path;
- отслеживать current corner index;
- завершать, отменять или репланить путь;
- синхронизировать authoritative transform/state.

### 4. Shared preview state + renderer

Должны:

- хранить authoritative debug path data;
- раздавать snapshot presentation-слою;
- визуализировать active path preview для всех observed players.

Shared preview не должен строиться заново локально на каждом клиенте по его client NavMesh. Источник preview для всех клиентов должен быть authoritative path state от хоста.

## FishNet Requirements

### Client -> Host

Использовать `ServerRpc` для move command:

- `RequestMoveTo(uint sequence, Vector3 requestedWorldPoint)`

### Host -> Clients

Допустимы:

- authoritative replicated movement state;
- отдельные `TargetRpc` / `ObserversRpc` для accept/reject;
- отдельная lightweight replication для shared path preview.

Клиент не должен иметь возможности двигать чужого player actor.

## Required Changes In Existing Code

### `Assets/Scripts/Players/PlayerMoving.cs`

Нужно перестроить из local movement executor в input sender / thin player navigation entrypoint.

### `Assets/Features/VoxelWorld/Prefabs/TestPlayer.prefab`

Нужно пересмотреть:

- текущий movement pipeline;
- конфигурацию `NetworkTransform`;
- player navigation components;
- visual debug preview attachment points.

Client-authoritative movement не должен оставаться каноническим режимом для nav-based player movement.

### `Assets/Features/VoxelWorld/Scenes/VoxelWorldTestScene.unity`

Нужно проверить:

- spawn bootstrap;
- nav warmup around spawn points;
- наличие всего необходимого для тестирования shared path preview.

### Nav readiness bootstrap

Нужно добавить явную стратегию, чтобы player spawn / first command не зависели от случайного отсутствия NavMesh в стартовой области.

## Debug Path Preview Requirements

Это обязательная часть задачи.

### Functional requirement

Каждый движущийся игрок должен иметь debug path preview, который видят все клиенты.

Примеры:

- игрок A движется -> path видят A, B, C;
- игрок B движется -> path видят A, B, C.

### Canonical rule

Shared preview должен отображать именно authoritative path, рассчитанный хостом.

### Optional owner-local preview

Допустим provisional local preview до host ответа, но он должен:

- визуально отличаться;
- не считаться каноническим;
- исчезать или заменяться после accept/reject.

### Minimal rendering expectation

Минимально допустимо:

- `LineRenderer` или эквивалентный lightweight renderer;
- обновление при accept/replan/stop/complete;
- очистка при completion/cancel/reject.

## Acceptance Criteria

- Клиент может отправить move request по клику в мир.
- Хост валидирует destination на своем NavMesh.
- Хост строит authoritative path.
- Игрок движется по host-side path, а не по client-authoritative local mover.
- Недопустимые destination/path корректно reject'ятся с reason.
- Для каждого moving player существует authoritative path preview.
- Этот preview виден на всех клиентах.
- Preview корректно обновляется при новой команде, replan, stop, cancel и completion.
- Если реализован provisional local preview, он визуально отделен от authoritative shared preview.
- Player spawn и first move command не зависят от hidden `NavMeshAgent` attach hacks.
- Pipeline не опирается на `Camera.main` как канонический источник authority/interest.

## Verification

- ручной тест: single host, single client, move command accepted/rejected;
- ручной тест: host + 2 clients, оба клиента видят preview друг друга;
- ручной тест: invalid destination вне walkable area, host reject без runtime errors;
- ручной тест: новая команда во время движения корректно заменяет active path;
- ручной тест: late join видит текущее движение и active preview moving players;
- ручной тест: первый move command после старта сцены не приводит к runtime ошибкам из-за отсутствия nav coverage;
- ручной тест: completion/cancel очищает preview на всех клиентах.

## Risks / Open Questions

- Если оставить рядом client-authoritative movement и host-side nav movement, возникнет двойная симуляция и несогласованное состояние.
- Если shared preview строить по локальному client NavMesh, разные peers могут видеть разный path debug.
- Если spawn/nav readiness не будет оформлен явно, lifecycle race останется даже при правильном movement flow.
- Возможно потребуется отдельный узкий contract для nav coverage readiness, которого пока нет в `TASK-0023` runtime-поверхности.

## Human Decisions Needed

- none currently

## Decision Log

- `2026-04-08` - задача создана после фиксации runtime NavMesh sidecar и обсуждения правильной host-authoritative модели player movement по NavMesh.

## Handoff Notes

Реализация задачи должна опираться на уже принятые решения по world authority и runtime NavMesh. Если в ходе реализации возникнет соблазн повесить `NavMeshAgent` на player prefab как client-local authoritative mover, это нужно считать архитектурно неправильным shortcut'ом и не делать.

Shared debug path preview обязателен и должен отображать authoritative path для всех клиентов, а не purely local preview инициатора.