249 lines
5.6 KiB
Markdown
249 lines
5.6 KiB
Markdown
# 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 文件
|
||
|
||
默认样例位置：
|
||
|
||
- [ProjectRuntime.mcruntimecfg](D:/MetaCore/TestProject/Runtime/ProjectRuntime.mcruntimecfg)
|
||
- [DataSources.mcruntime](D:/MetaCore/TestProject/Runtime/DataSources.mcruntime)
|
||
- [Bindings.mcruntime](D:/MetaCore/TestProject/Runtime/Bindings.mcruntime)
|
||
- [Diagnostics.mcruntimestate](D:/MetaCore/TestProject/Runtime/Diagnostics.mcruntimestate)
|
||
- [RuntimeReplay.mcstream](D:/MetaCore/TestProject/Runtime/RuntimeReplay.mcstream)
|
||
- [Main.mcscene](D:/MetaCore/TestProject/Scenes/Main.mcscene)
|
||
|
||
## 当前支持的 binding 目标
|
||
|
||
第一阶段当前支持：
|
||
|
||
- `Transform.Position`
|
||
- `MeshRenderer.Visible`
|
||
- `MeshRenderer.BaseColor`
|
||
- `Light.Intensity`
|
||
- `Light.Color`
|
||
|
||
## 方案一：File Replay 演示
|
||
|
||
这是最简单的演示路径。
|
||
|
||
### 生成 replay 配置
|
||
|
||
```powershell
|
||
D:\MetaCore\build\vs2022-debug\Debug\MetaCoreRuntimeConfigTool.exe D:\MetaCore\TestProject\Runtime
|
||
```
|
||
|
||
这会生成：
|
||
|
||
- `ProjectRuntime.mcruntimecfg`
|
||
- replay 版本的 `DataSources.mcruntime`
|
||
- `Bindings.mcruntime`
|
||
- `Main.mcscene`
|
||
- `RuntimeReplay.mcstream`
|
||
|
||
### 启动 Player
|
||
|
||
```powershell
|
||
D:\MetaCore\build\vs2022-debug\Debug\MetaCorePlayer.exe
|
||
```
|
||
|
||
预期结果：
|
||
|
||
- `MetaCorePlayer` 会从项目 / runtime 配置里加载启动场景
|
||
- `MetaCorePlayer` 会加载二进制 `.mcruntime`
|
||
- 运行时数据来自 `file_replay`
|
||
- 样板对象会随时间改变位置、显隐、颜色和告警灯强度
|
||
|
||
## 方案二：TCP 演示
|
||
|
||
这是当前最小 live adapter 路线。
|
||
|
||
### 生成 TCP 配置
|
||
|
||
```powershell
|
||
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
|
||
|
||
```powershell
|
||
D:\MetaCore\build\vs2022-debug\Debug\MetaCorePlayer.exe
|
||
```
|
||
|
||
### 启动 TCP 发送器
|
||
|
||
```powershell
|
||
D:\MetaCore\build\vs2022-debug\Debug\MetaCoreTcpSenderTool.exe
|
||
```
|
||
|
||
预期结果：
|
||
|
||
- `MetaCorePlayer` 连接 TCP source
|
||
- 发送器逐行输出 runtime updates
|
||
- 样板对象会改变位置、显隐、颜色和告警灯强度
|
||
|
||
## TCP 文本协议
|
||
|
||
当前行格式：
|
||
|
||
```text
|
||
<data_point_id> <value_type> <payload>
|
||
```
|
||
|
||
示例：
|
||
|
||
```text
|
||
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 喂数据
|
||
|
||
## 常用构建命令
|
||
|
||
```powershell
|
||
cmake --build --preset build-debug --target MetaCoreEditorApp MetaCorePlayer MetaCoreRuntimeConfigTool MetaCoreTcpSenderTool MetaCoreSmokeTests
|
||
```
|
||
|
||
## Smoke Test 命令
|
||
|
||
```powershell
|
||
D:\MetaCore\build\vs2022-debug\Debug\MetaCoreSmokeTests.exe
|
||
```
|
||
|
||
## 当前限制
|
||
|
||
这些限制是当前阶段有意为之：
|
||
|
||
- TCP adapter 仍然是最小文本协议，不是工业协议
|
||
- runtime diagnostics 当前是二进制快照导出，不是完整时序监控系统
|
||
- binding 目标是白名单，不支持任意反射路径
|
||
- Studio 的 source 编辑还是表单式，不是完整表格或节点图
|
||
|
||
## 下一步建议
|
||
|
||
- 给 Player 增加运行时 diagnostics overlay 或面板
|
||
- 增加多对象、多 source 的样板项目
|
||
- 在当前 TCP 边界之上接一个更接近生产的 adapter
|