gengjiayuan/MetaCore
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
master
MetaCore/docs/designs/metacore-runtime-data-usage.md

5.6 KiB
Raw Permalink Blame History

MetaCore RuntimeData 使用说明

生成时间：2026-03-27
状态：草案
范围：第一阶段 A / Sprint 4+

目的

这份文档说明当前 MetaCore RuntimeData 管线应该如何实际使用。

它主要服务于：

  • 内部开发
  • 演示准备
  • 第一轮交付验证

当前支持的 adapter 类型：

  • mock
  • file_replay
  • tcp

当前运行时配置产物：

  • Runtime/ProjectRuntime.mcruntimecfg
  • Runtime/DataSources.mcruntime
  • Runtime/Bindings.mcruntime
  • Runtime/Diagnostics.mcruntimestate

当前交付模型

当前流程如下：

  1. 编写或生成运行时配置
  2. 保存二进制 .mcruntime 文档
  3. 启动 MetaCorePlayer
  4. 通过某个 adapter 喂入运行时更新
  5. 验证场景对象是否按照 binding 发生变化

RuntimeData 文件

默认样例位置：

当前支持的 binding 目标

第一阶段当前支持：

  • Transform.Position
  • MeshRenderer.Visible
  • MeshRenderer.BaseColor
  • Light.Intensity
  • Light.Color

方案一：File Replay 演示

这是最简单的演示路径。

生成 replay 配置

D:\MetaCore\build\vs2022-debug\Debug\MetaCoreRuntimeConfigTool.exe D:\MetaCore\TestProject\Runtime

这会生成：

  • ProjectRuntime.mcruntimecfg
  • replay 版本的 DataSources.mcruntime
  • Bindings.mcruntime
  • Main.mcscene
  • RuntimeReplay.mcstream

启动 Player

D:\MetaCore\build\vs2022-debug\Debug\MetaCorePlayer.exe

预期结果：

  • MetaCorePlayer 会从项目 / runtime 配置里加载启动场景
  • MetaCorePlayer 会加载二进制 .mcruntime
  • 运行时数据来自 file_replay
  • 样板对象会随时间改变位置、显隐、颜色和告警灯强度

方案二：TCP 演示

这是当前最小 live adapter 路线。

生成 TCP 配置

D:\MetaCore\build\vs2022-debug\Debug\MetaCoreRuntimeConfigTool.exe D:\MetaCore\TestProject\Runtime --tcp

这会生成：

  • ProjectRuntime.mcruntimecfg
  • TCP 版本的 DataSources.mcruntime
  • Bindings.mcruntime
  • Main.mcscene

当前默认 TCP source 使用：

  • host = 127.0.0.1
  • port = 7001

启动 Player

D:\MetaCore\build\vs2022-debug\Debug\MetaCorePlayer.exe

启动 TCP 发送器

D:\MetaCore\build\vs2022-debug\Debug\MetaCoreTcpSenderTool.exe

预期结果：

  • MetaCorePlayer 连接 TCP source
  • 发送器逐行输出 runtime updates
  • 样板对象会改变位置、显隐、颜色和告警灯强度

TCP 文本协议

当前行格式：

<data_point_id> <value_type> <payload>

示例：

cube.visible bool true
cube.position vec3 1.0 2.0 3.0
cube.base_color vec3 0.7 0.6 0.5

支持的值类型：

  • bool
  • int64
  • double
  • string
  • vec3

Studio 中的使用方式

当前 Studio 的入口有：

  • Inspector 面板
    • Runtime Data Bindings
  • 运行时数据 面板

Inspector 当前支持

  • 新增 Replay Source
  • 新增 TCP Source
  • 编辑 source 显示名
  • 编辑 source adapter 类型
  • 编辑 replay 的 file_path
  • 编辑 TCP 的 host
  • 编辑 TCP 的 port
  • 新增 DataPoint
  • 编辑 data point 的 Point Id
  • 编辑 data point 的 External Address
  • 编辑 data point 的 Source
  • 编辑 data point 的 Value Type
  • 给当前对象新增 binding
  • 编辑 binding target 和绑定的数据点
  • 保存 runtime 配置

RuntimeData 面板当前支持

  • source / data point / binding 数量统计
  • 项目 runtime 路径摘要
  • 最近一次 Player 写出的 diagnostics 快照
  • source 摘要
  • 校验结果摘要
  • 当前所有校验问题列表

校验规则

当 runtime 配置中存在 Error 级问题时，保存会被拒绝。

当前阻断规则包括：

  • 空或重复的 SourceId
  • 空 AdapterType
  • file_replay source 缺少 file_path
  • tcp source 缺少 port
  • 空或重复的 DataPointId
  • DataPoint 引用了不存在的 SourceId
  • 空或重复的 BindingId
  • Binding 引用了不存在的 DataPointId
  • Binding 缺少 TargetObjectId

当前 Warning 包括：

  • 空 ExternalAddress
  • 没有定义任何 source

推荐演示流程

如果只是为了最快演示：

  1. 用 MetaCoreRuntimeConfigTool 生成配置
  2. 打开 MetaCoreEditorApp
  3. 如有需要，在 Inspector 中调整 binding
  4. 保存 runtime 配置
  5. 启动 MetaCorePlayer
  6. 用 replay 或 TCP sender 喂数据

常用构建命令

cmake --build --preset build-debug --target MetaCoreEditorApp MetaCorePlayer MetaCoreRuntimeConfigTool MetaCoreTcpSenderTool MetaCoreSmokeTests

Smoke Test 命令

D:\MetaCore\build\vs2022-debug\Debug\MetaCoreSmokeTests.exe

当前限制

这些限制是当前阶段有意为之：

  • TCP adapter 仍然是最小文本协议，不是工业协议
  • runtime diagnostics 当前是二进制快照导出，不是完整时序监控系统
  • binding 目标是白名单，不支持任意反射路径
  • Studio 的 source 编辑还是表单式，不是完整表格或节点图

下一步建议

  • 给 Player 增加运行时 diagnostics overlay 或面板
  • 增加多对象、多 source 的样板项目
  • 在当前 TCP 边界之上接一个更接近生产的 adapter