App.tsx

Обзор файла

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

Основная функциональность

• Инициализация и хранение состояния игрока и текущего состояния игры.

• Обработка выбора локаций, элементов и элементалей.

• Запуск и обработка боёв с противниками.

• Управление уведомлениями об достижениях, повышениях уровней и получении новых элементалей.

• Управление показом обучающих туториалов.

• Сохранение и загрузка состояния игры и настроек из localStorage.

• Управление вкладками интерфейса и переходами между игровыми фазами.

• Включение/отключение фоновой музыки с учётом взаимодействия пользователя.

Ключевые компоненты и методы

Константы

• INITIAL_PLAYER: начальные параметры игрока, включая имя, ману, статистику, коллекцию элементалей и достижения.

Компонент App

Главный функциональный React-компонент, реализующий логику игры и связывающий UI с бизнес-логикой.

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

• activeTab: текущая активная вкладка интерфейса (профиль, бой, коллекция, настройки).

• gameState: объект текущего состояния игры, включая игрока, оппонента, фазу игры, лог боя и др.

• newAchievements: массив новых достижений для отображения уведомлений.

• levelUp: номер нового уровня при повышении игрока.

• newElementalReward: информация о недавно полученном элементале.

• musicEnabled: флаг включения фоновой музыки.

• userInteracted: флаг первого взаимодействия пользователя (для активации музыки).

• rulesPageOpen: флаг открытия страницы правил.

• musicVolume: уровень громкости музыки.

• Состояния туториалов: отображение и флаги просмотра для боевого и коллекционного туториалов.

Хуки эффекта (useEffect)

• Загрузка состояния игры, настроек аудио и туториалов из localStorage при монтировании.

• Автоматическое сохранение состояния игры, настроек аудио и туториалов в localStorage при изменениях.

• Управление CSS классом modal-open для тела документа при открытии/закрытии страницы правил.

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

• Автоматическое скрытие уведомления о новом элементале через 5 секунд.

Основные функции (useCallback)

updatePlayer(updates: Partial<PlayerStats>): void

Обновляет состояние игрока с учётом новых параметров, рассчитывает изменения маны, опыта, уровней, достижений и статистики. Автоматически обновляет уведомления о достижениях и повышениях уровней.

Параметры:

• updates — частичный объект с обновлениями полей игрока.

Пример использования:

updatePlayer({ mana: 1800, wins: 5 });

selectLocation(location: Location): void

Позволяет игроку выбрать локацию для боя, если у него достаточно маны. Переводит состояние игры в фазу выбора элемента.

selectElement(element: Element): void

Выбирает элемент для боя.

selectElemental(elemental: ElementalRarity | null): void

Выбирает элементаля из коллекции для боя.

returnToLocationSelection(): void

Возвращает игрока к выбору локации, сбрасывая выбор элемента и элементаля.

returnToElementSelection(): void

Возвращает игрока к выбору элемента, сбрасывая выбор элементаля.

startBattleProcess(): void

Запускает процесс боя: проверяет наличие выбранной локации и элемента, достаточно ли маны для ставки, создаёт оппонента и переводит игру в фазу выбора элементаля.

startBattle(): void

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

onBattleAnimationComplete(): void

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

returnToMenu(): void

Возвращает игру в главное меню, сбрасывает выборы и очищает состояние оппонента и лога боя.

handleTabChange(tab: 'profile' | 'battle' | 'collection' | 'settings'): void

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

dismissAchievement(achievementId: string): void

Закрывает уведомление об указанном достижении.

dismissElementalReward(): void

Закрывает уведомление о новом элементале.

levelUpElementalById(elementalId: string): void

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

Туториалы

• handleBattleTutorialComplete(), handleBattleTutorialSkip(): обработка завершения и пропуска боевого туториала.

• handleCollectionTutorialComplete(), handleCollectionTutorialSkip(): обработка завершения и пропуска коллекционного туториала.

• showBattleTutorialManually(), showCollectionTutorialManually(): ручной запуск туториалов.

resetGameCache(): void

Сбрасывает все сохранённые данные игры и настроек, восстанавливая первоначальное состояние приложения.

handleUserInteraction(): void

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

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

Компонент App импортирует и использует следующие внешние модули и компоненты:

• UI-компоненты из папки ./components/:

  • AchievementNotification, AudioPlayer, BattleAnimationPixi, BattleComponent, BattleResultPage, CollectionTab, GlassGradientHeader, Navigation, ProfileHeader, ProfileTab, RulesPage, SettingsTab, StepByStepTutorial, TutorialTooltip.

• Логика игры из ./gameLogic: функции для расчёта боя, управления коллекцией, получения случайных наград, проверки условий и пр.

• Типы из ./types: определения типов данных для элементов, редкости, состояния игры и статистики игрока.

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

Пример использования

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

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

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

• Система боёв основана на предварительном расчёте результата (вычисление победителя, изменения маны, защиты), а затем воспроизведении анимации и применении результата.

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

• Туториалы реализованы как отдельные компоненты с возможностью показа, пропуска и запоминания состояния просмотра.

• Сохранение и загрузка данных происходит с помощью localStorage для состояния игры, аудио и туториалов, обеспечивая сохранность прогресса между сессиями.

Структура компонентов и поток данных

componentDiagram
    App <|-- ProfileHeader
    App <|-- Navigation
    App <|-- GlassGradientHeader
    App <|-- AudioPlayer
    App <|-- RulesPage
    App <|-- ProfileTab
    App <|-- BattleComponent
    App <|-- BattleAnimationPixi
    App <|-- BattleResultPage
    App <|-- CollectionTab
    App <|-- SettingsTab
    App <|-- StepByStepTutorial
    App <|-- TutorialTooltip
    App o-- "gameLogic" : использует функции
    App o-- "types" : использует типы

    App : Управляет состоянием игры и интерфейса
    App : Обрабатывает выборы и действия пользователя
    App : Передаёт данные и колбеки дочерним компонентам
    App : Обрабатывает логику боя и обновляет игрока

Заключение

Файл App.tsx является сердцем приложения, объединяя пользовательский интерфейс с комплексной игровой логикой. Он обеспечивает управление всей жизненной циклом игры, от выбора параметров до ведения боёв и отображения достижений. Благодаря модульной структуре и разделению задач между компонентами и утилитами, приложение остаётся масштабируемым и удобным для поддержки.