gameLogic.ts

Обзор

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

Основные задачи файла:

Описание базовых данных элементалей, их эволюций и локаций.
Управление коллекцией элементалей: создание, добавление, получение характеристик.
Механизмы прокачки уровня и повышения редкости с проверкой условий и расчетом стоимости.
Логика боя между элементалями с учетом стихийной системы и защиты элементалей.
Управление кулдаунами элементалей после использования в боях.
Генерация случайных наград и соперников.
Определение рангов, титулов и достижений игрока.

Файл является ключевым слоем бизнес-логики и тесно взаимодействует с UI-компонентами и другими частями игры, предоставляя им готовые функции и константы для игрового процесса.

Основные сущности и константы

Элементы (стихии)

export const ELEMENTS: Record<Element, ElementData>

Описывает базовые стихии: земля, вода и огонь.
Каждая стихия имеет имя, эмодзи и цвет.

Локации

export const LOCATIONS: Record<Location, LocationData>

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

Типы элементалей и эволюции

export const ELEMENTAL_TYPES: Record<Element, Record<ElementalRarity, ElementalData>>
export const EVOLUTION_STAGES: Record<Element, Record<ElementalRarity, EvolutionData[]>>

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

Функции управления коллекцией элементалей

`generateElementalId(element: Element, rarity: ElementalRarity): string`

Генерирует уникальный идентификатор для элементаля на основе его стихии, редкости и текущего времени.

Параметры:

element — стихия элементаля.
rarity — редкость элементаля.

Возвращаемое значение:

Уникальная строка ID.

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

const id = generateElementalId('fire', 'rare');

`createInitialCollection(): ElementalCollection`

Создаёт стартовую коллекцию элементалей для игрока, включая по одному элементалю каждого типа редкости "common".

Возвращаемое значение:

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

`addElementalToCollection(collection: ElementalCollection, element: Element, rarity: ElementalRarity): ElementalCollection`

Добавляет новый элементаль в коллекцию, генерируя для него уникальный ID и обновляя счётчики владения.

Параметры:

collection — текущая коллекция игрока.
element — стихия нового элементаля.
rarity — редкость нового элементаля.

Возвращаемое значение:

Обновлённая коллекция с добавленным элементалем.

Функции прокачки и развития элементалей

`getElementalProtection(elemental: CollectedElemental): number`

Возвращает процент защиты элементаля, зависящий от стихии и редкости.

`addExperienceToElemental(elemental: CollectedElemental, exp: number): CollectedElemental`

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

Параметры:

elemental — элементаль для прокачки.
exp — добавляемый опыт.

Возвращаемое значение:

Обновлённый элементаль с учётом нового опыта и уровня.

`getLevelUpCost(elemental: CollectedElemental): number`

Вычисляет стоимость повышения уровня элементаля в мане, с учётом редкости.

`getRarityUpgradeCost(currentRarity: ElementalRarity): number`

Возвращает стоимость повышения редкости элементаля на следующую ступень.

`canLevelUpElemental(elemental: CollectedElemental, playerMana: number): boolean`

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

`levelUpElemental(elemental: CollectedElemental): CollectedElemental`

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

`getNextRarity(currentRarity: ElementalRarity): ElementalRarity`

Возвращает следующую редкость для элементаля или оставляет "immortal" без изменений.

`getMaxLevelForRarity(rarity: ElementalRarity): number`

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

Система кулдауна (Cooldown)

`getElementalCooldownHours(rarity: ElementalRarity): number`

Возвращает длительность кулдауна в часах для элементаля заданной редкости.

`setElementalCooldown(elemental: CollectedElemental): CollectedElemental`

Устанавливает время окончания кулдауна для элементаля на основе текущего времени и длительности.

`isElementalOnCooldown(elemental: CollectedElemental): boolean`

Проверяет активен ли кулдаун у элементаля.

`getElementalCooldownRemaining(elemental: CollectedElemental): number`

Возвращает остаток времени кулдауна в миллисекундах.

`formatCooldownTime(milliseconds: number): string`

Форматирует время кулдауна для отображения (например, "2h 30m" или "Ready").

`getElementalCooldownProgress(elemental: CollectedElemental): number`

Возвращает прогресс кулдауна в процентах для визуального отображения.

Механика боя и соперники

`getWinner(element1: Element, element2: Element): BattleResult`

Определяет победителя по стихиям согласно правилу: земля > вода > огонь > земля. Возвращает "player", "opponent" или "draw".

`generateOpponent(location: Location): Opponent`

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

`getRandomElement(): Element`

Возвращает случайный элемент из доступных стихий.

`getRandomElementalReward(): { element: Element; rarity: ElementalRarity }`

Генерирует случайную награду в виде элементаля с вероятностями для разных редкостей.

`calculateBattleResult(...)`

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

Параметры:

baseWager: ставка маны.
playerElement: стихия игрока.
playerElemental: редкость элементаля игрока (или null).
opponentElement: стихия соперника.
opponentElemental: редкость элементаля соперника (или null).
playerCollection: коллекция игрока (для получения защиты).

Возвращаемое значение:

Объект с изменениями маны (playerManaChange, opponentManaChange), победителем (winner) и сохранённой защитой (protectionSaved).

Система рангов и титулов

`getRank(level: number): string`

Возвращает ранг игрока по уровню: Novice, Adept, Expert, Master.

`getTitle(wins: number, winStreak: number): string`

Возвращает титул игрока в зависимости от количества побед и серии побед.

Достижения

`getAchievementDefinitions(): Achievement[]`

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

Вспомогательные функции

getAvailableElementals(element: Element): ElementalRarity[] — список доступных редкостей для стихии.
getElementalData(element: Element, rarity: ElementalRarity): ElementalData — получение данных элементаля.
calculateProtectedMana(wager, element, elementalRarity): number — вычисление количества маны, защищённой элементалем.
getElementalProtectionFromCollection(collection, element, rarity): number — защита элементаля из коллекции.
canAffordLocation(playerMana, location): boolean — проверка доступности локации по мане.
getAvailableMana(playerMana, selectedLocation): number — доступная мана после оплаты локации.

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

UI-компоненты (например, CollectionTab.tsx, BattleComponent.tsx) используют функции из этого файла для реализации игрового процесса, отображения коллекции, прокачки и боёв.
Типы импортируются из types.ts для строгой типизации сущностей.
Используется глобальный объект window.triggerCardVibration для вибрационной обратной связи после прокачки.
Логика боя и генерации противников интегрирована с визуальными компонентами анимации и экранами результатов.

Визуальная структура — диаграмма классов и функций

classDiagram
    class gameLogic {
        <<module>>
        +ELEMENTS: Record<Element, ElementData>
        +LOCATIONS: Record<Location, LocationData>
        +ELEMENTAL_TYPES: Record<Element, Record<ElementalRarity, ElementalData>>
        +EVOLUTION_STAGES: Record<Element, Record<ElementalRarity, EvolutionData[]>>
        +generateElementalId(element: Element, rarity: ElementalRarity): string
        +createInitialCollection(): ElementalCollection
        +addElementalToCollection(collection: ElementalCollection, element: Element, rarity: ElementalRarity): ElementalCollection
        +getElementalProtection(elemental: CollectedElemental): number
        +addExperienceToElemental(elemental: CollectedElemental, exp: number): CollectedElemental
        +getLevelUpCost(elemental: CollectedElemental): number
        +getRarityUpgradeCost(currentRarity: ElementalRarity): number
        +canLevelUpElemental(elemental: CollectedElemental, playerMana: number): boolean
        +levelUpElemental(elemental: CollectedElemental): CollectedElemental
        +getNextRarity(currentRarity: ElementalRarity): ElementalRarity
        +getMaxLevelForRarity(rarity: ElementalRarity): number
        +getElementalCooldownHours(rarity: ElementalRarity): number
        +setElementalCooldown(elemental: CollectedElemental): CollectedElemental
        +isElementalOnCooldown(elemental: CollectedElemental): boolean
        +getElementalCooldownRemaining(elemental: CollectedElemental): number
        +formatCooldownTime(milliseconds: number): string
        +getElementalCooldownProgress(elemental: CollectedElemental): number
        +getRandomElementalReward(): {element: Element, rarity: ElementalRarity}
        +getWinner(element1: Element, element2: Element): BattleResult
        +generateOpponent(location: Location): Opponent
        +getRandomElement(): Element
        +getRank(level: number): string
        +getTitle(wins: number, winStreak: number): string
        +getAchievementDefinitions(): Achievement[]
        +getAvailableElementals(element: Element): ElementalRarity[]
        +getElementalData(element: Element, rarity: ElementalRarity): ElementalData
        +calculateProtectedMana(wager: number, element: Element | null, elementalRarity: ElementalRarity | null): number
        +getElementalProtectionFromCollection(collection: ElementalCollection, element: Element, rarity: ElementalRarity): number
        +calculateBattleResult(baseWager: number, playerElement: Element, playerElemental: ElementalRarity | null,
                              opponentElement: Element, opponentElemental: ElementalRarity | null, playerCollection?: ElementalCollection):
                              {playerManaChange: number, opponentManaChange: number, winner: BattleResult, protectionSaved: number}
        +canAffordLocation(playerMana: number, location: Location): boolean
        +getAvailableMana(playerMana: number, selectedLocation: Location | null): number
    }

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

Проверка возможности прокачки элементаля

const canLevelUp = canLevelUpElemental(myElemental, player.mana);
if (canLevelUp) {
  // Можно открыть модальное окно прокачки
}

Повышение уровня или редкости элементаля

const leveledUpElemental = levelUpElemental(myElemental);
// Обновить коллекцию элементалей с новым элементалем

Расчёт результата боя

const battleResult = calculateBattleResult(
  wager,
  playerElement,
  playerElementalRarity,
  opponentElement,
  opponentElementalRarity,
  playerCollection
);

if (battleResult.winner === 'player') {
  console.log('Победа!');
}

Итог

gameLogic.ts — это ядро бизнес-логики игры, обеспечивающее полный набор функций для управления коллекцией элементалей, их прокачкой, проведением боёв и системой достижений. Благодаря строгой типизации и детальному учёту игровых правил, модуль служит надёжной основой для UI и серверной части игры, обеспечивая масштабируемость и простоту поддержки.

Конец документации файла gameLogic.ts