教學:製作附加包/物品

From Minecraft基岩版开发Wiki
物品
系列教學
所屬系列
難易度
初級
前置知識
適用版本
國際版
≥ 1.12.0
實踐裝置
WindowsAndroid
所需軟體

歡迎你來閱讀本篇自訂物品教學!物品是MC中非常重要的一個概念,本教學希望從原理開始,通俗易懂地向你展示如何在基岩版加入一個物品。

當然,在閱讀本篇教學之前,請確保你已經能夠建立一個行為包和資源包,建立一個新物品需要兩個包的共同合作。如果你還不清楚,請先瀏覽開始之前包的構建執行、除錯與匯出頁面後再來瀏覽本教學。

引言[edit]

準備好合適的工具[edit]

如果你是Windows使用者,你可以使用Visual Studio Code來編寫。這是一個非常強大且實用的IDE,可以大幅簡化你的工作流程。

如果你是Android使用者,MT管理器也許是個不錯的選擇。

不同版本之間的差異[edit]

自訂物品有三個分水嶺版本存在:

  • 1.10,這是你可以建立自訂物品的最低版本,包含最基礎最簡單的一些元件;
  • 1.16.100,該版本加入或修改了非常多全新的物品元件,使得物品功能有了巨大的飛躍;
  • 1.20.X,從1.20.0開始的後續版本開始令1.16.100加入的物品元件走出實驗性玩法(即不開啟實驗性玩法也能夠使用它們),並進行了非常多的整合與修改。這意味著這些物品元件正趨於穩定。

了解了這些之後,我們就可以按照需求選擇版本。本教學將基於1.10和1.20+的版本編寫,因為它們是穩定的。當然,1.16.100~1.20-的物品格式編寫我們也會簡單介紹,向你展示其中的一些重點內容。

模板的取得[edit]

Mojang提供了一些原版的實例,這對於我們編寫自己的物品有一些幫助。你可以在這裡下載到原版的樣例包:

1.10至1.16.100的自訂物品編寫[edit]

首先建立一個行為包和資源包,並寫入manifest.json。這是在閱讀本教學之前應掌握的基礎,這裡不多贅述。

行為包部分[edit]

物品的行為包部分主要宣告這個物品在底層上是如何工作的,例如定義它可以吃,可以種下種子等等屬性。因此,如果這個物品不能按照你預期的方式工作,你可以看看是不是行為包出了問題。

在你的行為包中新建一個資料夾items,請注意名字必須完全對應,不要忘記s。接下來我們建立一個檔案my_custom_item.item.json,寫入下面的內容:

{
  "format_version": "1.16.0",
  "minecraft:item": {
    "description": {
      "identifier": "test:my_custom_item"
    }
  }
}

這是一個自訂物品所具有的最基本的屬性,相當於你給這個物品打了一個地基。我們來簡單解釋一下這裡的內容:

  • format_version格式版本
我們寫的是標準的舊版本物品,它將代表Minecraft將以舊版本的元件格式來分析它。我們可以寫入1.101.16.100(不包括)之間的合理版本。
  • description物品描述
介紹該物品最基礎的一些屬性。
    • identifierID
這是物品的唯一識別碼,即ID,是獨屬於這個物品的唯一屬性。/give/clear等對物品操作的指令都有物品ID這樣的參數,指代的就是這裡的內容。我們在這裡寫入了"test:my_custom_item",其中的test我們稱之為命名空間,代表的是你這個包的一些通用屬性,它可以任意填寫,但不允許minecraft作為命名空間,因為這是給原物品使用的。我們建議你的命名空間足夠獨特且易懂,否則如果名稱過於通用可能會在多個包同時應用的情況下產生衝突。my_custom_item叫做ID名稱,根據你的物品的性質而命名,建議起的直觀易懂一些。現在你已經知道,ID是由命名空間和ID名稱所組成的了。

現在我們打完了地基,開始建大樓吧!假設我們希望這個物品只能堆疊至多1個,你可以看下面這段程式碼:

{
  "format_version": "1.16.0",
  "minecraft:item": {
    "description": {
      "identifier": "test:my_custom_item"
    },
    "components": {
      "minecraft:max_stack_size": 1
    }
  }
}

這樣的話,你的自訂物品將至多堆疊1個。我們現在來解釋一下:

  • components元件
宣告該物品所具有的元件。元件是Minecraft自訂內容中的重要成分,Minecraft已經將一些功能做成了元件,你只需要像拼拼圖一樣將你想要的功能拼在一起就可以了。元件被廣泛地用於基岩版附加包的方方面面,包括物品、方塊、實體等都是採用元件這個形式。
    • minecraft:max_stack_size最大堆疊
這是舊版本物品中可用的其中一個元件。將這個值設定為1,你會發現這個物品將是1個為1組。它的預設值為64,代表該物品將以64個為1組。

舊版本物品的元件數目十分有限,目前僅有以下幾個可用:

舊版本物品最常用的一個例子是食物。事實上1.20+的物品元件因minecraft:food元件不支援施加自訂的狀態效果,想要更方便的加入帶有狀態效果的物品就只能用舊版本物品。下面是一個原版的實例,蜂蜜瓶。請注意這個實例來自原版,所以它的命名空間是minecraft,你的自訂物品是不能把minecraft作為命名空間的!

{
  "format_version": "1.14",
  "minecraft:item": {
    "description": {
      "identifier": "minecraft:honey_bottle"
    },
    "components": {
      "minecraft:use_duration": 40,
      "minecraft:max_stack_size": 16,
      "minecraft:food": {
        "nutrition": 6,
        "saturation_modifier": "poor",
        "can_always_eat": true,
        "using_converts_to": "glass_bottle",
        "remove_effects": [
          "poison"
        ]
      }
    }
  }
}

關於此物品的物品元件解釋,請自行在相關的元件頁面查閱,這裡不予贅述。當然需要指出的一點是,能夠讀懂原版實例是提升自己能力很重要的一環,請多加訓練這樣的能力。

資源包部分[edit]

物品的資源包主要宣告這個物品如何在你的遊戲畫面上呈現,包括它的圖示、動畫和文字翻譯等。因此如果你的物品不能正常顯示,或者文字音效等外顯方面出了問題,你可以來排查一下資源包的問題。當然有時候重啟遊戲或許可以解決問題。這裡要指代的內容多而繁雜,希望你可以耐心地讀下去。

首先,同理地,在你的資源包中新建一個資料夾items,注意名字必須完全對應。接下來我們建立一個檔案my_custom_item.item.json,寫入下面的內容:

{
  "format_version": "1.16.0",
  "minecraft:item": {
    "description": {
      "identifier": "test:my_custom_item",
      "category": "Equipment"
    },
    "components": {
      "minecraft:icon": "my_custom_item"
    }
  }
}

同樣地,我們來解釋一下這其中的內容:

  • format_version格式版本
和行為包同理。我們可以寫入1.101.16.100(不包括)之間的合理版本。
  • description物品描述
介紹該物品最基礎的一些屬性。
  • identifierID
這裡寫入的ID必須和行為包完全一致。
  • category物品目錄
指代該物品將要放到配方手冊(或創造模式物品欄)中哪一欄的位置。基岩版的配方手冊有4個欄位:建築(Construction)、裝備(Equipment)、物品(Items)、自然(Nature),你可以在這4個值中選擇一個填進。
  • minecraft:icon物品圖示
指代該物品將要呼叫的圖示。該圖示是在textures/item_texture.json中所呼叫的。我們寫入了my_custom_item,稱之為短ID,短ID是可以任意寫的,但最好清楚直觀。

在資源包的物品元件中允許以下內容:

請自行查閱其中所允許的內容。溫馨提醒,如果你定義了你的物品為食物並且想使用喝下食物的音效,請按下文定義:

"minecraft:use_animation": "drink"


接下來我們希望讓這個物品正確地顯示出來。現在請在你的資源包目錄下新建一個資料夾textures,並建立一個新檔案item_texture.json(注意沒有s),寫入下面的內容:

{
  "resource_pack_name": "vanilla",
  "texture_name": "atlas.items",
  "texture_data": {
    "my_custom_item": { "textures": "textures/items/my_custom_item" }
  }
}

前兩行你可以不必留意,把它們當作是固定內容。從第三行的texture_data開始,這是物品的短ID與物品貼圖所連結的地方。一般格式為

"texture_data": {
  "(短ID)": { "textures": "(物品贴图文件路径,不带后缀名)" },
  "(短ID)": { "textures": "(物品贴图文件路径,不带后缀名)" },
  ...
}

因此還需要將你的物品貼圖放到對應位置上。如果你急於沒有貼圖的話,先從原版實例那裡暫時使用原版貼圖,之後,如果你有自己畫的需求,推薦使用Blockbench(Windows)、IsoPix(Android)或者專業的畫圖軟體(例如Photoshop)畫圖。推薦16×16的貼圖,但不管怎麼說必須是一個正方形的貼圖,即長寬相等。


到此為止你的物品就應該可以正常顯示了,然而如果此時你進入遊戲,你的物品名字會變成一段「亂碼」:item.test:my_custom_item.name,這其實是在地化鍵名。不要慌張,這是我們還沒有定義它的名字。我們需要在資源包的語言檔案下指定它的名字。在你的資源包目錄下新建一個資料夾texts,並建立兩個新的文字檔en_US.langzh_CN.lang,分別寫入下面的內容:

en_US.lang

item.test:my_custom_item.name=My Custom Item

zh_CN.lang

item.test:my_custom_item.name=我的自定义物品
  • item.test:my_custom_item.name翻譯鍵名,指代在遊戲中要用什麼樣的翻譯顯示這段文字。一般而言,物品的鍵名格式為item.(物品ID).name。右側為你希望讓它顯示出來的內容,並用等號連接。

現在你已經寫好了你的第一個自訂物品!它將只能堆疊一個,顯示出你自訂的貼圖。當然,僅憑舊版元件能夠實現的內容太少了,因此我們需要更高版本的元件來實現我們想要的功能。

1.20及更高版本的自訂物品編寫[edit]

首先請注意,1.20或更高版本很多地方都是與低版本元件的編寫大同小異的,因此請確保你已經清楚了1.10~1.16.100格式版本的物品編寫方式。我們在這裡只是簡要提一些大概流程和差異點。

行為包部分[edit]

我們同樣還是先新建一個資料夾items,建立一個檔案my_custom_item_2.item.json。你不必刪除你剛剛寫入的內容,因為新版的物品是可以相容舊版物品的。寫入下面的內容:

{
  "format_version": "1.20.60",
  "minecraft:item": {
    "description": {
      "identifier": "test:my_custom_item_2",
      "menu_category": { "category": "equipment" }
    },
    "components": {
      "minecraft:icon": { "texture": "my_custom_item_2" }
    }
  }
}

相信你已經注意到了,在1.20+的物品中,我們把categoryminecraft:icon放到了行為包裡來寫,而在舊版本中這是屬於資源包的部分。事實上我們在1.20+中可以把本應在資源包items中的元件一併搬到行為包中,因為Mojang在1.16.100時對這些內容做了整合,並在1.20+的版本開始正式公布。這樣可以更加方便地調整物品的元件,改變它的底層行為。

我們在這裡先搭好框架,在後面我們來舉幾個簡單的例子幫助你理解。關於1.20+可用的元件,見1.20可用的物品元件

資源包部分[edit]

在高版本中的資源包部分,我們不必再建立items資料夾了,因為這裡的內容都放在了行為包裡,包括短ID的設定。而item_texture.json和語言檔案的設定步驟則是和上面所一致的。但是語言檔案上還是有一些細微的差異點,在於翻譯鍵名從item.(物品ID).name改為了item.(物品ID),少了後面的.name

1.16.100至1.20的自訂物品編寫[edit]

將這一部分放到後面來展示,是因為兩點:

  • 第一,啟用這些元件必須使用假日創作者功能實驗性玩法,而實驗性玩法一般都是不穩定的,它需要你不斷地維護且不能關閉,否則你可能會被背刺,你的物品功能不能正常實現,這對你的創作較為不利。
  • 第二,在1.20之後對這些元件進行了大規模的整合、移除和棄用,因此現在的文件大多已不適用於這個版本區間。所幸在Manual:資料驅動/物品還剩下一些有關於這個版本區間的元件介紹供你使用。

關於行為包和資源包的相關部分,事實上和1.20的自訂物品編寫更加接近,即沒有資源包的items資料夾,所有元件整合到行為包中去。

如果你正在使用中國版,很不幸的是如果你需要的話你可能必須要用這個版本區間的物品元件。當然,中國版擁有非常豐富的介面可供你使用,你完全可以透過它們實現意想不到的功能。

一些範例[edit]

製作一把自己的劍[edit]

製作一把劍在舊版本物品中是難以實現的。然而在1.20+的物品元件中,實現一把劍並不是什麼非常困難的事情。我們這裡略過資源包,因為這些步驟都是一般的。實現一把劍的幾個關鍵要素如下:

基於此我們可以寫出如下內容:

{
    "format_version": "1.20.60",
    "minecraft:item": {
        "description": {
            "identifier": "wiki:emerald_sword",
            "menu_category": { "category": "equipment", "creative_category": "itemGroup.name.sword" }
        },
        "components": {
            "minecraft:damage": 9,
            "minecraft:enchantable": { "value": 10, "slot": "sword" },
            "minecraft:can_destroy_in_creative": false,
            "minecraft:digger": { "destroy_speeds": [ { "block": "minecraft:web", "speed": 15 }, { "block": "minecraft:bamboo", "speed": 30 } ] },
            "minecraft:icon": { "texture": "emerald_sword" },
            "minecraft:max_stack_size": 1,
            "minecraft:hand_equipped": true,
            "minecraft:durability": { "max_durability": 300, "damage_chance": { "min": 1, "max": 2 } }
        }
    }
}

這樣就實現了一把可以+9傷害的,耐久值為300的綠寶石劍!

製作一個放下即炸的TNT![edit]

我們知道TNT必須點燃之後才能開始爆炸,但是我們可以直接製作一個放下即炸的TNT!實現它的關鍵要素如下:

基於此我們可以寫出如下內容:

{
    "format_version": "1.20.0",
    "minecraft:item": {
        "description": {
            "identifier": "wiki:tnt"
        },
        "components": {
            "minecraft:entity_placer": { "entity": "minecraft:tnt" },
            "minecraft:icon": { "texture": "wiki_tnt" }
        }
    }
}

在資源包也搞定之後,可以將物品使用在一個方塊上,它將直接像生怪蛋一樣召喚一個TNT!

製作一個自訂的手榴彈[edit]

假如說你希望實現一個手榴彈,且落地即炸,這背後需要的工作量比較大,但是你也需要一個自訂物品,畢竟如果把雞蛋雪球改了就有污染原版的嫌疑了哦。

  • 主要問題在於我們如何建立一個可投擲的物品。這可以使用minecraft:projectileminecraft:throwable來實現;
  • 當然你應該不希望它連續投出(即一直按下右鍵就像加特林一樣),我們可以加一個冷卻,這可以使用minecraft:cooldown來實現。

基於此我們可以寫出如下內容:

{
    "format_version": "1.20.10",
    "minecraft:item": {
        "description": {
            "identifier": "wiki:grenade"
        },
        "components": {
            "minecraft:cooldown": { "category": "grenade", "duration": 0.3 },
            "minecraft:projectile": { "minimum_critical_power": 1, "projectile_entity": "wiki:grenade" },
            "minecraft:throwable": { "do_swing_animation": true, "max_launch_power": 1, "scale_power_by_draw_duration": false },
            "minecraft:icon": { "texture": "grenade" }
        }
    }
}

當然手榴彈還需要自訂實體的合力發揮才能實現。如果你在這個基礎上,將minecraft:projectileprojectile_entity改為minecraft:arrow,你就可以立刻獲得簡易版飛刀了(當然ID名要記得改)。

本教學為基礎教學,不同元件的結合會產生非常有意思的效果,例如自訂盔甲、武器、食物、投擲物等都可以實現。希望對你有所幫助。有關自訂物品的詳解請前往mcwzh:基岩版物品文件檢視。

引言[edit]

基岩版1.12更新中,Mojang正式向開發人員提供了自訂物品的相關介面。但由於當時 Mojang在附加包方面的開發重心仍在於開放自訂實體的相關介面上,故物品介面在很長的一段時間裡都處於「極不完善」的狀態。

直至1.16.100.56 beta版本,自訂物品相關介面才得到了大幅增強,同時自該版本起,Mojang摒棄了資源包中的物品組態檔,使物品的定義更加便捷且架構更加合理。

因1.16.100以後的新版物品結構簡單,定義方便,功能多樣,故本教學僅介紹新版物品的定義方法。

在1.20.30正式版以後,隨著物品事件逐漸被棄用,新的物品元件逐漸走出實驗玩法以及腳本API中相關內容的完善,自訂物品部分功能的實現方式又發生了變化。

簡介[edit]

一個完整的物品應該由兩部分組成:

  • 物品資源(物品的紋理、名稱)
  • 物品行為(物品的行為、屬性、賦命名空間識別碼等)

在本教學中,我們將建立一個簡單的物品。在第一節中,我們將學習如何定義物品行為;在第二節中,我們將給這個物品分配紋理、名稱。

物品行為[edit]

要定義一個物品的行為,你需要在行為包中的 items資料夾下新建JSON檔案,並將其命名為<物品ID>.json

物品的基本架構如下:
{
  "format_version": "1.20.30",//格式版本
  "minecraft:item": {
    "description": {
    }, //描述
    "components": {
    }, //组件
    "events": {
    } //事件
  }
}
描述 (description) 物件儲存了用於描述該物品的基礎資訊,其中最重要值的便是identifier,其定義了物品的賦命名空間識別碼

其詳細資料結構見此

格式版本(format_version)決定遊戲以何種版本的規則讀取檔案,不同的格式版本的元件、事件寫法可能不同。

元件(components)物件決定物品的行為,你可以選擇並加入需要的元件屬性,例如加入minecraft:glint元件可以讓物品具有附魔光芒、加入minecraft:food元件可以讓物品可以被食用。

完整的元件列表見此

事件(events)物件儲存了該物品可能用到的所有事件,其可以由特定的觸發器元件觸發或者由元件內的觸發器參數觸發,對於初學者,可暫時忽略這部分。

新增物品[edit]

首先我們在行為包檔案根目錄下新建一個名為items的資料夾,所有的物品檔案將儲存於此資料夾中,你也可以建立子資料夾以分類物品檔案。

新建一個文字文件,將其後綴改為.json,並修改檔案名稱為識別碼後半部分。在這之後,我們可以向其中寫下這些內容以定義一個基礎物品。

在你的物品JSON檔案裡加入以下內容:
{
    "format_version": "1.20.30",
    "minecraft:item": {
        "description": {
            "identifier":"wiki:custom_item",//该物品赋命名空间标识符,出现重复的标识符会被识别为同一物品。
            "menu_category": {
                "category": "items",
				"group": "itemGroup.name.custom"
            }//物品创造模式分类与分组,在不同格式版本写法不同
        },
        "components": {
            "minecraft:icon": {
                "texture": "wiki.custom_item"//定义纹理,填短名称
            }
        }
    }
}
進入遊戲,你會發現自己的物品沒有紋理且有一個奇怪的名稱,這是因為我們還沒有定義物品的資源。

物品資源[edit]

現在我們有了一個物品,本節我們將要給這個物品加入紋理與名稱。

加入紋理[edit]

紋理儲存在資源包中,為了方便存取,我們需要給紋理定義一個短名稱。

首先,我們需要一個16×16的.png图檔作為紋理,並將其放入資源包的textures/items資料夾中。

接著我們需要給這個紋理分配短名稱,所有物品短名稱都儲存在资源包/textures/item_texture.json,其中包含短名稱及其分配紋理的列表,加入以下內容:
{
	"resource_pack_name": "示例资源包",//资源包名称
	"texture_name": "atlas.items",//纹理类型,不可更改
	"texture_data": {
	    "wiki.custom_item": {//纹理短名称,应与minecraft:icon组件中填写的值相同
	       "textures": "textures/items/custom_item"//纹理路径,不带.png后缀
        }
	}
}

加入名稱[edit]

最後,我們要為物品加入一個好聽的名字。遊戲會為這個物品分配一個形似item.<物品标识符>的翻譯鍵,我們只需要在語言檔案中定義它即可。

首先在資源包中新建名為texts的資料夾,在其中新建名為zh_CN.lang的文字檔,輸入以下內容:
item.wiki:custom_item=自定义物品
更多資訊見Manual:製作附加包/在地化

你知道嗎[edit]

  • 自訂物品的Json檔案名稱並不要求必須與物品ID相同。
  • 物品紋理並不強制要求解析度為16×16,但若不是專門製作高清資源包的話,建議物品貼圖大小不要超過128*128,既節省精力,又節省空間和效能。

< 紋理 | 物品元件 >