fisrt commit

docs/REQUIREMENTS.md

@@ -0,0 +1,412 @@
+# 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 раз | Скин "Призрак" |