主题

自定义武器与工具 ​

自定义武器与工具属于特殊的自定义物品，在支持自定义物品所有特性的基础上，还具有武器或工具相关的功能。本文将介绍如何通过 custom_item_type: "weapon" 和 netease:weapon 组件来创建剑、镐、斧、铲、锄等自定义武器与采集工具。

前置条件

请先阅读 自定义基础物品 了解物品注册的基础流程（步骤 1-6）。武器与工具的注册在此基础上进行扩展。format_version 使用 1.10。

概述 ​

自定义武器/工具与普通自定义物品的区别在于：

  • 攻击伤害：通过 netease:weapon 组件的 attack_damage 字段设置额外攻击伤害。
  • 挖掘能力：通过 type、level、speed 字段，让工具拥有与原版镐/斧/铲/锄一致的挖掘行为和破坏速度。
  • 攻击动画：type 字段决定了手持攻击时播放的动画类型（如剑的横扫、斧的劈砍）。
  • 附魔兼容：enchantment 字段控制在附魔台上可获得的附魔等级与品质。
  • 铁砧修复：level 字段同时决定了铁砧修复时所用的材料类型。

武器/工具继承普通自定义物品的所有能力，包括自定义贴图、自定义配方、脚本事件监听等。

注册流程 ​

注册流程与 自定义基础物品 的步骤 1-6 基本相同，额外需要：

  1. 步骤 1-6 保持不变：创建 netease_items_beh 目录、编写物品 JSON、配置贴图、编写 item_texture.json、创建 netease_items_res 资源定义、添加 zh_CN.lang 本地化。

  2. 在 description 中设置 custom_item_type：

    json
    "description": {
  "identifier": "mymod:my_sword",
  "custom_item_type": "weapon"
}

  3. 在 components 中添加 netease:weapon 组件（必填）：

    json
    "netease:weapon": {
  "type": "sword",
  "level": 3,
  "speed": 8,
  "attack_damage": 7,
  "enchantment": 10
}

  4. 设置堆叠数量：自定义武器/工具只支持 minecraft:max_stack_size 设为 1。

  5. 设置耐久度（可选）：通过 minecraft:max_damage 组件设置最大耐久值。

注意

custom_item_type 设为 weapon 后，物品的默认 category 会变为 Equipment（装备），无需手动指定。若需要放到其他分类，可显式设置 category 字段。

武器类型（custom_item_type: weapon） ​

在行为包物品 JSON 的 description 中，将 custom_item_type 设为 "weapon" 即可将该物品标记为武器/工具类型：

json
"description": {
  "identifier": "mymod:my_pickaxe",
  "custom_item_type": "weapon"
}

该声明会使物品获得以下默认行为：

行为说明
默认分类category 自动设为 Equipment，在创造模式物品栏的"装备"分页中显示
手持渲染自动以武器方式竖直手持渲染（等同于 minecraft:hand_equipped: true）
组件要求必须包含 netease:weapon 组件，否则武器功能不生效

netease:weapon 组件详解 ​

netease:weapon 是武器/工具的核心组件，定义在行为包 netease_items_beh 的物品 JSON 中。所有字段如下：

键类型默认值说明
typestr（必填）武器/工具的类型，决定攻击动画和挖掘行为。可选值：sword（剑）、shovel（铲）、pickaxe（镐）、hatchet（斧）、hoe（锄）
levelint（必填）工具等级，影响挖掘等级判定和铁砧修复材料。详见 工具挖掘等级
speedint0采集工具挖掘方块时的基础速度倍率。对采集工具（镐、斧、铲、锄）生效，剑类型通常设为 0 或较低值
attack_damageint0额外攻击伤害值。玩家的最终攻击伤害 = 基础攻击力（1）+ 该值
enchantmentint0附魔能力值，影响在附魔台上获得的附魔等级与品质。详见 附魔兼容

type 字段详解 ​

type 决定了工具的行为特征：

type 值对应工具攻击动画挖掘加速方块类型
sword剑横扫动画蜘蛛网、竹子等（与原版剑一致）
pickaxe镐劈砍动画石质方块、矿石、金属方块等
hatchet斧劈砍动画木质方块、南瓜、菌类方块等
shovel铲劈砍动画泥土、沙子、砂砾、雪等
hoe锄劈砍动画干草块、树叶、海绵等（1.16+ 行为）

提示

type 为 hatchet（斧）而非 axe，这是中国版的命名约定，请注意区分。

speed 字段详解 ​

speed 表示该工具对其对应类型方块的挖掘基础速度。速度越高，挖掘越快。以下是原版工具的速度参考值：

材质等级原版速度值
木制工具2
石制工具4
铁制工具6
钻石工具8
下界合金工具9
金制工具12

对于剑类型，speed 通常设为 0，因为剑的挖掘加速仅对蜘蛛网等少数方块生效（固定 15 倍速，不受此字段影响）。

attack_damage 字段详解 ​

attack_damage 为额外攻击伤害值，叠加在玩家基础攻击力之上。以下是原版武器/工具的攻击伤害参考值：

物品attack_damage最终伤害（基础 1 + 额外）
木剑34
石剑45
铁剑56
钻石剑67
下界合金剑78
木镐12
铁镐34
钻石镐45

工具挖掘等级 ​

level 字段对应工具的挖掘等级。当工具类型为镐（pickaxe）时，挖掘等级决定了能否正常采集特定矿石并产生掉落物。只有当工具挖掘等级 >= 方块要求的最低等级时，方块才会掉落物品。

等级对照表 ​

level 值对应材质可挖掘方块（镐为例）
0木 / 金石头、煤矿石、下界石英矿等基础石质方块
1石铁矿石、青金石矿石
2铁钻石矿石、绿宝石矿石、金矿石、红石矿石
3钻石黑曜石、远古残骸
4+下界合金与等级 3 相同（目前无更高需求的方块）

铁砧修复材料 ​

level 同时决定了该武器/工具在铁砧中使用何种材料进行修复：

level 值修复材料
0（且 speed = 2）木板
0（且 speed != 2）金锭
1圆石
2铁锭
3钻石
> 3无法使用铁砧修复

注意

如果 level 大于 3，该武器/工具将无法在铁砧中使用材料修复。如需支持修复，请将 level 设置在 0-3 范围内。

耐久度 ​

通过 minecraft:max_damage 组件为武器/工具设置耐久度。耐久值范围为 [0, 32767]。

json
"minecraft:max_damage": 1561

原版武器/工具耐久度参考：

材质耐久度
木制59
石制131
铁制250
钻石1561
下界合金2031
金制32

耐久度消耗规则：

  • 攻击实体：每次攻击消耗 1 点耐久。
  • 挖掘方块：每破坏一个方块消耗 1 点耐久（对于剑破坏方块消耗 2 点耐久）。
  • 耐久为 0：物品损坏消失。

提示

自定义武器/工具的 minecraft:max_stack_size 只能设为 1。如果堆叠数量大于 1，耐久度行为可能不符合预期。

附魔兼容 ​

netease:weapon 组件中的 enchantment 字段控制物品的附魔能力值。该值影响物品在附魔台上能够获得的附魔种类和等级。

附魔能力值参考 ​

材质附魔能力值
木制15
石制5
铁制14
钻石10
下界合金15
金制22

附魔能力值越高，在附魔台上获得高等级附魔和多重附魔的概率越大。金制工具虽然耐久最低，但附魔能力最高，这与原版行为一致。

附魔类型 ​

根据 type 字段的不同，武器/工具可获得的附魔类型也不同：

type可用附魔
sword锋利、亡灵杀手、节肢杀手、击退、火焰附加、抢夺、耐久、经验修补
pickaxe效率、时运、精准采集、耐久、经验修补
hatchet效率、锋利、时运、精准采集、耐久、经验修补
shovel效率、时运、精准采集、耐久、经验修补
hoe效率、时运、精准采集、耐久、经验修补

完整示例：自定义剑 ​

以下是一把完整的自定义钻石级剑的配置示例，包含行为包和资源包文件。

行为包 — 物品定义 ​

文件路径

behavior/netease_items_beh/mymod_flame_sword.json

json
{
  "format_version": "1.10",
  "minecraft:item": {
    "description": {
      "identifier": "mymod:flame_sword",
      "custom_item_type": "weapon"
    },
    "components": {
      "minecraft:max_stack_size": 1,
      "minecraft:max_damage": 1561,
      "netease:weapon": {
        "type": "sword",
        "level": 3,
        "speed": 0,
        "attack_damage": 8,
        "enchantment": 14
      },
      "netease:fire_resistant": {
        "value": true
      },
      "netease:customtips": {
        "value": "§6火焰之刃"
      }
    }
  }
}

资源包 — 贴图映射 ​

文件路径

resource/textures/item_texture.json

json
{
  "resource_pack_name": "mymod",
  "texture_name": "atlas.items",
  "texture_data": {
    "mymod_flame_sword": {
      "textures": "textures/items/flame_sword"
    }
  }
}

资源包 — 物品表现 ​

文件路径

resource/netease_items_res/mymod_flame_sword.json

json
{
  "format_version": "1.10",
  "minecraft:item": {
    "description": {
      "identifier": "mymod:flame_sword",
      "category": "Equipment"
    },
    "components": {
      "minecraft:icon": "mymod_flame_sword",
      "minecraft:hand_equipped": true
    }
  }
}

本地化 ​

文件路径

resource/texts/zh_CN.lang

item.mymod:flame_sword.name=烈焰之剑

完整示例：自定义镐 ​

以下是一把自定义铁级镐的完整配置。

行为包 — 物品定义 ​

文件路径

behavior/netease_items_beh/mymod_mithril_pickaxe.json

json
{
  "format_version": "1.10",
  "minecraft:item": {
    "description": {
      "identifier": "mymod:mithril_pickaxe",
      "custom_item_type": "weapon"
    },
    "components": {
      "minecraft:max_stack_size": 1,
      "minecraft:max_damage": 500,
      "netease:weapon": {
        "type": "pickaxe",
        "level": 2,
        "speed": 7,
        "attack_damage": 4,
        "enchantment": 14
      }
    }
  }
}

资源包 — 贴图映射 ​

文件路径

resource/textures/item_texture.json（在已有文件中追加）

json
{
  "resource_pack_name": "mymod",
  "texture_name": "atlas.items",
  "texture_data": {
    "mymod_mithril_pickaxe": {
      "textures": "textures/items/mithril_pickaxe"
    }
  }
}

资源包 — 物品表现 ​

文件路径

resource/netease_items_res/mymod_mithril_pickaxe.json

json
{
  "format_version": "1.10",
  "minecraft:item": {
    "description": {
      "identifier": "mymod:mithril_pickaxe",
      "category": "Equipment"
    },
    "components": {
      "minecraft:icon": "mymod_mithril_pickaxe",
      "minecraft:hand_equipped": true
    }
  }
}

本地化 ​

文件路径

resource/texts/zh_CN.lang

item.mymod:mithril_pickaxe.name=秘银镐

与脚本配合 ​

通过 Python 脚本（Mod SDK），可以为自定义武器实现更丰富的功能：

  • 自定义攻击效果：监听 ServerItemUseOnEvent 或 ActorUseItemServerEvent 事件，在攻击命中时触发粒子特效、播放音效或施加状态效果。
  • 耐久度控制：通过 ItemDurabilityChangedServerEvent 事件监听耐久变化，实现不消耗耐久或额外消耗的逻辑。
  • 特殊挖掘行为：监听 PlayerTryDestroyBlockServerEvent 事件，为特定方块实现自定义挖掘速度或掉落物。

如果需要为武器添加 3D 模型和自定义攻击动画（如第一人称挥砍特效、第三人称手臂动画），请参考 自定义 3D 物品。

常见问题 ​

Q: 武器没有攻击伤害 / 挖掘不掉落物品？

确认 custom_item_type 已正确设为 "weapon"，且 netease:weapon 组件存在于 components 中。缺少任一配置都会导致武器功能失效。

Q: 铁砧无法修复自定义武器？

检查 level 值。level 大于 3 时无法使用铁砧修复。将 level 设为 0-3 中的合适值。

Q: 附魔台上附魔效果很差？

提高 enchantment 附魔能力值。该值越高，获得高级附魔的概率越大。参考金制工具的值为 22。

Q: 工具类型写了 axe 不生效？

中国版中斧的 type 值为 hatchet，不是 axe。

下一步 ​