指南
如何用插件制作自定义物品
更新于 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 生成这个