Document Faset architecture and roadmap through MVP

PLAN.md

@@ -0,0 +1,221 @@
+# План разработки Faset Engine
+
+Версия 1.0 · 18 сентября 2026 года.
+
+**Статус:** базовая архитектура принята; реализация движка и MVP ещё не началась. Выполнены исследование исходников, выбор архитектуры и создание карты документации. Все пункты реализации ниже открыты. Этот документ определяет порядок работ; контракты подсистем находятся в [ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## 1. Результат MVP
+
+MVP — редактор и runtime, на которых можно завершить два небольших десктопных проекта: 2D-сцену с управляемым персонажем и физикой Box2D и 3D-сцену с моделью из Blender, физикой Box3D, освещением и дверью с поведением на C++.
+
+Для обоих проектов работает полный путь: создать проект → собрать сцену руками или через MCP редактора → сохранить и открыть → запустить отдельный Player → изменить C++ и пересобрать → экспортировать → запустить самостоятельную игру на Linux и Windows.
+
+### Обязательные границы
+
+- MCP обслуживает только редактор и его сервисы авторинга, импорта и сборки. Play/Stop и логи — функции редактора; API чтения или изменения игрового мира через MCP не создаётся. Player и экспорт не содержат MCP.
+- C++ gameplay входит в MVP. Lua — обязательный следующий этап, но не условие MVP и не обязательная зависимость каждой игры.
+- Собственный retained-mode UI редактора имеет основную тёмную тему; Dear ImGui остаётся отладочным инструментом.
+- Базовый renderer требует Vulkan 1.3 и явно проверяемый набор возможностей; аппаратный RT, mesh shaders и виртуализированная геометрия не обязательны.
+- Blender используется без модификации исходников. Обычный импорт GLB работает без дополнения; дополнение обеспечивает удобный экспорт и устойчивые IDs.
+- Gameplay статически линкуется с Player в development и release. Изменение C++ требует stop/build/restart; сохранение состояния при горячей замене C++ не входит в MVP.
+- Windows-сборка первоначально выполняется и проверяется на Windows, Linux-сборка — на Linux. Кросс-компиляция не является условием MVP.
+- Редактируемая сцена отделена от симуляции. Stop сохраняет авторский документ; изменения игры автоматически в него не переносятся.
+
+### За пределами MVP
+
+Lua, C++ hot reload, Blender live link, встроенное изображение Player, стабильный ABI между разными SDK, наследуемые варианты шаблонов, multiplayer/rollback, полноценные игровые UI и audio toolkit, advanced animation tools, виртуальные текстуры и аналоги Nanite/Lumen/VSM. Небольшой HUD или звук демонстрации не следует превращать в такие подсистемы.
+
+## 2. Правила реализации
+
+Этап закрывается работающим результатом и записанными проверками. Порядок зависит от готовности контрактов, а не от заранее обещанных календарных сроков. Внутри этапа задачи оформляются небольшими изменениями с подходящей проверкой.
+
+- Архитектура хранит принятые контракты, PLAN — статус и объём. Исследования сохраняют наблюдения об исходных проектах и явно обозначают историю альтернатив.
+- Скриншот, API-заглушка или сборка только одной ОС не означают завершение этапа.
+- Корректность, удобство и производительность проверяются отдельно. Числа публикуются вместе со сценой, оборудованием, настройками и методом измерения.
+- Форматы, миграции и команды проверяются без GUI; GPU и оконное поведение — в соответствующей среде.
+- Исходные данные и настройки хранятся в Git. Кэши восстанавливаются. Сбой не заменяет рабочие данные частично подготовленной версией.
+
+## 3. Этапы до MVP
+
+### M0. Воспроизводимый фундамент
+
+**Результат:** минимальный C++-проект собирается в согласованной среде Linux и Windows.
+
+- [ ] Создать targets Core, Runtime, Editor, Player, SchemaExporter, инструментов и примеров; запретить зависимости Runtime/Player на Editor/MCP.
+- [ ] Настроить CMake presets, Ninja, Clang/clang-cl, development/release и базовые проверки CI обеих ОС.
+- [ ] Зафиксировать стандарт C++, версии компиляторов, Windows SDK/runtime, библиотек и Slang; определить проверяемую матрицу ОС, архитектур и GPU.
+- [ ] Закрепить EnTT, SDL3, Slang, Box2D, Box3D и отладочный ImGui с воспроизводимым получением, notices и возможностью локальной сборки. Research commits не считать автоматически dependency versions.
+- [ ] Определить ошибки, журналирование, проверки инвариантов, владение ресурсами и формат диагностик.
+- [ ] Выбрать необходимые библиотеки шрифтов/текста, изображений и glTF, зафиксировать их лицензии и владельцев интеграции.
+
+**Готово:** чистая сборка проходит на обеих ОС, пример запускается, версии видны в отчёте. Офлайн-сборка проверяется с заранее подготовленными инструментами и зависимостями; обязательных облачных сервисов нет.
+
+### M1. Документы, метаданные и команды
+
+**Зависит от:** M0. **Результат:** авторский документ корректно меняется и сохраняется без GUI.
+
+- [ ] Реализовать постоянные ID ресурсов, объектов, компонентов, типов и полей; временные runtime handles с world/session и generation хранить отдельно.
+- [ ] Создать явную типизированную C++-регистрацию схем, декларативные constraints и подсказки Inspector; отделить описание данных от исполняемых callbacks.
+- [ ] Ввести версионированные JSON-форматы проекта, сцены, материала и import settings; стабильную запись и сохранение неизвестных данных отсутствующего модуля.
+- [ ] Создать AuthoringService: query, команды, транзакции, validation, revisions, Undo/Redo, dirty state, атомарное сохранение и recovery.
+- [ ] Поддержать объекты, компоненты, изменение полей и иерархии, batch-команды и понятные ошибки.
+- [ ] Добавить миграции с fixtures: переименование при прежнем FieldId, новый default, несовместимый тип и отсутствующая схема.
+
+**Готово:** round-trip сохраняет смысл и ID; неверная транзакция не применяется частично; Undo/Redo восстанавливает ссылки; устаревшая revision даёт конфликт. Документы не содержат EnTT handles или адресов памяти.
+
+### M2. Платформа и базовая графика
+
+**Зависит от:** M0; загрузка сцены подключается к M1.
+
+- [ ] Подключить SDL3 через Faset Platform: окно, ввод, текст, DPI и Vulkan surface.
+- [ ] Реализовать Vulkan 1.3 backend с проверкой features/limits/formats, ресурсами, синхронизацией и освобождением после завершения GPU.
+- [ ] Создать Render Graph на одной graphics queue с явными чтениями/записями и barriers; подключить validation и метки проходов.
+- [ ] Компилировать Slang в SPIR-V с закреплёнными layout/binding conventions; выгружать reflection в собственный формат. Проверить совместимый HLSL-пример.
+- [ ] Получить спрайты, прозрачность и слои для 2D; static meshes, текстуры, базовый PBR, свет и обычную shadow map для 3D.
+- [ ] Использовать direct draws и CPU frustum culling как эталон; ввести CPU/GPU timings и счётчики ресурсов.
+- [ ] Обновлять шейдер с безопасной заменой pipeline: ошибка сохраняет рабочий вариант, изменение layout требует проверки совместимости.
+
+**Готово:** корректны resize/minimize, пересоздание attachments и повторный запуск; validation не сообщает ошибок в проверяемых сценариях. В игру идут SPIR-V и метаданные без обязательного Slang compiler. Создание pipelines драйвером остаётся отдельным этапом.
+
+### M3. Runtime, gameplay, физика и Player
+
+**Зависит от:** M1 и M2 для визуального запуска.
+
+- [ ] Преобразовывать authoring-сцену в EnTT-мир с картой происхождения и удобным typed API объектов/компонентов.
+- [ ] Создать gameplay static library и SchemaExporter с теми же регистрациями: экспорт схем без запуска gameplay lifecycle или графического окна. Editor читает проверяемый декларативный результат.
+- [ ] Реализовать OnStart, Update, FixedUpdate, LateUpdate, OnDestroy и события физики; регистрировать только нужные обработчики.
+- [ ] Зафиксировать tick (default 60 Гц): structural commands → ввод → FixedUpdate → физика → readback/events → реакции. Spawn/despawn и изменение состава компонентов вступают в силу со следующего tick.
+- [ ] Вызывать Update один раз за игровой кадр, LateUpdate после подготовки отображаемых положений. Интерполяция не пишет обратно в симуляцию.
+- [ ] Подключить независимые адаптеры Box2D/Box3D: тела и коллайдеры для демо, collision layers, события и debug drawing. Динамическим телом управляет физика; телепортация явная.
+- [ ] Ограничить catch-up (начальный лимит четыре ticks за проход); лишнее время локального Player отбрасывать с диагностикой. После pause/reset не догонять паузу; teleport/spawn сбрасывает историю интерполяции.
+- [ ] Запускать Player отдельным процессом/окном из текущего снимка сцены, включая несохранённые правки; реализовать Play/Stop, pause/single-step, логи и обработку завершения.
+
+**Готово:** C++-поведение появляется в Inspector через schema export, двигает объект и реагирует на физику. Stop сохраняет авторскую сцену. Ошибка сборки оставляет старую схему/сборку с явным статусом устаревания; старый результат не выдаётся за новый. Player не содержит MCP и не требует Editor.
+
+### M4. Собственная UI-основа
+
+**Зависит от:** M1, M2.
+
+- [ ] Построить retained tree, layout, clipping/scroll, события, focus, keyboard navigation, drag/drop и lifecycle widgets.
+- [ ] Подключить шрифты/shaping по выбору M0; проверить кириллицу, выделение/редактирование текста, clipboard, IME и разный DPI.
+- [ ] Разделить C++-поведение, декларативную компоновку и стили с тёмной темой; поддержать программное создание Inspector.
+- [ ] Реализовать кнопки, текстовые/числовые поля, списки/дерево, выбор ресурса, вкладки, панели и разделители.
+- [ ] Добавить минимальный docking в одном окне и сохранение раскладки; дополнительные системные окна редактора отложить.
+- [ ] Перезагружать layout/styles с проверкой и сохранением рабочего состояния; ImGui использовать для диагностики.
+
+**Готово:** интерфейс доступен клавиатурой, текст и DPI работают, стили меняются без C++ rebuild. Правка widget вызывает AuthoringService; один drag создаёт один Undo.
+
+### M5. Ресурсы и Blender
+
+**Зависит от:** M1, M2; UI состояния подключается по M4.
+
+- [ ] Реализовать AssetId, import settings, dependency graph, artifacts и manifest готового поколения.
+- [ ] Включить в ключ кэша входы, настройки, версии importer/toolchain и целевой профиль; показывать ошибки/устаревшие результаты.
+- [ ] Импортировать профиль glTF/GLB и изображения для демо; описать PBR-подмножество, единицы, оси и collider policy.
+- [ ] Поддержать обычный GLB без Blender add-on; явно ограничить matching после rename/restructure без устойчивых IDs.
+- [ ] Создать минимальное необязательное дополнение обычного Blender: export button, сохраняемые IDs и manifest; записывать версию exporter и профиль.
+- [ ] Обновлять только импортированную основу, сохраняя gameplay/physics settings и overrides Faset. Исчезновение цели создаёт конфликт.
+- [ ] Публиковать GLB/manifest/зависимости как согласованное поколение; ошибка/отмена оставляет последний рабочий artifact.
+- [ ] Предоставить одинаковый импорт через UI/CLI/MCP редактора; длительная операция имеет ID, progress и cancellation.
+
+**Готово:** изменение mesh в Blender обновляет несколько экземпляров без потери компонентов/overrides; rename со стабильным ID сохраняет связь, удаление создаёт понятный конфликт. Игра использует cooked assets без Blender.
+
+### M6. Редактор и повторно используемые сцены
+
+**Зависит от:** M1, M3, M4, M5.
+
+- [ ] Собрать Scene Tree, Inspector, Asset Browser, 2D/3D viewport, Console, Project Settings и команды Save/Play/Build.
+- [ ] Реализовать selection, focus, gizmos, создание объектов/компонентов, поиск и основные shortcuts.
+- [ ] Ввести шаблон как scene asset: InstanceId, исходные ObjectId/ComponentId, sparse overrides и вложенные экземпляры без циклов.
+- [ ] Адресовать overrides по цепочке инстанцирования и IDs, независимо от имён/parenting; при duplicate remap внутренних ссылок, внешние сохранить.
+- [ ] Поддержать локальные добавления, suppression, ограниченный reparent внутри экземпляра с явным local/world transform; массивы переопределять целиком.
+- [ ] Показывать происхождение значения, Revert и открытие источника. Сохранять конфликтующие данные исчезнувших targets/types; Apply to template и inherited variants отложить.
+- [ ] Обеспечить одинаковые операции и Undo/Redo для 2D/3D; восстановить проект с очищенным кэшем.
+
+**Готово:** пользователь создаёт сцену без ручного JSON, размещает два экземпляра, меняет один, обновляет источник, отменяет правки и переоткрывает проект без потери идентичности.
+
+### M7. MCP редактора и расширения
+
+**Зависит от:** M1, M5, M6; headless проверки возможны раньше GUI.
+
+- [ ] Подключить MCP к AuthoringService: документы/query/schema, create/delete/set, batches, Undo/Redo, import/build/export, Play/Stop и диагностика редактора.
+- [ ] Ввести capabilities и структурированные ошибки. Headless authoring/build не требует GUI; screenshot editor viewport требует render backend и GPU.
+- [ ] Проверять revisions и конфликты ручных/MCP-изменений; не повторять слепую запись поверх нового состояния. Повтор запроса не дублирует завершённую транзакцию.
+- [ ] Предоставить jobs ID/progress/result/cancellation; отделить отмену задачи от Undo документа.
+- [ ] Загружать editor DLL/SO при старте: manifest, exact SDK/build compatibility, зависимости и владельцы регистраций. Обновление — через перезапуск.
+- [ ] Проверить extension-пакет с runtime-компонентом и editor-командой/панелью; правки документов проходят через command API.
+
+**Готово:** ручные и MCP-операции дают эквивалентные канонические документы и историю. Нет MCP runtime-entity read/write; MCP transport отсутствует в Player и SchemaExporter. Отключённый пакет не уничтожает данные неизвестного компонента; экспорт сообщает о нерешённой зависимости.
+
+### M8. Экспорт законченных примеров
+
+**Зависит от:** M3, M5, M6, M7.
+
+- [ ] Создать BuildService: validate → C++/schema build → resource/Slang cook → package → проверить результат.
+- [ ] Разделить development/release manifests; исключить Editor, MCP, Blender, schema helpers и shader compiler из обязательного runtime игры.
+- [ ] Подготовить две маленькие 2D/3D-игры с исходниками, понятным управлением и сценариями проверки.
+- [ ] Проверить stop/build/restart, save/reopen, nested scenes, Blender reimport и shader compile failure.
+- [ ] Собрать обе игры на каждой целевой ОС и запустить в чистой среде с поддерживаемым GPU-драйвером и документированными runtime-зависимостями.
+- [ ] Сформировать notices, manifest ресурсов/toolchain, отчёт и инструкции разработчику/игроку.
+
+**Готово:** все четыре сочетания «2D/3D × Linux/Windows» запускаются без исходного дерева Faset и редактора. Недостающий asset или библиотека обнаруживаются до публикации пакета.
+
+### M9. Приёмка MVP
+
+**Зависит от:** M0–M8.
+
+- [ ] Пройти новую установку и создание проекта по документации на обеих ОС.
+- [ ] Повторить authoring-сценарий руками и через MCP; проверить Undo/Redo и конфликт revision при одновременной правке.
+- [ ] Проверить recovery после сбоя сохранения, импорта, сборки и завершения Player с ошибкой.
+- [ ] Записать startup, edit/build/run, import, CPU/GPU frame time и memory с оборудованием/сценами; по результатам установить бюджеты следующего этапа.
+- [ ] Устранить блокирующие дефекты UX, текста, DPI, форматов и exports; записать ограничения.
+- [ ] Обновить docs, приложить проверенные результаты и только затем поставить первый MVP tag.
+
+## 4. Развитие после MVP
+
+### P1. Lua и скорость итераций
+
+Добавить Lua runtime/editor пакет поверх публичного API, проверяемых handles и схем. Предусмотреть диагностику, отладку, Inspector и явный lifecycle перезагрузки. Сохранение состояния при reload проектируется отдельно. Проверка: C++ и Lua используют одни данные/фазы; C++-only export не включает Lua.
+
+Улучшать schema/build cache, сообщения компилятора, шаблоны проектов, переход к коду, autosave и измеренное время «изменение → результат». Dynamic gameplay loading рассматривать при подтверждённой проблеме линковки.
+
+### P2. GPU-driven visibility и LOD
+
+Сохранить direct renderer как эталон. Порядок: GPU instance IDs → GPU frustum culling → fixed indirect batches → current HZB/debug view → two-pass occlusion с контролем истории → подготовленный mesh LOD с hysteresis.
+
+Проверять пустую сцену, рост/переполнение буферов, массовое удаление, открывающуюся дверь, исчезновение заслона, camera cut, teleport и resize. Не требовать синхронного GPU readback. Сравнивать полный кадр на закрытых и открытых сценах: HZB может быть дороже эталона. Основа — [исследование 15](docs/studies/15-renderer-implementation-notes.md).
+
+### P3. Освещение, тени и temporal reconstruction
+
+Расширить local lights, добавить clustered/Forward+ при измеренной необходимости, cascaded sun shadows и ограниченный local shadow atlas. Shadow views имеют собственную видимость и бюджеты.
+
+Затем: previous transforms, motion vectors, jitter, history rejection и TAA; temporal upscaling — после устойчивого TAA. Проверять тонкую геометрию, движение, disocclusion, camera cut и смену разрешения, сравнивать с режимом без temporal. У cache/pass видны затраты и причины обновления.
+
+### P4. Непрямой свет и продвинутая геометрия
+
+Начать с подготовленного непрямого света и reflection probes; затем исследовать динамическую GI с бюджетами памяти/обновления и screen/world-space данными. RT — дополнительный путь для подходящих GPU, с базовой альтернативой. Критерии: заслоны, невидимые камерой поверхности, утечки света, изменение освещения и время полного кадра.
+
+Cluster LOD, streaming/residency, visibility buffer, virtual shadow maps и virtual textures — самостоятельные проекты после измерения узких мест. Подобные техники не означают автоматического достижения масштаба Nanite/Lumen. Очередность GI и виртуализации геометрии зависит от демонстрационной игры и профилирования.
+
+### P5. Инструменты создания игр
+
+- Animation/skinning workflows, state machines, blending и root motion с согласованной фазой симуляции.
+- Игровой UI и audio pipeline как отдельные задачи; повторное использование низкоуровневых сервисов без включения всего редактора в игру.
+- Tilemaps, анимация спрайтов, 2D-свет, удобные коллизии и специализированный импорт.
+- Material/node editor с общими схемами и shader diagnostics; расширенная post-processing pipeline.
+- Variants, безопасное Apply to template, overrides коллекций и инструменты разрешения конфликтов.
+- Task scheduler после профилирования: объявленные чтения/записи компонентов и внешних ресурсов, structural barriers и согласованные physics jobs. Сам EnTT не обеспечивает эту потокобезопасность.
+
+### P6. Доставка и экосистема
+
+Проверяемый native plugin ABI для выбранных сценариев, SDK/пакеты, миграции, доступность, локализация, несколько окон, встраиваемый вид Player и Blender live link.
+
+Другие graphics backends, cross-compilation, remote build workers и ОС оцениваются отдельно. Сеть, replay/rollback и multiplayer требуют собственного контракта; фиксированный timestep его не создаёт. MCP остаётся редакторской интеграцией, а не API экспортируемой игры.
+
+## 5. Зависимости и запись результата
+
+Критический путь: M0 → M1/M2 → M3/M4/M5 → M6 → M7 → M8 → M9. UI-прототип может использовать простую поверхность M2; сервисы M1/M5/M7 проверяются без готового GUI. Контракты данных/владения/форматов согласуются до параллельной реализации потребителей.
+
+P1–P3 могут развиваться параллельно после MVP при наличии проверок; P4 требует зрелого renderer и диагностики. P5/P6 выбираются по потребностям игр и не считаются обязательным содержимым ближайшего релиза.
+
+Для закрытого этапа записывать commit/tag, сценарии, платформы/оборудование, результаты, ограничения и ссылки на отчёты. До такой записи пункты остаются открытыми.