附加包小册 §06：第一个物品

附加包允许我们通过数据驱动的方式创建自定义物品，在本文章中，我们将创建一个最简单的物品。

一般地，一个自定义物品应当由两部分组成：

行为文件；
资源文件。

命名空间

我们首先要了解一下命名空间（Namespace） 的概念：

命名空间是一个字符串，用于标识资源的唯一性，命名空间和ID之间使用:进行连接，其可以防止内容冲突[^1]。

不同的附加包应该有不同的命名空间，当需要覆盖原版或其他附加包的内容时，我们才可以使用相同的命名空间。

在为我们的项目取命名空间时，应该注意：

避免使用过于模糊的词语；
避免使用custom、addon、content、mob、car等命名空间，这可能与其他附加包重复；
除非覆盖原版内容，否则避免使用minecraft或minecoin作为命名空间。

格式版本间的差异

自定义物品（以及方块）有以下可用的格式版本：

1.10：最初的格式版本，只含有最基础的组件，但无需开启实验性玩法；
1.16.100：内容大为丰富，在很长一段时间内是自定义物品的最佳选择，但需要开启假日创作者实验性玩法，在较新版本无法使用；
1.20.0+：趋于稳定的格式版本，兼有1.16.100格式版本的功能与1.10格式版本的稳定性。

因此，我们建议使用1.20.0+格式版本，这里我们选用1.20.30。

行为文件

在我们的行为包下新建items文件夹，然后创建一个<物品ID>.json文件。

文件不一定必须按照<物品ID>.json的格式进行命名，这里这么做是为了方便后续查找；

我们也可以把这个文件创建在items的子文件夹下。

在这个文件中写入以下内容：

{
  "format_version": "1.20.30",
  "minecraft:item": {
    "description": {
      "identifier": "example:first_item",
      "menu_category": {
        "category": "items"
      }
    },
    "components": {
      "minecraft:icon": {
        "texture": "example.first_item"
      }
    }
  }
}

format_version是文件使用的格式版本，这里是1.20.30；

在description中：

identifier设置了物品的命名空间ID，注意这里的命名空间是example，在实际的项目中不建议使用；
menu_category设置了物品在创造模式物品栏的位置，category会设置物品的分类，group会设置物品的分组；
- 一般地，category可以填nature、equipment、construction或items；
- 一般地，group可以填任意原版分组的本地化字符串，注意设置的分组要与分类相对应；
- 我们也可以通过item_catalog添加自定义分组。

[!IMPORTANT]
如果选用 1.21.60+ 格式版本，请务必为分组添加命名空间！

在components中，我们可以为物品添加组件，每一个组件都可以为物品添加相应的功能：

minecraft:icon组件设置了物品的图标，应该填写物品的纹理名，这里的纹理名是example.first_item；
- 虽然物品组件不是必须声明的，但我们通常会声明minecraft:icon组件来设置物品的图标。

资源文件

进行到这一步进入游戏，我们就可以在创造模式物品栏的「物品」分类看到我们的自定义物品了，然而这时它还没有纹理，并且名称为一大串英文字符。

接下来，我们将会学习如何为自定义物品的添加客户端资源。

物品纹理

在上文中，我们将物品的纹理名设置为了example.first_item，为了使游戏正常读取纹理，我们需要在资源包的textures文件夹创建一个item_texture.json，映射纹理名和纹理路径。

假定我们的纹理为textures/items/first_item.png，则应该在其中写入：

{
    "resource_pack_name": "第一个附加包",
    "texture_name": "atlas.items",
    "texture_data": {
        "example.first_item": {
            "textures": "textures/items/first_item"
        }
    }
}

在其中：

resource_pack_name设置了资源包的名称；
texture_name设置纹理类型，因为要定义物品纹理名，因此只能填写atlas.items；
texture_data对象中定义了所有物品纹理名，其按照如下格式：

"texture_data": {
  "<纹理名1>": {
    "textures": "<纹理路径1>"
  },
  "<纹理名2>": {
    "textures": "<纹理路径2>"
  },
  "<纹理名3>": {
    "textures": "<纹理路径3>"
  }
}

纹理路径中不要出现后缀名

物品名称

在语言文件中添加如下内容：

1	item.example:first_item.name=第一个物品

这时，将附加包导入进游戏，我们就可以看到新添加的自定义物品已经拥有了完整的行为以及资源了。

小结

在本节中，我们了解了：

如何加入自定义物品；
如何为自定义物品添加资源。

接下来，我们将会趁热打铁，了解如何添加一个最简单的自定义方块。

[^1]: 命名空间 - 中文 Minecraft Wiki