5 分钟学会 JSON

几乎所有附加包文件都是用 JSON 写的。它是一种把数据写成文本的简单方式，规则只有寥寥几条。学会一次，你就能读懂任何附加包文件。

初识 JSON

下面是一个描述宠物的小 JSON 文件：

{
  "name": "Biscuit",
  "age": 3,
  "is_friendly": true,
  "favorite_foods": ["bone", "cookie"],
  "owner": {
    "name": "Alex",
    "level": 12
  }
}

把它念出来：“Biscuit 3 岁，很友好，喜欢骨头和饼干，主人是 12 级的 Alex。”JSON 就是这么回事：名字和值。

基本组成

对象

对象用花括号 { } 包起来。它包含键值对：

• 键永远是用双引号括起来的文本，比如 "name"。
• 冒号 : 把键和它的值分开。
• 逗号 , 把一对和下一对分开。

每个附加包文件都以一个对象开头，所以第一个字符永远是 {，最后一个永远是 }。

数组

数组是用方括号 [ ] 包起来的列表。各项之间用逗号分隔。顺序很重要。

{
  "version": [1, 0, 0],
  "tags": ["sword", "weapon"],
  "rows": [
    { "item": "minecraft:stick" },
    { "item": "minecraft:diamond" }
  ]
}

数组里可以放数字、文本、对象，甚至其他数组。

值

值只有少数几种：

注意类型。64 和 "64" 看起来很像，但前者是数字，后者是文本。如果 Minecraft 需要一个数字而你给了它文本，这个设置就会被忽略，或者文件加载失败。

嵌套：附加包文件的结构

对象里面可以再放对象。附加包文件经常用这种方式来组织内容。下面是一个真实的物品文件：

{
  "format_version": "1.26.30",
  "minecraft:item": {
    "description": {
      "identifier": "demo:ruby",
      "menu_category": {
        "category": "items"
      }
    },
    "components": {
      "minecraft:max_stack_size": 16,
      "minecraft:icon": {
        "textures": {
          "default": "ruby"
        }
      }
    }
  }
}

从外往里顺着路径看：文件里有一个 "minecraft:item" 对象，它包含 "description" 和 "components"。在 components 里，"minecraft:max_stack_size" 被设为数字 16。当本 wiki 说“在 components 中设置 minecraft:max_stack_size”时，指的就是这个位置。

提示：每一层缩进两个空格。游戏并不需要缩进，但这样结构一目了然。

标识符和命名空间

你添加的每样东西都需要一个标识符：一个由冒号分隔的两部分组成的唯一名字。

demo:ruby

• 冒号前面的部分是命名空间，就像你的签名。
• 冒号后面的部分是这个东西的名字。

Minecraft 自己的内容使用 minecraft 命名空间，比如 minecraft:diamond。千万不要把 minecraft 用在你自己的内容上。 选一个简短又独特的名字，比如你的姓名缩写或项目名：sam:ruby、dragons:fire_egg。

让你远离麻烦的规则：

1. 只使用小写字母、数字和下划线。
2. 不要有空格。用 ruby_sword，不要用 ruby sword。
3. 整个附加包使用同一个命名空间。
4. 一旦玩家的世界里已经有了你的物品，就不要再改名，否则那些物品会消失。

像 minecraft:icon 这样的组件名也使用 minecraft 命名空间，因为它们是游戏内置的。你可以在物品组件参考中查到每一个。

format_version

大多数文件都以 "format_version" 开头。它告诉 Minecraft 你写的是哪个版本的文件格式，好让游戏知道该怎么读。注意，在物品、方块和实体文件中它是加了引号的文本，比如 "1.26.30"；但在 manifest.json 中它是普通数字 2。

拿不准的时候，就从本 wiki 中能正常运行的示例里复制 format_version，并让同类文件保持一致。

常见错误

大多数出错的包都是由这五种错误造成的。

1. 末尾多余的逗号

最后一项后面不允许有逗号。

{
  "nutrition": 4,
  "saturation_modifier": 0.6,
}

删掉 0.6 后面的逗号就好了。

2. 缺少逗号

正好相反的问题：两对之间忘了加逗号。

{
  "nutrition": 4
  "saturation_modifier": 0.6
}

在 4 后面加一个逗号。

3. 缺少引号或引号不对

键和文本需要双引号，开头和结尾都要有。

{
  name: 'Ruby'
}

改正后是 { "name": "Ruby" }。

4. 括号不配对

每个 { 都需要一个 }，每个 [ 都需要一个 ]，而且顺序要对。在 VS Code 中点击某个括号旁边时，它会高亮与之配对的括号，检查起来很方便。

5. 注释

标准 JSON 没有注释。你可能会在 Mojang 的一些示例文件中看到 // 注释行，游戏在很多地方也确实会跳过它们，但其他工具和校验器会拒绝它们。最稳妥的习惯是不要在 JSON 里写注释。

其他文件类型

并不是所有文件都是 JSON。你还会遇到：

• .lang 文件：用于名称的普通 key=value 行，比如 item.demo:ruby.name=Ruby。
• .mcfunction 文件：每行一条命令。参见函数。
• .js 文件：用于脚本的 JavaScript。
• .png 文件：纹理。

跳过 JSON

如果觉得这么多括号太繁琐，你不是一个人。在 GodCraft 中你完全不用手写 JSON：只需用滑块、开关和选择器填写表单，应用每次都会写出有效的文件。这是做出能用的东西的快捷方式，而且你随时可以回到这里，了解应用替你写了些什么。

既然你已经能读懂 JSON 了，试试你的第一个自定义物品，或者在导出与游玩中学习如何把你的包放进游戏。