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

5.9 KiB
Raw Permalink Blame History

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

高层架构

外部数据源
    |
    v
数据源 Adapter
    |
    v
归一化 Runtime Update
    |
    v
Binding Dispatcher
    |
    +--> 场景对象 Binding Applier
    |
    +--> Runtime Diagnostics / Fault State

核心概念

1. Data Source Definition

这部分由项目级配置定义。

它描述：

  • source id
  • adapter 类型
  • 连接参数
  • 启动模式
  • 重连策略

建议结构：

MetaCoreDataSourceDefinition
  Id
  AdapterType
  DisplayName
  ConnectionSettings
  AutoConnect
  ReconnectPolicy

2. Data Point Definition

这是项目面对的数据契约。

它定义：

  • source id
  • 外部地址或键
  • 逻辑 point id
  • 期望值类型
  • 更新语义

建议结构：

MetaCoreDataPointDefinition
  Id
  SourceId
  ExternalAddress
  ValueType
  UpdateMode
  FallbackBehavior

3. Scene Binding Definition

它把逻辑数据点绑定到场景目标。

它定义：

  • 目标对象 id
  • 目标组件路径
  • 转换规则
  • 可选转换器
  • 缺失数据行为

建议结构：

MetaCoreSceneBindingDefinition
  BindingId
  DataPointId
  TargetObjectId
  TargetPath
  BindingMode
  ConverterId
  MissingDataPolicy

4. Runtime Update

这是 adapter 输出的归一化 payload。

它不应该暴露协议专属表示。

建议结构：

MetaCoreRuntimeDataValue
  Type
  BoolValue
  IntValue
  FloatValue
  Vec3Value
  StringValue
  Timestamp
  Quality

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 接口

建议运行时接口：

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

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

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