# 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)`. **Компоненты (пример):** ```ts 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-конфиги (единый источник правды, дружелюбен к балансу). ```ts // src/data/towers.ts export const TOWERS: Record = { 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 ```bash 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.