VanguardReMaster/docs/3d-ux-backlog.md

3D UX backlog

Анализ требований по UX-долгам 3D-поля. Это план доработок, не реализация. Дата анализа: 2026-10-24.

0. Фактическое состояние

Промпт предполагает наличие CardMoveAnimator, CameraDirector, TriggerCheckSequence, OnCardMoved/OnTargetChanged, CostPaymentController, ArrowDirector, AttackResolutionQueue и DOTween/UniTask. В текущем коде их нет или они называются иначе:

Компонент	Сейчас
InputLockService	есть: Runtime/Battle/InputLockService.cs
AnimationConfig	есть: Runtime/Battle/AnimationConfig.cs + Resources/AnimationConfig.asset; полей из нового ТЗ нет
Карты	Card3D + пул в GameBoard3D; движение — экспоненциальное сглаживание, не дуга, длительность не задаётся
События поля	CardClicked, CardRightClicked, CardDropped, SlotClicked, PileClicked; OnCardMoved/OnTargetChanged отсутствуют
Карточные оверлеи	CardListView, CardDetailOverlay, OverlayNavigationService есть
Боевой HUD	есть верхний uGUI CombatStats (POWER vs SHIELD), отдельного боевого оверлея нет
Стрелка	один AttackArrowView: LineRenderer, оранжевый, без dash/grow, без Boost, якоря в центре карт
Триггеры	карты статично рендерятся в Trigger Zone; камеры/последовательности проверки нет
Стоимость	ad-hoc выбор в BattleView: один DamageIndex/DiscardPrintingId; нет EffectConfig/overlay
Анимационный стек	пакетов DOTween/UniTask в Packages/manifest.json нет
Камера	фиксированная, GameBoard3D.EnsureCamera() выставляет pose при создании/показе

Важное следствие: текущий GameBoard3D.Render ставит immediate = true для новой/сменившей зону карты. Это телепорт при появлении/переносе и должно быть устранено в рамках CardMoveAnimator.

1. CardMoveAnimator

Задачи

1. Ввести CardMoveAnimator и очередь запросов CardMoveRequest: CardInstance/InstanceId, FromZone, ToZone, from/to pose, Duration, Delay, ArcHeight, флаги flip/rest, Important.
2. Перевести на него все переходы:
   • поле ↔ поле (V/RC), hand → field (Call), field → hand;
   • deck → hand/field/Damage/Trigger/Drop;
   • field → Drop/Damage;
   • deck → Trigger;
   • Trigger → hand/Drop/field;
   • guardian/intercept/retire/damage/trigger.
3. Движение по дуге: позиция через Lerp + подъём sin(pi*t)*ArcHeight (или bezier), ease-in-out SmoothStep; rotation/scale интерполировать одновременно.
4. Длительности из AnimationConfig: MoveDuration, ImportantMoveDuration, MoveDelayBetweenCards, ArcHeight; дефолты 0.4–0.6 / 0.8–1.0 / 0.15–0.25.
5. Все переходы последовательности выполняются через один async-контекст: stagger-паузы входят в блокировку; lock снимается в try/finally.
6. Не использовать transform.position = ... в игровой логике. Исключения: drag под курсором, Snap первичной раскладки и сервисные телепорты при reset/clear.
7. Переработать diff в GameBoard3D.Render: по InstanceId и переходу зоны определить источник и анимировать; пул не должен менять ключ/Ref раньше старта анимации.
8. Для скрытой информации (deck/opponent hand/drop) не анимировать лицо карты до раскрытия; рубашка/флип — часть запроса.
9. Добавить события/хуки CardMoveStarted/CardMoveFinished (или эквивалент), чтобы trigger/camera/arrow не полагались на таймеры.

Критерий

Любое перемещение плавное, без телепорта; последовательные перемещения идут с задержкой; ввод заблокирован до конца пачки; lock не остаётся после исключения/отмены.

2. TriggerCheckSequence + CameraDirector

Задачи

1. CameraDirector: снимок position/rotation/FOV при входе в цепочку; ZoomToTrigger(), ReturnToOrigin(), повторный зум; идемпотентный Restore(); не допускать накопления смещения/дрейфа.
2. Учесть текущий GameBoard3D.EnsureCamera(): он не должен перезаписывать камеру во время работы режиссёра; ввести явное владение камерой.
3. TriggerCheckSequence как оркестратор:
   • A (одиночная): zoom → card from deck to Trigger → reveal hold → return camera → resolve effect;
   • B (цепочка): zoom once → card 1 → hold → if choice: return camera → choose target → re-zoom → next card → after last return to snapshot;
   • после последней проверки камера точно в исходном pose.
4. Тайминги из AnimationConfig: CameraZoomDuration, TriggerRevealHold, CameraReturnDuration, CameraRezoomDuration.
5. InputLock на всю последовательность; перед выбором цели камеру вернуть и lock снять; после выбора — снова lock и re-zoom.
6. Не сбрасывать цепочку при повторном snapshot/clock; sequence state должен быть идемпотентным и завершаться по snapshot/событию.

Критерий

Одиночная проверка: зум → карта → резолв → камера вернулась. Цепочка: зум один раз, проверки по очереди, выбор цели при возвращённой камере, после последней — точный исходный pose без дрейфа.

3. Ориентация карт

Задачи

1. Trigger Zone:
   • своя карта: локальный yaw +90° (по часовой вокруг Y);
   • противника: зеркально −90°;
   • yaw задаётся матрицей/позой с учётом localSeat, а не только BaseYaw.
2. Скрытые карты:
   • рука противника, колода (обе), Drop при флаге — рубашкой вверх;
   • переворот 180° вокруг X интерполируется вместе с move;
   • DropZoneFaceDown добавить в PlaymatLayoutConfig/BoardConfig; по правилам Classic default = false (Drop лицом вверх), но флаг обязателен.
3. Card3D.SetState/SetPose расширить произвольной ориентацией и начальным pose; не сбрасывать rotation через Snap, если идёт анимация.
4. Trigger-зона противника остаётся зеркальной по позиции и повороту.

Критерий

Своя Trigger Zone — 90° по часовой; противника — зеркально. Opponent hand / deck / Drop (если faceDown) показывают рубашку; flip происходит в процессе анимации, не мгновенно.

4. CostPaymentController + EffectConfig

Текущее ограничение

Сейчас цена выбирается ad-hoc: _pendingAbilityCost и один AbilityDamageIntent.DamageIndex/DiscardPrintingId. CounterBlast и SoulBlast на сервере автоматически забирают следующие карты; выбрать несколько конкретных целей нельзя. Для требований multi-target cost нужен протокол + движок, а не только UI.

Задачи

1. EffectConfig (ScriptableObject): CostType (CounterBlast/SoulBlast/…), Amount, AllowFewer, MinRequired, TargetZone.
2. CostPaymentController: открыть overlay → собрать выбор → проверить X == N или X <= N && X >= MinRequired → подтвердить → применить стоимость → закрыть.
3. CostPaymentOverlay: описание, счётчик Выбрано: X / N (или X при AllowFewer), подсветка hover/selected, повторный клик — toggle, кнопка подтверждения disabled при невалидном выборе, красный счётчик.
4. Ввод: lock, кроме кликов по валидным целям и подтверждения.
5. Серверная часть: новый intent/массив выбранных damage/soul indexes (или расширение ActivateAbilityCommand) с идемпотентностью и проверкой количества; обновить CounterBlast/SoulBlast так, чтобы они принимали выбор, а не брали первые карты.
6. Совместимость с текущими AbilityDamageTargeting/damage choice; client protocol versioning не ломать.

Критерий

Оверлей со счётчиком, toggle и зелёной подсветкой; кнопка активна только при корректном выборе; после подтверждения стоимость применена и ввод разблокирован; неверный выбор не отправляется.

5. TargetArrow / ArrowDirector

Задачи

1. ArrowConfig (SO): AttackColor, BoostColor, GrowDuration, DashScrollSpeed, Thickness, BoostGrowDuration, BoostThickness, HeadLength, HeadWidth, FadeDuration.
2. Обобщить AttackArrowView до TargetArrow: тип Attack/Boost, цвет, наконечник, общий материал/шейдер/анимация; отдельные префабы только при доказанной необходимости.
3. ArrowDirector: одна attack-стрелка, N boost-стрелок; очистка при смене фазы/боя/уходе карты; подписка на изменение цели/перемещение.
4. Геометрия:
   • над плейматом (Y offset), без z-fighting;
   • лёгкая дуга, чтобы не перекрывать карты;
   • наконечник у края карты-цели, не в центре;
   • from/to anchors обновлять после анимации карт.
5. Анимация attack: grow 0→1, бегущий dash, pulse, fade+scale down. Boost: те же скрипты, синий цвет, тоньше/быстрее; несколько стрелок — stagger.
6. AttackResolutionQueue: очередь целей, пошаговый резолв, подсветка текущей цели + пауза; пока одна цель, но API на будущее.
7. Боевой оверлей не создавать. Power/Shield показывать у карт через World-Space UI. Сейчас CombatStats — верхний uGUI-стрип; решить: оставить как debug/скрыть или перенести показатели к картам.
8. Пунктир: рекомендуемый подход — world-space dash shader: плотность штриха зависит от мирового расстояния, а не от UV stretch; один материал для attack/boost; работает с изогнутым LineRenderer. Fallback — сегментированный mesh, если шейдер/платформа не даст стабильного результата. Выбор зафиксировать в ArrowConfig/документе.

Критерий

Атака — красная пунктирная стрелка с наконечником; Boost — синяя от заднего ряда к переднему; dash анимирован; исчезновение плавное; якоря у края; несколько boost-стрелок со stagger; камера/движение карт не ломают точки.

6. Конфиги и техническая база

1. Расширить AnimationConfig: MoveDuration, ImportantMoveDuration, MoveDelayBetweenCards, ArcHeight, CameraZoomDuration, TriggerRevealHold, CameraReturnDuration, CameraRezoomDuration, GrowDuration, DashScrollSpeed, BoostGrowDuration, BoostThickness, ArrowFade.
2. Новые ScriptableObject: EffectConfig, ArrowConfig.
3. Подход к асинхронности: в проекте нет UniTask/DOTween. Нужно решение:
   • предпочтительно добавить UniTask и вести последовательности async/await;
   • либо использовать Coroutine + общий AnimationSequence без новых зависимостей. Зафиксировать до реализации; не смешивать три подхода.
4. Не ломать CardListView, CardDetailOverlay, InputLockService, существующий Card3D/GameBoard3D pooling.
5. Проверки: EditMode-тесты на интерполяцию/ориентации/валидацию цены/якоря стрелок; smoke; серверные тесты при изменении протокола цены.

7. Порядок работ

1. P0: AnimationConfig + CardMoveAnimator + интеграция diff/pool + ориентации (п.1, 3).
2. P0: CameraDirector + TriggerCheckSequence (п.2).
3. P1: ArrowConfig + TargetArrow/ArrowDirector + attack/boost анимации + AttackResolutionQueue (п.5).
4. P1: EffectConfig + CostPaymentController/Overlay + протокол/движок multi-target cost (п.4).
5. P2: World-Space Power/Shield, удаление/скрытие CombatStats при необходимости, polish и профилирование.

8. Открытые решения перед кодом

• UniTask или Coroutine (в проекте нет ни DOTween, ни UniTask).
• DropZoneFaceDown default: false по Classic, но нужен ли рубашкой вверх для Drop в текущем UX?
• Dash: world-space shader или сегментированный mesh (рекомендация — shader, fallback — mesh).
• Судьба верхнего CombatStats: скрыть/оставить debug/перенести к картам.
• Протокол multi-target cost: новый CostPaymentIntent или расширение ActivateAbilityIntent массивами (влияет на Vanguard.Shared и обратную совместимость).
• Камера: кто владеет Camera во время trigger sequence и как это сочетается с EnsureCamera().