JSON¶

JSON（JavaScript Object Notation）是一种使用纯文本表示结构化数据的数据交换格式。Minecraft基岩版的附加包、世界模板、资源定义、行为定义、脚本配置和许多工具配置均大量使用JSON文件。

概述¶

JSON以较少的语法表达对象、数组、字符串、数字、布尔值和空值。它最初源自JavaScript对象字面量的表示方式，但已经独立成为通用数据格式。JSON文件通常使用.json扩展名，标准MIME类型为application/json。

在基岩版开发中，JSON不是一种脚本语言，而是数据定义格式。游戏引擎读取这些文件后，根据文件所在目录、根字段、format_version和各字段值来构造对应的游戏内容。

基本结构¶

一个JSON文档由一个根值组成。根值通常是对象（Object），也可以是数组（Array）。基岩版附加包的大多数JSON文件以对象作为根值。

清单文件片段

{
  "format_version": 2,
  "header": {
    "name": "pack.name",
    "description": "pack.description",
    "uuid": "2f4a2bda-9866-4b39-8e8b-51d516e7e0c6",
    "version": [1, 0, 0],
    "min_engine_version": [1, 20, 0]
  },
  "modules": [
    {
      "type": "data",
      "uuid": "6b1e7f21-3e62-44b0-bcc5-2fd6ab3f8a99",
      "version": [1, 0, 0]
    }
  ]
}

对象与字段¶

对象（Object）使用一对花括号{}表示。对象内部由零个或多个字段（Field）组成，每个字段由键（Key）和值组成。键必须写成字符串，键和值之间使用冒号分隔，多个字段之间使用逗号分隔。

{
  "name": "示例",
  "enabled": true
}

对象常用于表达具名属性。附加包中的组件、描述、条件、事件响应和清单信息通常都以对象形式出现。

数组¶

数组（Array）使用一对方括号[]表示。数组内部由零个或多个元素（Element）组成，元素之间使用逗号分隔。数组元素没有字段名，只通过顺序区分；每个元素的位置称为索引（Index），索引从0开始。

{
  "version": [1, 0, 0],
  "tags": ["stone", "ore"]
}

数组常用于表达版本号、坐标、列表和候选项。是否允许任意长度、是否要求固定长度、每个元素允许什么类型，取决于具体文件的架构。

值类型¶

JSON包含以下基本值类型：

类型	示例	说明
对象	`{ "x": 0 }`	由字段组成的结构。
数组	`[1, 2, 3]`	由元素组成的有序列表。
字符串	`"minecraft:stone"`	使用英文直引号包裹的文本。
数字	`16`、`0.5`	整数或浮点数。
布尔值	`true`、`false`	真值或假值。
空值	`null`	表示空或未给定的值。

空白与缩进¶

JSON允许在字段、值、逗号、冒号和括号之间加入空格、制表符和换行符。空白不改变数据含义，但合理缩进可以显著提高可读性。本站示例通常使用2个空格缩进。

注释¶

标准JSON规范不包含注释语法。Minecraft基岩版的许多JSON解析位置接受//单行注释和/* ... */多行注释，但这属于游戏解析器的扩展能力，不应视为所有JSON工具都能识别的通用规则。

因此，面向游戏加载的文件可以在确认当前解析位置支持的前提下使用注释；面向通用工具、网页接口或严格JSON校验器的文件不应依赖注释。

与架构的关系¶

JSON只规定数据如何书写，不规定某个字段是否存在、字段值是否有效或游戏会如何解释字段。基岩版开发中的有效性主要由具体文件类型的架构（Schema）决定。例如：

清单文件要求存在header和modules等字段。
方块定义要求在minecraft:block根对象下书写描述和组件。
物品定义、配方、战利品表、实体定义和客户端资源文件各自拥有不同的字段集合。

因此，一个文件可以是语法正确的JSON，但仍然不是有效的基岩版内容文件。开发时应同时检查JSON语法、文件路径、format_version、架构要求和内容日志。