73 lines
14 KiB
Markdown
73 lines
14 KiB
Markdown
# 04. Принятые рекомендации для Faset Engine
|
||
|
||
**Редакция 18.09.2026.** Здесь собраны выводы исследования после утверждения пользователем. Это проектные решения, не описание уже реализованных возможностей. Основной контракт — [ARCHITECTURE.md](../ARCHITECTURE.md); этапы и критерии до/после MVP — [PLAN.md](../../PLAN.md). Разбор других движков остаётся в исследованиях как обоснование.
|
||
|
||
Faset — движок для десктопных 2D- и 3D-игр под Linux и Windows. Он должен давать понятный ручной authoring workflow и те же операции над проектом через MCP. Первый результат — маленькие 2D- и 3D-демо, созданные в редакторе и экспортированные в самостоятельные игры на обеих ОС.
|
||
|
||
## 1. Принятый стек
|
||
|
||
- Ядро и gameplay сначала на C++; EnTT для runtime ECS. Автор работает с объектами и компонентами, не с устройством ECS storage.
|
||
- Поддержка Lua обязательно добавляется после C++-основы отдельным модулем. Использование Lua конкретным проектом необязательно; C++ остаётся полноценным способом писать игру.
|
||
- SDL3, Vulkan 1.3, собственный renderer и RenderGraph, Slang. Baseline 3D — обычные PBR-материалы и тени; передовые технологии из UE развиваются после MVP.
|
||
- Собственный retained UI редактора на C++, декларативные layout/styles и тёмная тема по умолчанию. ImGui — инструмент отладки, не основа пользовательского интерфейса.
|
||
- CMake + Ninja; Clang на Linux, clang-cl на Windows. Gameplay статически включается в отдельный Player. Редакторские plugins — DLL/SO под точную версию SDK/toolchain.
|
||
- Box2D и Box3D, отдельные миры и типы для 2D/3D с общими правилами lifecycle и диагностики. Конкретные dependency pins закрепляются при интеграции.
|
||
|
||
## 2. Источник истины и границы процессов
|
||
|
||
AuthoringService владеет JSON-документами сцен/ресурсов, metadata schema, стабильными IDs, validation, revisions, транзакциями и Undo. UI, CLI, редакторские plugins и MCP вызывают его операции. Runtime world создаётся отдельно из проверенного snapshot; EnTT handles временные и не сериализуются.
|
||
|
||
Play запускает отдельный Player со snapshot редактируемой сцены. Дальнейшие изменения документа не меняют этот snapshot. Начальный цикл C++: Stop → incremental build → Play; редактор сохраняет рабочий контекст. Состояние Player не записывается обратно в сцену автоматически. Универсальный native hot reload и обратный Apply runtime state не входят в MVP.
|
||
|
||
**Граница MCP принята явно:** редактор/authoring, импорт, build/export, Play/Stop и editor logs. MCP не инспектирует и не редактирует runtime world. Player и экспортированные игры не содержат MCP server/client; управление запуском остаётся редакторской операцией.
|
||
|
||
## 3. Постоянные идентификаторы и метаданные
|
||
|
||
Различаются `ObjectId` авторского объекта, `ComponentId` конкретного компонента, `TypeId` его схемы, `FieldId` поля, `AssetId` ресурса, `InstanceId` размещения шаблона и временный runtime handle. Имя типа, подпись объекта и путь файла не подменяют идентичность. Переименование поля сохраняет `FieldId`; несовместимое изменение формата требует schema migration.
|
||
|
||
Явные metadata содержат тип, defaults, units/ranges, enum values, Inspector grouping, ссылки, schema version и доступность операции. Inspector, сериализация, validation и authoring MCP используют одну схему. Она не означает автоматическую рефлексию произвольного C++ и не заменяет будущие Lua bindings.
|
||
|
||
JSON содержит стабильные IDs и версии схем. Cooked данные — отдельный двоичный формат. Native pointers, GPU IDs и EnTT handles в authoring source недопустимы. Неизвестные компоненты сохраняются с диагностикой, чтобы отсутствие editor plugin не уничтожало данные.
|
||
|
||
## 4. Сцены, шаблоны и nested instances
|
||
|
||
Scene — открываемый документ объектов/компонентов; template/prefab — та же модель как повторно используемый ресурс. Экземпляр хранит ссылку на шаблон и override layer. Вложения ацикличны. Идентичность унаследованного объекта — instance chain плюс исходный `ObjectId`; цепочка инстанцирования независима от transform parenting.
|
||
|
||
Patch адресует instance chain, `ObjectId`, `ComponentId`, `FieldId` и проверяет `TypeId`. В v1 массив заменяется целиком. Порядок значений: шаблон → overrides вложенного размещения в содержащем шаблоне → overrides внешнего экземпляра. Последний явный override выигрывает; Revert удаляет его и возвращает нижележащее значение.
|
||
|
||
Добавления получают новые IDs в документе-владельце. Дублирование экземпляра создаёт новый `InstanceId`, переназначает внутренние ссылки и сохраняет внешние. Reparent разрешён внутри одного экземпляра с проверкой циклов; перенос через nested boundary запрещён. Перемещение экземпляра целиком допустимо; сохранение local/world transform задаётся явно.
|
||
|
||
Удаление унаследованного объекта — suppression объекта и разрешённого поддерева. Удаление локального добавления изменяет документ-владелец. Ссылки и patches на исчезнувшую/подавленную цель, несовместимый тип и цикл дают конфликт; пользовательские данные не отбрасываются. Пока новая версия не согласована, сохраняется последняя рабочая. [Подробные правила](01-architecture.md).
|
||
|
||
В MVP входят композиция, field overrides, добавление объектов/компонентов, suppression и ограниченный reparent. **После MVP:** template variants/наследование, Apply overrides to template, перенос между экземплярами, поэлементное слияние массивов.
|
||
|
||
## 5. Транзакции и Undo
|
||
|
||
Любая authoring-команда явно задаёт документ, targets и ожидаемую revision. Сначала строится и проверяется кандидат, затем публикуется одно изменение; конфликт revision не даёт частичного результата. Ручной drag использует временный preview и один commit/Undo; MCP batch также создаёт одну согласованную authoring-транзакцию. Это не глобальная транзакция поверх всех файлов проекта.
|
||
|
||
Команды возвращают новые IDs, revision, изменения и структурированную диагностику. Долгие операции получают operation ID, progress/status/cancel. Повтор с тем же idempotency key и payload возвращает сохранённый результат в пределах определённого срока журнала. Runtime structural command buffer решает другую задачу и не создаёт editor Undo на каждый gameplay tick.
|
||
|
||
## 6. Ассеты и официальный Blender
|
||
|
||
Источник истины — исходные ресурсы, настройки импорта и постоянные IDs. Derived cache восстанавливается; importer version, recipe, зависимости и target profile участвуют в invalidation. Публикация нового поколения происходит после полной проверки; error/cancel сохраняют последнюю рабочую версию.
|
||
|
||
Используется обычный официальный Blender без патчей или отдельного fork. Стандартные glTF/GLB импортируются самостоятельно. Необязательный Python add-on добавляет удобную кнопку, устойчивые IDs частей и manifest для более надёжного roundtrip. Без source IDs нельзя гарантировать сопоставление после rename/reorder; при неоднозначности нужны diagnostic и явный remap, а не угадывание по имени.
|
||
|
||
Blender принадлежит геометрия, rig и animation; gameplay, physics settings и overrides принадлежат Faset. Reimport обновляет baseline и сохраняет совместимый пользовательский слой. Произвольные Blender material graphs не переносятся автоматически: поддерживается оговорённый glTF PBR-профиль, процедурные материалы требуют bake/ручного соответствия. Pixel-perfect совпадение разных renderer не обещается. [Разбор импорта](17-asset-pipeline-and-blender-roundtrip.md).
|
||
|
||
## 7. Редактор и доступность действий
|
||
|
||
Обязательный первый интерфейс: Project/Asset Browser, Scene Tree, schema Inspector, 2D/3D viewport, выбор/transform, Undo/Redo, open/save, Play/Stop и Build. Главные действия доступны через меню, shortcuts и command palette; ошибки показывают target и причину. Состояния template, instance override и conflict различимы без одного только цвета.
|
||
|
||
Custom widgets и plugins используют общий binding/transaction слой. DLL/SO загружается только при точном соответствии SDK; registrations принадлежат plugin scope и снимаются при завершении его жизненного цикла. Gameplay Player не зависит от редакторского UI или plugins. Наличие декларативного layout не требует собственного визуального UI Builder в MVP.
|
||
|
||
## 8. До и после MVP
|
||
|
||
До MVP нужны identity/schema, документы/транзакции, EnTT mapping, базовые 2D/3D rendering и physics, импорт glTF/GLB, экземпляры/overrides, retained editor UI, editor-only MCP, отдельный Player и воспроизводимый build/cook/export. Интеграция проверяется на двух небольших демо под Linux и Windows. Сборка на одной ОС не доказывает работу другой.
|
||
|
||
После MVP развиваются обязательный Lua-модуль, графика по выбранным измеряемым направлениям, advanced profiling/tools, расширенный Blender live link, variants и более сложные операции над шаблонами. Nanite/Lumen/VSM/TSR-подобные механизмы не являются условием первого самостоятельного экспорта. Точная последовательность и проверки собраны в [PLAN.md](../../PLAN.md).
|
||
|
||
## 9. История альтернатив — superseded
|
||
|
||
Первоначальный обзор предлагал выбрать язык позже, сравнивал C#/Flecs, готовые native/web UI и ImGui, допускал remote runtime world в automation, ранние prefab variants и один основной dimensionality slice. Эти варианты сохраняются в историческом сравнении, но не являются текущими рекомендациями Faset. Приняты C++/EnTT и собственный retained UI, editor-only MCP, nested composition без inheritance в MVP и два небольших сквозных 2D/3D-демо.
|