Arena Battle

Боевые багги на арене от третьего лица. 3D-шутер на Three.js с системой прокачки, достижениями и процедурными уровнями.

---

Скриншоты

---

Содержание

• Геймплей
• Особенности
• Управление
• Враги
• Оружие
• Пикапы
• Система звёзд
• Достижения
• Улучшения
• Технологии
• Архитектура
• Установка и запуск
• Сборка
• Разработка

---

Геймплей

Уничтожайте врагов на арене, собирайте пикапы и проходите уровни. После каждого уровня можно улучшить багги в мастерской. Цель — пройти все три уровня и получить золото.

• 3 уровня с нарастающей сложностью
• 3 типа врагов с разным поведением и характеристиками
• 5 видов пикапов для поддержки в бою
• 3 жизни — после гибели можно возродиться (до 3 раз)
• Система звёзд — бронза, серебро, золото за уровень
• 15 достижений за особые условия
• Мастерская — улучшения между уровнями

Особенности

• Процедурные арены — препятствия генерируются случайно
• Разрушаемые препятствия — можно стрелять по стенам и колоннам
• Event-driven архитектура — системы общаются через шину событий
• Чистая доменная логика — все правила изолированы от рендера
• Конфиг-драйвен дизайн — баланс правится в config-файлах без изменения кода
• Однофайловый билд — вся игра в единственном index.html
• Сохраняемый прогресс — статистика, достижения и улучшения в localStorage

Управление

Клавиша	Действие
W / ↑	Вперёд
S / ↓	Назад
A / ←	Поворот влево
D / →	Поворот вправо
Space / ЛКМ	Стрельба
Shift	Активировать щит
Esc	Пауза

Враги

Тип	Описание	Прочность	Скорость	Очки
Scout	Быстрый разведчик, слабый, но юркий	40 HP	7	100
Tank	Тяжёлый багги, медленный и прочный	120 HP	4	250
Boss	Финальный босс, огромный и опасный	500 HP	5	2000

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

Оружие

Название	Урон	Скорость стрельбы	Патроны	Радиус splash
Standard Cannon	25	2 выстр/с	30	—
Heavy Cannon	60	0.8 выстр/с	12	2.0
Rapid Fire	6	3 выстр/с	80	—

Heavy Cannon наносит splash-урон по площади.

Пикапы

Тип	Эффект	Время возрождения
❤️ Health	+40 HP	20 с
🛡️ Shield	Щит на 5 с	30 с
📦 Ammo	Полный боезапас	15 с
⚡ Speed Boost	Ускорение на 8 с	25 с
🔥 Rapid Fire	Ускоренная стрельба на 10 с	40 с

Система звёзд

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

Рейтинг	Условия
🥉 Бронза	Минимальный порог по очкам, времени и точности
🥈 Серебро	Выше порог по всем трём критериям
🥇 Золото	Максимальный порог по всем трём критериям

Достижения

Достижения выдаются единоразово при выполнении особых условий в бою.

Достижение	Условие
💀 Первая кровь	Уничтожьте первого врага
☠️ Бойня	Уничтожьте всех врагов на уровне
🎯 Охотник	Уничтожьте 10 Tank-ов всего
👑 Убийца боссов	Уничтожьте босса
💥 Двойная угроза	Уничтожьте 2+ врагов одним взрывом
🎖️ Меткий стрелок	80%+ точности за уровень
🏅 Глаз-алмаз	95%+ точности за уровень
🛡️ Безупречный	Без попаданий по вам
🧱 Неуязвимый	Ни разу не потеряв HP
⭐ Золотая лихорадка	Золото на любом уровне
🏆 Перфекционист	Золото на всех уровнях
📦 Жадина	Собрать все пикапы на уровне
🔥 Преданный делу	Сыграть 5 уровней
⚔️ Ветеран	Сыграть 10 уровней
🎖️ Тур службы	Пройти все уровни

Улучшения

Между уровнями открывается мастерская, где можно потратить накопленные очки на улучшения:

Улучшение	Макс. уровень	Эффект
🛡️ Броня	3	+50 HP за уровень
⚡ Двигатель	2	+1.5 к скорости за уровень
💥 Калибр	3	+15% к урону за уровень
📦 Боекомплект	2	+10 к патронам за уровень

Улучшения персистентны — сохраняются между сессиями и применяются ко всем последующим миссиям.

Технологии

Технология	Назначение
React 19	UI-слой и управление компонентами
Three.js + React Three Fiber	3D-рендеринг
TypeScript 5.9	Типизация
Zustand	Управление состоянием
Vite 7	Сборка и HMR
Tailwind CSS 4.1	Стилизация
vite-plugin-singlefile	Однофайловый билд

Физика: Кастомная (circle-circle коллизии) — без сторонних физических движков.

Анимации и эффекты:

• Процедурные частицы (взрывы, искры)
• Screen shake при попаданиях и взрывах
• 3D-туман и динамическое освещение

Архитектура

src/
├── config/          # Конфигурации (баланс, уровни, оружие, враги)
├── core/            # Инфраструктура (логгер, рандом, шедулер)
├── domain/
│   ├── entities/    # Доменные сущности (Player, Enemy, Projectile...)
│   ├── rules/       # Чистые функции правил (DamageRules, StarRating)
│   └── types/       # Базовые типы (Vec3, Result, Faction...)
├── events/          # EventBus и определения событий
├── systems/         # Игровые системы (логика без рендера)
├── services/        # Сервисы (StatsService, CollisionService)
├── store/           # Zustand-сторы (ui, gameWorld, gamification, debug)
├── render/          # React Three Fiber компоненты (3D сцена)
├── ui/              # React-компоненты интерфейса
├── input/           # Ввод с клавиатуры
├── audio/           # Звуковые эффекты
├── effects/         # Визуальные эффекты (частицы, screen shake)
├── game/            # Game Loop и Game State Machine
├── commands/        # Команды (MoveCommand, ShootCommand)
└── utils/           # Утилиты

Ключевые принципы:

1. Config-driven баланс — все числовые параметры в src/config/. Для изменения баланса достаточно править конфиги.
2. Event-driven коммуникация — системы общаются через EventBus, а не прямыми вызовами.
3. Чистая доменная логика — domain/ не зависит от React, Three.js или UI.
4. ECS-подход — GameLoop оркестрирует системы, каждая система обновляет свой срез состояния.
5. Unidirectional data flow — Zustand stores → React components → R3F canvas, события идут через EventBus.

Игровой цикл

Игра использует фиксированный шаг (fixed timestep) с частотой 60 Hz для детерминированной физики:

1. Обработка ввода
2. Обновление игрока (движение, стрельба, shield)
3. AI врагов (патрулирование, преследование, атака)
4. Физика снарядов (движение, коллизии с препятствиями)
5. Combat resolution (попадания, урон, смерть)
6. Взрывы и splash-урон
7. Пикапы (возрождение, подбор)
8. Эффекты (частицы, screen shake)
9. Проверка условий победы/поражения

Установка и запуск

# Клонирование
git clone https://github.com/Zulus-Code/arena-battle.git
cd arena-battle

# Установка зависимостей
npm install

# Запуск в режиме разработки
npm run dev

Откройте http://localhost:5173 в браузере.

Сборка

npm run build

Готовый билд — один файл dist/index.html, в который встроены все ресурсы (JS, CSS, 3D-модели). Можно открыть локально или залить на любой хостинг.

npm run preview   # Просмотр собранного билда

Разработка

# TypeScript проверка
npm run typecheck

# Линтинг
npm run lint

Структура коммитов

Проект использует Conventional Commits (неформально). Примеры:

• feat: add shield power-up
• fix: correct collision detection for obstacles
• refactor: extract damage calculation to DomainRules
• config: rebalance Scout speed

---

Планы / Roadmap

• Мультиплеер (локальная сеть / WebRTC)
• Новые типы врагов и оружия
• Редактор уровней
• Система скинов для багги
• Leaderboard
• Мобильное управление (touch + gyroscope)
• Звуковое сопровождение (музыка)

---

Лицензия

MIT