ai-qpid-pvz/PLAN.md

План разработки проекта: 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/ — полностью развернуто, работает без внешних зависимостей.