指南
如何用插件製作自訂物品
更新於 2026年10月18日
自訂的劍、法杖、鑰匙和工具，是最多人想要的插件功能之一。插件沒辦法在遊戲裡加入真正全新的物品，但可以拿一個原版物品，替它加上名稱、物品描述和隱藏標籤，並在玩家使用時做出反應。玩家用一般的遊戲就能加入，不需要模組。
把物品換成你自己的。
用 Codexe 產生這個逐步說明
1.列出物品
每個物品都要寫：基礎材料、顯示名稱、物品描述的每一行，以及它的作用。「一根名叫 Fire Wand 的烈焰桿，按右鍵發射火球，冷卻 5 秒」就是一個完整的物品。
2.用 PersistentDataContainer 替物品加上標籤
用
NamespacedKey把fire_wand這類 id 存進物品的PersistentDataContainer。插件是靠這個標籤而不是名稱來辨識物品，所以在鐵砧裡改名不會做出複製品。3.撰寫技能
每個技能都是一個事件監聽器：右鍵用
PlayerInteractEvent，攻擊用EntityDamageByEntityEvent，工具用BlockBreakEvent。再依玩家和物品分別加上冷卻時間。4.決定玩家怎麼取得物品
管理員的
/give指令、合成配方、商店、生物掉落物或寶箱獎勵。5.讓所有東西都能設定
名稱、物品描述、傷害、冷卻時間和配方都放在
config.yml，這樣不用重新建置就能調整物品平衡。6.建置並試用每個物品
讓 Codexe 編譯插件，用「立即試用」加入測試伺服器，把每個物品都給自己一份並實際使用。
為什麼用標籤而不是名稱
檢查顯示名稱或物品描述是最經典的錯誤：任何有鐵砧的玩家都能把一根木棒改名成「Fire Wand」。PersistentDataContainer（Minecraft 1.14 以上）會在物品上儲存玩家無法修改的資料，而且因為它是物品的一部分，重新啟動、放進箱子或交易之後都會保留。
1.8 到 1.13 沒有 PersistentDataContainer；插件會透過函式庫使用 NBT，或在物品描述裡藏一個隱藏標記。在需求中寫明版本，Codexe 就會採用該版本支援的做法。
技能和背後的事件
| 技能 | 事件 | 說明 |
|---|---|---|
| 右鍵技能 | PlayerInteractEvent | 檢查是哪隻手，每隻手各觸發一次 |
| 攻擊時的額外傷害或效果 | EntityDamageByEntityEvent | 確認攻擊者是手持該物品的玩家 |
| 範圍挖掘工具 | BlockBreakEvent | 尊重 WorldGuard 等保護插件 |
| 手持時的被動效果 | 重複執行的任務或 PlayerItemHeldEvent | 收起物品時移除效果 |
| 弓或投射物 | EntityShootBowEvent、ProjectileHitEvent | 替投射物加上標籤，才知道它是從哪裡射出的 |
材質和模型
插件改變的是物品的作用，而不是外觀。自訂外觀需要玩家下載的資源包：在舊版本中，物品會帶一個 CustomModelData 數值，由資源包對應到某個模型；從 1.21.2 開始，物品也可以透過 item_model 元件指向自己的模型。沒有資源包時，物品看起來就是帶自訂名稱的基礎材料，這對很多伺服器來說已經足夠。
描述範例
「一個名為 MagicItems 的 Paper 1.21.4 插件。三個物品，每個都用 PersistentDataContainer id 加上標籤：Fire Wand（烈焰桿，按右鍵發射火球，冷卻 5 秒）、Frost Blade（鐵劍，命中時給予緩慢 II 持續 3 秒）、Miner's Pick（鑽石鎬，可挖 3x3，但在玩家不能建造的 WorldGuard 區域內不行）。擁有 magicitems.admin 的玩家可使用 /mi give <player> <item>。每個物品各有一個有序合成配方。名稱、物品描述、冷卻時間和配方都放在 config.yml。」
常見問題
自訂物品要用插件還是模組？
如果玩家要用一般的遊戲加入，就用插件：這些物品是有新行為的原版物品。如果你需要真正全新、有自己渲染方式的物品或方塊，就用模組，但每位玩家都得安裝它。請看插件與模組比較。
可以搭配 ItemsAdder 或 Nexo 使用嗎？
你的插件可以相依它們，但它們是付費插件：Codexe 的測試伺服器無法安裝，所以需要它們的插件在那裡不會啟用。plugin.yml 裡列出的免費相依插件，會自動幫你裝到測試伺服器上。
更新之後物品會失效嗎？
用 PersistentDataContainer 加上標籤的物品，在 Minecraft 更新後仍會保留標籤。技能可能需要針對新的 API 重新建置；請看更新插件。
製作你的自訂物品
這則提示詞開啟後即可直接傳送：
“一個名為 MagicItems 的 Paper 1.21.4 插件，有三個用 PersistentDataContainer 加上標籤的物品：Fire Wand（烈焰桿，按右鍵發射火球，冷卻 5 秒）、Frost Blade（鐵劍，命中時給予緩慢 II 持續 3 秒）、Miner's Pick（可挖 3x3 的鑽石鎬）。magicitems.admin 可使用 /mi give，每個物品各有一個有序合成配方，名稱、物品描述、冷卻時間和配方都放在 config.yml。”
用 Codexe 產生這個