Differences

This shows you the differences between two versions of the page.

--- zh_cn:tutorial:items [2024/12/08 14:24] – [创建物品实例] solidblock
+++ zh_cn:tutorial:items [2025/07/22 15:18] (current) – fix typo [注册物品的最佳实践（1.21.2 之前）] solidblock
@@ Line 4: / Line 4: @@
 添加基本的物品是编写模组的第一步。你将需要创建 ''Item'' 对象，注册，并提供纹理。要向物品添加其他行为，你将需要自定义的 ''Item'' 类。在本教程以及以后的所有教程中，均使用 ''tutorial'' 作为命名空间。如果你有单独的模组 ID，那就直接使用它。
-===== 创建物品实例 =====
+===== 创建物品实例（1.21.2 之前） =====
 :!: 如果是使用的 1.21.2 之后的版本，请直接跳到[[#在 1.21.2+ 中创建物品]]。
@@ Line 21: / Line 21: @@
 </yarncode>
-===== 注册物品 =====
+===== 注册物品（1.21.2 之前） =====
 我们创建了基本的物品，但是在 Minecraft 中还不存在，因为还没有注册。在 Minecraft 中，几乎所有东西都有注册表，物品也不例外。
-注册新的内容使用原版的注册表，基本语法为 ''<yarn class_2378>.<yarn method_10230>(注册表类型, <yarn class_2960>, 内容)''。注册表类型存储为 ''<yarn class_7923>'' 或 ''<yarn class_2378>'' 类的静态字段中，ID（identifier）则是标注你的内容的。内容是你添加的东西的实例。对于物品而言，语法就是 ''<yarn class_2378>#<yarn method_10230>(<yarn class_7923>.<yarn field_41178>, <yarn class_2960>, <yarn class_1792>)''。可以在初始化过程的任何地方调用它，方法本身会返回物品的实例。
+注册新的内容使用原版的注册表，基本语法为 ''<yarn class_2378>.//<yarn method_10230>//(注册表类型, <yarn class_2960>, 内容)''。注册表类型存储为 ''<yarn class_7923>'' 或 ''<yarn class_2378>'' 类的静态字段中，ID（identifier）则是标注你的内容的。内容是你添加的东西的实例。对于物品而言，语法就是 ''<yarn class_2378>.//<yarn method_10230>//(<yarn class_7923>.<yarn field_41178>, <yarn class_2960>, <yarn class_1792>)''。可以在初始化过程的任何地方调用它，方法本身会返回物品的实例。
 对于 1.21 之后的版本，''Identifier'' 是通过 ''%%Identifier.of("namespace", "path")%%'' 创建的。对于 1.21 之前的版本，是通过 ''%%new Identifier("namespace", "path")%%'' 或 ''%%new Identifier("namespace:path")%%''。当命名空间或路径包含非法字符（例如大写字母、中文）时，会失败。
@@ Line 43: / Line 43: @@
 现在新物品已添加到 Minecraft 中，运行“Minecraft Client”运行配置或者 ''runClient'' Gradle任务以查看它的运行情况，在游戏内执行命令 ''/give @s tutorial:custom_item''。
-===== 注册物品的最佳实践 =====
+===== 注册物品的最佳实践（1.21.2 之前） =====
-在上面的代码中，简直创建了//一个//物品。但是，如果模组有//许多//物品，则这样并不方块，因为你每次都需要注册、创建一个 ''Identifier''。所以我们创建一个专门的类存储物品对象，例如 ''ModItems'' 或者 ''TutorialItems''，然后简单的 ''register'' 方法便捷地注册物品。这在实际模组开发中很常见。你也可以看看原版的 ''Items'' 类以了解 Minecraft 中如何以类似方式完成的。
+在上面的代码中，简直创建了//一个//物品。但是，如果模组有//许多//物品，则这样并不方便，因为你每次都需要注册、创建一个 ''Identifier''。所以我们创建一个专门的类存储物品对象，例如 ''ModItems'' 或者 ''TutorialItems''，然后简单的 ''register'' 方法便捷地注册物品。这在实际模组开发中很常见。你也可以看看原版的 ''Items'' 类以了解 Minecraft 中如何以类似方式完成的。
 在这个例子中，创建一个 ''TutorialItems'' 类，并在 ''ModInitializer'' 中引用这个类。
@@ Line 108: / Line 108: @@
 在方法 ''Items.register'' 中，注册表键（registry key）会先写到 ''settings'' 中，然后使用那个 ''settings'' 去创建物品。
-===== 添加物品纹理 =====
+===== 添加物品模型、纹理和模型映射 =====
-如果第一步成功注册了你的物品，就可以成输入命令 ''/give @s tutorial:custom_item'' 成功得到你的物品。你会发现纹理缺乏，Minecraft 会像这样报错：
+如果第一步成功注册了你的物品，就可以成输入命令 ''/give @s tutorial:custom_item'' 成功得到你的物品。你会发现纹理缺失，Minecraft 会像这样报错：
     [Server-Worker-1/WARN]: Unable to load model: 'tutorial:custom_item#inventory' referenced from: tutorial:custom_item#inventory: java.io.FileNotFoundException: tutorial:models/item/custom_item.json
-这是因为我们还没有给物品提供纹理和模型。所以，你需要定义物品模组并提供纹理图像。你会需要将这些添加到你的资源的目的下，直接路径如下：
+这是因为我们还没有给物品提供**纹理**（texture）、**烘焙模型**（baked module，以下简称模型）以及相应的**模型映射**（自 1.21.4 开始）。这些文件分别位于以下位置：
 为物品注册纹理需要物品模型.json文件和纹理图像文件。 您将需要将它们添加到资源目录中。每个的直接路径是：
@@ Line 120: / Line 120: @@
   * 物品模型：''.../resources/assets/tutorial/models/item/custom_item.json''
   * 物品纹理：''.../resources/assets/tutorial/textures/item/custom_item.png''
+  * 物品模型映射（自从 1.21.4）：''.../resources/assets/tutorial/items/custom_item.json''
 我们将使用[[https://i.imgur.com/CqLSMEQ.png|这个示例纹理]]。
 一个非常简单的物品模型长这个样子：
-<code JavaScript>
+<code javascript /resources/assets/tutorial/models/item/custom_item.json>
 {
   "parent": "item/generated",
@@ Line 132: / Line 133: @@
 }
 </code>
 你的物品模型的 ''parent''改变了物品在手中以及在物品栏内等情形下的渲染。''item/generated'' 用于许多简单的物品。''item/handheld'' 用于手持其纹理左下角的物品。在 json 中，''textures/layer0'' 是图像文件的位置。
+从 1.21.4 开始，还需要物品模型映射（1.21.4 之前不需要），其内容如下：
+<code javascript /resources/assets/tutorial/items/custom_item.json>
+{
+  "model": {
+    "type": "model",
+    "model": "tutorial:item/custom_item"
+  }
+}
+</code>
+该物品模型映射将指定物品使用对应的物品模型。
+> :!: 手动创建这些文件显然会很累。了解数据生成可看看 [[datagen_model]] 页面。
 ===== 创建物品类 =====
@@ Line 191: / Line 208: @@
 这个例子中，物品默认不可破坏，并隐藏关于这一点的物品提示：
 <yarncode java>
-    // For versions below 1.21.2:
+    // 对于 1.21.2 之前的版本：
     public static final CustomItem CUSTOM_ITEM = register("custom_item", new CustomItem(new class_1792.class_1793()
         .component(DataComponentTypes.UNBREAKABLE, new UnbreakableComponent(true))));
-    // For versions since 1.21.2:
+    // 对于从 1.21.2 及以后、1.21.4 之前的版本：
     public static final Item CUSTOM_ITEM = register("custom_item", CustomItem::new, new Item.Settings()
         .component(DataComponentTypes.UNBREAKABLE, new UnbreakableComponent(true)));
+    // 对于从 1.21.4 及以后:
+    public static final Item CUSTOM_ITEM = register("custom_item", CustomItem::new, new Item.Settings()
+        .component(DataComponentTypes.UNBREAKABLE, Unit.INSTANCE));
 </yarncode>
@@ Line 205: / Line 227: @@
     // 我们新物品的实例，最大堆叠数为 16
-    // For versions below 1.21.2:
+    // 对于 1.21.2 之前的版本：
     public static final CustomItem CUSTOM_ITEM = register("custom_item", new CustomItem(new class_1792.class_1793().maxCount(16)));
-    // For versions since 1.21.2:
+    // 自从 1.21.2 开始：
     public static final Item CUSTOM_ITEM = register("custom_item", CustomItem::new, new Item.Settings().maxCount(16));
     [...]
@@ Line 274: / Line 297: @@
 类似地，你也可以使用 ''CompostingChanceRegistry'' 来让物品可以在堆肥桶中堆肥。
 ===== 下一步 =====
-试着[[zh_cn:tutorial:itemgroup|将你的物品添加到一个物品组中]]。
+试着[[itemgroup|将你的物品添加到一个物品组中]]。你的物品还没有名字，所以还可以看看[[lang|如何创建语言文件]]。