Friflo.Engine.ECS 序列化实战:JSON 场景文件保存与 Prefab 加载机制解析
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 数组里完整表达,根实体在前、子实体自然跟随,编辑器里浏览起来非常直观。
💡
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);
三个值得注意的实现细节:
- 永久 ID 语义:测试代码中用
new EntityStore(PidType.UsePidAsId)创建 Store(Test_EntitySerializer.cs)。这样实体 ID 稳定,场景文件里的id才能作为跨文件、跨版本的稳定引用——这是 Prefab 机制能工作的基础。 - Pretty 输出:写入时自动开启格式化输出(
writer.SetPretty(true)),JSON 对人类可读,方便手动编辑和 diff。 - 流式写入:实体逐个序列化、逐个写入流,不要求整店 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。
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):
- Step 1:用
EntityClient遍历场景所有DataEntity,为每个节点打上PrefabLink/OpModify/OpRemove标志,同时把modify记录汇入mods表; - Step 2:遍历
mods,把被修改 / 删除的 Prefab 节点 ID 登记进prefabs[].nodes映射; - Step 3:遍历
prefabs,加载 Prefab 文件本体,逐节点实例化——不在映射里的节点直接创建新实体并复制全部组件(OpKeep,最常见路径),在映射里的按 Modify / Remove 处理。
4.4 保存与版本控制的"零 diff"目标
保存方向是加载的逆过程:遍历 EntityStore,普通实体写全部组件,Prefab 实例节点只写链接与差异字段。设计目标非常明确:
- 未修改的场景原样保存 → 版本控制里 0 diff;
- 小修改只产生小 diff,且实体顺序不变,合并冲突最少;
- 加载是增量的:实体边读边进
EntityStore,编辑器无需等整个文件加载完即可操作。
5. 上手路线:从仓库哪里开始读代码
- 序列化核心:src/ECS/Serialize/EntitySerializer.cs(写入 L137-L184,读取 L265-L390)
- 数据结构定义:src/ECS/Serialize/DataEntity.cs
- Prefab 设计文档(推荐先读):docs/prefab-lab.md
- 端到端测试(最好的"活文档"):src/Tests/ECS/Serialize/Test_EntitySerializer.cs
- 测试用场景文件:src/Tests/assets/read_scene.json
- 单实体 JSON 往返:DataEntitySerializer.cs
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 工作流,这套设计非常值得直接借鉴。



