# План разработки проекта: Plants vs. Zombies (ai.qpid.pro)

## 1. Цели и архитектурные принципы
- **Цель**: создать быстрый, легкий, полностью автономный браузерный клон Plants vs. Zombies, доступный на постоянном домене `https://ai.qpid.pro`, с максимальной глубиной удержания игроков (Retention), реиграбельностью, системой крафта, прокачки и пассивного прогресса.
- **Архитектурные принципы**:
  1. *Zero External Runtime Dependencies*: отсутствие внешних CDN или тяжелых фреймворков.
  2. *Single Static Origin*: чистый Nginx в Docker раздает сжатую статику, 100% исполнение на стороне клиента.
  3. *Zero Asset Loading Delay*: процедурная графика Canvas и синтез звука через Web Audio API.
  4. *Mobile & Desktop Hybrid*: идеальный отклик как для мыши, так и для сенсорных экранов.
  5. *Autonomous Testability*: встроенный API `window.PvZTestAPI` и CLI-раннер `test_game.py` для непрерывного контроля качества.
  6. *Глубокая система прогресса и крафта (RPG & Idle Core)*:
     - **Сбор ресурсов в бою**: зомби дропают монеты и ремесленные материалы (Гумус, Металлолом, Солнечную эссенцию).
     - **Садовая Мастерская**: отдельная уютная локация крафта и селекции растений.
     - **3 Уровня прокачки каждого растения**: от базового саженца до плазменных и шипованных ультимейтов.
     - **Глобальные перки садовника**: пассивные бонусы на всю игру (стартовое солнце, ускорение перезарядки, магнетизм).

---

## 2. Реализованные фазы разработки (v1.0 — v1.6)

### ✅ Фаза I (v1.1): «Мобильность, HiDPI и Музыка» (Выполнено)
- Тач-события (`touchstart`, `touchmove`, `touchend`) и свайп-сбор солнц.
- Поддержка `window.devicePixelRatio` для четкости на Retina/HiDPI.
- Полифоническая музыкальная тема *«Grasswalk»* на Web Audio API.
- Локальное сохранение очков и рекордов в `localStorage`.

### ✅ Фаза II (v1.2): «Тактический арсенал и новые зомби» (Выполнено)
- 4 новых растения: Картофельная мина, Повторитель, Зубастик, Халапеньо.
- 3 новых зомби: Зомби с шестом, Зомби с газетой, Зомби-футболист.
- Анимированная шкала прогресса волны в правом верхнем углу.

### ✅ Фаза III (v1.3): «Смена биомов (Ночь и Бассейн)» (Выполнено)
- Ночной газон: отсутствие падающего солнца, грибная экономика (Солнцегриб, Дымогриб), надгробия и Могилоед.
- Бассейн: 6 дорожек, 2 водных линии с кувшинками, зомби-уточки, очистители бассейна.

### ✅ Фаза IV (v1.4): «Кампания и Магазин Безумного Дэйва» (Выполнено)
- Кампания из уровней 1-1...1-10 с последовательной прогрессией.
- Выпадение серебряных, золотых и алмазных монет из зомби.
- Магазин Дэйва с покупкой +1 слота под семена и садовых грабель.

### ✅ Фаза V (v1.5): «Дополнительные режимы и мини-игры» (Выполнено)
- Режим «Выживание» (Endless Survival) с флагами.
- Мини-игра «Боулинг орехами» (Wall-nut Bowling) с рикошетом и конвейерной лентой.
- Режим «Я, Зомби» (I, Zombie).

### ✅ Фаза VI (v1.6): «Полировка UI, Меню, Авторизация/Гость и Test API» (Выполнено)
- **Исправление режима «Я, Зомби»**: синхронный старт без таймеров, 5 подсолнухов, +150 солнца за поедание, поражение при солнце < 50 и отсутствии зомби.
- **Устранение наложений UI**: верхний независимый Flexbox тулбар `.top-nav-bar` вне игрового холста.
- **Главное меню и перезапуск**: кнопка «🏠 Меню» на панели + кнопки «В МЕНЮ» на экранах победы и поражения.
- **Система авторизации и профилей**: окно входа/регистрации по логину и паролю + режим «Гость» (сессионная игра).
- **Автономное тестирование игры**: модуль `window.PvZTestAPI` и CLI-тест `scripts/test_game.py` (46 автотестов).

### ✅ Фаза VII (v1.7): «Сад-Мастерская: Крафт, 3 Уровня прокачки растений и Перки» (Выполнено)
- **Интерактивная локация «Сад-Мастерская»**: модальный экран с панелью материалов (🧪 биогумус, ⚙️ детали, ☀️ эссенция, 💎 кристаллы, 💰 монеты) и вкладками прокачки растений и перков.
- **3 Уровня прокачки растений (Tiers 1-3)**: Горохострел (криты + плазменный пирсинг), Подсолнух (ускорение + аура лечения), Стеноорех (поглощение урона + шипы отдачи), Картофельная мина (быстрый взвод 6с + ядерный Spudow 3x3), Повторитель, Ледяной горох, Зубастик.
- **5 Пассивных Перков Садовника**: Магнитный газон (автосбор), Стартовый капитал (+50/100/150 ☀️), Ускоренный полив (-10/20/30% CD), Упорные корни (+20/35/50% HP), Золотая рука (+30/60/100% дроп).
- **Анимированный лут**: подпрыгивание, свечение и притягивание магнитом.
- **Полное сохранение**: синхронизация материалов, уровней и перков с профилями в `PvZAuth`.
- **68/68 автоматических тестов** успешно проходят в `scripts/test_game.py`.

---

## 3. Детализация следующего Спринта v1.8: «Дзен-Сад (Пассивный доход и улитка Стинки) и Альманах»

### 3.1. Локация «Сад-Мастерская» (Garden Lab & Workshop)
* Переход на отдельный экран/модальное окно Сада из главного меню или верхней панели управления.
* Визуальное оформление: уютная теплица с деревянным верстаком, грядками и полками с колбами.
* 3 вкладки в интерфейсе:
  1. **«Селекция растений»**: список всех растений игрока, текущий уровень (★, ★★, ★★★), стоимость улучшения в ресурсах.
  2. **«Пассивные перки»**: ветки перков с индикатором прокачки.
  3. **«Хранилище материалов»**: баланс собранных ресурсов.

### 3.2. Ремесленные материалы (Ресурсы боя)
| Ресурс | Иконка | Источник получения | Назначение |
|---|---|---|---|
| **Монеты** | 💰 | Зомби, газонокосилки, Дзен-сад | Базовые улучшения, магазин |
| **Био-гумус** | 🧪 | Обычные зомби, зомби с шестом, газетчики (шанс 25%) | Прокачка травяных растений |
| **Зомби-металл** | ⚙️ | Зомби с ведром, конусом, футболисты (шанс 40%) | Прокачка прочности, орехов, шипов |
| **Солнечная эссенция** | ☀️ | Сбор солнц на газоне (каждое 10-е солнце дает +1 эссенцию) | Прокачка подсолнухов и энергетиков |
| **Кристаллы льда/огня** | 💎 | Боссы, прохождение флагов в Выживании, редкие зомби | Ультимативные улучшения 3-го уровня |

### 3.3. Таблица 3 уровней прокачки растений (Plant Tiers)
Каждое растение получает 3 ступени мастерства:

1. **Горохострел (Peashooter)**:
   - ★ **Ур. 1 (Базовый)**: Урон 20, интервал стрельбы 1.4 сек.
   - ★★ **Ур. 2 («Скорострел»)**: Урон 25, интервал 1.15 сек, шанс критического удара 15% (x2 урон со вспышкой).
   - ★★★ **Ур. 3 («Плазменный стрелок»)**: Плазменный энергетический заряд пробивает первого зомби насквозь и ранит следующего на 50% урона.
2. **Подсолнух (Sunflower)**:
   - ★ **Ур. 1 (Базовый)**: 25 ☀️ каждые 12 сек.
   - ★★ **Ур. 2 («Крупный подсолнух»)**: 35 ☀️ каждые 10 сек.
   - ★★★ **Ур. 3 («Благодатный свет»)**: Каждая вспышка солнца излучает ауру, восстанавливающую +30 HP всем соседним растениям в радиусе 1 клетки.
3. **Стеноорех (Wall-nut)**:
   - ★ **Ур. 1 (Базовый)**: 400 HP.
   - ★★ **Ур. 2 («Каменный монолит»)**: 700 HP + поглощение 15% входящего урона.
   - ★★★ **Ур. 3 («Шипованный бастион»)**: 1000 HP + возврат 30% полученного урона атакующим зомби при каждом укусе.
4. **Картофельная мина (Potato Mine)**:
   - ★ **Ур. 1 (Базовый)**: Время взведения 15 сек, взрыв в клетке на 1800 урона.
   - ★★ **Ур. 2 («Быстрый фитиль»)**: Время взведения сокращено до 6 сек!
   - ★★★ **Ур. 3 («Атомный Spudow»)**: Взрыв 3x3 клетки + оставляет горящую яму лавы, замедляющую и сжигающую врагов.
5. **Повторитель (Repeater)**:
   - ★: 2 горошины за выстрел.
   - ★★: 2 горошины + шанс 20% выпустить третью горошину.
   - ★★★: Огненный Повторитель — горошины зажигаются и наносят сплэш-урон.
6. **Ледяной горох (Snow Pea)**:
   - ★: Замедление на 4 сек, урон 20.
   - ★★: Увеличенный холод (замедление 6 сек, зона заморозки задевает зомби позади).
   - ★★★: Шанс 15% полностью превратить зомби в ледяную глыбу на 2 сек.
7. **Зубастик (Chomper)**:
   - ★: Заглатывание и 30 сек жевания.
   - ★★: Жевание ускорено до 14 сек.
   - ★★★: Способен проглотить сразу 2 зомби подряд перед началом жевания!

### 3.4. Глобальные Пассивные Перки Садовника
Постоянные пассивные улучшения, действующие во всех режимах игры:
* 🧲 **Магнитный газон (Ур. 1-3)**: Радиус автосбора монет и солнц увеличен на +30% / +60% / Полный автосбор по экрану.
* 💰 **Стартовый капитал (Ур. 1-3)**: Старт боя с +50 ☀️ / +100 ☀️ / +150 ☀️.
* ⏳ **Ускоренный полив (Ур. 1-3)**: Время перезарядки (cooldown) всех карточек семян снижено на -10% / -20% / -30%.
* 🛡️ **Упорные корни (Ур. 1-3)**: Запас здоровья всех растений на газоне увеличен на +15% / +30% / +50%.
* 🍀 **Золотая рука (Ур. 1-3)**: Шанс дропа монет и редких материалов из зомби повышен на +25% / +50% / +75%.

---

## 4. Завершённые фазы (v1.8 — v2.1)

### ✅ Фаза VIII (v1.8): «Дзен-Сад (Пассивный доход и улитка Стинки) и Альманах» (Выполнено)
- **Дзен-Сад с 8 горшками**: покупка саженцев (100 монет), 4 стадии роста, уход (лейка, удобрение, граммофон).
- **Улитка Стинки (Stinky the Snail)**: автосбор монет, кормление шоколадом для 3x ускорения.
- **Пассивный оффлайн-доход**: начисление монет при возвращении в игру.
- **Пригородный Альманах**: полное иллюстрированное досье на 13 растений и 8 зомби, включая секретного Зомби-Йети с дропом 4 алмазов.

### ✅ Фаза IX (v1.9): «Садовый Рогалик (Roguelike Drafting) и Система Достижений» (Выполнено)
- **Режим Рогалика**: этажи, драфт семян и 6 уникальных реликвий (Цепная молния, Токсичная почва, Солнечный резонанс, Железная кора, Вампирский сок, Древесный стимулятор).
- **HUD активных реликвий**: индикация на экране во время боя.
- **Система достижений**: 14+ трофеев с прогресс-барами, всплывающими тост-уведомлениями, наградами в монетах/кристаллах и сохранением в профиль.

### ✅ Фаза X (v2.0): «Туман, Крыша, Древо Мудрости, Доктор Зомбосс и Лидерборды» (Выполнено)
- **Биомы Туман и Крыша**:
  - Крыша: скошенная черепица, кирпичная труба, необходимость Цветочных Горшков (`flowerpot`).
  - Туман: плотная атмосферная пелена над правой частью газона с динамическим дрейфом.
  - Навесная артиллерия: Капустопульта (`cabbagepult`) и Арбузопульта (`melonpult`) с параболической физикой и сплэш-уроном.
- **Древо Мудрости и Чит-коды**:
  - Рост за древесное удобрение (150 монет) с мудрыми советами садовника.
  - Секретные клавиатурные чит-коды: `mustache` (усы), `future` (неоновые киберочки), `daisies` (цветы при смерти), `dance` (танцы нежити), `pinata`.
- **Финальный босс Доктор Зомбосс & Зомбот**:
  - 6000 HP, 3 фазы боя.
  - Раздавливание растений лапой робота, десант зомби на резинках (Bungee), ледяные и огненные шары (растопление Халапеньо / заморозка Ледяным горохом), бросок фургона на 3-й фазе.
  - Эпический салют взрывов и богатый дроп при победе.
- **Доска Почёта и Рекорды**:
  - Топ-10 результатов по режимам: Выживание, Рогалик, Приключение, Я Зомби, Боулинг, Зомбосс.

### ✅ Фаза XI (v2.1 Финал): «Саундтрек, Boss Rush, Кастомные темы и PWA» (Выполнено)
- **Мульти-биомовый процедурный саундтрек**:
  - Web Audio синтезатор генерирует уникальные музыкальные темы для каждого биома:
    - `day` (солнечный весёлый Grasswalk),
    - `night` (таинственный эфирный минор Moonglow),
    - `pool` (карибский баунс / маримба Watery Lounge),
    - `fog` (напряжённый эмбиент с детьюнированными пэдами),
    - `roof` (героический марш с восходящими аккордами),
    - `boss` (драйвовый тяжёлый рок/метал Brainiac Maniac).
  - Методы `PvZAudio.startMusic(theme)`, `setTheme(theme)`, `getTheme()`.
- **Режим «Boss Rush» (Череда Боссов)**:
  - 3 эскалирующие волны:
    1. Орда тяжелоатлетов-футболистов и зомби с ведрами;
    2. Элитный спецназ с шестами и газетами;
    3. Доктор Зомбосс на боевом Зомботе.
  - Награда за победу: +500 монет и +2 алмаза, собственный раздел в Доске Почёта.
- **Визуальные темы и кастомные скины**:
  - Переключение в шапке игры в один клик:
    - 🎨 **Классика** (традиционный газон и интерфейс),
    - 🎨 **Киберпанк** (неоновый циан и маджента, матричные сетки),
    - 🎨 **Ретро 8-бит** (пиксельный аркадный стиль CRT),
    - 🎨 **Зима** (морозный лазурный газон, снежные акценты).
  - Сохранение выбранной темы в аккаунт игрока.
- **PWA (Progressive Web App) и Офлайн-игра**:
  - `manifest.json` со всеми размерами иконок и standalone-режимом.
  - `sw.js` Service Worker с кэшированием всех файлов игры для мгновенного запуска без интернета.
  - Сгенерированные иконки 192x192, 512x512 и favicon.ico.
- **Тестовый охват**:
  - **172/172 автотестов** проходят со 100% успехом в `scripts/test_game.py` и `window.PvZTestAPI`.
- **Домен**: `https://ai.qpid.pro/` — полностью развернуто, работает без внешних зависимостей.