types.ts

Обзор файла

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

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

Описание типов и интерфейсов

Основные типы

• Element
  Тип, представляющий элементы в игре.
  Возможные значения: 'earth' | 'water' | 'fire'
  Используется для указания стихии элементаля или выбранного элемента игроком.

• Location
  Тип, описывающий возможные локации.
  Возможные значения: 'swamp' | 'village' | 'castle' | 'free'
  Применяется для выбора игрового места действия.

• ElementalRarity
  Тип, определяющий редкость элементаля.
  Возможные значения: 'common' | 'rare' | 'epic' | 'immortal'
  Влияет на характеристики и ценность элементаля.

Интерфейсы данных

ElementData

interface ElementData {
  name: string;
  emoji: string;
  color?: string;
}

• Назначение: Описывает свойства элемента (стихии).

• Поля:

  • name — название элемента (например, "Earth").

  • emoji — эмодзи, символизирующий элемент.

  • color (опционально) — цветовое оформление элемента.

LocationData

interface LocationData {
  name: string;
  emoji: string;
  mana: number;
}

• Назначение: Данные о локации в игре.

• Поля:

  • name — название локации.

  • emoji — эмодзи для визуального представления.

  • mana — количество маны, доступное в локации.

ElementalData

interface ElementalData {
  name: string;
  emoji: string;
  rarity: string;
  protection: number;
  evolutionCost?: number;
  legendary?: boolean;
}

• Назначение: Хранит базовые характеристики элементаля.

• Поля:

  • name — имя элементаля.

  • emoji — эмодзи.

  • rarity — редкость элементаля (строка, обычно из ElementalRarity).

  • protection — уровень защиты.

  • evolutionCost (опционально) — стоимость эволюции.

  • legendary (опционально) — признак легендарности.

Система коллекций

CollectedElemental

interface CollectedElemental {
  id: string;
  element: Element;
  rarity: ElementalRarity;
  level: number;
  experience: number;
  isOwned: boolean;
  lastUsed?: number;
  timesUsed: number;
  cooldownEndTime?: number;
}

• Назначение: Представляет элементаля, собранного игроком.

• Поля:

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

  • element — стихия.

  • rarity — редкость.

  • level — уровень.

  • experience — накопленный опыт.

  • isOwned — флаг владения.

  • lastUsed (опционально) — время последнего использования (timestamp).

  • timesUsed — количество применений.

  • cooldownEndTime (опционально) — время окончания перезарядки.

ElementalCollection

interface ElementalCollection {
  elementals: Record<string, CollectedElemental>;
  totalOwned: number;
  totalImmortal: number;
  totalEpic: number;
  collectionProgress: Record<Element, number>;
}

• Назначение: Хранит всю коллекцию элементалей игрока.

• Поля:

  • elementals — словарь элементалей по их ID.

  • totalOwned — общее количество владений.

  • totalImmortal — количество бессмертных элементалей.

  • totalEpic — количество эпических элементалей.

  • collectionProgress — прогресс по каждому элементу.

EvolutionData

interface EvolutionData {
  stage: number;
  name: string;
  emoji: string;
  protection: number;
  cost: number;
  requiredLevel: number;
}

• Назначение: Данные для этапа эволюции элементаля.

• Поля:

  • stage — номер стадии эволюции.

  • name — имя стадии.

  • emoji — эмодзи.

  • protection — защита на этом этапе.

  • cost — стоимость эволюции.

  • requiredLevel — уровень, необходимый для перехода.

Статистика и игрок

PlayerStats

interface PlayerStats {
  name: string;
  avatar?: string;
  mana: number;
  wins: number;
  losses: number;
  selectedElement: Element | null;
  selectedLocation: Location | null;
  selectedElemental: ElementalRarity | null;
  winStreak: number;
  bestStreak: number;
  maxLossStreak: number;
  currentLossStreak: number;
  totalBattles: number;
  experience: number;
  level: number;
  favoriteElement: string | null;
  elementStats: Record<Element, number>;
  achievements: string[];
  lastManaChange: number;
  totalManaWon: number;
  totalManaLost: number;
  elementalCollection: ElementalCollection;
  totalElementalsCollected: number;
  immortalElementalsOwned: number;
  epicElementalsOwned: number;
}

• Назначение: Описывает профиль и прогресс игрока.

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

Противник

interface Opponent {
  name: string;
  avatar: string;
  level: number;
  rarity: string;
  wager: number;
  element?: Element;
  elemental?: ElementalRarity;
}

• Назначение: Информация об оппоненте в бою.

• Поля: Имя, аватар, уровень, редкость, ставка, а также опционально элемент и редкость элементаля.

Отображение элементаля

interface ElementalDisplayData {
  currentName: string;
  currentEmoji: string;
  currentProtection: number;
  canLevelUp: boolean;
  levelUpCost: number;
  maxLevel: number;
  canUpgradeRarity: boolean;
  isImmortal: boolean;
}

• Назначение: Данные для UI по отображению состояния элементаля.

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

Достижения

interface Achievement {
  id: string;
  icon: string;
  name: string;
  desc: string;
  condition: (player: PlayerStats) => boolean;
}

• Назначение: Определяет достижение, которое может быть получено игроком.

• Поля:

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

  • icon — иконка достижения.

  • name — название.

  • desc — описание.

  • condition — функция проверки выполнения условия достижения по состоянию игрока.

Лог боя

interface BattleLog {
  playerElement: Element;
  opponentElement: Element;
  playerElemental: ElementalRarity | null;
  opponentElemental: ElementalRarity | null;
  baseWager: number;
  protectionSaved: number;
  finalChange: number;
  winner: BattleResult;
}

• Назначение: Запись результатов и параметров конкретного боя.

• Поля: Элементы игроков и оппонентов, ставки, защита, итоговые изменения, результат боя.

Состояние игры

interface GameState {
  player: PlayerStats;
  currentOpponent: Opponent | null;
  opponentElement: Element | null;
  gamePhase: GamePhase;
  battleLog: BattleLog | null;
  initialBattleMana?: number;
  battleResult?: BattleResult;
}

• Назначение: Хранит текущее состояние игры, включая игрока, оппонента, фазу игры и результаты.

• Поля: Объекты игроков и оппонентов, текущая фаза и логи боя.

Перечисления

• GamePhase

type GamePhase =
  | 'menu'
  | 'locationSelection'
  | 'elementSelection'
  | 'elementalSelection'
  | 'battleAnimation'
  | 'result'
  | 'collection';

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

• BattleResult

type BattleResult = 'player' | 'opponent' | 'draw';

• Возможные исходы боя.

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

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

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

• ElementalCollection организован как словарь для быстрого доступа к элементалям по ID.

• Поля времени (lastUsed, cooldownEndTime) представлены в виде timestamp для удобства вычислений и синхронизации.

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

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

• Основные игровые механики (выбор элементов, локаций, боёв, коллекций) опираются на типы и интерфейсы из этого файла для описания и валидации данных.

• Интерфейсы состояния (GameState, PlayerStats, Opponent) используются в логике управления состоянием (например, в Redux или контексте React).

• Типы коллекций и элементалей взаимодействуют с UI-компонентами для отображения данных и с бизнес-логикой для изменения характеристик игрока.

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

• Боевая система использует BattleLog и BattleResult для записи и обработки результатов сражений.

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

const player: PlayerStats = {
  name: "Игрок1",
  mana: 100,
  wins: 5,
  losses: 2,
  selectedElement: "fire",
  selectedLocation: "castle",
  selectedElemental: "epic",
  winStreak: 3,
  bestStreak: 4,
  maxLossStreak: 2,
  currentLossStreak: 0,
  totalBattles: 7,
  experience: 1500,
  level: 10,
  favoriteElement: "fire",
  elementStats: { earth: 3, water: 2, fire: 5 },
  achievements: [],
  lastManaChange: Date.now(),
  totalManaWon: 300,
  totalManaLost: 100,
  elementalCollection: {
    elementals: {},
    totalOwned: 0,
    totalImmortal: 0,
    totalEpic: 0,
    collectionProgress: { earth: 0, water: 0, fire: 0 }
  },
  totalElementalsCollected: 0,
  immortalElementalsOwned: 0,
  epicElementalsOwned: 0
};

Диаграмма структуры файла

classDiagram
    class ElementData {
        +name: string
        +emoji: string
        +color?: string
    }
    class LocationData {
        +name: string
        +emoji: string
        +mana: number
    }
    class ElementalData {
        +name: string
        +emoji: string
        +rarity: string
        +protection: number
        +evolutionCost?: number
        +legendary?: boolean
    }
    class CollectedElemental {
        +id: string
        +element: Element
        +rarity: ElementalRarity
        +level: number
        +experience: number
        +isOwned: boolean
        +lastUsed?: number
        +timesUsed: number
        +cooldownEndTime?: number
    }
    class ElementalCollection {
        +elementals: Record<string, CollectedElemental>
        +totalOwned: number
        +totalImmortal: number
        +totalEpic: number
        +collectionProgress: Record<Element, number>
    }
    class EvolutionData {
        +stage: number
        +name: string
        +emoji: string
        +protection: number
        +cost: number
        +requiredLevel: number
    }
    class PlayerStats {
        +name: string
        +avatar?: string
        +mana: number
        +wins: number
        +losses: number
        +selectedElement: Element | null
        +selectedLocation: Location | null
        +selectedElemental: ElementalRarity | null
        +winStreak: number
        +bestStreak: number
        +maxLossStreak: number
        +currentLossStreak: number
        +totalBattles: number
        +experience: number
        +level: number
        +favoriteElement: string | null
        +elementStats: Record<Element, number>
        +achievements: string[]
        +lastManaChange: number
        +totalManaWon: number
        +totalManaLost: number
        +elementalCollection: ElementalCollection
        +totalElementalsCollected: number
        +immortalElementalsOwned: number
        +epicElementalsOwned: number
    }
    class Opponent {
        +name: string
        +avatar: string
        +level: number
        +rarity: string
        +wager: number
        +element?: Element
        +elemental?: ElementalRarity
    }
    class ElementalDisplayData {
        +currentName: string
        +currentEmoji: string
        +currentProtection: number
        +canLevelUp: boolean
        +levelUpCost: number
        +maxLevel: number
        +canUpgradeRarity: boolean
        +isImmortal: boolean
    }
    class Achievement {
        +id: string
        +icon: string
        +name: string
        +desc: string
        +condition(player: PlayerStats): boolean
    }
    class BattleLog {
        +playerElement: Element
        +opponentElement: Element
        +playerElemental: ElementalRarity | null
        +opponentElemental: ElementalRarity | null
        +baseWager: number
        +protectionSaved: number
        +finalChange: number
        +winner: BattleResult
    }
    class GameState {
        +player: PlayerStats
        +currentOpponent: Opponent | null
        +opponentElement: Element | null
        +gamePhase: GamePhase
        +battleLog: BattleLog | null
        +initialBattleMana?: number
        +battleResult?: BattleResult
    }

    PlayerStats --> ElementalCollection
    GameState --> PlayerStats
    GameState --> Opponent
    GameState --> BattleLog
    Achievement ..> PlayerStats : condition

Заключение

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