# План разработки Faset Engine

Версия 1.1 · 18 сентября 2026 года.

**Статус:** идёт реализация MVP. Готовность этапов определяется всеми их критериями, включая проверку обеих ОС; отдельные работающие подсистемы ещё не закрывают этап целиком. Текущие результаты и ограничения записаны в [журнале реализации](docs/IMPLEMENTATION.md). Этот документ определяет порядок работ; контракты подсистем находятся в [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 остаётся отладочным инструментом.
- Основной язык интерфейса редактора, встроенных команд, диагностик, публичного API и описаний CLI/MCP tools — английский. Пользовательский текст и проекты поддерживают Unicode; локализация редактора следует после MVP.
- Базовый 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 с прямыми вызовами Vulkan API, проверкой features/limits/formats, ресурсами, синхронизацией и освобождением после завершения GPU; изолировать Vulkan handles и команды от gameplay и редакторских API.
- [ ] Создать 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.
- [ ] Реализовать кнопки, текстовые/числовые поля, списки/дерево, выбор ресурса, вкладки, панели и разделители.
- [ ] Оформить встроенные подписи, команды, подсказки и сообщения на английском; проверить, что Unicode-текст проекта отображается и редактируется независимо от языка интерфейса.
- [ ] Добавить минимальный 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, сценарии, платформы/оборудование, результаты, ограничения и ссылки на отчёты. До такой записи пункты остаются открытыми.