MetaCore/docs/designs/metacore-mature-engine-gap-and-work-plan.md

MetaCore 与成熟引擎的差距及工作计划

更新时间：2026-07-13
状态：当前差距评估与执行建议
读者：产品、架构、引擎、编辑器、渲染、工具链、测试、交付

目的

本文基于当前仓库代码、测试和已有设计文档，回答两个问题：

1. MetaCore 与 Unity、Unreal Engine、Godot 等成熟通用引擎相比，还缺少什么。
2. 在 MetaCore 当前“工业仿真、数字孪生、国产化 C/S 交付”的产品定位下，接下来真正需要做什么。

本文不是要求第一阶段复制成熟引擎的全部功能，而是把“通用能力差距”和“当前产品必须补齐的能力”分开管理，避免功能面无限扩张。

当前结论

MetaCore 已经超过单纯编辑器 Demo 阶段，当前具备：

• EnTT ECS 与 GameObject + Component 场景语义。
• 场景层级、选择、复制、删除、重挂接、保存和加载。
• ImGui 编辑器壳、Hierarchy、Scene、Inspector、Project、Console 等基础工作流。
• Filament 场景渲染、PBR、glTF/GLB、环境光、基础阴影和编辑器离屏视口。
• GUID、meta、Asset Database、导入、重导入、依赖图、热重载和 Cook 基础链路。
• 基础 Prefab 创建、实例化、Apply 和 Revert。
• 原生 C++ 行为注册及 OnPlayStart / FixedUpdate / Update / LateUpdate / OnPlayStop 生命周期。
• glTF 动画元数据导入、Clip 选择、循环、速度控制和运行时播放。
• RmlUi 运行时 UI、UI 文档和可视编辑工作流基础。
• 独立 Player、RuntimeData TCP/文件回放、场景绑定和诊断。

截至 2026-07-13，当前 MetaCoreSmokeTests 构建成功并全部通过，一次完整运行耗时约 65.90 秒。

综合判断：项目处于“早期 Alpha 的垂直引擎底座”阶段。架构主线已经成立，但生产可用性、运行时系统广度、性能工程和发布可靠性仍明显弱于成熟引擎。

差距总览

能力域	当前基础	主要问题	产品优先级
发布与部署	Player、Cook、运行时配置	尚未形成可重复、可验证的完整交付包	P0
资产管线	GUID、meta、依赖、热重载、glTF	Import Settings、派生数据、预览和引用修复不完整	P0
用户逻辑开发	原生 C++ 行为和生命周期	缺用户脚本工程、编译热重载、调试和通用事件/时间系统	P0
输入与运行时交互	键鼠采集、编辑器交互	缺 Input Map、运行时事件和统一输入路由	P0
物理	未形成独立模块	缺碰撞、刚体、射线、触发器和角色控制	P1；有仿真交互需求时升 P0
渲染生产力	Filament、PBR、glTF、环境光	灯光、阴影、后处理、LOD、粒子和调试视图不足	P1
动画	Clip 导入与播放	缺状态机、混合、重定向、Root Motion 和动画工具	P1
UI	RmlUi 运行时与编辑器基础	控件、事件、适配、数据绑定和编辑/运行一致性不足	P1
Scene / Prefab	单场景和基础 Prefab	缺多场景、流式加载、嵌套 Prefab、Variant 和细粒度 Override	P1
工程基础设施	CMake、代码生成、Smoke Tests	缺分层测试、性能回归、GPU 回归、CI 和崩溃诊断	P0/P1
音频	无正式系统	缺完整音频资源和运行时	P2
导航 / AI	无正式系统	缺 NavMesh、寻路、避障和调试工具	P2
XR / Web	主要为架构预留	缺 OpenXR 与 Web 构建交付闭环	后续阶段

P0：当前必须解决的问题

1. 发布与部署还不具备正式交付厚度

Linux 首发执行状态（2026-07-13）

• 建立 Linux x86_64 BuildProfile、公共发布服务以及 CLI / Editor 共用入口。
• 建立 Build -> Cook -> Stage -> Package -> Validate 命令链和原子 staging。
• 生成运行时项目描述、SHA-256 Release Manifest、便携目录、归档和独立符号包。
• Player 支持严格交付模式、任意工作目录启动、版本/缺失/损坏错误码和有限帧 smoke 参数。
• 增加日志轮转、Crashpad 本地 Minidump 接口、handler staging 和现场诊断包导出。
• 解决 Crashpad vcpkg 端口与当前 libc++ 15 的兼容问题，并完成真实 Minidump/符号回溯验收。
• 增加 Ubuntu 22.04 clean-container 验证脚本与镜像定义。
• 在正式 Ubuntu 22.04 clean image 完成 GPU/UI smoke 实机验收。
• 实现并验收 Windows 对等后端；完成前本问题不能全平台关闭。

问题

• Cook 已存在，但尚未形成统一的一键 Build / Package 工作流。
• 缺少 Debug、Development、Release 以及目标平台构建 Profile。
• 缺少运行库、Filament、字体、材质和项目内容的自动依赖收集。
• 缺少从空输出目录构建以及 clean machine 运行验证。
• Linux Player 启动流程仍存在未接入路径。
• 缺少发布清单、引擎/资产版本兼容规则、补丁和升级策略。
• 现场崩溃后的日志、Dump、符号和诊断收集能力不足。

需要做的事

• 定义统一 BuildProfile：平台、配置、图形后端、启动场景、输出目录和资源策略。
• 建立 Build -> Cook -> Stage -> Package -> Validate 命令链。
• 自动收集可执行文件、动态库、Filament 材质、RmlUi、字体、配置和 cooked 资产。
• 生成包含文件 Hash、版本和依赖信息的发布 Manifest。
• 完成 Windows 与 Linux Player 启动和路径规则统一。
• 建立 clean-machine 或干净容器验证脚本。
• 增加缺文件、损坏资产、版本不兼容时的明确错误报告。
• 建立崩溃 Dump、日志归档和现场诊断包导出能力。

验收标准

• 从干净输出目录执行一次命令即可生成完整交付包。
• 交付包不依赖源码目录、vcpkg 安装目录或编辑器工作目录。
• 在未安装开发工具链的目标机器上可以启动、加载启动场景并显示 UI。
• 删除任一必需文件后，验证工具能够在交付前报告具体缺失项。

2. 资产管线还不是生产级

问题

• glTF/GLB 是当前正式主线，但 FBX/OBJ 等格式仍偏占位或不完整。
• 纹理缺少色彩空间、压缩、Mipmap、最大尺寸、法线贴图等 Import Settings。
• 缺少稳定的缩略图、资源预览和派生数据缓存。
• 批量导入和复杂重导入可能阻塞编辑器主线程。
• 移动、重命名、删除和重导入后的引用检查与修复工具仍不完整。
• 子资产、平台差异化 Cook 和缓存失效规则仍需强化。

需要做的事

• 明确 glTF/GLB 的正式支持矩阵和导入错误规范（见 资产导入契约）。
• 删除或明确标识通用占位导入结果，避免占位资产被当成成功导入。
• 建立 Model、Texture、Material 的版本化 Import Settings。
• 实现纹理色彩空间、Mipmap、尺寸、压缩和法线贴图设置；Linux 生产链使用 Basis Universal UASTC/KTX2，None 保留未压缩像素链。
• 建立缩略图与预览缓存，并定义缓存失效条件；纹理、材质球和固定相机模型预览均由后台服务生成并持久化。
• 把大型模型解析、纹理处理和派生数据生成移出 UI 主线程；解析循环和 Basis 编码支持协作式取消，原子提交阶段不可中断。
• 增加资源引用检查、孤立资源检查和 GUID/路径修复工具，并报告失效引用、无入边资产和构建不可达资产。
• 建立独立 Assets 黄金回归目标，覆盖 glTF 外部 Buffer、模型 Mesh 产物、纹理 KTX2、缩略图、损坏输入、不支持格式和构建不可达分析；层级、材质、贴图和动画覆盖继续由 Smoke 回归验证。

实施状态（2026-07-14）：R2 的导入契约、版本化设置、DDC、事务化后台作业、UASTC/KTX2 纹理链、持久化预览、Asset Index、引用审计、安全删除、构建不可达分析及独立黄金回归均已完成。当前验收范围按项目决策锁定为 Linux；Windows 兼容与平台门禁不作为本问题的关闭条件，后续单独恢复。

验收标准

• 同一源资产和相同设置可生成稳定一致的导入结果。
• 重导入不改变稳定子资产 GUID，也不破坏 Scene、Prefab 和 Material 引用。
• 大型资产导入期间编辑器仍可响应，并显示进度、取消和错误信息。
• 资产移动、重命名或删除后可准确列出受影响引用。

3. 用户逻辑开发闭环不完整

Linux 首期实施状态（2026-07-15）

• 路线锁定为 Linux x86_64 原生 C++ 项目插件；嵌入式语言、Windows 对等后端和编辑器内调试器不在首期范围。
• 新增 Editor / Player 共用的 MetaCoreScripting 运行时，统一生命周期、字段、时间、事件和定时器执行。
• 建立版本化 C ABI、Capability 协商、不透明对象句柄和受控组件/字段访问，动态库边界不暴露 STL、EnTT 或编辑器上下文。
• 建立脚本工程和行为模板、Clang 15/libc++ 构建、唯一 Build ID 输出、compile_commands.json 及 VS Code/LLDB Attach 配置。
• Inspector 提供生成工程、创建行为、后台编译和加载入口；Playing/Paused 时新模块排队，Stop 回到 Edit 后再原子替换。
• 候选模块支持 ABI、Schema、TypeId、Manifest 和 SHA-256 校验；失败时保留旧模块和场景字段。
• 字段支持稳定 Field ID、旧名称迁移、Bool/Int/Float/Vec3/String/AssetRef/GameObjectRef，并保留未知或失效引用数据。
• Player 加载同一脚本模块并执行同一生命周期；发布流水线构建、Stage、记录、校验模块与独立调试符号。
• 增加独立 MetaCoreScriptingTests，覆盖字段迁移、失败回退、句柄失效、异常隔离、事件重入、定时器清理及真实插件生成/编译/加载。
• 在安装 LLDB/CodeLLDB 的开发环境完成 Editor 与 Player 用户代码断点、调用栈和单步人工验收。
• 使用包含项目脚本的正式 clean Ubuntu 22.04 发布包完成独立 Player 实机验收。

问题

• 当前原生 Script Registry 能承载内置行为，但还不是面向项目开发者的成熟脚本系统。
• 缺少用户脚本项目的创建、编译、加载、卸载和热重载流程。
• 缺少稳定的脚本 API、组件访问、安全失效和版本兼容规则。
• 缺少脚本断点、调用栈、字段错误和生命周期异常诊断。
• 缺少统一事件总线、定时器、协程或任务调度抽象。

需要做的事

• 明确第一阶段脚本路线：Linux x86_64 原生 C++ 项目插件；嵌入式语言后续评估。
• 建立项目脚本模板、构建目标和编辑器编译入口。
• 支持脚本模块加载、卸载和失败回退。
• 定义脚本 API 稳定边界和对象/组件句柄失效规则。
• 支持可序列化字段、资源引用和 GameObject 引用。
• 增加统一时间、定时器和事件系统。
• 增加脚本错误定位、日志上下文和运行时异常隔离。
• 在明确安全边界后实现仅 Edit 态提交的脚本热重载。

验收标准

• 用户可以在项目目录创建一个新行为并在编辑器中完成编译和挂载。
• 行为字段可编辑、保存、加载，并进入 Player。
• 编译或加载失败不会破坏当前场景，且能定位到具体脚本和错误。
• Play/Stop 后运行态修改按照明确规则恢复或保留。

4. 缺少通用运行时输入与交互层

问题

• 当前输入主要服务编辑器相机、选择和 Gizmo。
• 缺少 Action / Axis、输入配置资源和用户重绑定。
• 3D 对象、运行时 UI 和脚本之间缺少统一事件路由。
• 缺少运行时 Raycast、Hover、Click、Drag 等高层交互语义。

需要做的事

• 定义 Input Action、Axis、Binding 和 Input Context 数据模型。
• 支持键盘、鼠标和基础手柄映射。
• 建立编辑器输入、Game View 输入和 Player 输入的焦点规则。
• 统一 RmlUi 与 3D 场景输入路由和事件消费顺序。
• 为运行时对象提供点击、悬停、拖拽和射线命中事件。
• 将输入配置纳入项目、Cook 和 Player 加载链路。

实施结果：已新增 MetaCoreRuntimeInput/MetaCoreRuntimeInteraction，由平台逐帧输入快照经 RmlUi 消费后求值 Input Map，并通过 Filament GPU Picking 生成定向 3D 交互事件。Editor Play Mode 与独立 Player 共用 Runtime/Input.mcruntime、脚本输入 ABI 和用户重绑定覆盖；项目创建、Cook/Stage 与正式打包校验均已接入。模块测试覆盖输入生命周期、Context 消费、序列化/损坏回退、异步 Picking 乱序与 Click 路由，相关 Scripting、Delivery 和端到端 Smoke Tests 同步通过。

验收标准

• 同一份输入配置可以在编辑器 Play Mode 和独立 Player 中工作。
• UI 捕获输入时不会错误操作 3D 场景。
• 用户可修改按键绑定而不重新编译项目。

5. 工程验证不足以支撑长期交付

问题

• 测试覆盖面已有不错基础，但大部分集中在一个耗时约一分钟的 Smoke Test 程序中。
• 缺少模块级单元测试、GPU 截图回归、性能基准和长稳测试。
• 缺少 Windows、Linux、统信、麒麟等目标平台的持续构建矩阵。
• 缺少内存、资源生命周期、启动时间和场景帧时间回归门槛。

需要做的事

• 把 Smoke Tests 拆分为 Foundation、Scene、Assets、Editor、RuntimeData、RuntimeUi 等测试目标。
• 保留端到端 Smoke Tests，同时缩短单次反馈时间。
• 增加 glTF、Scene、Prefab、Material、UI 的黄金文件回归测试。
• 增加 Filament 关键场景截图对比测试。
• 建立启动、导入、加载、帧时间和内存基准。
• 建立目标平台 CI 构建与 Player 启动检查。
• 增加 AddressSanitizer、UndefinedBehaviorSanitizer 或对应平台内存诊断任务。

验收标准

• 普通模块修改能在较短时间内得到对应测试结果。
• 渲染输出、资产格式或性能发生非预期变化时，CI 能够发现。
• 每个正式支持平台至少有构建、启动和最小场景加载验证。

P1：主干闭环后需要补强的能力

6. 物理与空间查询

需要引入可替换的物理模块边界，并逐步提供：

• Collider、RigidBody、Trigger 和 Physics Material。
• Raycast、Shape Cast、Overlap Query。
• 固定时间步、碰撞层和碰撞矩阵。
• 约束、角色控制器和物理调试视图。
• 场景序列化、Prefab、脚本回调和 Player 集成。

关闭状态（2026-07-17）：问题 6 在 Linux x86_64 正式关闭。MetaCorePhysics 使用可替换后端边界和 Bullet 3 单线程、单精度 CPU 世界，坐标约定与引擎统一为 Z-up，默认重力为 (0, 0, -9.81)。已交付基础/凸包/静态三角网格 Collider、Static/Kinematic/Dynamic RigidBody、Trigger、32 层碰撞矩阵、物理材质、同步 Raycast/Shape Cast/Overlap、Fixed/Hinge/Slider/6DoF、Z-up 胶囊角色控制器、脚本 Physics Capability、Editor Play Mode、Player、Cook 校验和 Physics/GPU 混合交互拾取。

最终补强包括：子层级 Collider 按最近刚体聚合为 compound shape，并在嵌套 RigidBody/CharacterController 处停止；查询和接触事件同时保留子 Collider ID 与刚体所有者 ID；角色控制器通过 sweep 完成最大坡度、台阶、墙面滑动、落地/跳跃、头顶阻挡和动态刚体推力语义；Scene View 的 Physics Debug 开关在 Edit Mode 使用无模拟预览世界、在 Play Mode 使用正式世界，绘制形状、AABB、活动/睡眠/Trigger/角色颜色、接触点与法线、约束与限制、最近查询及 Body/Contact/Query/固定步耗时统计。

网格碰撞派生数据采用版本化 .mccollision 格式，缓存键覆盖 Mesh GUID、源载荷 Hash、有效缩放、形状/烘焙设置和 Bullet 后端版本；源载荷或缩放变化会自动失效，版本不兼容会被拒绝。Editor 使用 DDC 原子缓存，Cook 将碰撞派生数据收集到 Content/Physics，独立 Player 优先读取该派生数据并保留开发态原始包回退；Cook 继续拒绝缺失载荷、损坏内容、动态凹网格以及 CharacterController/RigidBody 非法组合。

验收结果：linux-development 完整构建成功，Editor 与 Player 均完成链接，CTest 7/7 通过。MetaCorePhysicsTests 覆盖 compound 聚合边界、子 Collider 命中、缓存失效、四类约束/Motor/断裂、Trigger 生命周期、Z-up 下落、角色坡度/落地/跳跃/头顶阻挡/台阶/推挤及序列化。基准场景包含 10,000 个静态 Collider、100 个动态刚体和每帧 1,000 次 Raycast；Linux x86_64 保守基线为世界构建 52.1 ms、固定步 4.58 ms、1,000 次 Raycast 1.21 ms、RSS 35.4 MiB，CTest 门禁分别为 62.5 ms、5.5 ms、1.45 ms 和 42.5 MiB（基线的 120%，按测量精度向上取整）。

正式限制：本轮关闭平台仅为 Linux x86_64；Windows 保留编译边界但不是门禁。首版不包含 Soft Body、布料、流体、车辆、关节骨骼、异步查询或动态凹三角网格，也不承诺跨平台位级确定性。单个 compound 刚体下的子 Collider 必须使用相同碰撞层和 Trigger 设置；不一致的组合会禁用该物理体并输出诊断，避免 Bullet 的 body 级过滤/响应产生错误语义。

第一阶段若只展示静态数字孪生场景，可以延后刚体模拟，但空间查询和触发交互通常应优先实现。

7. 渲染生产力

需要补齐：

• Directional、Point、Spot Light 的完整组件语义。
• 阴影开关、级联、质量、偏移和性能配置。
• 天空盒、IBL、静态反射探针和环境配置资产化。
• 后处理 Profile：曝光、色调映射、Bloom、抗锯齿等。
• 模板化 Material 扩展工作流，而不只依赖固定 PBR 参数。
• LOD Group、实例批次、遮挡剔除和大型场景可见性策略。
• 粒子、Line/Trail、Decal、Terrain 等常用表现组件首版。
• Lit/Unlit、材质通道、级联、LOD、遮挡、探针及性能调试视图。

阶段实施状态（2026-07-22）

R7.1–R7.4 的代码交付范围已经接通；问题 7 的功能清单在本版本完成。正式关闭仍受本文末尾列出的“GPU 参考机签收门禁”约束：当前工作站没有可用的 NVIDIA 参考环境，因此不能把 SSIM、GPU p95 和 Editor/Player 像素一致性伪报为通过。

已经完成：

• 新增独立 MetaCoreRendering 模块及生成式反射注册；建立版本化 MetaCoreRenderSettingsDocument、MetaCoreEnvironmentProfileDocument 和 MetaCorePostProcessProfileDocument。新项目会生成 Runtime/Rendering.mcruntime，Editor、Player 和 Cook 使用同一份配置。
• MetaCoreLightComponent 已支持 Directional、Point、Spot、物理强度、颜色/色温、范围、Spot 内外角、衰减、阴影开关、Bias、Normal Bias、优先级和 Lighting Mask。旧场景缺少灯光类型时迁移为 Directional，并将旧归一化强度迁移到物理强度范围。
• Filament 后端已创建并增量同步三类灯光，映射位置、方向、强度、范围、Spot Cone、灯光通道及阴影参数；方向光支持 1/2/4 级联和分割/距离/Atlas 配置，Point/Spot 阴影按优先级、相机距离和对象 ID 确定性分配预算。
• Environment/Post-process Profile 已具备版本化二进制读写和 GUID 引用。运行时扫描 Assets、Runtime，按 Camera > Scene > 引擎默认值解析后处理；缺失 Profile 会报告 GUID 和回退行为。Cook 会收集启动场景引用的 Profile，并拒绝缺失、损坏或版本不兼容的内容。
• Profile 和 Runtime/Rendering.mcruntime 现在按文件路径、大小及修改时间检测变化，并在最多约 250 ms 内重新加载；同一 GUID 的内容修改、新建 Profile 和 KTX 更新都会重新提交，不再要求重启 Editor。Game View 使用主相机并与 Player 保持 Camera > Scene > 默认值优先级；Scene View 继续使用编辑器相机和 Scene Profile。Bloom 阈值 UI 已按 Filament 实际能力收敛为固定 1.0 阈值开关，不再显示无效的任意数值滑块。
• 后处理已映射 None/FXAA/TAA、1/2/4/8 MSAA、Bloom、手动曝光、ACES/Filmic/Linear Tone Mapping、饱和度和对比度。自动曝光会根据环境和场景物理灯光估算照度，在 Profile 上下限内按亮/暗适应速度平滑；TAA+MSAA 会确定性降级为 MSAA 1 并输出诊断。默认曝光已改为 EV100 15、Bloom 默认关闭，修复导入普通 PBR 模型看起来像自发光的问题。
• 材质资产已增加稳定 TemplateId + TemplateVersion + 强类型参数表，注册 PBR、Unlit、Transparent、Decal、Terrain、Particle、Line/Trail 七种内置模板；Inspector 根据 Schema 编辑参数，模板切换仅迁移名称和类型兼容的值，旧 Shader Model 自动迁移且保持材质 GUID。
• 七种模板现在都有引擎随版本发布的 .mat 源码和由 Host matc 生成的 .filamat；Editor/Player 构建会自动 stage，Cook 生成包含模板版本、源码 Hash、产物 Hash、平台、后端和编译选项的 templates.manifest.json。项目材质缺模板、参数不兼容或使用未来模板版本时 Cook 失败；Player 不执行临时材质编译。
• 已新增 ReflectionProbe、LODGroup、ParticleEmitter、LineRenderer、TrailRenderer、DecalProjector、Terrain 的可反射组件定义，并接通场景快照、JSON、Prefab 创建/实例化/Apply、Undo/Play 状态、Inspector、Render Snapshot 和 Player 类型注册。确定性算法层现已包含 LOD 迟滞、阴影分配、最多两个反射探针选择/归一化混合、实例批次键、遮挡宽限历史、可见性原因统计，以及固定随机种子的 CPU 粒子模拟和全局/发射器预算丢弃。
• Reflection Probe Inspector 新增源环境、16–2048 烘焙尺寸、派生 GUID 和“烘焙/重新烘焙”入口。tools/bake_reflection_probe.sh 使用 GLIBC 兼容 cmgen 输出版本 1 的 probe_ibl.ktx、probe_skybox.ktx、SH 和带源 SHA-256 的 probe.mcrprobe；Cook 校验版本、GUID、路径、KTX 和源 Hash，并收集到 Content/Rendering/ReflectionProbes/<GUID>。
• Render Bridge 已接入静态 BVH，依次执行 Layer/距离/视锥、LOD、实例批次和保守遮挡；遮挡使用上一帧 64×36 深度层级、相机突变/动态/新出现对象宽限。统计现在包含提交/可见、各剔除原因、LOD、实例批次、Draw Call、可见三角形、显存估算及 CPU/GPU 时间。实例批次键改为无字符串分配的 GUID Hash，100k CPU 基准 p95 从 26.00 ms 降至 2.66 ms。
• Filament 执行后端新增可复用动态 Vertex/Index Buffer 池：CPU 粒子转 Billboard，Line/Trail 转相机朝向 Ribbon，Decal 首版提交 Box Projector 体，Terrain 导入 16-bit Heightmap 并按距离改变采样步长；全局粒子/动态线预算确定性截断，Terrain 投射/接收阴影。相关资源随 Editor、Play Mode 和 Player 使用同一 Render Snapshot。
• 修复 ParticleEmitter 首次发射或粒子数增长时动态网格扩容导致的 Filament PreconditionPanic：统一按“移出 Scene、销毁 Renderable/Entity、销毁 MaterialInstance、销毁 Vertex/Index Buffer”的依赖顺序释放资源。该路径同时覆盖 Particle、Line、Trail、Decal 和 Terrain；Smoke 回归会强制执行 1→128 粒子扩容、组件移除和桥接器关闭。
• Scene View 新增 Lit、Unlit、Wireframe、Overdraw、World Normal、Albedo、Roughness、Metallic、Shadow Cascades、LOD、Occlusion、Reflection Probe 模式；专用 render_debug.filamat 在调试时替换 primitive 材质并在切回 Lit 时恢复。Development Player 可使用 --render-debug <mode>，正式 Release Player 确定性拒绝该参数并输出诊断。
• Editor 新增“渲染设置”面板，可编辑 Runtime/Rendering.mcruntime 的质量、级联阴影、Atlas/本地光阴影预算、AA/MSAA、实例化、LOD、遮挡宽限、粒子及动态线预算。Scene 面板可创建/选择并直接编辑 Environment/Post-process Profile；Camera Inspector 可设置 Post-process 覆盖，并明确显示 Camera > Scene > 引擎默认值的优先级。
• 新增独立 MetaCoreRenderTests，覆盖渲染配置/Profile 往返、Profile 优先级、模板校验与迁移、LOD 迟滞、阴影/粒子预算、反射探针双混合、实例分批、遮挡宽限、可见性统计、CPU 粒子确定性，以及七类表现组件的场景快照和 JSON 往返。

首版实现边界与待签收项：

• Filament 的环境光是 Scene 级对象；本版保存并计算最多两个对象探针的权重、烘焙和交付数据，但 Lit 路径尚不能对每个 glTF primitive 做真正的双探针纹理混合。调试视图可显示选择与权重。这是当前后端限制，不应描述成已经完成对象级混合。
• 自动曝光使用场景物理灯光/环境估算，不是 GPU 亮度直方图；Wireframe/Overdraw 是诊断材质替换，其中 Overdraw 还不是逐像素累加热图。
• Decal 当前是 Box Projector 体提交与 Layer/距离/角度 CPU 过滤，尚未实现对接收表面的法线/Base Color 投影；Terrain 已渲染 16-bit 高度场和距离 LOD，但四层混合、Picking 与 Bullet 静态高度场尚未进入执行后端。这几项必须在 GPU 签收前继续补齐，不能用组件/算法存在代替完成。
• 工业厂区正式门禁仍未执行：需要修复 NVIDIA 驱动并锁定参考机，在 1920×1080 固定相机路径记录 Manifest、SSIM ≥ 0.995、稳态 CPU/GPU p95 ≤ 16.67 ms 和相对基线不回退超过 10%。因此“功能清单完成”不等于问题 7 已正式关闭。

本次构建与验证

• 构建根目录：/home/hello/MetaCore/build/linux-development。
• Filament Host Tools 构建根目录：/home/hello/MetaCore/build/filament-host-tools；工程实际使用的工具位于 build/filament-host-tools/install/bin/matc 和 build/filament-host-tools/install/bin/cmgen。
• CMake 配置：Ninja、RelWithDebInfo；目录名为 linux-development，但它不是纯 Debug 构建。
• Editor 可执行文件：build/linux-development/MetaCoreEditorApp。
• Player 可执行文件：build/linux-development/MetaCorePlayer。
• 渲染测试：build/linux-development/MetaCoreRenderTests。
• 100k CPU 可见性基准：build/linux-development/MetaCoreRenderBenchmark。
• 主要静态库：build/linux-development/libMetaCoreRendering.a、libMetaCoreRender.a、libMetaCoreEditor.a。
• 2026-07-22 最新验证已重新编译并链接 MetaCoreRenderTests、MetaCoreSmokeTests、MetaCoreEditorApp 和 MetaCorePlayer；沙箱内 MetaCoreRenderTests 与 MetaCoreSmokeTests CTest 2/2 通过。另在宿主 DISPLAY=:0、NVIDIA RTX 4060、OpenGL 后端使用 METACORE_SMOKE_PARTICLE_LIFECYCLE_ONLY=1 定点执行粒子动态 Renderable 的创建、1→128 扩容、移除和 Shutdown，退出码为 0。此前 100k 基准结果为：100k 输入、17,955 可见对象、32,767 BVH 节点，BVH 构建 28.15 ms、120 帧稳态 CPU p95 2.66 ms；该数值仅覆盖 CPU 可见性与实例分组，不冒充 1080p GPU 帧时间。
• 已解决 Ubuntu 22.04 / GLIBC 2.35 上 SDK 预编译 matc、cmgen 依赖 GLIBC 2.38 而无法启动的问题。tools/build_filament_host_tools.sh 会检出与 SDK 匹配的 Filament v1.71.5（提交 b0f2090cccf3c11f524ed8053746aba3de6be199），在目标主机上用 Clang/libc++ 构建并安装 Host Tools；CMake 会优先探测这组工具，也允许通过 METACORE_FILAMENT_MATC、METACORE_FILAMENT_CMGEN 单独覆盖路径。
• 新 matc、cmgen 的 ELF 版本需求最高均为 GLIBC_2.35，已在当前 GLIBC 2.35 主机执行验证：matc 成功重新生成 grid.filamat、rml_ui.filamat，cmgen 成功从 HDR 生成 IBL KTX、Skybox KTX 和球谐系数。首次准备工具执行 ./tools/build_filament_host_tools.sh，后续构建可复用增量产物。
• 本轮 ELF 检查结果：MetaCoreEditorApp 与 MetaCorePlayer 的最高需求为 GLIBC_2.34，matc 与 cmgen 为 GLIBC_2.35，符合 Ubuntu 22.04 / GLIBC 2.35 目标版本。
• 调整位置：全局质量/阴影/AA/LOD/遮挡/粒子和动态线预算及调试视图在 Editor 的“渲染设置”面板；环境与场景后处理在 Scene 面板“渲染 Profile”；相机覆盖在 Camera Inspector“后处理覆盖”；材质模板和参数在 Material Inspector；灯光、LOD 和表现组件在对象 Inspector；Reflection Probe 的源环境、尺寸及烘焙按钮在该组件 Inspector。
• 当前没有生成 Release/Development 交付包；本次“build”产物是上述 CMake 构建目录中的开发验证二进制。问题 7 只有在剩余执行后端、GPU 回归和工业场景性能门禁完成后才能标记关闭。

8. 动画系统

当前 Clip 播放基础之上，需要逐步增加：

• Animator Controller 和状态机。
• Cross Fade、Blend Tree、Layer 和 Mask。
• 骨骼 Avatar、动画重定向和 Root Motion。
• 动画事件、参数驱动和脚本控制 API。
• 动画预览、时间轴和状态调试器。
• 机械装配动画和 Timeline 类编排能力。

9. UI 系统

需要补齐：

• 稳定的 Button、Image、Text、Input、List、Scroll 等控件库。
• UI 事件、焦点、键盘导航和输入消费规则。
• Anchor、缩放、DPI、宽高比和多分辨率适配。
• 主题、字体、图集、本地化和基础动效。
• UI 到 RuntimeData、脚本和场景对象的统一数据绑定。
• 编辑器预览与 Player 渲染的一致性测试。

10. Scene 与 Prefab

需要补齐：

• 多场景编辑、Additive Load、SubScene 和异步流式加载。
• 大场景分区、按需加载和场景依赖检查。
• 嵌套 Prefab、Prefab Variant 和实例同步。
• 细粒度 Override 记录、可视化、Apply 和 Revert。
• 跨场景对象引用规则。
• Scene、Component、Prefab 的格式版本迁移机制。

11. 编辑器生产力与插件边界

需要补齐：

• 完整 Game View 与分辨率/输入模拟。
• 通用资源拖拽、上下文菜单、搜索和命令面板。
• 布局持久化、崩溃恢复和场景自动保存。
• 项目模板、创建向导、Build Settings 和平台设置面板。
• 稳定的插件 SDK、扩展点、版本检查和插件隔离。
• 大型 Hierarchy、Project Browser 和 Inspector 的性能优化。

P2：按产品需要扩展

这些属于成熟通用引擎常见能力，但不应阻塞第一阶段工业 C/S 交付：

• 音频资源、3D 音频、混音器和流式播放。
• NavMesh、寻路、动态避障和导航调试。
• 通用网络复制、RPC、会话和预测。
• Terrain、植被、复杂粒子和电影级 Timeline。
• OpenXR、VR 交互和设备适配。
• WebGPU、浏览器资源加载和 Web 发布。
• 多人协作编辑、资源锁和版本控制深度集成。
• 可视化脚本、Shader Graph 和高级内容创作工具。

代码结构风险

当前代码虽已建立服务接口和模块机制，但大型实现仍然过度集中：

• MetaCoreBuiltinCoreServicesModule.cpp 约 1 万行。
• MetaCoreBuiltinEditorModule.cpp 约 9500 行。
• MetaCoreEditorApp.cpp 约 3000 行。
• MetaCoreSmokeTests.cpp 约 5500 行。

继续在这些文件中横向增加功能，会逐步放大编译时间、合并冲突、测试隔离和模块替换成本。

需要做的事：

• 按 Asset、Prefab、Script、PlayMode、Material、UI、Build 等职责拆分实现文件。
• 保留现有服务接口，把注册组合留在 Builtin Module 中。
• 将无 UI 的业务逻辑从 ImGui Panel 中抽离为可测试服务。
• 避免 Editor 直接承载 Player 所需的通用运行时逻辑。
• 建立清晰依赖方向，防止 Foundation、Scene、Runtime 反向依赖 Editor。
• 为资源处理、Cook 和后台任务建立统一 Job/Task 抽象。

推荐执行顺序

R1：可交付闭环
  Build Profile -> Stage/Package -> clean-machine 验证 -> 崩溃诊断

R2：生产级内容管线
  Import Settings -> 异步导入 -> 缩略图/缓存 -> 引用检查与修复

R3：应用逻辑与交互
  用户脚本工程 -> 时间/事件 -> Input Map -> UI/3D 事件路由

R4：表现与内容复用
  UI 强化 -> 灯光/阴影/后处理 -> 动画状态机 -> Prefab/Scene 强化

R5：工程化与平台化
  测试拆分 -> 性能回归 -> 平台 CI -> 长稳与资源泄漏验证

R6：按项目需求扩展
  物理 -> 音频 -> 导航 -> XR/Web -> 其他通用引擎能力

其中 R1、R2、R3 是 MetaCore 从“可展示原型”进入“真实项目生产”的关键，不应被 P2 功能插队。

阶段完成定义

当以下条件全部成立时，可以认为 MetaCore 已从早期 Alpha 进入可交付基础版本：

• 用户可以创建项目、导入正式支持的模型和编辑场景。
• 材质、动画、UI、Prefab 和用户行为能够保存、Cook 并在 Player 中运行。
• 项目可以通过统一命令生成不依赖开发环境的交付包。
• 同一项目在 Editor Play Mode 和独立 Player 中的核心行为一致。
• 资产重导入、移动和重命名不会静默破坏引用。
• 脚本、资产和运行时配置错误均有可定位的诊断信息。
• 目标平台具备自动构建、启动、最小渲染和长稳验证。
• 关键工作流有分层测试、黄金资产回归和性能基线保护。

与既有计划的关系

本文是现状评估和后续任务入口，不替代已有专项设计：

• 产品范围仍以 metacore-product-plan.md 和 metacore-phase1-scope.md 为准。
• 现有 M1-M4 文档记录第一阶段原始里程碑，但其中部分状态已落后于当前代码。
• 发布、UI、模型和材质的详细实现继续参考对应专项设计。
• 后续更新 Roadmap 时，应优先把本文 P0 项合并进正式里程碑和验收矩阵。