同步官网文档8m_25d

mconline/15-玩法组件教程/8-自定义物品/0-摘要.md

@@ -0,0 +1,17 @@
+---
+front: https://nie.res.netease.com/r/pic/20211104/69055361-2e7a-452f-8b1a-f23e1262a03a.jpg
+hard: 入门
+time: 5分钟
+---
+
+# 摘要
+
+在本章中，我们将一起深入学习自定义物品。
+
+- 在第一节（*认识自定义物品*）中，我们将认识自定义物品的基本结构和形式，以及我们可继承的原版物品功能。
+- 在第二节（*制作一个新药水*）中，我们将一起学习自定义**药水**（**Potion**）。
+- 在第三节（*制作一个新武器*）中，我们将制作一个自定义的**武器**（**Weapon**）。
+- 在第四节（*制作一个新盔甲*）中，我们将一起来做一个自定义**盔甲**（**Armor**）。
+- 在最后一节（*挑战：制作一个3D盔甲*）的挑战中，我们将一起只做一个3D的盔甲，我们将使用**附着物**（**Attachable**，***挂件***）来实现这一功能。
+
+本章关键词：物品 附着物 格式版本 描述 组件 事件 图集 药水 武器 盔甲

mconline/15-玩法组件教程/8-自定义物品/1-认识自定义物品.md

@@ -0,0 +1,140 @@
+---
+front: https://nie.res.netease.com/r/pic/20211104/69055361-2e7a-452f-8b1a-f23e1262a03a.jpg
+hard: 高级
+time: 20分钟
+---
+
+# 认识自定义物品
+
+在本节中，我们一起来接触自定义物品。
+
+物品和实体一样，也是可以通过JSON文件数据驱动来定义的。为了演示，我们使用在第七章中我们一起创建的拥有完整文件夹的附加包。我们记得，我们已经将这个附加包导入游戏。我们在我的世界开发工作台中将其打开。
+
+![](./images/9.1_item_config.png)
+
+我们希望使用配置功能新建一个物品，然后在“**资源管理**”窗格中找到物品的定义文件并研究这些文件。
+
+我们可以看到，向导将提示我们建立如下配套文件：
+
+```shell
+./behavior_pack/netease_items_beh/tutorial_demo_item_demo.json
+./resource_pack/netease_items_res/tutorial_demo_item_demo.json
+./resource_pack/attachables/tutorial_demo_item_demo.json
+```
+
+这分别是物品的行为包定义文件、资源包定义文件和附作物文件。**附着物**（**Attachable**，***挂件***）作为一种可选的类实体物体，在物品定义中往往起到配合盔甲作为盔甲的模型或配合一般物品作为其自定义模型的作用。一般的物品是不需要这个文件的，所以我们如果选取了普通的物品或者“空”物品，那么这个文件是不会建立的。
+
+## 行为包定义
+
+我们先来看物品的行为包定义文件，这里以我们新创建的`./behavior_pack/netease_items_beh/tutorial_demo_item_demo.json`为例。
+
+```json
+{
+  "format_version": "1.10",
+  "minecraft:item": {
+    "description": {
+      "identifier": "tutorial_demo:item_demo",
+      "category": "construction",
+      "custom_item_type": "none"
+    },
+    "components": {
+
+    }/*,
+    "events": {
+      // no use at 1.10 format
+    }*/
+  }
+}
+```
+
+- `format_version`：这是该物体文件的**格式版本**（**Format Version**）。物品稳定的格式版本有`1.10`、`1.14`和`1.16`，这三种格式版本均为不需要开启实验性玩法的稳定格式版本，也是我们这里推荐的格式版本，我们尤为推荐格式版本`1.10`。`1.16.100`及以上的格式版本意味着新版物品，这需要开启实验性玩法，我们不推荐使用。不过需要注意的是，如果使用`1.16.100`及以上的新版物品，则只需创建行为包定义文件，客户端需要的数据将从服务端通过来自数据包的形式接收。
+- `minecraft:item`：物品的模式标识符，从标识符上来看并不区分客户端和服务端，引擎会根据其文件放置在行为包还是资源包来判断其为服务端还是客户端。其下有`description`、`components`和`events`对象。
+
+`description`代表该物品的**描述**（**Description**）。
+
+- `identifier`：字符串，该物品的赋命名空间标识符，格式为`<namespace>:<identifier>`，客户端和服务端的标识符要保持一致。
+- `category`：字符串，该物品的物品栏分类，`construction`为第一个分类。可以使用自定义的分类，自定义分类可以详见<a href="../../../mcguide/20-玩法开发/15-自定义游戏内容/13-自定义物品分页.html" rel="noopenner">自定义物品分页</a>。
+- `custom_item_type`：可选，字符串，中国版特有的描述属性，可以继承原版的一些种类的物品，从而定义具有原版硬编码特性的物品。目前可以填写`weapon`、`armor`、`egg`、`ranged_weapon`、`bucket`、`projectile_item`、`shield`等。
+
+`components`代表该物品的服务端**组件**（**Component**）。物品的大部分组件都是服务端的。但是，在资源包中（即客户端中），也存在部分可用的物品组件。并且其中一些组件有着重要的作用，例如添加物品的图标。
+
+`events`代表该物品的服务端**事件**（**Event**），**并且只有在格式版本为`1.16.100`及以上时才有效**。与实体类似，物品服务端定义文件也允许定义一些事件，不过，目前可定义的事件只能由少数组件触发。也就是说目前定义事件的功能是比较有限的。我们可以看一个原版物品附魔金苹果的事件段落的节选。
+
+```json
+"events" : {
+  "consumed" : {
+    "sequence" : [
+      {
+        "add_mob_effect" : {
+          "effect" : "regeneration",
+          "duration" : 5,
+          "amplifier" : 1,
+          "target" : "holder"
+        }
+      },
+      {
+        "add_mob_effect" : {
+          "effect" : "absorption",
+          "duration" : 120,
+          "amplifier" : 0,
+          "target" : "holder"
+        }
+      }
+    ]
+  }
+}
+```
+
+这个`consumed`事件由`minecraft:food`组件触发，可以给予食用者生命恢复和生命吸收状态效果。
+
+## 资源包定义
+
+我们再来看物品的资源包定义文件，我们依旧以通过配置新创建的`./resource_pack/netease_items_res/tutorial_demo_item_demo.json`为例。
+
+```json
+{
+  "format_version": "1.10",
+  "minecraft:item": {
+    "description": {
+      "identifier": "tutorial_demo:item_demo"
+    },
+    "components": {
+      "minecraft:icon": "tutorial_demo:item_demo"
+    }
+  }
+}
+```
+
+因为和行为包定义文件具有相同的模式标识符`minecraft:item`，所以理应具有相同的文件模式。但是，资源包定义中各个段落的支持情况却和行为包中的有所不同。资源包定义中只支持`description`和`components`，而且`description`只用来定义标识符，且`components`中支持的组件数目也没有行为包中的多。
+
+但是，我们看到了一个极为重要的组件：`minecraft:icon`。该组件可以用于定义我们的物品图标。我们可以看到该组件的值已经自动为我们填写了`"tutorial_demo:item_demo"`。事实上，这里的值无需带有命名空间，但是为了不和其他模组冲突，我们还是可以为其加上命名空间的。
+
+`minecraft:icon`的值是一个纹理的**短名称**。该短名称的定义并不像实体那样，它不是被定义在客户端定义文件中的。该短名称定义在一种被称为**图集定义文件**（**Atlas Definition File**）的文件中。
+
+### 图集
+
+**图集**（**Atlas**）是我的世界中一种只存在于内存中的纹理文件的称呼。我的世界每次启动游戏时，都会在游戏内依据资源包中的纹理创建图集。比如，物品会根据资源包中的各个小的物品贴图，以图集定义文件为索引创建物品图集。下面展示了一个原版的我的世界创建的**物品图集**。
+
+![](./images/9.1_item_atlas.png)
+
+我们的模组中的物品想要拥有图标，就必须引用一个物品图集中的图标。但是，如果我们不像物品图集中定义新的纹理，那么我们就无法引用自定义的图标，只能引用原版图标。不过，好在我们拥有自定义图集的能力，那便是修改图集定义文件。
+
+我们可以以我们编辑器自动为我们生成的图集文件为例。为了讲解方便，我已经在其中手动添加了我们新物品的图标纹理。物品图集定义文件位于资源包`textures`文件夹根目录下，名称为`item_texture.json`。
+
+```json
+{
+  "resource_pack_name": "tutorial_demo",
+  "texture_name": "atlas.items",
+  "texture_data": {
+    "tutorial_demo:item_demo": {
+      "textures": "textures/items/tutorial_demo/item_demo"
+    }
+  }
+}
+```
+
+- `resource_pack_name`：字符串，我们资源包的名称，这可能影响到图集中精灵图的排序情况。不过普通开发者并不用担心这一点，只有某些特殊的着色器开发者需要注意图集的UV情况。
+- `texture_name`：字符串，在物品图集中必须为`atlas.items`，它是代表物品图集的标识符。
+- `texture_data`：对象，这里定义了所有的短名称。所有的字段都是`"<short_name>": { /* texture definition */ }`的形式。一般来说，纹理定义对象中只会有一个`textures`字段，代表该纹理的相对根目录的路径，不带有扩展名。扩展名将按照`tga`、`png`、`jpg`的格式顺序依次检查是否存在，并且读取第一个检查到的纹理。皆不存在时将会报出错误。
+
+这样，我们就定义好了该物品的图标，从而完成了一个基础的空白物品的定义。

mconline/15-玩法组件教程/8-自定义物品/2-制作一个新药水.md

@@ -0,0 +1,97 @@
+---
+front: https://nie.res.netease.com/r/pic/20211104/69055361-2e7a-452f-8b1a-f23e1262a03a.jpg
+hard: 高级
+time: 15分钟
+---
+
+# 制作一个新药水
+
+在本节中，我们一起来制作一个新的药水物品。
+
+## 创建配置
+
+我们打开我的世界开发工作台的编辑器，通过创建**配置**的方式快速创建一个新物品。
+
+![](./images/9.1_item_config.png)
+
+![](./images/9.2_potion_create.png)
+
+我们希望创建的物品可以像食品那样被吃掉或喝掉，所以这里我们选择“**可食用物品**”作为数据模板。
+
+![](./images/9.2_potion_created.png)
+
+创建完成后，我们便可以在“属性”窗格中看到我们新物品的属性了。
+
+## 更改属性
+
+和普通的空物品相比，可食用物品多了一些组件。其中尤为重要的便是“**食物属性**”组件。
+
+这个组件其实就是JSON文件中的`minecraft:food`组件。`minecraft:food`主要用于定义一个物品食用后恢复的**饥饿值**（**Hunger Value**）和**饱和度**（**Saturation**），同时可以定义食用时触发的事件、产生的状态效果等。我们就需要用到产生状态效果这一功能。
+
+我们保持“**饥饿值满后是否可以**”食用这一栏为选中状态，把“**补充饥饿值**”改为0。由于下面已经自动生成了一个“**附加效果**”，所以我们只需要更改“**效果类型**”等属性为我们需要的值即可。
+
+这样，我们就制作了一个和药水功能基本一致的物品了。不过还有一点我们需要注意。普通食品和液体食品的食用动画和播放的音效是不同的。不过，这一点我们也可以进行更改。
+
+![](./images/9.2_potion_modded.png)
+
+我们在“**资源包组件**”中加入“**使用动画**”组件。将使用动画的`eat`更改为`drink`即可。只不过，由于编辑器的限制，我们需要在资源包中手动更改该组件的值。我们在资源包中更改如下：
+
+```json
+{
+  "format_version": "1.10",
+  "minecraft:item": {
+    "description": {
+      "identifier": "tutorial_demo:potion"
+    },
+    "components": {
+      "minecraft:icon": "tutorial_demo:potion",
+      "minecraft:use_animation": "drink" // 更改此处
+    }
+  }
+}
+```
+
+同时，我们也可以打开行为包来查看我们的行为包定义文件。通过编辑器修改，然后再打开文件亲自学习JSON的写法是一种非常好的附加包学习方式。行为包中的文件如下：
+
+```json
+{
+  "format_version": "1.10",
+  "minecraft:item": {
+    "description": {
+      "identifier": "tutorial_demo:potion",
+      "category": "Nature"
+    },
+    "components": {
+      "minecraft:foil": true,
+      "minecraft:food": {
+        "can_always_eat": true,
+        "effects": [
+          {
+            "amplifier": 3,
+            "chance": 1.0,
+            "duration": 20,
+            "name": "health_boost"
+          }
+        ],
+        "nutrition": 0
+      },
+      "minecraft:max_stack_size": 64,
+      "minecraft:use_duration": 20.0
+    }
+  }
+}
+```
+
+这样，我们的药水就创建完成了！我们打开游戏来验证效果。
+
+![](./images/9.2_potion_in-game.png)
+
+可以看到药水正确添加到了“自然”（Nature）分类中。
+
+![](./images/9.2_potion_drunk.png)
+
+喝药水的声音也是液体食用声音。
+
+![](./images/9.2_potion_effect.png)
+
+并且在食用后正确给予了我们效果。这代表我们成功添加了一个新的药水物品！

mconline/15-玩法组件教程/8-自定义物品/3-制作一个新武器.md

@@ -0,0 +1,76 @@
+---
+front: https://nie.res.netease.com/r/pic/20211104/69055361-2e7a-452f-8b1a-f23e1262a03a.jpg
+hard: 高级
+time: 10分钟
+---
+
+# 制作一个新武器
+
+在本节中，我们将一起新建一个武器，使其具备攻击特性。
+
+## 创建配置
+
+我们打开我的世界开发工作台的编辑器，通过创建**配置**的方式快速创建一个新物品。
+
+![](./images/9.3_weapon_create.png)
+
+我们以“**自定义武器**”为基础，这样便可以创建一个武器。
+
+![](./images/9.3_weapon_created.png)
+
+## 更改属性
+
+我们一起来考察这个物品的组件。我们可以看到，决定了这个物品为武器的组件为“**武器属性**”组件。该组件为中国版自制的组件`minecraft:weapon`。这个组件决定了一个武器的伤害、附魔能力、挖掘等级、基础挖掘速度等属性。我们可以根绝自己的意愿对该组件进行自定义。比如，我们把武器的伤害改为20。
+
+![](./images/9.3_weapon_modded.png)
+
+我们这里提供一对稍加修改之后的武器物品对应的定义文件。行为包定义文件如下：
+
+```json
+{
+  "format_version": "1.10",
+  "minecraft:item": {
+    "description": {
+      "identifier": "tutorial_demo:weapon",
+      "category": "Equipment",
+      "custom_item_type": "weapon"
+    },
+    "components": {
+      "minecraft:max_damage": 10,
+      "netease:weapon": {
+        "attack_damage": 20,
+        "enchantment": 10,
+        "level": 3,
+        "speed": 5,
+        "type": "sword"
+      }
+    }
+  }
+}
+```
+
+资源包定义文件如下：
+
+```json
+{
+  "format_version": "1.10",
+  "minecraft:item": {
+    "description": {
+      "identifier": "tutorial_demo:weapon"
+    },
+    "components": {
+      "minecraft:icon": "tutorial_demo:weapon"
+    }
+  }
+}
+```
+
+值得注意的是，这里的“**耐久**”组件对应的是`minecraft:max_damage`，即最大的**损坏值**（**Damage Value**，简称**DV**），而非攻击能够产生的**伤害**（**Damage**）。该武器能够造成的攻击伤害由`netease:weapon/attack_damage`定义。这里的损坏值即我们在其他语境下经常提到的特殊值、数据值或附加值。之所以称为损坏值，是因为该物品每用一次便会一定程度上地损坏一次，损坏值也会逐渐增大。当损坏值达到最大损坏值时，物品便会因为损坏殆尽而破碎。所以最大损坏值也就是物品的**耐久**（**Durability**）。
+
+我们进入游戏测试我们的武器。
+
+![](./images/9.3_weapon_in-game.png)
+
+![image-20211217180955089](./images/9.3_weapon_kill.png)
+
+可以看到，我们的武器确实如我们修改的那样，多出了一个+20的攻击伤害。这代表我们的武器自定义成功了！

mconline/15-玩法组件教程/8-自定义物品/4-制作一个新盔甲.md

@@ -0,0 +1,98 @@
+---
+front: https://nie.res.netease.com/r/pic/20211104/69055361-2e7a-452f-8b1a-f23e1262a03a.jpg
+hard: 高级
+time: 15分钟
+---
+
+# 制作一个新盔甲
+
+在本节中，我们将一起新建一个盔甲，使其具备一定的防御能力。
+
+## 创建配置
+
+我们打开我的世界开发工作台的编辑器，通过创建**配置**的方式快速创建一个新物品。
+
+![](./images/9.4_armor_create.png)
+
+我们以“**自定义盔甲**”为基础，这样便可以创建一个盔甲。
+
+![](./images/9.4_armor_created.png)
+
+我们可以看到，盔甲相比于其他物品，多出了一个盔甲穿戴属性栏。这里便是盔甲的**附着物**（**Attachable**，***挂件***）定义的位置。
+
+## 更改属性
+
+我们先着眼于行为包组件。我们可以看到，盔甲具有一个“**盔甲属性**”组件，其本质是JSON中的`netease:armor`组件。该组件可以做到修改盔甲的**护甲值**（**Armor Value**）和附魔能力等。
+
+对于盔甲的附着物，其JSON文件存放在资源包的`attachables`文件夹中。它的定义文件与实体的资源包定义文件几乎一致，只不过它只有那么一个资源包定义。附着物的作用是单纯显示一个没有行为逻辑的模型，比如玩家身上穿着的盔甲模型。因此它只需要一个资源包定义文件。
+
+我们将该物品对应的JSON文件的示例放出供大家参考。首先是行为包定义文件。
+
+```json
+{
+  "format_version": "1.10",
+  "minecraft:item": {
+    "description": {
+      "category": "Equipment",
+      "identifier": "tutorial_demo:armor",
+      "custom_item_type": "armor"
+    },
+    "components": {
+      "minecraft:max_damage": 10,
+      "netease:armor": {
+        "armor_slot": 1,
+        "defense": 20,
+        "enchantment": 10
+      }
+    }
+  }
+}
+```
+
+然后是资源包。
+
+```json
+{
+  "format_version": "1.10",
+  "minecraft:item": {
+    "description": {
+      "identifier": "tutorial_demo:armor"
+    },
+    "components": {
+      "minecraft:icon": "tutorial_demo:armor"
+    }
+  }
+}
+```
+
+附着物的定义文件也非常简单，因为这种格式我们之前在第八章中就已经充分学习过了。
+
+```json
+{
+  "format_version": "1.8.0",
+  "minecraft:attachable": {
+    "description": {
+      "identifier": "tutorial_demo:armor",
+      "geometry": {
+        "default": "geometry.humanoid.armor.chestplate"
+      },
+      "materials": {
+        "default": "armor",
+        "enchanted": "armor_enchanted"
+      },
+      "textures": {
+        "default": "textures/models/armor/diamond_1",
+        "enchanted": "textures/misc/enchanted_item_glint"
+      },
+      "render_controllers": [
+        "controller.render.armor"
+      ],
+      "scripts": {
+        "parent_setup": "variable.chest_layer_visible = 0.0;"
+      }
+    }
+  }
+}
+```
+
+在下一节的挑战中，我们将为这个物品添加一个3D模型，这将用到我们的附着物功能。

mconline/15-玩法组件教程/8-自定义物品/5-挑战：制作一个3D盔甲.md

@@ -0,0 +1,65 @@
+---
+front: https://nie.res.netease.com/r/pic/20211104/69055361-2e7a-452f-8b1a-f23e1262a03a.jpg
+hard: 高级
+time: 20分钟
+---
+
+# 挑战：制作一个3D盔甲
+
+接下来，我们为我们上一节中添加的盔甲挂接一个模型。所使用的模型可在[3D盔甲资源包](https://g79.gdl.netease.com/addonguide-9.zip)下载。
+
+## 准备3D盔甲模型
+
+3D盔甲模型本质上就是一个实体模型，所以我们可以用Blockbench来制作这样的模型。在玩法地图教程中，我们一起制作了很多模型，这些模型都可以在玩法地图教程的示例包中下载找到。我们拿出一个T恤衫模型，将`.bbmodel`文件在Blockbench中打开。
+
+![](./images/9.5_export.png)
+
+我们通过Blockbench的导出功能将模型的**几何**（**Geometry**）导出为JSON文件。然后将这个文件和纹理文件一起准备好，将其导入到编辑器中。
+
+![](./images/9.5_import_geo.png)
+
+将几何文件放置在资源包的`models/entity`下。
+
+![](./images/9.5_import_texture.png)
+
+将纹理文件放在`textures/models/armor`下。事实上，纹理文件不像几何文件那么严格，因此放在其他文件夹中也是可以的。但是，为了和原包保持一致，且避免和其他附加包冲突，我们还是作此安排。
+
+## 编辑附着物
+
+我们打开我们的附着物JSON定义文件。我们需要将附着物的几何和纹理修改为我们自己的资源。
+
+```json
+{
+  "format_version": "1.8.0",
+  "minecraft:attachable": {
+    "description": {
+      "identifier": "tutorial_demo:armor",
+      "geometry": {
+        "default": "geometry.mc_t-shirt" // 修改此处
+      },
+      "materials": {
+        "default": "armor",
+        "enchanted": "armor_enchanted"
+      },
+      "textures": {
+        "default": "textures/models/armor/mc_t-shirt", // 修改此处
+        "enchanted": "textures/misc/enchanted_item_glint"
+      },
+      "render_controllers": [
+        "controller.render.armor"
+      ],
+      "scripts": {
+        "parent_setup": "variable.chest_layer_visible = 0.0;"
+      }
+    }
+  }
+}
+```
+
+我们按照上述写法进行修改，这样，我们的几何和默认纹理就修改成功了。
+
+![](./images/9.5_t-shirt_in-game.png)
+
+![](./images/9.5_t-shirt_preview.png)
+
+打开游戏自测观察效果，我们可以看到，盔甲穿着到身上之后确实显示出了应有的模型和纹理！