MetaCore/docs/designs/metacore-infernux-reference-roadmap.md

MetaCore Infernux Reference Roadmap

Status: active implementation reference Updated: 2026-06-01

Goal

Use the local Infernux source tree as a Unity-like behavior reference while keeping MetaCore's native architecture intact.

MetaCore keeps:

• C++20 static components as the first scripting surface.
• EnTT scene storage with GameObject/Component editor semantics.
• Filament rendering.
• ImGui editor UI.
• RmlUi runtime UI.
• JSON authoring assets and Cooked runtime assets.

Infernux is used only to understand complete engine workflows. It is not a build dependency, and its Python/Vulkan architecture is not imported into MetaCore.

Local reference path:

D:/MetaCore/.codex/external/Infernux

Reference Policy

Allowed:

• Read Infernux source before implementing a MetaCore feature.
• Extract user-visible behavior, state transitions, data flow, and acceptance tests.
• Recreate workflows in MetaCore's C++/Filament/RmlUi architecture.

Not allowed for the mainline implementation:

• Add Infernux as a dependency.
• Import pybind11 or the Python production layer.
• Port the Vulkan RenderGraph or RenderStack.
• Use Infernux packaging based on Nuitka/PyInstaller.
• Use ImGui as MetaCore runtime UI.

Small MIT-licensed code snippets may only be copied after an explicit licensing review and with attribution. The default is behavior-level reimplementation.

Module Map

Milestone	Infernux reference	MetaCore implementation target	Implementation rule
M1 Component/Inspector	components/component.py, components/serialized_field.py, engine/ui/inspector_components.py, engine/ui/inspector_utils.py	MetaCoreReflection, MetaCoreIComponentTypeRegistry, editor Inspector	Replace Python descriptors with C++ reflection metadata and static registration.
M2 AssetDatabase/Project	C++ AssetDatabase, Python Project panel integration	MetaCoreIAssetDatabaseService, Project panel, import pipeline	Keep .mcmeta, GUID, and AssetRecord as MetaCore ownership model.
M3 Prefab	engine/_scene_prefab.py, prefab undo commands	.mcprefab.json, MetaCoreIPrefabService, PrefabInstanceMetadata	Recreate Create/Instantiate/Apply/Revert/Break behavior using MetaCore scene documents.
M4 Play Mode	engine/play_mode.py, _play_mode_serialization.py	MetaCoreIPlayModeService, runtime scene clone, C++ lifecycle	Use scene snapshots/clones; do not introduce Python runtime scripts.
M5 Scene View/Gizmos	_scene_view_gizmo.py, gizmos/*, C++ EditorTools	ImGuizmo path first, C++ OnDrawGizmos later	Keep ImGuizmo initially; only move to Filament-drawn gizmos after workflow gaps are proven.
M6 Materials	material assets, previewer, inspector material fields	Filament material assets and MeshRenderer material references	Copy behavior, not Vulkan shader/resource code.
M7 Runtime UI	ui/ui_canvas.py, ui/ui_text.py, ui/ui_image.py, ui/ui_button.py	RmlUi UI documents and Player rendering	Match Canvas/Text/Image/Button workflow through RmlUi.
M8 Build Settings	engine/ui/build_settings_panel.py, game builder	Build Settings document, Cook, Player package	Use MetaCore Cook/Package instead of Python app bundling.
M9 RuntimeData	Infernux runtime diagnostics patterns as loose reference	Existing MetaCoreRuntimeData	RuntimeData integrates after the engine workflow is stable.

Implementation Order

1. M1: C++ component reflection and automatic Inspector foundation.
2. M2: AssetDatabase and Project panel production workflow.
3. M3: Prefab workflow.
4. M4: Play Mode isolation and C++ lifecycle.
5. M5-M9: Scene interaction, materials, runtime UI, build pipeline, RuntimeData integration.

Acceptance Rule

Before implementing each milestone, inspect the matching Infernux module and write down the behavior being mirrored. The MetaCore implementation is accepted only when the same workflow works through MetaCore-native systems.