Arcanum_TD/PLAN.md

Arcanum: Wardens of the Realm

Tower Defense в средневеково-магической стилистике. Веб. План на реализацию (исполнитель — Sonnet).

---

0. Концепция

Игрок — последний Архимаг угасающего королевства. Он защищает цитадель от вторжения Тёмного Ковенанта, расставляя на древних каменных башнях рунические печати, через которые течёт магия стихий. По карте идут лей-линии — потоки маны, усиливающие башни рядом. Сам Архимаг — подвижный герой с четырьмя заклинаниями.

Три столпа геймплея:

1. Рунный синергизм — у каждой башни 1 основная + 2 слота вторичных рун; руны комбинируются в уникальные эффекты.
2. Лей-линии — «магический рельеф» карты, создающий задачу оптимального размещения.
3. Архимаг — активный игровой элемент поверх пассивной экономики TD; позиционирование и таймингы заклинаний решают исходы волн.

Мета-слой (roguelike-lite): между забегами открываются новые руны в Томе Рун за эссенцию, выпадающую с боссов.

---

1. Технологический стек

Слой	Технология	Зачем
Build	Vite + TypeScript	Быстрый HMR, строгая типизация
Рендеринг игры	PixiJS v8 (WebGPU-first)	2D/2.5D, шейдеры, сотни юнитов на экране
UI / меню / HUD	React 18	Декларативный UI поверх canvas
Стили	TailwindCSS + shadcn/ui	Быстрая сборка красивых меню
Состояние	Zustand	Лёгкий стор, подписки из Pixi и React
Анимации UI	GSAP	Переходы, ink-wipe, rune-glow
Аудио	Howler.js	Кроссбраузерный звук, пулы
Многопоток	Web Workers	A* pathfinding вне основного потока
Шрифты	Cinzel (заголовки), EB Garamond (текст), MedievalSharp (акценты)	Средневековая типографика
Тесты	Vitest + Playwright (smoke)	Юнит + e2e одного уровня
Деплой	Vercel / Netlify	Статический билд

Почему не Phaser/Three.js: Phaser диктует архитектуру и «чувствуется как движок»; Three избыточен для 2.5D. PixiJS даёт чистый рендерер — больше свободы для собственной ECS и визуальных эффектов.

---

2. Визуальное направление («красивый веб»)

• Стиль: изометрическая 2.5D-проекция, hand-painted look (опорно — вайб Bastion / Octopath HD-2D).
• Палитра: глубокая полночь (#0E1220) + обожжённое золото (#C9A14A) + уголь (#E8702A) + морозный циан (#6ECBD5) + пергамент (#E9DCC0).
• Динамический свет: каждая башня излучает цветной свет (огонь пульсирует, мороз мерцает, арканум медленно вращается).
• Постэффекты: bloom на магических снарядах, лёгкая хроматическая аберрация на боссовых ударах, цветокоррекция по биому.
• Частицы: угольки, снег, руны-светлячки вокруг лей-линий, дым от смерти врагов.
• UI-каркас: пергамент + золотая филигрань (CSS border-image + SVG), кнопки с rune-glow на hover, иконки — нарисованные от руки.
• Переходы: чернильное клякса-вайп между меню и игрой.
• Превью размещения: призрачная башня + пульсирующий круг радиуса с рунным узором на земле.

---

3. Контент MVP

3.1 Башни (6 архетипов, по 3 тира)

Башня	Урон	Особенность
Archers' Loft	физ	дальняя, точная, single-target
Pyromancer Spire	огонь	AoE + burn DoT
Cryomancer Sanctum	лёд	slow → freeze → shatter-комбо
Stormcaller Obelisk	молния	chain-lightning по 3-5 целям
Chapel of Light	поддержка	хилит стены, баффает соседние башни
Bone Totem	призыв	поднимает скелета из трупа врага

3.2 Руны-модификаторы (12, открываются мета-прогрессией)

Pierce, Chain, Seek, Burn, Frost, Shock, Vampire, Echo, Curse, Weight, Fracture, Hex. Каждая даёт измеримый эффект + визуальный маркер на башне.

3.3 Враги (9)

Goblin Scout (быстрый), Orc Brute (танк), Warg Rider (swarm), Wraith (фазовый — только магия), Cursed Troll (регенит), Siege Golem (броня), Necromancer (воскрешает соседей), Dragon (летающий босс), Lich-King (финальный босс, 3 фазы).

3.4 Герой — The Archmage

• Ходит по карте по клику.
• 4 активных заклинания: Fireball (AoE-урон), Blizzard (AoE-slow), Blink (телепорт), Time Warp (глобальный slow 5 сек).
• Получает XP с каждой волны, улучшает заклинания по дереву навыков.

3.5 Экономика

• Gold — с убийств → башни/апгрейды.
• Mana — регенерит сам, бонус от лей-линий → заклинания героя.
• Essence — падает с боссов, не тратится внутри забега → Том Рун между забегами.

3.6 Волны

20 волн на карту, каждая 5-я — элитная, каждая 10-я — босс. Все волны описаны декларативно (TS-конфиги): состав, тайминги, паттерн спавна.

3.7 Карты MVP (3 + босс-арена)

1. King's Road — открытые поля, один путь (туториальная).
2. Whispering Woods — ветвление, враги делятся.
3. Frostfall Pass — горный проход, узкие точки, снежная погода.
4. Obsidian Keep — финальный босс, 3 фазы.

---

4. Архитектура

4.1 Слои

┌─────────────────────────────────────────┐
│ React UI (меню, HUD, модалки)           │
└────────────────┬────────────────────────┘
                 │ hooks (useGameStore)
┌────────────────▼────────────────────────┐
│ Zustand — общий стор (game, meta, set.) │
└────────────────┬────────────────────────┘
                 │ подписки
┌────────────────▼────────────────────────┐
│ Game Core — ECS-lite (Entities + Systems)│
└────────────────┬────────────────────────┘
                 │ рендер-команды
┌────────────────▼────────────────────────┐
│ PixiJS — слои, спрайты, шейдеры, частицы│
└─────────────────────────────────────────┘

4.2 ECS-lite

Сущности — объекты с id. Компоненты — чистые дата-классы. Системы — функции update(dt, world).

Компоненты (пример):

TransformComponent   { x, y, rotation }
HealthComponent      { current, max, armor, magicResist }
MovementComponent    { speed, path, pathIndex }
TargetingComponent   { range, mode: 'first'|'last'|'strongest'|'weakest' }
AttackComponent      { damage, type, cooldown, projectile, runes: RuneId[] }
StatusEffectsComp    { effects: Effect[] }
RenderComponent      { sprite, layer, anim }
TeamComponent        { team: 'player'|'enemy' }
LootComponent        { gold, essence }

Системы (порядок выполнения за тик): InputSystem → WaveSystem → SpawnSystem → MovementSystem → TargetingSystem → AttackSystem → ProjectileSystem → StatusEffectSystem → CollisionSystem → DeathSystem → EconomySystem → RenderSystem

4.3 Data-driven контент

Все башни/враги/волны/руны — типизированные TS-конфиги (единый источник правды, дружелюбен к балансу).

// src/data/towers.ts
export const TOWERS: Record<TowerId, TowerDef> = {
  archers_loft: {
    id: 'archers_loft',
    name: "Archers' Loft",
    tiers: [
      { cost: 50,  damage: 8,  range: 180, cooldown: 0.8 },
      { cost: 75,  damage: 14, range: 200, cooldown: 0.7 },
      { cost: 120, damage: 22, range: 220, cooldown: 0.6 },
    ],
    projectile: 'arrow',
    damageType: 'physical',
    sprite: 'towers/archers_loft',
  },
  // …
}

4.4 Структура проекта

tower-def/
├── index.html
├── package.json
├── vite.config.ts
├── tsconfig.json
├── tailwind.config.ts
├── public/
│   └── assets/ { sprites/, audio/, fonts/, shaders/ }
├── src/
│   ├── main.tsx
│   ├── App.tsx
│   ├── ui/                    # React
│   │   ├── screens/ { MainMenu, CampaignMap, GameHUD, TomeOfRunes, Settings, GameOver }
│   │   ├── hud/     { WaveIndicator, GoldBar, ManaBar, TowerShop, TowerInfoPanel, SpellBar }
│   │   └── components/        # shadcn wrappers
│   ├── game/
│   │   ├── core/              # GameEngine, EntityManager, EventBus, Time
│   │   ├── components/        # ECS data-классы
│   │   ├── systems/           # ECS логика
│   │   ├── entities/ { towers/, enemies/, projectiles/, hero/ }
│   │   ├── rendering/ { PixiRoot, layers, shaders/, particles/, camera }
│   │   ├── map/ { GridMap, Pathfinding, LeyLines, TilePalette }
│   │   ├── combat/ { DamageResolver, RuneEffects, Synergies }
│   │   ├── economy/
│   │   ├── audio/             # Howler-обёртка
│   │   └── input/             # pointer, keyboard, pan/zoom
│   ├── state/                 # Zustand сторы
│   │   ├── gameStore.ts
│   │   ├── metaStore.ts
│   │   ├── settingsStore.ts
│   │   └── selectors.ts
│   ├── data/                  # контент (TS)
│   │   ├── towers.ts
│   │   ├── enemies.ts
│   │   ├── runes.ts
│   │   ├── waves/
│   │   └── levels/
│   ├── workers/
│   │   └── pathfinding.worker.ts
│   ├── lib/ { save, rng, math }
│   └── styles/globals.css
└── tests/ { unit/, e2e/ }

4.5 Ключевые архитектурные решения

• Фиксированный tick (60 Hz) + интерполяция при рендере → детерминированная симуляция.
• Object pooling для снарядов, частиц, всплывающих цифр — без GC-stutter.
• Pathfinding в воркере — карта блокирует тайлы, воркер пересчитывает путь, возвращает массив точек.
• Seeded RNG (mulberry32) — воспроизводимые забеги, детерминированные тесты.
• Save/load: localStorage + версия схемы + миграции.
• Event Bus для одиночных событий (смерть, конец волны, босс-триггер); тонкая обвязка над EventTarget.

---

5. План разработки по фазам

Каждая фаза заканчивается играбельным билдом. Sonnet прогоняет npm run build и проходит ключевой сценарий вручную перед тем, как двигаться дальше.

Фаза 0 — Bootstrap (день 1)

• Vite + TS + React + Tailwind + shadcn/ui.
• Монтирование PixiJS-канваса внутри React.
• Скелет Zustand-сторов.
• Главное меню → пустой экран игры.
• Готово: кликабельное меню, чёрный канвас с FPS-оверлеем.

Фаза 1 — Сетка и путь (дни 2-3)

• GridMap с типами тайлов (buildable / path / blocked / ley-line).
• Изометрический рендер + параллакс-фон.
• A* в воркере.
• Визуализация пути (debug-overlay).
• Готово: видна сетка, клики меняют тайлы, путь рисуется.

Фаза 2 — Первый враг + первая башня (дни 4-6)

• ECS-ядро (Entity, Component, System).
• Один враг идёт по пути.
• Башня «Archer»: размещение, таргет, снаряд, урон.
• Health-bar, death-анимация.
• Готово: вертикальный срез — башня убивает гоблина.

Фаза 3 — Экономика и волны (дни 7-8)

• Gold с убийств, покупка башен.
• WaveSystem из конфигов, countdown между волнами.
• Условия победы/поражения (HP нексуса).
• Базовый HUD.
• Готово: полная петля на 5 волн.

Фаза 4 — Ростер башен (дни 9-11)

• Все 6 архетипов с уникальным поведением.
• Типы снарядов (arrow/fireball/icicle/chain/heal/summon).
• 3 тира улучшений.
• Превью радиуса.

Фаза 5 — Ростер врагов + эффекты (дни 12-14)

• Все 9 типов врагов.
• Фреймворк статус-эффектов (burn/freeze/shock/curse).
• Типы урона и резистов.
• Рунные слоты + первые 6 рун.

Фаза 6 — Архимаг (дни 15-17)

• Подвижный герой.
• 4 заклинания с кулдаунами и маной.
• UI таргетинга.
• Дерево прокачки.

Фаза 7 — Карты + мета (дни 18-20)

• Экран кампании.
• 3 уровня MVP с разными биомами.
• Том Рун (мета-экран).
• Save/load с версионированием.

Фаза 8 — Босс + глубина контента (дни 21-23)

• Боссы с фазами.
• Финальный уровень «Obsidian Keep».
• Минимальные cutscene-кадры (парящие иллюстрации + текст).

Фаза 9 — Juice и полировка (дни 24-27)

• Частицы для всех заклинаний.
• Шейдеры (fire, frost, arcane glow).
• Camera shake, hit-flashes, damage-numbers.
• Амбиент + музыкальные треки (3-4) + sfx.
• GSAP-анимации меню.
• Экран настроек (аудио, разрешение, доступность).

Фаза 10 — Баланс и релиз (дни 28-30)

• Прогон всех волн, балансировка.
• Режимы сложности (Normal / Heroic / Nightmare).
• Performance-проход (pooling, batching).
• Билд и деплой.

Итого: ~30 дней разработки для одного разработчика (Sonnet) при полной занятости. Приоритет при нехватке времени: фазы 0-3 (playable core) > 4-5 (контент) > 9 (полировка) > 6-8 (герой/мета) — их можно урезать.

---

6. Определения «готово» (Definition of Done)

• ✅ TypeScript strict, zero any в прод-коде.
• ✅ npm run build проходит без warnings.
• ✅ 60 FPS на MacBook M1 при 80 врагах на экране.
• ✅ Первый paint < 2 сек, бандл < 2 МБ (gzip).
• ✅ Поддержка Chrome/Firefox/Safari последних 2 версий.
• ✅ Работает на тач-устройствах (iPad-первого класса).
• ✅ Клавиатурная навигация по меню.
• ✅ Минимум 1 юнит-тест для: DamageResolver, Pathfinding, WaveSystem, SaveSystem.

---

7. Риски и как их смять

Риск	Смягчение
Перфоманс падает при 200+ врагах	Object pooling + sprite batching + culling по камере
Pathfinding блокирует рендер	Вынос в Web Worker с самого начала (фаза 1)
Переусложнение рун → нечитаемость	Лимит: 2 слота рун + визуальный маркер на башне + tooltip с итоговой формулой
React ре-рендерится слишком часто	Подписки Zustand с селекторами; HUD обновляется только по событиям волны/золота
Контент-бутылочное горло (арт)	MVP-арт: placeholder-спрайты (Kenney assets) → заменить в фазе 9; геймплей не ждёт графики
Звук блокируется автоплеем	Инициализация Howler по первому клику пользователя

---

8. Что не входит в MVP (осознанно отложено)

• Мультиплеер / кооп.
• Редактор уровней.
• Локализация (только EN + RU-интерфейс, тексты в отдельном словаре для будущей i18n).
• Сторимод с развёрнутыми кат-сценами.
• Мобильная UI-оптимизация за пределами «работает на планшете».

---

9. Что от Sonnet ожидается между фазами

1. Обновить PROGRESS.md (создать в фазе 0) — одна строчка на фазу с датой.
2. Фиксировать ключевые решения в DECISIONS.md (ADR-стиль, 5-10 строк).
3. Запустить билд и smoke-прогон сценария фазы. Если что-то сломалось — не двигаться дальше.
4. Не вводить новые зависимости без явной причины (каждый npm-пакет добавляется с комментарием «зачем»).

---

10. Первый шаг для Sonnet

cd g:/Dev/Tower_Def
npm create vite@latest . -- --template react-ts
npm i pixi.js@8 zustand howler gsap
npm i -D tailwindcss postcss autoprefixer @types/howler vitest
npx tailwindcss init -p

Дальше — раздел 5, фаза 0.