蓝图格式版本 (Format Versioning)

随着 Maingraph for MC 的不断进化，蓝图的存储格式也在进行迭代。为了确保旧版本的蓝图能够继续运行，同时引入更强大的新特性，我们采用了格式版本化机制。

版本概览

目前蓝图支持以下两种格式：

版本号	引入版本	存储特点	性能
Format 1	v0.1.0	全字符串化。所有数据（数字、布尔等）均以字符串形式存储在 JSON 中。	较低（转换开销大）
Format 2	v0.1.2	原生类型存储。数字存储为 JSON Number，布尔存储为 JSON Boolean，列表存储为 JSON Array。	极高（零转换开销）
Format 3	v0.1.4	注册系统重构。标准化了内部节点注册与端口标识符，支持更精确的 i18n 映射与元数据管理。	极高

为什么要版本化？

在早期的 v0.1.0 版本中，为了快速实现原型，引擎将所有数据都序列化为字符串。这虽然简单，但在处理复杂的数学运算或大型列表时，频繁的字符串转换会导致不必要的 CPU 消耗。

Format 2 的引入标志着引擎进入了“去字符串化 (De-stringification)”时代。通过在 JSON 中直接存储原生类型，引擎可以直接将数据注入 Java 逻辑，无需任何中间转换。

工作原理

蓝图引擎在加载每一个 .json 文件时，会首先检查根节点的 format_version 字段：

1. 自动识别:

   • 如果 format_version 缺失，引擎将其视为 Format 1 (Legacy)。
   • 如果 format_version 为 2，则启用 Format 2 逻辑。

2. 向下兼容:

   • 引擎内置了完善的兼容逻辑。当你打开一个旧版（Format 1）蓝图并点击保存时，编辑器会自动将其升级为 Format 2。
   • 你无需手动修改任何旧蓝图文件。

3. 原生类型提取:

   • 在 Format 2 下，引擎会根据 JSON 值的原始类型（如 123.45 而非 "123.45"）直接读取数据，确保了数据精度并提升了运行速度。

如何检查我的蓝图版本？

通常情况下，你不需要关心这个。如果你需要手动查看，可以使用文本编辑器打开 world/mgmc_blueprints/ 下的 .json 文件：

{
  "format_version": 2,
  "execution": [
    ...
  ]
}

未来规划

未来的版本可能会引入更高级的节点树预编译信息，届时 format_version 将继续作为平滑迁移的保障。