Friflo.Engine.ECS 序列化实战:JSON 场景文件保存与 Prefab 加载机制解析

原创2026-10-27 15:01:381,679 阅读

Friflo.Engine.ECS 序列化实战:JSON 场景文件保存与 Prefab 加载机制解析

Friflo.Engine.ECS 是一款高性能 C# ECS(Entity Component System)引擎,其内置的 JSON 序列化功能可以把整个 EntityStore 的场景数据一键保存为 JSON 场景文件,再完整加载回内存;更强大的是它实现了类似游戏引擎的 Prefab(预制体) 机制——场景文件只记录"引用 + 差异",让场景文件更小、版本控制 diff 更干净。

本文带你用最短的篇幅搞懂三件事:

  • ECS 场景文件(JSON)长什么样;
  • 如何用 EntitySerializer 保存 / 加载场景;
  • Prefab 的链接格式、加载三步走与最小 diff 设计。

1. 场景文件为什么是"实体 JSON 数组"

Friflo.Engine.ECS 序列化模块的核心类是 EntitySerializer,它把 Entity 转换为一个普通的 POCO 类 —— DataEntity,再写入 JSON 流。

DataEntity 的每个字段都对应场景文件里的一级字段:

JSON 字段 含义
id 实体的永久 ID(pid),用于跨文件稳定引用
children 子实体 ID 列表,用数组而非 parentId 是为了保留子节点顺序
components 组件 / 脚本数据,key 是类型名
tags 实体标签列表
prefab 该实体是某个 Prefab 的实例,指向外部资源文件
modify 对该 Prefab 内某节点做修改或删除
sceneName 标记该实体是场景根

一个真实的测试场景文件(write_scene.json)长这样:

[{
    "id": 10,
    "children": [11],
    "components": {
        "pos": {"x":1,"y":2,"z":3},
        "script1": {"val1":10}
    },
    "tags": ["test-tag", "TestTag3"]
},{
    "id": 11
}]

可以看到:结构(树)、数据(组件)、标记(tags) 都在一个 JSON 数组里完整表达,根实体在前、子实体自然跟随,编辑器里浏览起来非常直观。

Friflo.Engine.ECS 编辑器中的场景序列化界面

💡 children 采用"父节点持有子 ID 数组"的设计,而非每个节点存 parentId。源码注释里说明:前者能稳定保持子节点顺序,对编辑器展示和版本控制合并冲突都更友好(见 DataEntity.cs)。


2. 保存场景:WriteStore 三件套

保存 API 在 EntitySerializer.cs 中,按需求选一个即可:

方法 用途
WriteStore(store, stream) 同步写出整个 Store 为 JSON 数组
WriteStoreAsync(store, stream) 异步版本,适合大场景不阻塞主线程
WriteEntities(entities, stream) 只写出指定实体列表

最简用法(同步保存整店到文件):

var serializer = new EntitySerializer();
using var file = new FileStream("scene.json", FileMode.Create, FileAccess.Write);
serializer.WriteStore(store, file);

三个值得注意的实现细节:

  1. 永久 ID 语义:测试代码中用 new EntityStore(PidType.UsePidAsId) 创建 Store(Test_EntitySerializer.cs)。这样实体 ID 稳定,场景文件里的 id 才能作为跨文件、跨版本的稳定引用——这是 Prefab 机制能工作的基础。
  2. Pretty 输出:写入时自动开启格式化输出(writer.SetPretty(true)),JSON 对人类可读,方便手动编辑和 diff。
  3. 流式写入:实体逐个序列化、逐个写入流,不要求整店 JSON 驻留内存,支持百万级实体场景。

3. 加载场景:ReadIntoStore 与 DataEntity 列表

加载方向提供两组 API(EntitySerializer.cs):

方法 用途
ReadIntoStore(store, stream) / ReadIntoStoreAsync 把 JSON 场景直接重建进 EntityStore(含子树关系)
ReadEntities(List<DataEntity>, stream) 只反序列化成 DataEntity POCO 列表,交给你自己的流程处理

加载回 Store 的用法:

var serializer = new EntitySerializer();
using var file = new FileStream("scene.json", FileMode.Open, FileAccess.Read);
ReadResult result = serializer.ReadIntoStore(store, file);
// result.entityCount = 读入实体数;result.error = null 表示成功

几个实战要点:

  • ReadResult 聚合结果:无论成功还是解析失败,都返回带 error 信息的 ReadResult,错误消息精确到 JSON 位置,便于排查场景文件问题。
  • 容错读取:未知字段(如场景里混入编辑器扩展字段)会被安全跳过,仓库里的 read_unknown_members.json 就专门覆盖了这个场景。
  • 单实体读写:WriteEntity(entity) / ReadIntoEntity(entity, json) 支持对单个实体做 JSON 往返,是编辑器 Inspector 面板保存组件的底层能力。
  • 工具链复用:编辑器的"粘贴实体树"功能就是用 ReadEntities 实现的,入口在 TreeUtils.cs。

Friflo.Engine.ECS 调试器中的查询结果集


4. Prefab 机制:场景文件只存"引用 + 差异"

这是 Friflo.Engine.ECS 序列化最有深度的部分,完整设计文档见 docs/prefab-lab.md。

4.1 Prefab 链接:文件名:uid 双保险

场景文件通过一个字段引用外部 Prefab:

{ "id": 1, "prefab": "player.scn:bb898e" }

链接格式是 "<文件名>:<uid>"。每个资源文件 <name> 都要求配一个 <name>.info 信息文件存 uid:

{ "uid": "bb898e" }

为什么两个都要?因为文件名让系统在 .info 文件丢失时能自动修复引用(误删、忘记提交版本库、移动文件忘了带 .info 等常见事故),而 uid 保证即使文件重命名,引用依然精准。

4.2 三类操作:Keep / Modify / Remove

场景里的 Prefab 实例节点只有三种状态,用位标志(NodeFlags)区分:

操作 含义 场景文件表现
OpKeep 原样保留 Prefab 节点 什么都不写(最常见)
OpModify 修改组件 "modify": "1:11" + components 里只存被改的组件
OpRemove 删除 Prefab 节点 "modify": "1:13" 且 components 为空

于是完整的场景文件小到惊人(示例摘自 prefab-lab.md):

[{
    "id": 1,
    "children": [2, 3, 4],
    "prefab": "player.scn:bb898e"
},{
    "id": 2
},{
    "id": 3,
    "components": { "pos": { "x": 1, "y": 2, "z": 3 } },
    "modify": "1:11"
},{
    "id": 4,
    "modify": "1:13"
}]

player.scn 里 4 个节点,场景里却只写了 4 条轻量记录:一个链接、一个新增节点、一个改组件、一个删除。

4.3 加载三步走

加载时(docs/prefab-lab.md):

  1. Step 1:用 EntityClient 遍历场景所有 DataEntity,为每个节点打上 PrefabLink / OpModify / OpRemove 标志,同时把 modify 记录汇入 mods 表;
  2. Step 2:遍历 mods,把被修改 / 删除的 Prefab 节点 ID 登记进 prefabs[].nodes 映射;
  3. Step 3:遍历 prefabs,加载 Prefab 文件本体,逐节点实例化——不在映射里的节点直接创建新实体并复制全部组件(OpKeep,最常见路径),在映射里的按 Modify / Remove 处理。

4.4 保存与版本控制的"零 diff"目标

保存方向是加载的逆过程:遍历 EntityStore,普通实体写全部组件,Prefab 实例节点只写链接与差异字段。设计目标非常明确:

  • 未修改的场景原样保存 → 版本控制里 0 diff;
  • 小修改只产生小 diff,且实体顺序不变,合并冲突最少;
  • 加载是增量的:实体边读边进 EntityStore,编辑器无需等整个文件加载完即可操作。

Friflo.Engine.ECS 实体调试器视图


5. 上手路线:从仓库哪里开始读代码

Friflo.Engine.ECS 与 Unity、MonoGame 等引擎集成示意


6. 总结

能力 关键 API / 机制
整店保存 WriteStore / WriteStoreAsync(流式、Pretty 输出)
整店加载 ReadIntoStore(直接重建 Store 与树)
POCO 反序列化 ReadEntities → List<DataEntity>,供自定义流程
Prefab 引用 "prefab": "文件:uid" + .info 文件自动修复
Prefab 差异 modify 字段 + OpKeep/Modify/Remove 位标志
版本控制友好 实体顺序稳定、无修改零 diff

Friflo.Engine.ECS 的序列化方案把"场景 = 实体 JSON 数组 + Prefab 差异"做到了工程级闭环:文件小、可读可 diff、加载增量可用。如果你的项目需要给 C# ECS 加上场景持久化和 Prefab 工作流,这套设计非常值得直接借鉴。

登录后查看全文
Friflo.Engine.ECS