349 lines
5.9 KiB
Markdown
349 lines
5.9 KiB
Markdown
# MetaCore RuntimeData 接入设计
|
||
|
||
生成时间：2026-03-27
|
||
状态：草案
|
||
范围：第一阶段 A
|
||
|
||
## 目的
|
||
|
||
这份文档定义 MetaCore RuntimeData 子系统的第一版正式设计。
|
||
|
||
目标不是一次性解决所有未来接入问题，而是在 Windows C/S 交付闭环里，为实时数据接入提供一条清晰、显式且不会污染场景逻辑或编辑器代码的路径。
|
||
|
||
## 问题陈述
|
||
|
||
第一阶段要求从一开始就支持实时数据接入。
|
||
|
||
这意味着 MetaCore 必须支持：
|
||
|
||
- 连接外部数据源
|
||
- 把输入值归一化
|
||
- 把值绑定到场景对象和组件
|
||
- 安全处理断连和非法 payload
|
||
- 在不改源码的情况下打包和交付项目
|
||
|
||
当前代码库已经具备：
|
||
|
||
- 场景与对象持久化
|
||
- package 与资源格式
|
||
- 编辑器服务注册
|
||
- 运行时场景基础
|
||
|
||
当前代码库尚未完整具备：
|
||
|
||
- 独立的运行时数据源抽象
|
||
- 项目级 binding 模型
|
||
- 归一化的运行时更新格式
|
||
- 明确的故障与重连策略
|
||
|
||
## 设计原则
|
||
|
||
### 1. Runtime 优先
|
||
|
||
RuntimeData 首先是运行时子系统。Studio 只是它的配置编辑端。
|
||
|
||
### 2. 协议相关逻辑必须隔离
|
||
|
||
场景对象不应该直接解析协议 payload。
|
||
|
||
### 3. 显式优先于聪明
|
||
|
||
binding 必须是可检查、可追踪、数据驱动的，不应该依赖对象名推断或隐式约定。
|
||
|
||
### 4. 安全降级
|
||
|
||
坏数据、目标缺失或断连必须以可见且可预测的方式失败。
|
||
|
||
### 5. 第一版表面要小
|
||
|
||
第一阶段只支持最小集合的数据类型和 adapter，再根据真实交付压力扩展。
|
||
|
||
## 推荐模块位置
|
||
|
||
新增一个模块：
|
||
|
||
- `Source/MetaCoreRuntimeData`
|
||
|
||
该模块应依赖：
|
||
|
||
- `MetaCoreFoundation`
|
||
- `MetaCoreScene`
|
||
|
||
该模块不应依赖：
|
||
|
||
- `MetaCoreEditor`
|
||
|
||
下游消费者可以是：
|
||
|
||
- `MetaCorePlayer`
|
||
- 未来用于预览和配置的 `MetaCoreEditor`
|
||
|
||
## 高层架构
|
||
|
||
```text
|
||
外部数据源
|
||
|
|
||
v
|
||
数据源 Adapter
|
||
|
|
||
v
|
||
归一化 Runtime Update
|
||
|
|
||
v
|
||
Binding Dispatcher
|
||
|
|
||
+--> 场景对象 Binding Applier
|
||
|
|
||
+--> Runtime Diagnostics / Fault State
|
||
```
|
||
|
||
## 核心概念
|
||
|
||
### 1. Data Source Definition
|
||
|
||
这部分由项目级配置定义。
|
||
|
||
它描述：
|
||
|
||
- source id
|
||
- adapter 类型
|
||
- 连接参数
|
||
- 启动模式
|
||
- 重连策略
|
||
|
||
建议结构：
|
||
|
||
```text
|
||
MetaCoreDataSourceDefinition
|
||
Id
|
||
AdapterType
|
||
DisplayName
|
||
ConnectionSettings
|
||
AutoConnect
|
||
ReconnectPolicy
|
||
```
|
||
|
||
### 2. Data Point Definition
|
||
|
||
这是项目面对的数据契约。
|
||
|
||
它定义：
|
||
|
||
- source id
|
||
- 外部地址或键
|
||
- 逻辑 point id
|
||
- 期望值类型
|
||
- 更新语义
|
||
|
||
建议结构：
|
||
|
||
```text
|
||
MetaCoreDataPointDefinition
|
||
Id
|
||
SourceId
|
||
ExternalAddress
|
||
ValueType
|
||
UpdateMode
|
||
FallbackBehavior
|
||
```
|
||
|
||
### 3. Scene Binding Definition
|
||
|
||
它把逻辑数据点绑定到场景目标。
|
||
|
||
它定义：
|
||
|
||
- 目标对象 id
|
||
- 目标组件路径
|
||
- 转换规则
|
||
- 可选转换器
|
||
- 缺失数据行为
|
||
|
||
建议结构：
|
||
|
||
```text
|
||
MetaCoreSceneBindingDefinition
|
||
BindingId
|
||
DataPointId
|
||
TargetObjectId
|
||
TargetPath
|
||
BindingMode
|
||
ConverterId
|
||
MissingDataPolicy
|
||
```
|
||
|
||
### 4. Runtime Update
|
||
|
||
这是 adapter 输出的归一化 payload。
|
||
|
||
它不应该暴露协议专属表示。
|
||
|
||
建议结构：
|
||
|
||
```text
|
||
MetaCoreRuntimeDataValue
|
||
Type
|
||
BoolValue
|
||
IntValue
|
||
FloatValue
|
||
Vec3Value
|
||
StringValue
|
||
Timestamp
|
||
Quality
|
||
```
|
||
|
||
```text
|
||
MetaCoreRuntimeDataUpdate
|
||
DataPointId
|
||
Value
|
||
Sequence
|
||
SourceTimestamp
|
||
```
|
||
|
||
## 第一阶段值类型
|
||
|
||
第一阶段故意保持小集合：
|
||
|
||
- `bool`
|
||
- `int64`
|
||
- `double`
|
||
- `string`
|
||
- `vec3`
|
||
|
||
除非有真实客户场景逼迫，不要在第一阶段引入任意 JSON 形态的通用绑定。
|
||
|
||
## Binding 目标
|
||
|
||
第一阶段只应支持一组很窄的 binding 目标。
|
||
|
||
建议初始目标：
|
||
|
||
- `Transform.Position`
|
||
- `MeshRenderer.Visible`
|
||
- `MeshRenderer.BaseColor`
|
||
- `Light.Intensity`
|
||
- `Light.Color`
|
||
|
||
如有必要可追加：
|
||
|
||
- 对象 active / visible 状态
|
||
- 未来 UI 组件的文本字段
|
||
|
||
不要一开始就做“任意反射字段随便绑”的通用系统。看起来优雅，实际通常不可控。
|
||
|
||
## Adapter 接口
|
||
|
||
建议运行时接口：
|
||
|
||
```text
|
||
MetaCoreIRuntimeDataSourceAdapter
|
||
GetAdapterType()
|
||
Configure()
|
||
Connect()
|
||
Disconnect()
|
||
Tick()
|
||
PollUpdates()
|
||
GetStatus()
|
||
```
|
||
|
||
要求：
|
||
|
||
- adapter 拥有传输与协议细节
|
||
- adapter 只输出归一化 update
|
||
- adapter 暴露明确状态
|
||
|
||
### Adapter 状态
|
||
|
||
建议状态：
|
||
|
||
- `Disconnected`
|
||
- `Connecting`
|
||
- `Connected`
|
||
- `Degraded`
|
||
- `Faulted`
|
||
|
||
## 第一阶段推荐 adapter
|
||
|
||
建议先做两类：
|
||
|
||
- `mock`
|
||
- `file_replay` 或一个简单 live adapter
|
||
|
||
如果要尽快验证交付闭环，最现实的顺序是：
|
||
|
||
1. `mock`
|
||
2. `file_replay`
|
||
3. `tcp`
|
||
|
||
不要一开始就冲复杂工业协议。
|
||
|
||
## Dispatcher 职责
|
||
|
||
Dispatcher 负责：
|
||
|
||
- 接收 runtime updates
|
||
- 找到对应 binding
|
||
- 找到目标场景对象
|
||
- 把值应用到目标字段
|
||
- 更新 binding 健康状态
|
||
- 记录 fault 和 stale
|
||
|
||
它不负责：
|
||
|
||
- 协议解析
|
||
- 编辑器 UI
|
||
- 行业业务逻辑
|
||
|
||
## 配置与持久化
|
||
|
||
第一阶段走二进制配置路线。
|
||
|
||
建议产物：
|
||
|
||
- `ProjectRuntime.mcruntimecfg`
|
||
- `DataSources.mcruntime`
|
||
- `Bindings.mcruntime`
|
||
- `Diagnostics.mcruntimestate`
|
||
|
||
这样可以：
|
||
|
||
- 保持运行时配置清晰
|
||
- 便于打包
|
||
- 与现有二进制 package 方向保持一致
|
||
|
||
## 失败模式
|
||
|
||
第一阶段必须显式处理：
|
||
|
||
- source 不存在
|
||
- 连接失败
|
||
- payload 类型不匹配
|
||
- binding 指向不存在对象
|
||
- 长时间无更新导致 stale
|
||
- 配置文件损坏
|
||
|
||
这些都不能静默失败。
|
||
|
||
## 测试要求
|
||
|
||
至少要覆盖：
|
||
|
||
- 配置读写
|
||
- 坏配置拒绝
|
||
- dispatcher 应用更新
|
||
- 缺失目标不崩
|
||
- stale 检测
|
||
- adapter 状态变化
|
||
- 二进制配置可回读
|
||
|
||
## 结论
|
||
|
||
RuntimeData 是 MetaCore 的重要行业子系统，但它应该是：
|
||
|
||
- 明确隔离的
|
||
- 运行时优先的
|
||
- 二进制配置驱动的
|
||
- 小范围起步的
|
||
|
||
第一阶段只要把这条线做成清晰、稳定、可诊断的子系统就够了，不应该过早抽象成一个万能绑定平台。
|