tengri/Documentation/TechnicalDesign/TDD_Debug.md

Система Debug HUD - Техническая Документация

Обзор

Страничная debug система с UI-интерфейсом для мониторинга состояния Movement системы в реальном времени.

Архитектурные принципы

• Модульность: Debug система отделена от Movement логики
• Расширяемость: Легкое добавление новых debug страниц
• Производительность: Контролируемая частота обновления
• UX: Интуитивная навигация и адаптивный интерфейс

Компоненты системы

AC_DebugHUD (Core Component)

Ответственности:

• Управление состоянием debug системы
• Регистрация и управление debug страницами
• Обновление данных в реальном времени
• Коммуникация с UI Widget

Ключевые функции:

• InitializeDebugHUD() - Инициализация системы
• UpdateHUD() - Обновление каждый кадр
• ToggleDebugHUD() - Включение/выключение
• NextPage()/PreviousPage() - Навигация
• RegisterDebugPage() - Добавление новых страниц

WBP_DebugHUD (UI Widget)

Ответственности:

• Отображение debug информации
• Адаптивное изменение размера
• Обработка текстового контента

UI Структура:

Canvas Panel
└── Border
    └── MainContainer (Vertical Box)
        ├── HeaderTextBox (заголовок страницы)
        ├── Border
        ├── ContentTextBox (основной контент)
        ├── Border
        └── NavigationTextBox (подсказки навигации)

Система страниц

Movement Constants Page

• Max Speed, Acceleration, Friction, Gravity
• Статус инициализации компонента
• Источник: AC_Movement.MovementConstants

Surface Classification Page

• Пороги углов для всех типов поверхностей
• Walkable ≤50°, Steep 50°-85°, Wall 85°-95°, Ceiling >95°
• Источник: AC_Movement.AngleThresholdsDegrees

Performance Metrics Page

• Frame counter, FPS в реальном времени
• Частота обновления debug системы
• Количество активных страниц
• Источник: внутренние метрики AC_DebugHUD

Структуры данных

S_DebugPage

{
  PageID: E_DebugPageID           // Уникальный идентификатор
  Title: string                   // Заголовок страницы
  Content: string                 // Текстовый контент (поддержка \n)
  IsVisible: boolean              // Участие в навигации
  UpdateFunction: E_DebugUpdateFunction // Функция обновления
}

S_DebugSettings

{
  CurrentMode: E_DebugMode        // Hidden/Visible
  CurrentPageIndex: number        // Индекс текущей страницы
  ShowVisualDebug: boolean        // Отдельно от HUD
  UpdateFrequency: Float          // Hz (0 = каждый кадр)
}

Управление

Keyboard Controls

• Tab - Toggle Debug HUD
• PageUp - Previous Page
• PageDown - Next Page
• Home - Toggle Visual Debug

Gamepad Controls (опционально)

• LT+RT+A - Toggle Debug HUD
• LT+RT+DPad Left/Right - Navigate Pages
• LT+RT+Y - Toggle Visual Debug

Производительность

Оптимизации

• Update frequency control (default: каждый кадр)
• Size To Content для минимального UI footprint
• Lazy widget updates (только при изменении данных)
• Efficient page switching без пересоздания UI

Benchmarks

• Инициализация: <1ms
• Update per frame: <0.1ms
• Memory footprint: ~50KB
• FPS impact: <1% при включенном HUD

Расширяемость

Добавление новой страницы

1. Добавить enum в E_DebugPageID
2. Добавить update function в E_DebugUpdateFunction
3. Реализовать Update[Name]Page() в AC_DebugHUD
4. Добавить case в UpdateCurrentPage() switch
5. Зарегистрировать через RegisterDebugPage()

Пример:

// 1. Enum
E_DebugPageID.InputInfo = "InputInfo"

// 2. Update function
E_DebugUpdateFunction.UpdateInputPage = "UpdateInputPage"

// 3. Implementation
private UpdateInputPage(Page: S_DebugPage): S_DebugPage {
  return {
    ...Page,
    Content: `Current Input: ${this.GetCurrentInput()}\n` +
             `Input Buffer: ${this.GetInputBuffer()}`
  }
}

// 4. Registration
this.RegisterDebugPage({
  PageID: E_DebugPageID.InputInfo,
  Title: "Input System",
  Content: '',
  IsVisible: true,
  UpdateFunction: E_DebugUpdateFunction.UpdateInputPage
});

Тестирование

Автоматические тесты

• TestDebugSystem() - системные тесты
• TestPageContentGeneration() - генерация контента
• TestNavigation() - навигация между страницами
• RunAllTests() - полный набор тестов

Debug команды

• DebugCommand_RunTests() - запуск тестов
• DebugCommand_StressTest() - стресс тест

Manual Testing Checklist

• Инициализация системы
• Навигация по всем страницам
• Корректность данных на каждой странице
• Real-time обновления (FPS, Frame counter)
• Toggle функциональность
• Адаптивный размер UI
• Производительность

Известные ограничения

1. Текстовый интерфейс: Только text-based debug info
2. Статические страницы: Страницы регистрируются при инициализации
3. Одиночный Widget: Один debug HUD на экран

Планы развития (Этап 3+)

1. Toast Messages система - Временные уведомления
2. Visual Debug элементы - Линии, сферы, collision shapes
3. Interactive элементы - Кнопки, слайдеры для real-time настройки
4. Сохранение настроек - Persistent debug preferences
5. Remote debugging - Debug через внешние инструменты

Интеграционные точки

С Movement System

• Получение Movement Constants
• Получение Angle Thresholds
• Real-time мониторинг состояния

С Input System

• Enhanced Input Actions для навигации
• Hotkey регистрация без конфликтов

С Game Framework

• Инициализация в BeginPlay
• Update в Tick
• Cleanup в EndPlay

Файловая структура

Content/
├── Debug/
│   ├── Components/
│   │   └── AC_DebugHUD.ts
│   ├── Enums/
│   │   ├── E_DebugMode.ts
│   │   ├── E_DebugPageID.ts
│   │   └── E_DebugUpdateFunction.ts
│   ├── Structs/
│   │   ├── S_DebugPage.ts
│   │   └── S_DebugSettings.ts
│   └── UI/
│       └── WBP_DebugHUD.ts
└── Movement/
    └── Blueprints/
        └── BP_MainCharacter.ts (integration point)