Faset_Engine/PLAN.md

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

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

Статус: C++ MVP реализован и принят; первый tag — v0.1.0-mvp. Исходники движка проверены на 4cb82556de31268d2bde73948dd1ff1b6c02f162; финальная публикация добавляет документацию и свидетельства, сохраняя код движка. Досье M0–M9 связывает каждый этап с проверками и точными revisions. Linux проверен на RTX 2080 Ti, Windows — в native CI через SwiftShader; это не сертификация всех GPU/драйверов. Системный IME и физические переходы между мониторами не проверены, native Wayland restore имеет явный skip; XWayland и Windows lifecycle прошли. Текст/DPI проверены на уровне widgets и SDL. Эти границы покрытия сохраняются открыто и не выдаются за пройденные сценарии. Контракты находятся в 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 и скорость итераций

Начальные бюджеты отслеживания для конкретных демо и Linux reference host: frame p95 ≤ 4 мс, GPU/readback p95 ≤ 1 мс, simulation/snapshot p95 ≤ 0,5 мс, явные Vulkan allocations ≤ 20 MiB, startup от main() ≤ 500 мс. Методика и исходные измерения ограничивают область этих чисел; для других сцен/ОС нужны отдельные baselines. Это бюджеты P1, а не обещание такой производительности любой игры.

Добавить 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.

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, сценарии, платформы/оборудование, результаты, ограничения и ссылки на отчёты. До такой записи пункты остаются открытыми.