# 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