製作你的第一個物品 1.21.4

了解如何登錄一個簡單的物品，以及如何為物品加入紋理、模型和名稱。

WARNING

This page is written for version 1.21.4. Documentation for older versions may be incomplete.

本頁面將向你介紹一些與物品相關的重要概念，以及如何登錄物品、設定紋理、建立模型及命名物品。

如果你不知道的話，Minecraft的所有事物都儲存在登錄中，物品也不例外。

準備你的物品類別

為了簡化登錄物品的流程，你可以建立一個方法，這個方法接受ID字串、物品設定，以及建立Item實例的「工廠方法」。

這個方法會使用傳入的ID建立一個物品，並將其登錄到遊戲的物品登錄中。

你可以把這個方法放在叫做 ModItems（或是其他你想要的名稱）的類別中 。

Mojang對物品也是這麼做的！ 看看 Items 類別以了解。

public class ModItems {
	public static Item register(String name, Function<Item.Properties, Item> itemFactory, Item.Properties settings) {
		// Create the item key.
		ResourceKey<Item> itemKey = ResourceKey.create(Registries.ITEM, ResourceLocation.fromNamespaceAndPath(FabricDocsReference.MOD_ID, name));

		// Create the item instance.
		Item item = itemFactory.apply(settings.setId(itemKey));

		// Register the item.
		Registry.register(BuiltInRegistries.ITEM, itemKey, item);

		return item;
	}

}

注意這個工廠方法使用了介面 Function，它允許我們稍後能夠指定 Item::new 作為透過物品設定建立物品的方法。

登錄物品

現在你可以用這個方法來登錄物品。

物品的登錄方法接受一個 'Item.Properties` 類別的實例作為參數。 這個類別允許你透過各式各樣的「建造方法」設定物品的屬性。

TIP

If you want to change your item's stack size, you can use the maxStackSize method in the Item.Properties class.

如果物品具有耐久，則這不會生效，因為對於任何具有耐久的物品，其堆疊大小永遠是1，以避免重複損壞。

public static final Item SUSPICIOUS_SUBSTANCE = register("suspicious_substance", Item::new, new Item.Properties());

Item::new 會告訴註冊方法，透過呼叫接收一個Item.Properties 作為參數的 Item 建構方法（new Item(...)），以從 Item.Properties 創建一個 Item 實例。

然而，若你嘗試執行修改過的用戶端，會發現我們的物品沒有被加入到遊戲中！ 這是因為你還沒有靜態初始化類別。

要這麼做，你需要在類別中添加靜態的初始化方法，然後在你的模組的初始化類別中呼叫。 目前，這個方法裡不需要有任何東西。

public static void initialize() {
}

public class FabricDocsReferenceItems implements ModInitializer {
	@Override
	public void onInitialize() {
		ModItems.initialize();
	}
}

呼叫一個類別裡的方法時，如果該類別尚未載入，就會進行靜態初始化——這意味著所有static欄位都會計算。 這就是這個虛擬 initialize 方法存在的目的。

把物品添加進物品群組

INFO

如果想要將物品添加進自訂 CreativeModeTab 中，請參閱 自訂物品群組。

舉例來說，如果我們想將這個物品加進「原材料」物品群組中，你會需要使用 Fabric API 的「物品群組事件」——即 ItemGroupEvents.modifyEntriesEvent。

這可以在你的物品類別中的 initialize 方法中完成。

// Get the event for modifying entries in the ingredients group.
// And register an event handler that adds our suspicious item to the ingredients group.
ItemGroupEvents.modifyEntriesEvent(CreativeModeTabs.INGREDIENTS)
		.register((itemGroup) -> itemGroup.accept(ModItems.SUSPICIOUS_SUBSTANCE));

載入遊戲，你就會看到我們的物品已經登錄，並顯示在「原材料」物品群組中了：

然而，這個物品還缺少了：

• 物品模型
• 紋理
• 翻譯（名稱）

給物品命名

這個物品現在還沒有翻譯，所以你需要為其添加。 Minecraft本身已經提供了這個物品的翻譯鍵： item.mod_id.suspicious_substance。

在 src/main/resources/assets/mod-id/lang/ 中建立一個JSON檔案，名為 zh_tw.json（繁體中文，英文則是en_us.json），並輸入翻譯鍵及其值：

{
  "item.mod_id.suspicious_substance": "Suspicious Substance"
}

你可以選擇重啟遊戲，或者建構模组並按下F3+T，以套用變更。

添加紋理與模型

要為你的物品提供紋理與模型，只需要建立一個 16x16 的紋理圖像並儲存在 assets/mod-id/textures/item 資料夾中。 根據物品的ID命名紋理檔案。別忘了 .png副檔名。

例如，你可以將這個範例紋理作為 suspicious_substance.png

Download 紋理

重啟/重新載入遊戲後，你應該會發現物品還沒有紋理，因為你還需要為物品添加一個使用此紋理的模型。

你可以建立一個簡單的 item/generated 模型——它只接受一個紋理，僅此而已。

在 assets/mod-id/models/item 資料夾中，建立模型JSON，檔名與物品ID相同；suspicious_substance.json

{
  "parent": "minecraft:item/generated",
  "textures": {
    "layer0": "fabric-docs-reference:item/suspicious_substance"
  }
}

解析模型JSON

• parent 這個模型繼承的父模型。 在這個例子中，是 item/generated 模型。
• textures：為模型定義紋理的地方。 layer0 鍵是模型要使用的紋理。

大多數物品都會繼承 item/generated 模型，因為它是個僅用於顯示紋理的模型。

除此之外，還有其他模型，例如 item/handheld 模型，用於表示玩家手中「持有」的物品，如工具。

建立物品模型描述

Minecraft並不知道我們把模型檔案放在哪裡，因此我們需要提供物品模型描述。

在 assets/mod-id/items 資料夾中建立物品模型描述JSON，檔案名稱與物品ID相同：suspicious_substance.json。

{
  "model": {
    "type": "minecraft:model",
    "model": "fabric-docs-reference:item/suspicious_substance"
  }
}

解析物品模型映射JSON

• model：包含對我們模型的引用的屬性。
  • type：模型的類型。 對於大部分物品而言，它應該是 minecraft:model
  • model：模型的ID。 它應該是這樣的形式：mod-id:item/item_name

現在你的物品在遊戲內應該是長這樣的：

讓物品可拿去堆肥或當作燃料

Fabric API 提供各式各樣的登錄，可以為你的物品添加額外屬性。

例如，如果你想要讓你的物品可以拿去堆肥，你可以使用 CompostableItemRegistry：

// Add the suspicious substance to the composting registry with a 30% chance of increasing the composter's level.
CompostingChanceRegistry.INSTANCE.add(ModItems.SUSPICIOUS_SUBSTANCE, 0.3f);

或者，如果要讓物品可以當燃料，可以使用 FuelRegistryEvents.BUILD事件：

// Add the suspicious substance to the registry of fuels, with a burn time of 30 seconds.
// Remember, Minecraft deals with logical based-time using ticks.
// 20 ticks = 1 second.
FuelRegistryEvents.BUILD.register((builder, context) -> {
	builder.add(ModItems.SUSPICIOUS_SUBSTANCE, 30 * 20);
});

添加基本的合成配方

如果要為你的物品添加合成配方，你需要將配方JSON檔案放在 data/mod-id/recipe 資料夾中。

更多關於合成配方格式的資訊，可參閱以下資源：

• 配方 JSON 生成器
• 中文 Minecraft Wiki - 配方 JSON

自訂物品提示

如果你想讓你的物品擁有自訂物品提示，你會需要建立繼承了 Item 的類別，並覆寫 appendHoverText方法。

INFO

這個範例使用了 LightningStick 類別，其於自訂物品交互頁面中建立。

@Override
public void appendHoverText(ItemStack stack, TooltipContext context, List<Component> tooltip, TooltipFlag type) {
	tooltip.add(Component.translatable("itemTooltip.fabric-docs-reference.lightning_stick").withStyle(ChatFormatting.GOLD));
}

每呼叫一次 add() 就會增加一行提示。