DemoController.tsx

Обзор

DemoController.tsx — это React-компонент, реализующий пользовательский интерфейс и логику управления демонстрационной (демо) сессией для различных игровых персонажей (персон). Компонент позволяет пользователю выбирать персону, запускать, приостанавливать и сбрасывать последовательность демонстрационных шагов, которые моделируют игровые действия для выбранной персоны. Визуально отображается прогресс выполнения шагов, а также текущий статус сети.

Компонент тесно интегрирован с источником данных о персонажах и демо-действиях (demo-personas.json), а также использует иконки из библиотеки lucide-react для улучшения UX.

Описание компонентов и функций

Интерфейсы

DemoStep

interface DemoStep {
  id: string;
  title: string;
  description: string;
  duration: number;
  action: () => void;
  completed: boolean;
}

• Описывает один шаг демонстрации.

• Свойства:

  • id: уникальный идентификатор шага.

  • title: название шага.

  • description: описание шага (включая стоимость и ожидаемый результат).

  • duration: длительность шага в секундах (фиксировано 30 секунд).

  • action: функция, вызываемая для выполнения действия шага.

  • completed: флаг, указывающий, выполнен ли шаг.

DemoControllerProps

interface DemoControllerProps {
  onPersonaChange: (persona: string) => void;
  onStepExecute: (step: DemoStep) => void;
  currentPersona: string;
}

• Свойства, передаваемые в компонент DemoController.

• Свойства:

  • onPersonaChange: callback при смене персонажа, принимает ключ персона.

  • onStepExecute: callback при выполнении шага, принимает объект шага.

  • currentPersona: строка, определяющая текущего выбранного персонажа.

Главный компонент: DemoController

export default function DemoController({ onPersonaChange, onStepExecute, currentPersona }: DemoControllerProps)

Назначение

Управляет демонстрационным процессом: выбором персонажа, списком шагов, контролем воспроизведения, отслеживанием времени и выполнением игровых действий.

Состояния (React useState)

• isPlaying: boolean — флаг, указывающий, запущена ли демонстрация.

• currentStep: number — индекс текущего шага в списке.

• elapsedTime: number — прошедшее время с начала демонстрации (в секундах).

• demoSteps: DemoStep[] — массив шагов для текущей персоны.

Основные эффекты (React useEffect)

• При изменении currentPersona:

  • Загружаются соответствующие шаги из файла demo-personas.json.

  • Каждый шаг создаётся на основе массива demoActions персоны.

  • Шагам назначается длительность 30 секунд и функция executeAction.

  • Сбрасывается текущий шаг на 0.

• При изменении isPlaying:

  • Запускается или останавливается таймер, увеличивающий elapsedTime каждую секунду.

Основные методы

• executeAction(action: any): void
  Вызывается для "выполнения" действия (здесь реализована заглушка с console.log). В реальном приложении должна инициировать игровые процессы.

• startDemo(): void
  Запускает демонстрацию, сбрасывая время.

• pauseDemo(): void
  Приостанавливает демонстрацию.

• resetDemo(): void
  Сбрасывает демонстрацию в начальное состояние: останавливает проигрывание, сбрасывает шаг и время, помечает все шаги как не выполненные.

• nextStep(): void
  Выполняет текущий шаг:

  • Помечает его как завершённый.

  • Вызывает onStepExecute с текущим шагом.

  • Переходит к следующему шагу или останавливает демонстрацию, если шагов больше нет.

• formatTime(seconds: number): string
  Форматирует секунды в строку М:СС. Используется для отображения времени.

Использование компонента

<DemoController
  currentPersona="casual_gamer"
  onPersonaChange={(persona) => console.log('Persona changed to', persona)}
  onStepExecute={(step) => console.log('Executed step', step)}
/>

• currentPersona — ключ персоны из demo-personas.json.

• onPersonaChange — вызывается при выборе другого персонажа.

• onStepExecute — вызывается при выполнении каждого шага.

Взаимодействие с другими частями системы

• demo-personas.json — основной источник данных о персонажах, их демо-действиях и статусе сети.

• InteractiveDemo — импортирован, но непосредственно в данном файле не используется. Возможно, связан с визуализацией демо-игры.

• GameProvider (useGame) — импортируется, но в коде не используется; вероятно, для доступа к игровому состоянию или API.

• lucide-react — библиотека иконок, используемых для визуального обозначения персонажей и управления (Play, Pause, Reset).

Важные детали реализации и алгоритмы

• Шаги демонстрации создаются динамически на основе выбранной персоны, что делает компонент универсальным для разных сценариев.

• Таймер реализован через setInterval, который обновляет состояние elapsedTime каждую секунду при включённом воспроизведении.

• Логика перехода между шагами гарантирует, что каждый шаг выполняется и отмечается как завершённый перед переходом к следующему.

• Визуальное оформление шагов меняется в зависимости от состояния: текущий, выполненный или ожидающий.

• Используется подход функциональных компонентов React с хуками для управления состоянием и побочными эффектами.

Структурная диаграмма компонента DemoController

classDiagram
    class DemoController {
        -isPlaying: boolean
        -currentStep: number
        -elapsedTime: number
        -demoSteps: DemoStep[]
        +startDemo(): void
        +pauseDemo(): void
        +resetDemo(): void
        +nextStep(): void
        +executeAction(action: any): void
        +formatTime(seconds: number): string
        +render(): JSX.Element
    }

    class DemoStep {
        +id: string
        +title: string
        +description: string
        +duration: number
        +action(): void
        +completed: boolean
    }

    DemoController ..> DemoStep : uses

Итог

Компонент DemoController.tsx предоставляет комплексный контроллер для управления демонстрационной сессией с выбором персонажей, последовательным выполнением шагов и визуализацией прогресса и состояния сети. Его гибкая архитектура позволяет легко адаптироваться под новые персональные демо-сценарии и интегрируется с остальными частями игрового приложения.