格式版本¶
格式版本（Format Version）是Minecraft基岩版附加包系统中标识JSON定义文件所遵循的数据架构版本的字符串。格式版本决定了引擎在解析该文件时应当采用的语法规则和行为语义。
概述¶
基岩版的数据驱动系统在持续发展过程中不断引入新功能和修改既有行为。为了在引入新特性的同时保持对旧内容的兼容性，引擎采用格式版本机制来区分不同时期的文件格式。每个定义文件（实体、方块、物品、配方等）的根对象中通常包含一个format_version字段，指示该文件应以哪个版本的规则被解析。
格式版本的值为语义化版本字符串，如1.20.80或1.21.0，通常与引入相应架构变更的游戏版本对应。
作用机制¶
引擎在加载一个定义文件时，会读取其format_version字段，并据此选择对应版本的解析逻辑。这意味着：
- 使用较旧格式版本的文件仍可被最新版本的游戏正确加载，因为引擎保留了旧版本的解析逻辑。
- 使用较新格式版本的文件可能包含旧版本中不存在的字段或结构，旧版本的游戏在遇到这些文件时通常会忽略无法识别的内容或产生解析错误。
- 在同一文件中，不同的格式版本可能导致同名字段的含义或行为不同。
格式版本与引擎版本¶
格式版本与引擎版本（Engine Version）是两个不同的概念。引擎版本是清单文件中min_engine_version字段所指定的最低游戏版本要求，影响的是整个附加包层面的行为和兼容性。格式版本则是单个定义文件层面的架构选择。
一个附加包中的不同定义文件可以使用不同的格式版本。但通常建议在同一附加包内统一使用最新的格式版本，以避免因混用不同版本的语义而产生混淆。
不要只为“数字更新”而改写文件
格式版本的数字低并不必然表示文件已经失效。旧版常见的1.10.0客户端实体、动画、动画控制器和渲染控制器，以及1.16.100附近的物品和纹理集示例，部分仍可能是当前资料认可或当前游戏兼容的格式。迁移旧包时应先检查当前官方资料和内容日志，再判断是否需要改写。
常见格式版本变化¶
以下列举了一些重要的格式版本变化示例：
- 实体定义：格式版本
1.8.0引入了当前的实体定义架构，取代了此前的旧格式。1.19.40后引入了实体属性系统。 - 方块定义：格式版本
1.19.70后的方块定义采用了新的组件命名规范（从驼峰命名改为蛇形命名），此前的格式仍被接受但不再推荐使用。 - 物品定义：格式版本
1.16.100引入了全新的物品定义架构，与之前的物品格式存在较大差异。1.20.50后进一步更新了组件结构。
某些版本迁移不仅是“字段新增”，还会出现字段重命名、组件重组与数值语义变化。例如：
- 旧方块组件
minecraft:aim_collision在后续版本中迁移为minecraft:selection_box。 - 旧方块组件
minecraft:block_collision在后续版本中迁移为minecraft:collision_box。 - 旧方块组件
minecraft:explosion_resistance在后续版本中迁移为minecraft:destructible_by_explosion，且字段结构发生变化。 - 旧物品
minecraft:food中的字符串型saturation_modifier在后续版本中迁移为浮点数写法。
这些变化说明“同一功能”在不同格式版本下可能需要完全不同的JSON结构。维护历史附加包时，应按目标版本逐项核对字段，而非只替换format_version数字。
格式版本的书写¶
格式版本的值为字符串类型，可以有以下几种写法：
- 三段式：
"1.20.80"，这是标准写法。 - 两段式：
"1.20"，等价于"1.20.0"。
建议始终使用三段式写法以保持明确性。