Project Overview

Цели и назначение проекта

Данный проект представляет собой веб-приложение — игру жанра "элементальная битва" с коллекционированием, развитием и сражениями персонажей-элементалей. Цель проекта — создать интерактивное, визуально привлекательное и технически устойчивое игровое пространство, в котором пользователь может:

• Управлять коллекцией элементалей различных стихий и редкостей;

• Участвовать в пошаговых битвах, выбирая локации и элементали для сражений;

• Развивать и прокачивать своих персонажей, повышая их уровень, редкость и способности;

• Получать достижения и просматривать подробную статистику;

• Настраивать игровой процесс и взаимодействовать с обучающими подсказками и туториалами.

Основные функциональные возможности реализованы через React-компоненты, обеспечивающие UI/UX, и бизнес-логику, сосредоточенную в модуле gameLogic.ts. Архитектура построена с упором на удобство расширения и поддержку различных фаз игры: от меню и выбора до анимаций и отображения результатов.

Пример рабочих сценариев и use cases

Сценарий битвы

1. Игрок выбирает локацию для битвы через интерфейс выбора (BattleComponent).

2. Затем выбирает элемент (земля, вода, огонь) и конкретного элементаля из своей коллекции.

3. После подтверждения начинается анимация битвы (BattleAnimationPixi), где визуально демонстрируются фазы боя.

4. Результаты битвы отображаются в компоненте BattleResultPage с подробной статистикой и изменениями в ресурсах.

5. Игрок получает опыт, ману, возможно, новые элементали или достижения.

Прокачка коллекции

• Вкладка коллекции (CollectionTab) позволяет просматривать все собранные элементали, фильтровать по стихиям и редкости.

• Для выбранного элементаля можно инициировать повышение уровня или редкости, при этом проверяется достаточность ресурсов (маны).

• Уровень и редкость влияет на боевые характеристики, которые учитываются в логике битвы.

Обучение пользователя

• При первом запуске или по запросу активируется пошаговый туториал (StepByStepTutorial, TutorialTooltip), который выделяет элементы интерфейса, отображает подсказки и контролирует прогресс обучения.

• Туториал охватывает ключевые этапы: выбор локации, выбор элемента, выбор элементаля и старт боя.

Стек и используемые технологии

• React + TypeScript — основной фреймворк для построения UI, обеспечивающий типизацию и модульность.

• PixiJS — библиотека для рендеринга 2D-графики и анимаций в битвах, используемая в BattleAnimationPixi и BattleEffects.

• CSS (модули и глобальные стили) — для стилизации интерфейса, включая поддержку адаптивности, анимаций и доступности.

• Node.js (для сборки и тестов) — скрипт test-setup.js использует Node.js утилиты для проверки качества кода (TS компиляция, ESLint, Prettier, тесты).

• Telegram Web App API — интеграция для вибрации и взаимодействия с Telegram Mini Apps (в компонентах с тактильной обратной связью).

• ReactDOM Client — для рендера приложения в DOM.

Выбор React обусловлен модульностью, широким сообществом и удобством создания интерактивных SPA. PixiJS применяется для высокопроизводительной графики, недоступной стандартными средствами React. TypeScript обеспечивает надежность и удобство разработки.

Высокоуровневая архитектура

Архитектура приложения разделена на несколько ключевых слоев и модулей:

• Frontend (React-компоненты) — UI и управление состоянием:

  • Основной компонент App.tsx управляет состоянием игры и переключением вкладок.

  • Вкладки: ProfileTab, CollectionTab, BattleComponent, SettingsTab, RulesPage.

  • Вспомогательные компоненты: Modal, Navigation, AudioPlayer, TutorialTooltip, AchievementNotification.

  • Анимации битвы и эффектов: BattleAnimationPixi с использованием PixiJS, BattleEffects.

• Game Logic (gameLogic.ts) — ядро бизнес-логики игры:

  • Определение элементов, локаций, редкостей, правил прокачки и боевых взаимодействий.

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

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

• Типы и интерфейсы (types.ts) — централизованное описание структур данных, обеспечивающее строгую типизацию.

• Стилизация (App.css, index.css) — глобальные и компонентные стили с поддержкой адаптивности и доступности.

• Тесты и качество кода (test-setup.js) — скрипт для проверки соответствия кода стандартам и успешного прохождения тестов.

Взаимодействия между компонентами организованы через пропсы и состояние React, бизнес-логика вызывается из компонентов по мере необходимости.

graph TB
    Browser[Browser React App]
    subgraph Frontend
        App["App.tsx (корневой компонент)"]
        Navigation["Navigation"]
        ProfileTab["ProfileTab"]
        CollectionTab["CollectionTab"]
        BattleComponent["BattleComponent"]
        BattleAnimationPixi["BattleAnimationPixi (PixiJS Анимация)"]
        SettingsTab["SettingsTab"]
        AchievementNotification["AchievementNotification"]
        TutorialTooltip["TutorialTooltip"]
        Modal["Modal"]
        AudioPlayer["AudioPlayer"]
    end
    subgraph Backend Logic
        GameLogic["gameLogic.ts (игровая логика)"]
        Types["types.ts (типизация)"]
    end
    subgraph Styling
        CssFiles["App.css, index.css"]
    end

    Browser --> App
    App --> Navigation
    App --> ProfileTab
    App --> CollectionTab
    App --> BattleComponent
    BattleComponent --> BattleAnimationPixi
    BattleAnimationPixi --> BattleEffects["BattleEffects (PixiJS эффекты)"]
    App --> SettingsTab
    App --> AchievementNotification
    App --> TutorialTooltip
    App --> Modal
    App --> AudioPlayer

    App --> GameLogic
    BattleComponent --> GameLogic
    CollectionTab --> GameLogic
    BattleAnimationPixi --> GameLogic

    App --> CssFiles

Навигация для разработчиков

Для Frontend-разработчиков

• Изучайте src/App.tsx — основной контроллер приложения, управляющий состояниями и вкладками.

• Работа с UI:

  • src/components/ — каталог с компонентами React.

  • Основные вкладки: ProfileTab.tsx, CollectionTab.tsx, BattleComponent.tsx, SettingsTab.tsx, RulesPage.tsx.

  • Анимации: BattleAnimationPixi.tsx, BattleEffects.tsx.

  • Вспомогательные: Modal.tsx, Navigation.tsx, AudioPlayer.tsx, TutorialTooltip.tsx.

• Стили: src/App.css, src/index.css.

• Для адаптивности и доступности обратите внимание на CSS-переменные и медиазапросы.

• Для реализации новых UI-элементов смотрите примеры в существующих компонентах.

Для Backend / Логики игры

• Основной модуль: src/gameLogic.ts — здесь реализованы все правила игры, генерация оппонентов, расчеты боёв, управление коллекцией и достижениями.

• Типы и интерфейсы: src/types.ts для строгой типизации данных.

• Логика вызвана из React-компонентов для обновления UI и состояния.

• Для добавления новых игровых правил, элементов или улучшений — начинайте изменения с gameLogic.ts.

Для тестирования и качества кода

• Скрипт test-setup.js запускает компиляцию TypeScript, линтинг, форматирование, тесты и сборку.

• HTML-файл interactive_test.html позволяет вручную проверить UX/UI и серверные статусы.

• Соблюдайте стандарты кода, используйте ESLint и Prettier согласно конфигурации.

Диаграмма ключевого рабочего процесса (пример: бой)

flowchart TD
    Start[Начало боя]
    SelectLocation[Выбор локации]
    SelectElement[Выбор элемента]
    SelectElemental[Выбор элементаля]
    BattleAnimation[Анимация боя (PixiJS)]
    BattleResult[Отображение результата]
    UpdateStats[Обновление статистики и достижений]
    End[Конец]

    Start --> SelectLocation --> SelectElement --> SelectElemental --> BattleAnimation --> BattleResult --> UpdateStats --> End

Данный обзор позволит разработчикам быстро получить понимание структуры, ключевых компонентов и рабочих процессов проекта, а также эффективно ориентироваться для внесения изменений и расширений.