# «Пепельные луга» — демо-витрина движка (проектная дока)

Внутренняя документация вертикального среза. Игра — демо движка `@rpg/engine`:
каждая подсистема задействована в геймплее, недостающие возможности внедряются
в движок жанронезависимо. Пользовательская дока движка — `docs/engine/`,
арт — `docs/art-style.md`, мир — `docs/world.md`.

## Матрица «подсистема движка → где показана»

| Подсистема | Где показана в демо | Статус |
|---|---|---|
| Engine (GameLoop, фиксированный шаг 60 Гц) | весь геймплей, `Game.ts` | готово |
| Renderer (480×270, целочисленный масштаб, pixelated) | весь рендер, `main.ts` + `computeScale` | готово |
| Camera (follow, bounds от западного угла, shake) | следование за героем; тряска при резонансе/уроне | готово |
| SceneManager (replace/push/pop, fade) | меню → локация → сумка/сейвы; переходы локаций | готово |
| InputManager (действия, геймпад, мульти-биндинг) | advance/attack/menu/inventory/debug; геймпад-карта | готово |
| VirtualJoystick | тач в локациях (включается при первом касании) | готово |
| IsometricTileMap + A* | карты локаций, движение по клику | готово |
| mapFormat (JSON+RLE) | карты — файлы `assets/maps/*.map`, генерация `npm run maps` | готово |
| Tiled-импорт | не задействован (дока + тест есть) | резерв |
| EventBus | `combat:hurt/attack/playerHit`, `quest:flower` | готово |
| GameState (флаги/вары) | прогресс квеста, hp/kills/motes/deaths; сериализация в сейвы | готово |
| SaveManager (слоты) | autosave (Esc) + 3 слота, `SaveSlotsScene` | готово |
| Settings + onChange | громкости master/music/sfx, `SettingsScene` | готово |
| AudioManager (шины) | музыка локаций с кроссфейдом, sfx боя/шагов/UI | готово |
| Tween + easing | хит-флэш, кольца резонанса, всплывающие тосты | готово |
| Particles (атмосфера + burst) | пепел лугов, туман прудов, удары/смерти сгустков | готово |
| StateMachine | `EnemyBrain` — ИИ сгустков (dormant/rise/chase/…/sleep/dead) | готово |
| ECS (World) | боевые сущности: враги и снаряды на `Entity` | готово |
| Panel/Button/MenuList | меню, настройки, сейвы, сумка | готово |
| DialogueRunner + DialogueBox | графы `data/dialogues.ts`, ветки квеста | готово |
| DebugOverlay | F3: fps/тайл/позиция/hp | готово |
| math/shapes (cone/circle) | конус удара, круг цели, кольца | готово |
| Cooldown | кулдауны удара/резонанса/атак врагов | готово |
| math/rng (mulberry32) | генерация карт и частиц, детерминированный shake | готово |

## Сюжетная рамка (акт 1, по docs/world.md)

1. Выжженные луга (хаб): Ирвин даёт квест «Три цветка» (флаг `quest_bells_taken`).
2. Мила предупреждает о накате у прудов, даёт вощёное полотно (`got_cloth`).
3. Серые пруды (опасная зона): туман, сгустки, сбор колокольчиков кликом (вар `flowers`).
4. Возврат: сдача Ирвину (`elder_hand_in`) — посадка цветов у тропы, тайлы зеленеют.
5. Крючок: Мила — «Слышишь гул снизу? Это разъезд. Это Машина дышит» (`trader_after`).

## Боевая модель (реальное время)

- Герой: HP 5 (сердечки), удар-конус по facing (1.0 юнита, 55°, урон 2, кд 0.45 с),
  резонанс удержанием ≥0.6 с (импульс r=3.0 юнита, усыпляет на 4 с, кд 3 с),
  неуязвимость 0.8 с после урона, отброс 0.75 юнита. Дистанции/скорости — в
  мировых юнитах (1 юнит = 1 тайл; на экране 32 px/юнит по линейке проекции).
- Враги «пепельные сгустки»: ползун (HP 3, стая), плевун (HP 2, дистанция + плевок),
  наст (HP 8, замах → удар по площади). Звук — ресурс: удар излучает гул r=4.5 юнита
  и будит спящих сгустков.
- Ввод: клик по врагу — авто-подход и удар; Space тап/удержание; геймпад X.

## Архитектура среза

- `packages/engine` — жанронезависимый движок, публичный API только `src/index.ts`.
- `apps/game/src/`:
  - `data/` — контент: `locations.ts` (определения локаций), `map.ts` (генераторы),
    `dialogues.ts` (графы), `npcs.ts`, `enemies.ts`, `quests.ts` (журнал/сумка);
  - `scenes/` — BootScene → MenuScene (+ SettingsScene, SaveSlotsScene) →
    LocationScene (+ InventoryScene);
  - `systems/` — PlayerController (путь + прямое движение), DialogueSystem,
    `combat/` (CombatWorld, EnemyBrain, PlayerCombat, CombatViews, HealthBar, stats).
- Инструменты: `tools/pixelart` (PNG-атласы), `tools/audio` (WAV-генератор),
  `tools/maps` (карты-файлы), `tools/smoke*.mjs` (смоук в реальном Chromium).

## Новое в движке за срез

- `render/shake.ts` — `Shake` + `Camera.addShake` (детерминированный rng).
- `math/shapes.ts` — `inCircle`, `inCone`, `angleBetween`, `nearest`.
- `core/Cooldown.ts` — `trigger/update/ready/progress`.
- `render/particleSim.ts` — чистая интеграция частиц; `Particles.burst/oneShot`.
- `anim/flash.ts` + `render/spriteFx.ts` — `TintFlash`/`flashSprite`.
- `input/InputManager` — `isActionJustReleased`, `wasKeyReleased`, `pointer.downTicks`,
  мульти-биндинг (одна клавиша → несколько действий).
- `core/StateMachine.transitionAny` — переход из любого состояния.
- `map/IsometricTileMap.setTile` — изменение тайла с перерисовкой ячейки.
- `map/pathfinding.findPathToNeighbor` — путь к краю занятого/непроходимого тайла
  (гейтинг взаимодействий по дистанции в демо).

## Дорожная карта (что осталось за срезом)

- Акт 1 до конца: посадка меняет пейзаж шире (поляна), финальная кат-сцена с Tween-камерой.
- Экономика Милы: торговля (соль/моты), мот-песок как валюта.
- Звонная книга Ирвина: журнал заданий расширяется за пределы одного квеста.
- Tiled-импорт: альтернативный путь производства карт (для больших локаций).
- Спектакль звонарей: мини-сцена с StateMachine-хореографией (витрина StateMachine вне боя).