tengri/Documentation/Roadmap.md

[//]: # (Documentation/Roadmap.md)

# Этап 1: Базовая настройка и константы
**Цель:** Система классификации поверхностей по углам

**Результат:** Стабильная база для всех последующих расчетов

**Что реализуем:**
- Переменные движения (MaxSpeed, Acceleration, Friction, Gravity)
- Система углов поверхностей (Walkable ≤50°, SteepSlope ≤85°, Wall ≤95°, Ceiling >95°)
- Конвертация градусы ↔ радианы
- Функции инициализации и тестирования констант
- Enhanced Input System интеграция

**Критерии успеха:**
- ✅ Корректная конвертация углов (точность <0.001)
- ✅ Все константы инициализируются при старте
- ✅ Debug вывод показывает правильные значения
- ✅ Автоматические тесты проходят

---

# Этап 2: Debug HUD система
**Цель:** Статичный debug вывод для удобной отладки

**Результат:** Профессиональная debug система

**Что реализуем:**
- Цветовое кодирование разных типов информации
- Функции переключения debug режимов
- Контроль частоты обновления HUD

**Критерии успеха:**
- ✅ Информация отображается статично на экране
- ✅ Цветовая дифференциация работает
- ✅ Легкое включение/выключение debug режимов
- ✅ Нет влияния на производительность

---

# Этап 3: Система сообщений в виде тостов
**Цель:** Удобный вывод сообщений для отладки

**Результат:** Система сообщений в виде тостов

**Что реализуем:**
- Функции для отображения сообщений в виде тостов
- Цветовая дифференциация сообщений
- Контроль времени отображения тостов
- Подстройка положения тостов на экране в зависимости от их количества
- Анимация появления и исчезновения тостов

**Критерии успеха:**
- ✅ Сообщения отображаются в виде тостов
- ✅ Цветовая дифференциация работает
- ✅ Тосты исчезают через заданное время
- ✅ Положение тостов адаптируется в зависимости от их количества
- ✅ Анимация появления и исчезновения тостов плавная и не вызывает рывков

---

# Этап 4: Детекция поверхностей
**Цель:** Надежное определение типа поверхности под персонажем

**Результат:** Стабильная классификация Walkable/SteepSlope/Wall/Ceiling

**Что реализуем:**
- Функции классификации поверхности по нормали
- Функции запросов состояния (IsSurfaceWalkable, IsSurfaceSteep, etc.)
- Вывод необходимых значений в Debug HUD
- Вывод результатов тестов в HUD

**Критерии успеха:**
- ✅ Точная классификация поверхностей по углам
- ✅ Стабильное определение типа поверхности
- ✅ Корректная работа с нормалями поверхностей
- ✅ Детальная debug информация
- ✅ Значения корректно отображаются в Debug HUD
- ✅ Результаты тестов отображаются в HUD

---

# Этап 5: Детекция текущего игрового девайса
**Цель:** Определение типа устройства ввода (мышь/клавиатура)

**Результат:** Стабильное определение типа устройства ввода

**Что реализуем:**
- Функции определения типа устройства (E_InputDeviceType)
- Функции проверки состояния устройства (IsKeyboard, IsGamepad)
- Смена подсказок в HUD в зависимости от устройства
- Вывод необходимых значений в Debug HUD
- Вывод результатов тестов в HUD

**Критерии успеха:**
- ✅ Корректное определение типа устройства ввода
- ✅ Подсказки в HUD меняются в зависимости от устройства
- ✅ Легкая интеграция с Enhanced Input System
- ✅ Отсутствие ошибок при смене устройства
- ✅ Значения корректно отображаются в Debug HUD
- ✅ Результаты тестов отображаются в HUD

---

# Этап 6: Вращение камерой мышкой или стиком
**Цель:** Плавное вращение камеры с учетом устройства ввода

**Результат:** Плавное управление камерой

**Что реализуем:**
- Плавное вращение камеры при движении мышью или стиком геймпада
- Учет чувствительности и инверсии осей
- Вывод необходимых значений в Debug HUD
- Вывод результатов тестов в HUD

**Критерии успеха:**
- ✅ Плавное вращение камеры при движении мышью
- ✅ Плавное вращение камеры при движении стиком геймпада
- ✅ Учет чувствительности и инверсии осей
- ✅ Отсутствие рывков и заиканий
- ✅ Значения корректно отображаются в Debug HUD
- ✅ Результаты тестов отображаются в HUD

---

# Этап 7: Базовое движение по земле
**Цель:** Плавное детерминированное движение по плоским поверхностям

**Результат:** Отзывчивое управление без рывков и заиканий

**Что реализуем:**
- VInterpTo для плавного ускорения и торможения
- Применение гравитации с правильным обнулением на земле
- Горизонтальное движение только на walkable поверхностях
- Ограничение максимальной скорости
- Вывод необходимых значений в Debug HUD
- Вывод результатов тестов в HUD

**Критерии успеха:**
- ✅ Плавное ускорение при нажатии WASD и стика геймпада
- ✅ Плавное торможение при отпускании клавиш/стика геймпада
- ✅ Скорость не превышает MaxSpeed
- ✅ Диагональное движение не быстрее прямого
- ✅ Стабильное поведение на земле
- ✅ Значения корректно отображаются в Debug HUD
- ✅ Результаты тестов отображаются в HUD

---

# Этап 8: Поворот персонажа вслед за движением
**Цель:** Плавный поворот персонажа в сторону движения

**Результат:** Персонаж естественно реагирует на направление движения

**Что реализуем:**
- При использовании мыши или стика геймпада персонаж поворачивается в сторону движения
- Учет наклона камеры для корректного поворота
- Вывод необходимых значений в Debug HUD
- Вывод результатов тестов в HUD

**Критерии успеха:**
- ✅ Персонаж плавно поворачивается в сторону движения
- ✅ Поворот учитывает наклон камеры
- ✅ Плавный переход между направлениями
- ✅ Нет рывков при повороте
- ✅ Персонаж не поворачивается, если не движется
- ✅ Поворот не влияет на скорость движения
- ✅ Значения корректно отображаются в Debug HUD
- ✅ Результаты тестов отображаются в HUD

---

# Этап 9: Детерминированный Sweep collision
**Цель:** Полное устранение tunneling через stepped collision detection
**Результат:** Bullet-proof система коллизий

**Что реализуем:**
- PerformDeterministicSweep с пошаговой проверкой
- HandleSweepCollision для обработки ударов
- Адаптивный размер шагов sweep
- Вывод необходимых значений в Debug HUD
- Вывод результатов тестов в HUD

**Критерии успеха:**
- ✅ Полное отсутствие tunneling при любых скоростях
- ✅ Стабильная Z позиция (разброс <0.5 единиц)
- ✅ Детерминированность (100% воспроизводимость)
- ✅ Performance <25 collision checks за кадр
- ✅ Значения корректно отображаются в Debug HUD
- ✅ Результаты тестов отображаются в HUD

---

# Этап 10: Обработка стен и углов
**Цель:** Плавное скольжение вдоль стен без застреваний
**Результат:** Качественная навигация в сложной геометрии

**Что реализуем:**
- Wall sliding - скольжение вдоль стен
- Corner resolution - обработка внутренних углов
- Multi-directional sweep - несколько попыток движения
- Edge detection и step-up механика
- Вывод необходимых значений в Debug HUD
- Вывод результатов тестов в HUD

**Критерии успеха:**
- ✅ Персонаж не застревает в углах
- ✅ Плавное скольжение вдоль стен любой геометрии
- ✅ Автоматический step-up на небольшие препятствия
- ✅ Работает в сложных лабиринтах
- ✅ Значения корректно отображаются в Debug HUD
- ✅ Результаты тестов отображаются в HUD

---

# Этап 11: Движение по склонам
**Цель:** Реалистичное поведение на наклонных поверхностях  
**Результат:** Естественное движение по пандусам и скатывание

**Что реализуем:**
- Slope walking - движение вверх/вниз по склонам ≤45°
- Slope sliding - скатывание с крутых поверхностей >45°
- Ground snapping - прилипание к неровной поверхности
- Momentum preservation на склонах
- Вывод необходимых значений в Debug HUD
- Вывод результатов тестов в HUD

**Критерии успеха:**
- ✅ Плавный подъем по пандусам ≤45°
- ✅ Реалистичное скатывание с крутых склонов >45°
- ✅ Отсутствие "прыжков" на неровностях
- ✅ Сохранение импульса при переходах между поверхностями
- ✅ Значения корректно отображаются в Debug HUD
- ✅ Результаты тестов отображаются в HUD

---

# Этап 12: Разделение физики и рендера
**Цель:** Детерминированная физика + плавная визуализация
**Результат:** AAA-качество визуального движения

**Что реализуем:**
- Dual position system (physics + render positions)
- Position interpolation для плавности
- Fixed timestep для физики (120Hz physics, variable render)
- Smooth transitions между состояниями
- Вывод необходимых значений в Debug HUD
- Вывод результатов тестов в HUD

**Критерии успеха:**
- ✅ Физика остается детерминированной
- ✅ Визуально плавное движение без микрозаиканий
- ✅ Stable 60+ FPS без влияния на физику
- ✅ Smooth interpolation работает корректно
- ✅ Значения корректно отображаются в Debug HUD
- ✅ Результаты тестов отображаются в HUD

---

# Этап 13: Профессиональная камера система
**Цель:** Плавная камера уровня AAA-игр
**Результат:** Комфортная камера без рывков

**Что реализуем:**
- Camera lag и damping для плавного следования
- Look-ahead prediction (камера смотрит вперед при движении)
- Smooth rotation следования за поворотами
- Dead zone для микродвижений
- Collision avoidance для камеры
- Вывод необходимых значений в Debug HUD
- Вывод результатов тестов в HUD

**Критерии успеха:**
- ✅ Камера не дергается при остановке/старте
- ✅ Плавные повороты и наклоны
- ✅ Предсказание направления движения
- ✅ Нет проваливания камеры в стены
- ✅ Значения корректно отображаются в Debug HUD
- ✅ Результаты тестов отображаются в HUD

---

# Этап 14: Adaptive stepping optimization
**Цель:** Оптимизация производительности sweep системы
**Результат:** Меньше collision checks без потери качества

**Что реализуем:**
- Variable step size в зависимости от скорости
- Субпиксельная точность для медленного движения
- Performance monitoring и auto-tuning
- Spatial optimization для collision queries
- Вывод необходимых значений в Debug HUD
- Вывод результатов тестов в HUD

**Критерии успеха:**
- ✅ <10 collision checks при обычном движении
- ✅ Субпиксельная точность при медленном движении
- ✅ Автоматическая адаптация под нагрузку
- ✅ Stable performance в сложных сценах
- ✅ Значения корректно отображаются в Debug HUD
- ✅ Результаты тестов отображаются в HUD

---

# Этап 15: Enhanced ground snapping
**Цель:** Плавное прилипание к неровным поверхностям
**Результат:** Персонаж идет по неровной геометрии без отрыва

**Что реализуем:**
- Multi-point ground detection
- Intelligent surface normal blending
- Smooth height transitions
- Predictive ground snapping
- Вывод необходимых значений в Debug HUD
- Вывод результатов тестов в HUD

**Критерии успеха:**
- ✅ Плавное движение по ступенькам
- ✅ Нет отрыва от неровной поверхности
- ✅ Smooth transitions на изменениях высоты
- ✅ Работает на любой сложности геометрии
- ✅ Значения корректно отображаются в Debug HUD
- ✅ Результаты тестов отображаются в HUD

---

# Этап 16: Система прыжков
**Цель:** Отзывчивое воздушное управление уровня лучших платформеров
**Результат:** Качественный платформинг с точным контролем

**Что реализуем:**
- Variable jump height (короткое/длинное нажатие)
- Air control с ограничениями и инерцией
- Coyote time (прыжок после покидания платформы)
- Jump buffering (ранние нажатия прыжка)
- Multi-jump система (опционально)
- Вывод необходимых значений в Debug HUD
- Вывод результатов тестов в HUD

**Критерии успеха:**
- ✅ Точный контроль высоты прыжка
- ✅ Forgiving jump timing (coyote + buffer)
- ✅ Responsive но не overpowered air control
- ✅ Плавные transitions между ground/air состояниями
- ✅ Значения корректно отображаются в Debug HUD
- ✅ Результаты тестов отображаются в HUD

---

# Этап 17: Custom Camera Collision System
**Цель:** Детерминированная замена SpringArm collision detection
**Результат:** Полный контроль над camera collision behavior

**Что реализуем:**
- Custom sphere trace от character к target camera position
- Smooth camera pull-in при collision с obstacles
- Character highlighting когда он за препятствием (Mario Odyssey style)
- Safe camera position recovery при застревании в геометрии
- Debug visualization для camera collision traces
- Integration с visual debug system

**Критерии успеха:**
- ✅ Камера никогда не проваливается сквозь препятствия
- ✅ Плавное приближение камеры при collision
- ✅ Character остается видимым (outline/highlight) когда за препятствием
- ✅ Детерминированное поведение на всех платформах
- ✅ Debug traces показывают camera collision queries
- ✅ Performance impact <0.1ms per frame

# Этап 18: Воздушная физика
**Цель:** Реалистичная но игровая воздушная физика
**Результат:** Естественное поведение в полете

**Что реализуем:**
- Air resistance и terminal velocity
- Wind/updraft systems
- Gliding механика
- Landing impact detection и анимации
- Air-to-ground transition smoothing
- Вывод необходимых значений в Debug HUD
- Вывод результатов тестов в HUD

**Критерии успеха:**
- ✅ Реалистичная траектория полета
- ✅ Плавные приземления без "хлопков"
- ✅ Terminal velocity ограничивает падение
- ✅ Responsive air control без нарушения физики
- ✅ Значения корректно отображаются в Debug HUD
- ✅ Результаты тестов отображаются в HUD

---

# Этап 19: Продвинутые склоны и поверхности
**Цель:** Сложные взаимодействия с геометрией
**Результат:** Разнообразные типы поверхностей

**Что реализуем:**
- Ice surfaces (скользкие поверхности с инерцией)
- Conveyor belts (движущиеся платформы)
- Bouncy surfaces (отскакивающие поверхности)
- Sticky surfaces (замедляющие движение)
- Slope acceleration/deceleration physics
- Вывод необходимых значений в Debug HUD
- Вывод результатов тестов в HUD

**Критерии успеха:**
- ✅ Каждый тип поверхности ощущается уникально
- ✅ Плавные переходы между типами поверхностей
- ✅ Детерминированное поведение всех типов
- ✅ Легкая настройка параметров поверхностей
- ✅ Значения корректно отображаются в Debug HUD
- ✅ Результаты тестов отображаются в HUD

---

# Этап 20: Wall interactions
**Цель:** Продвинутые взаимодействия со стенами
**Результат:** Wall jumping, wall sliding, wall climbing

**Что реализуем:**
- Wall jumping с momentum preservation
- Wall sliding с контролем скорости
- Wall climbing на специальных поверхностях
- Corner grabbing и edge detection
- Wall run система (опционально)
- Вывод необходимых значений в Debug HUD
- Вывод результатов тестов в HUD

**Критерии успеха:**
- ✅ Responsive wall jumping с правильными углами
- ✅ Контролируемое wall sliding
- ✅ Smooth transitions wall ↔ ground ↔ air
- ✅ Интуитивное управление wall mechanics
- ✅ Значения корректно отображаются в Debug HUD
- ✅ Результаты тестов отображаются в HUD

---

# Этап 21: Специальные движения
**Цель:** Уникальные движения для богатого геймплея
**Результат:** Dash, ground pound, ledge grab и другие

**Что реализуем:**
- Dash/dodge с invincibility frames
- Ground pound с area impact
- Ledge grabbing и climbing
- Slide/crouch движения
- Special movement abilities
- Вывод необходимых значений в Debug HUD
- Вывод результатов тестов в HUD

**Критерии успеха:**
- ✅ Каждое движение ощущается impact-ful
- ✅ Smooth combinations между движениями
- ✅ Balanced timing и cooldowns
- ✅ Clear visual и audio feedback
- ✅ Значения корректно отображаются в Debug HUD
- ✅ Результаты тестов отображаются в HUD

---

# Этап 22: Performance optimization
**Цель:** 60 FPS на целевом железе в любых сценариях
**Результат:** Оптимизированная система коллизий

**Что реализуем:**
- Spatial partitioning для collision objects
- LOD system для collision complexity
- Multi-threading collision checks
- Memory pool для collision queries
- Predictive collision culling
- Вывод необходимых значений в Debug HUD
- Вывод результатов тестов в HUD

**Критерии успеха:**
- ✅ Stable 60+ FPS на целевом железе
- ✅ <5ms на collision detection в worst case
- ✅ Scalable performance до 100+ collision objects
- ✅ Minimal memory allocations в runtime
- ✅ Значения корректно отображаются в Debug HUD
- ✅ Результаты тестов отображаются в HUD

---

# Этап 23: Debug и профилирование tools
**Цель:** Профессиональные инструменты для тонкой настройки
**Результат:** Полный контроль над системой

**Что реализуем:**
- Visual collision debugging (rays, sweeps, contacts)
- Real-time performance metrics и profiling
- Tweakable parameters в runtime через UI
- Automated testing suite для regression testing
- Replay system для детерминированности
- Вывод необходимых значений в Debug HUD
- Вывод результатов тестов в HUD

**Критерии успеха:**
- ✅ Visual debugging показывает все collision queries
- ✅ Real-time параметры настраиваются без restart
- ✅ Performance metrics точные и useful
- ✅ Automated tests покрывают все основные сценарии
- ✅ Значения корректно отображаются в Debug HUD
- ✅ Результаты тестов отображаются в HUD

---

# Этап 24: Edge cases и stress testing
**Цель:** Bullet-proof система для любых условий
**Результат:** Система работает в экстремальных сценариях

**Что реализуем:**
- Extreme velocity testing (10000+ units/sec)
- Complex geometry stress tests
- Memory leak detection и prevention
- Determinism verification tools
- Edge case handling (NaN, infinity, etc.)
- Вывод необходимых значений в Debug HUD
- Вывод результатов тестов в HUD

**Критерии успеха:**
- ✅ Система не ломается при экстремальных значениях
- ✅ No memory leaks при длительной работе
- ✅ Determinism поддерживается в любых условиях
- ✅ Graceful degradation при перегрузке
- ✅ Значения корректно отображаются в Debug HUD
- ✅ Результаты тестов отображаются в HUD

---

# Этап 25: User experience polish
**Время:** 3-4 дня | **Сложность:** Средняя  
**Цель:** Finalized user experience
**Результат:** Система ощущается как в коммерческой игре

**Что реализуем:**
- Input buffering и prediction
- Haptic feedback integration (геймпады)
- Audio feedback integration для movement
- Visual effects integration (dust, particles)
- Accessibility options
- Вывод необходимых значений в Debug HUD
- Вывод результатов тестов в HUD

**Критерии успеха:**
- ✅ Controls ощущаются максимально responsive
- ✅ Rich feedback для всех действий
- ✅ Поддержка различных input методов
- ✅ Accessibility options работают корректно
- ✅ Значения корректно отображаются в Debug HUD
- ✅ Результаты тестов отображаются в HUD

---