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

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

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

Сюжетная рамка (акт 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/agent.mjs + tools/agent-lib.mjs + tools/checks/ (агентный мост: check/snapshot/сценарии), 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 — путь к краю занятого/непроходимого тайла (гейтинг взаимодействий по дистанции в демо).
• cutscene/CutsceneRunner.ts — view-агностичный раннер шагов (call/cameraMove/burst/wait/setFlag), шаг с seconds: 0 — параллельный; сцена ставит геймплей на паузу по active.

Новое в движке за срез (агентный набор инструментов)

• agent/types.ts — SceneAgent/AgentHost/Invariant/SnapshotLayer: движковый каркас моста жанронезависим (по образцу StorageLike), тесты без Pixi.
• agent/EngineAgent.ts — снапшот (движковый слой + сцена), инварианты, ручной шаг (step/waitFor), атомарная инъекция ввода (tapVirtual/press/key), команды.
• core/Engine.stepTick/stepTicks/tickCount + GameLoop.setManual/resetTiming — детерминированные шаги логики без «догоняния» rAF.
• input/InputManager.inject* — инъекция через те же структуры, что реальные события.
• dialogue/DialogueRunner — раскрыт для снапшота (nodeId/choices/waitingForChoice).
• Игра: agent/GameAgent.ts (window.__agent), agent/snapshot.ts, data/validate.ts, сцены реализуют SceneAgent (whitelist-команды, lastToast).

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

Текущий срез — движок для ИИ-агента + геймплей на нём (план утверждён):

• ✅ Батч 0 — агентный набор инструментов (готово): мост window.__agent, валидация контента, tools/agent.mjs, смоуки на мосту, docs/llms.txt + docs/engine/agent.md + docs/engine/practices.md.
• ✅ Батч 1 — единый механизм переходов (готово): TransitionDef (step/click, условия, lockedText), дисарм тайла входа, returnTo, сейвы v3, телепорт-колодцы (Звенец ↔ луга), сценарий tools/checks/transitions.mjs.
• Батч 2: интерьеры (дом Ирвина, лавка Милы) + интерактивные объекты.
• Батч 3: взаимодействие с миром шире (знаки/подбор/рычаг, мот-песок).
• Батч 4: ИИ врагов (LOS/шум/патруль/wary/flee/return).
• Принцип среза: каждая геймплейная система имеет сценарий в tools/checks/.

Дальше (запрос игрока, после моста):

• Телепортация (геймплей): точки перехода внутри локации (порталы/колодцы) и между локациями без «пешего» перехода (витрина SceneManager + fade).
• Здания с интерьерами: вход в дома (двери-переходы), интерьерные карты, объекты внутри (сундук, лавка).
• Взаимодействие с миром шире: интерактивные объекты (не только NPC/цветки), осмотр/подбор предметов, реакция мира (вары/флаги).
• Системы и ИИ врагов: расширение EnemyBrain (патруль/агро-радиус/отступление), поведение вне боя — спящие стаи, реакция на звук без боя (витрина StateMachine).

Остальное (по мере готовности базиса):

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