# 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 的重要行业子系统，但它应该是：

- 明确隔离的
- 运行时优先的
- 二进制配置驱动的
- 小范围起步的

第一阶段只要把这条线做成清晰、稳定、可诊断的子系统就够了，不应该过早抽象成一个万能绑定平台。