# Game Requirements

## Overview

Хардкорный roguelite-платформер с процедурной генерацией уровней. Игрок собирает монетки, избегая врагов и ловушек. Уникальная механика оружия — оглушающие "газовые" снаряды. Между забегами игрок тратит накопленную валюту на апгрейды в магазине.

---

## Core Gameplay

### Цель игры
- Собрать все монетки на уровне
- Избегать контакта с врагами и ловушками
- Пройти как можно больше уровней
- Накопить валюту для покупки апгрейдов

### Персонаж
- Базовое управление: движение влево/вправо, прыжок
- Оружие: выпускает оглушающие снаряды ("пуки")
- Смерть при любом контакте с активным врагом (one-hit kill по умолчанию)

### Система снарядов
- Максимум **3 снаряда** в запасе (базовое значение)
- После использования снаряд **восстанавливается через время** (~3 сек)
- Нельзя "спамить" — требуется тактическое использование
- Снаряд оглушает врага при попадании
- Направление выстрела: в сторону движения персонажа

### Враги

#### Типы врагов
| Тип | Поведение | Появляется с уровня |
|-----|-----------|---------------------|
| **Патрульный** | Ходит туда-сюда по платформе | 1 |
| **Прыгун** | Прыгает по платформам вертикально | 3 |
| **Летун** | Летает по фиксированной траектории | 5 |
| **Преследователь** | Медленно движется к игроку | 7 |
| **Спринтер** | Патрульный, но быстрый | 10 |

#### Состояния врагов
- **Активное**: опасны, убивают при контакте
- **Оглушённое**: безопасны, можно проходить сквозь
- Оглушение действует **3 секунды** (базовое значение), затем враг восстанавливается
- Визуальный индикатор времени оглушения над врагом (круговой таймер)

### Ловушки

| Тип | Поведение | Появляется с уровня |
|-----|-----------|---------------------|
| **Шипы** | Статичные, мгновенная смерть | 2 |
| **Падающая платформа** | Падает через 0.5сек после наступания | 4 |
| **Пила** | Движется по траектории | 6 |
| **Турель** | Стреляет снарядами с интервалом | 8 |
| **Лазер** | Включается/выключается по таймеру | 10 |

### Прогрессия уровней
- После сбора всех монеток — переход на следующий уровень
- С каждым уровнем сложность увеличивается:
  - Больше врагов
  - Новые типы врагов
  - Появляются ловушки
  - Больше монеток (нужно больше собрать)
  - Сложнее структура уровня

---

## Game Feel (Критически важно)

### Coyote Time
- Игрок может прыгнуть в течение **100мс** после схода с платформы
- Незаметно для игрока, но убирает фрустрацию от "несправедливых" смертей

### Input Buffering (Jump Buffer)
- Если прыжок нажат за **100мс** до приземления — прыжок выполнится автоматически
- Предотвращает ощущение "съеденных" инпутов

### Variable Jump Height
- Короткое нажатие = низкий прыжок
- Длинное нажатие = высокий прыжок
- Даёт точный контроль над персонажем

### Edge Correction
- Если персонаж чуть-чуть не допрыгнул до края платформы — подтянуть на ~4 пикселя
- Работает только для небольших расстояний

### Responsive Controls
- Минимальное время разгона/торможения
- Мгновенная смена направления
- Никакой "скользкости"

---

## Visual Juice

### Частицы
- Пыль при приземлении
- Пыль при беге (каждые N кадров)
- Облачко при выстреле снарядом
- "Звёздочки" при оглушении врага
- Блеск/свечение монеток
- Взрыв частиц при смерти персонажа

### Screen Shake
- Лёгкая тряска при смерти
- Микро-тряска при оглушении врага
- **Обязательно**: опция отключения в настройках

### Squash & Stretch
- Персонаж вытягивается вертикально при прыжке
- Сжимается горизонтально при приземлении
- Враги "сплющиваются" при оглушении
- Монетки слегка пульсируют

### Хитстоп (Freeze Frame)
- Микро-пауза (2-3 кадра) при попадании снарядом во врага
- Усиливает ощущение импакта

---

## Meta-Progression System

### Валюта
- **Газокоины** — основная мета-валюта
- Все монетки собранные за забег конвертируются в газокоины после смерти
- Конверсия: 1 монетка = 1 газокоин
- Бонус за пройденные уровни: +10% за каждый уровень

### Магазин апгрейдов

Философия: апгрейды **разнообразят** игру и дают **небольшие** преимущества, но НЕ делают её лёгкой. Многие апгрейды — это tradeoff'ы (плюс в одном, минус в другом).

#### Категория: Персонаж

| Апгрейд | Эффект | Цена | Примечание |
|---------|--------|------|------------|
| **Лёгкие ботинки** | +10% скорость бега | 100 | — |
| **Пружинные ботинки** | +15% высота прыжка | 150 | — |
| **Тяжёлая броня** | +1 жизнь за забег | 500 | -15% скорость |
| **Двойной прыжок** | Можно прыгнуть в воздухе | 800 | — |
| **Dash** | Рывок по нажатию, 2сек кулдаун | 600 | — |
| **Скользкий** | Неуязвим 0.5сек после урона | 400 | Работает только с доп. жизнями |

#### Категория: Оружие

| Апгрейд | Эффект | Цена | Примечание |
|---------|--------|------|------------|
| **Большой запас** | +1 снаряд (макс. 4) | 300 | — |
| **Быстрая перезарядка** | -20% время восстановления | 250 | — |
| **Дальнобойность** | +30% дальность полёта снаряда | 200 | — |
| **Мощное оглушение** | +1сек время оглушения | 350 | — |
| **Разрывной снаряд** | Снаряд оглушает врагов в радиусе | 700 | -1 снаряд в запасе |
| **Рикошет** | Снаряд отскакивает от стен 1 раз | 450 | — |
| **Скорострел** | -40% время перезарядки | 400 | -30% время оглушения |

#### Категория: Выживание

| Апгрейд | Эффект | Цена | Примечание |
|---------|--------|------|------------|
| **Второй шанс** | 1 раз за забег: воскрешение на месте | 1000 | Одноразовый за забег |
| **Магнит** | Монетки притягиваются с расстояния | 200 | — |
| **Орлиный глаз** | Видно весь уровень на мини-карте | 300 | — |
| **Чутьё опасности** | Враги подсвечиваются за экраном | 250 | — |
| **Ловкач** | Hitbox персонажа уменьшен на 10% | 600 | — |

#### Категория: Риск/Награда

| Апгрейд | Эффект | Цена | Примечание |
|---------|--------|------|------------|
| **Жадность** | +50% монеток на уровне | 400 | +25% врагов |
| **Хардкор** | x2 очки | 300 | Нет coyote time |
| **Берсерк** | +30% скорость, бесконечные снаряды | 500 | Активируется на 10сек при 0 HP (перед смертью) |
| **Пацифист** | x3 очки за уровень | 350 | Нельзя использовать снаряды |
| **Спидран** | +100 очков за каждые 10сек до таймера | 200 | Таймер 60сек на уровень, смерть по истечении |

#### Категория: Косметика (не влияет на геймплей)

| Апгрейд | Эффект | Цена |
|---------|--------|------|
| **Скин: Космонавт** | Новый вид персонажа | 150 |
| **Скин: Рыцарь** | Новый вид персонажа | 150 |
| **Скин: Ниндзя** | Новый вид персонажа | 150 |
| **След: Радуга** | Радужный след при беге | 100 |
| **След: Огонь** | Огненный след | 100 |
| **Снаряд: Облачко** | Другой вид снаряда | 50 |
| **Снаряд: Сердечко** | Другой вид снаряда | 50 |

### Система разблокировок

Некоторые апгрейды требуют достижений для разблокировки покупки:

| Апгрейд | Требование |
|---------|------------|
| Двойной прыжок | Дойти до уровня 5 |
| Dash | Собрать 500 монеток за один забег |
| Второй шанс | Умереть 50 раз |
| Хардкор | Пройти уровень без использования снарядов |
| Берсерк | Оглушить 100 врагов |
| Пацифист | Дойти до уровня 3 без снарядов |

### Баланс хардкорности

Принципы сохранения сложности:
1. **Базовая игра остаётся one-hit kill** — доп. жизни дорогие и имеют штрафы
2. **Tradeoff'ы** — большинство сильных апгрейдов имеют минусы
3. **Сложность масштабируется** — чем больше апгрейдов, тем сложнее уровни
4. **Потолок силы** — апгрейды не стакаются бесконечно
5. **Риск/награда** — самые выгодные апгрейды усложняют игру

---

## Level Generation

### Подход: комнатная генерация (Spelunky-style)
- Уровень — сетка из "комнат" (например, 4x4)
- Каждая комната — готовый шаблон
- Алгоритм гарантирует путь от входа до всех монеток
- Шаблоны подбираются по сложности уровня

### Параметры генерации по уровням

| Уровень | Комнат | Монеток | Врагов | Ловушек |
|---------|--------|---------|--------|---------|
| 1-2 | 6-8 | 5-8 | 2-3 | 0 |
| 3-5 | 8-10 | 8-12 | 4-6 | 1-2 |
| 6-9 | 10-12 | 12-16 | 6-8 | 3-4 |
| 10+ | 12-16 | 16-20 | 8-12 | 5-6 |

### Seed система
- Каждый уровень имеет seed
- Seed отображается на экране паузы
- Можно ввести seed для воспроизведения уровня (отдельный режим, без влияния на лидерборд)

---

## Scoring System

### Базовые очки
- Монетка: **10 очков**
- Завершение уровня: **100 очков × номер уровня**
- Оглушение врага: **5 очков**

### Комбо-система
- Сбор монеток без паузы увеличивает множитель
- Пауза >2сек сбрасывает комбо
- Множители: x1 → x2 → x3 → x5 → x10 (макс)
- Попадание снарядом во врага не сбрасывает комбо

### Бонусы за уровень
- **Быстрое прохождение** (<30 сек): +50% очков за уровень
- **Без урона** (если есть доп. жизни): +25% очков
- **Без снарядов**: +100% очков

---

## UI/UX

### HUD (во время игры)
- Счётчик монеток: "собрано / всего"
- Индикатор снарядов (иконки с cooldown-анимацией)
- Текущее комбо (если активно)
- Номер уровня
- Очки
- Мини-карта (если куплен апгрейд)
- HP (если есть доп. жизни)

### Экран паузы
- Продолжить
- Настройки
- Seed уровня
- Выход в меню (с подтверждением)

### Game Over экран
- Финальный счёт
- Статистика забега:
  - Пройдено уровней
  - Собрано монеток
  - Оглушено врагов
  - Время игры
- Заработано газокоинов
- Кнопка "В магазин"
- Кнопка "Играть снова"
- Таблица лидеров

### Главное меню
- Играть
- Магазин
- Лидерборд
- Настройки
- Достижения

### Настройки
- Громкость музыки
- Громкость звуков
- Screen shake: вкл/выкл
- Показывать FPS
- Сбросить прогресс (с подтверждением)

---

## Power-ups (внутри забега)

Редкие предметы, появляющиеся на уровнях:

| Power-up | Эффект | Длительность |
|----------|--------|--------------|
| **Щит** | Защита от 1 удара | До использования |
| **Магнит** | Притягивает монетки | 15 сек |
| **Часы** | Замедляет врагов на 50% | 10 сек |
| **Кофе** | +50% скорость персонажа | 10 сек |
| **Бесконечность** | Бесконечные снаряды | 8 сек |
| **Призрак** | Проход сквозь врагов | 5 сек |

Появление: 10% шанс на уровне, максимум 1 power-up на уровень.

---

## Technical Requirements

### Платформа
- Браузер (desktop)
- Поддержка клавиатуры
- Возможно: геймпад (future)

### Управление

| Действие | Клавиатура | Геймпад (future) |
|----------|------------|------------------|
| Движение | A/D или ←/→ | Left Stick / D-Pad |
| Прыжок | W / ↑ / Space | A / X |
| Стрельба | F / J / Enter | B / Square |
| Dash (если куплен) | Shift / K | RB / R1 |
| Пауза | Escape / P | Start |

### Производительность
- 60 FPS на современных браузерах
- Минимальное разрешение: 800x600
- Рекомендуемое: 1280x720

### Хранение данных (MVP)
- localStorage для:
  - Газокоины (валюта)
  - Купленные апгрейды
  - Активные апгрейды
  - Лидерборд (топ-10)
  - Достижения
  - Настройки

---

## MVP Scope

### Фаза 1: Core Loop
- [ ] Движение персонажа с game feel (coyote time, input buffer, variable jump)
- [ ] Система снарядов
- [ ] Базовый враг (патрульный)
- [ ] Механика оглушения
- [ ] Сбор монеток
- [ ] Процедурная генерация (простая)
- [ ] Переход между уровнями
- [ ] Game Over

### Фаза 2: Juice & Polish
- [ ] Частицы (пыль, эффекты)
- [ ] Squash & stretch анимации
- [ ] Screen shake (с опцией отключения)
- [ ] Звуковые эффекты
- [ ] Базовая музыка

### Фаза 3: Meta-Progression
- [ ] Система газокоинов
- [ ] Магазин с апгрейдами (5-10 базовых)
- [ ] Сохранение прогресса
- [ ] Экран Game Over со статистикой

### Фаза 4: Content
- [ ] Дополнительные типы врагов (3-4)
- [ ] Ловушки (2-3 типа)
- [ ] Power-ups (3-4 типа)
- [ ] Больше апгрейдов в магазине
- [ ] Достижения

### Фаза 5: Polish
- [ ] Комбо-система
- [ ] Лидерборд
- [ ] Полный UI/UX
- [ ] Баланс сложности
- [ ] Seed система

### Отложено на будущее
- [ ] Бекенд для глобального лидерборда
- [ ] Ежедневные челленджи (один seed на день)
- [ ] Боссы
- [ ] Мобильная версия
- [ ] Мультиплеер (гонка)
- [ ] Steam-релиз

---

## Достижения

| Достижение | Условие | Награда |
|------------|---------|---------|
| Первые шаги | Пройти уровень 1 | 10 газокоинов |
| Коллекционер | Собрать 1000 монеток (всего) | 50 газокоинов |
| Мастер оглушения | Оглушить 100 врагов | Разблокировка "Берсерк" |
| Пацифист | Пройти уровень без снарядов | Разблокировка "Пацифист" |
| Марафонец | Дойти до уровня 10 | 100 газокоинов |
| Скоростной забег | Пройти 5 уровней за 3 минуты | 75 газокоинов |
| Неубиваемый | Пройти 3 уровня с 1HP без урона | 150 газокоинов |
| Богач | Накопить 5000 газокоинов | Скин "Золотой" |
| Комбо-мастер | Собрать x10 комбо | 50 газокоинов |
| Умер 100 раз | Умереть 100 раз | Скин "Призрак" |