Initial commit: Arcanum TD — medieval fantasy tower defense

Vite + React + PixiJS + TypeScript. Features: - 4-level campaign (King's Road → Obsidian Keep) - Isometric 2.5D grid with ley-line mechanics - ECS architecture (entities, components, systems) - 4 tower types, hero spellcaster, 10+ enemy types - Lich King boss with 3-phase AI - Meta-progression: essence, rune unlocks - Full UI redesign with fantasy design system Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-19 12:31:49 +03:00
commit 7a62067af1
91 changed files with 11832 additions and 0 deletions
@@ -0,0 +1,349 @@
+# 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<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
+
+```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.