Элементальная коллекция

Общее описание

Модуль "Элементальная коллекция" отвечает за управление коллекцией элементалей игрока — персонажей различных стихий и редкостей. Он обеспечивает функциональность фильтрации, отображения, прокачки и повышения уровня элементалей. Основная задача — предоставить игроку удобный интерфейс для обзора своих персонажей, выбора подходящих для прокачки и контроля ресурсов (маны), необходимых для улучшений.

Этот модуль решает несколько ключевых проблем:

• Удобное представление коллекции с возможностью фильтрации по стихиям и редкости.

• Контроль доступности ресурсов и проверка условий для прокачки.

• Обработка логики повышения уровня и редкости элементалей.

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

Как работает модуль

Фильтрация и отображение коллекции

Основной компонент интерфейса — CollectionTab.tsx. Он управляет состоянием выбранных фильтров по стихиям (selectedElement) и редкости (selectedRarity), а также текущим выбранным элементалем для прокачки.

• Игрок может фильтровать коллекцию с помощью кнопок, выбирая определённую стихию (земля, вода, огонь, или все) и/или редкость (common, rare, epic, immortal, или все).

• Отфильтрованный список элементалей сортируется по редкости (от самой редкой к самой распространённой) и элементу (для согласованности).

• Для каждого элементаля создаётся карточка CollectibleCard с отображением визуальных данных и кнопкой для прокачки.

const filteredElementals = ownedElementals
  .filter(elemental => {
    if (selectedElement !== 'all' && elemental.element !== selectedElement)
      return false;
    if (selectedRarity !== 'all' && elemental.rarity !== selectedRarity)
      return false;
    return true;
  })
  .sort(sortByRarity);

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

Прокачка и подтверждение улучшений

При нажатии на кнопку прокачки в карточке элементаля вызывается функция handleLevelUpClick, которая открывает модальное окно подтверждения прокачки (showConfirmModal).

• Модальное окно отображает текущий уровень, новый уровень после прокачки, стоимость в мане и остаток маны после списания.

• Если прокачка подразумевает повышение редкости (например, переход с common на rare), кнопка и заголовок модального окна меняются с "Level Up" на "Upgrade".

• Пользователь может подтвердить или отменить операцию.

• Подтверждение вызывает функцию onLevelUpElemental, переданную из родительского компонента, которая обновляет состояние коллекции (логика повышения реализована в gameLogic.ts).

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

const handleConfirmLevelUp = () => {
  if (selectedElemental && selectedDisplayData) {
    onLevelUpElemental(selectedElemental.id);
    setShowConfirmModal(false);
    // Вибрация карточки после прокачки
  }
};

Карточка элементаля (CollectibleCard.tsx)

Компонент карточки отображает:

• Изображение или эмодзи элементаля (если изображение не загрузилось).

• Редкость и элемент с соответствующими цветами.

• Индикатор таймера кулдауна (если персонаж на кулдауне после боя).

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

• Название персонажа, сформированное детерминированным образом на основе id, стихий и редкости.

• Краткое описание с параметром защиты.

Карточка также содержит логику вибрации для подтверждения прокачки, которая использует либо Telegram WebApp API (при запуске внутри Telegram), либо Web Vibration API в браузере.

Логика прокачки и ресурсов (gameLogic.ts)

В модуле бизнес-логики реализованы функции для:

• Определения стоимости прокачки уровня и повышения редкости.

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

• Повышения уровня или редкости элементаля с генерацией нового id при апгрейде редкости.

• Расчёта максимального уровня для каждой редкости (обычно до 4 для common, rare, epic, и 1 для immortal).

• Управления кулдаунами элементалей после использования в боях.

export const canLevelUpElemental = (
  elemental: CollectedElemental,
  playerMana: number
): boolean => {
  if (elemental.rarity === 'immortal') {
    return false;
  }

  const maxLevel = getMaxLevelForRarity(elemental.rarity);
  const canUpgradeRarity = elemental.level >= maxLevel;

  if (canUpgradeRarity) {
    const upgradeCost = getRarityUpgradeCost(elemental.rarity);
    return playerMana >= upgradeCost;
  }

  const levelUpCost = getLevelUpCost(elemental);
  return elemental.level < maxLevel && playerMana >= levelUpCost;
};

Таким образом, бизнес-логика обеспечивает правильное ограничение прокачки и экономическую балансировку.

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

• UI-компоненты: CollectionTab и CollectibleCard отвечают за визуализацию, пользовательское взаимодействие и вызовы функций обновления коллекции.

• Игровая логика (gameLogic.ts): предоставляет все необходимые функции для расчёта стоимости прокачки, проверки условий, генерации новых элементалей и управления коллекцией.

• Родительский компонент (например, App.tsx) передаёт данные игрока и функции обновления, а также обновляет состояние после прокачки.

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

• Модальные окна: реализации подтверждения прокачки используют React Portal для отображения модального окна поверх основного интерфейса.

Ключевые концепции и особенности

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

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

• Отдельное управление редкостью и уровнем: элементали сначала прокачиваются по уровню до максимума, после чего происходит повышение редкости с созданием нового экземпляра.

• Индивидуальные идентификаторы элементалей: при повышении редкости создаётся новый уникальный ID, что позволяет отслеживать развитие каждого персонажа.

• Кулдаун: после использования элементаль может быть временно заблокирован (находится на кулдауне), что отражается в UI и ограничивает его использование.

• Вибрация для обратной связи: расширяет пользовательский опыт, особенно на мобильных устройствах и в Telegram Mini Apps.

• Детерминированное имя персонажа: для каждого элементаля формируется стабильное уникальное имя на основе его id, стихий и редкости, создавая атмосферу и узнаваемость.

Визуализация процесса прокачки элементаля

sequenceDiagram
    participant User as Игрок
    participant UI as CollectionTab
    participant Card as CollectibleCard
    participant Logic as gameLogic.ts
    participant Parent as Родительский компонент

    User->>UI: Выбирает фильтры коллекции
    UI->>UI: Фильтрует и отображает элементалей
    User->>Card: Нажимает "Level Up" на карточке
    Card->>UI: Вызывает handleLevelUpClick
    UI->>UI: Открывает модальное окно подтверждения
    User->>UI: Подтверждает прокачку
    UI->>Parent: Вызывает onLevelUpElemental(elementalId)
    Parent->>Logic: levelUpElemental(elemental)
    Logic-->>Parent: Обновлённый элементаль или новый с повышенной редкостью
    Parent->>UI: Обновляет состояние игрока и коллекции
    UI->>Card: Триггерит вибрацию на карточке
    Card-->>User: Визуальная и тактильная обратная связь

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