Mareli
7a62067af1
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>
350 lines
20 KiB
Markdown
350 lines
20 KiB
Markdown
# 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.
|