自定义盾牌

自定义盾牌（Shield）允许玩家通过右键进入格挡状态，减少或抵消来自不同伤害源的伤害。你可以配置可防御/不可防御的伤害类型、耐久消耗，还可以通过 Attachable 添加 3D 盾牌模型。

前置条件

请先阅读 自定义基础物品 了解通用注册流程（步骤 1-6）。format_version 使用 1.10。

概述

自定义盾牌在基础物品之上扩展了格挡防御功能。通过 netease:shield 组件，你可以精确控制盾牌能够防御哪些伤害源，以及格挡时是否消耗耐久。

identifier 命名限制

盾牌物品 identifier 的冒号后部分不可以叫 shield（例如不能是 mymod:shield），否则会与原版盾牌冲突导致异常。建议使用 mymod:iron_shield 等名称。

netease:shield 组件

字段	类型	默认值	说明
defence_damage_source_list	array(str)	[]	可以防御的伤害源类型列表
undefence_damage_source_list	array(str)	[]	不可防御的伤害源类型列表
is_consume_damage	bool	true	格挡时是否消耗耐久

伤害源配置逻辑

• 如果 defence_damage_source_list 不为空 → 只防御列表中的伤害源
• 如果 undefence_damage_source_list 不为空 → 防御除列表外的所有伤害源
• 两个列表不应同时配置；若同时配置则 defence_damage_source_list 优先

常用伤害源类型

伤害源	说明
entity_attack	实体近战攻击
projectile	抛射物伤害
explosion	爆炸伤害
fire	火焰伤害
fire_tick	着火 tick 伤害
magic	魔法伤害
wither	凋灵效果伤害
anvil	铁砧坠落伤害
thorns	荆棘反伤

格挡机制

• 玩家右键持盾进入格挡状态（与原版盾牌行为一致）
• 格挡时面朝方向的伤害将被减免
• 如果 is_consume_damage 为 true，每次成功格挡会消耗耐久值
• 需要配合 minecraft:max_damage 组件设置盾牌耐久

3D 盾牌模型

自定义盾牌支持通过 Attachable 实现 3D 模型渲染。配置方式与 自定义 3D 物品 中的 Attachable 相同，但需要注意：

• 盾牌通常挂载在左手（leftItem 骨骼）
• 需要为格挡状态制作单独的动画
• 使用 c.item_slot == 'off_hand' 条件控制左手渲染

Attachable 示例

{
  "format_version": "1.10.0",
  "minecraft:attachable": {
    "description": {
      "identifier": "mymod:iron_shield",
      "materials": {
        "default": "entity_alphatest",
        "enchanted": "entity_alphatest_glint"
      },
      "textures": {
        "default": "textures/items/iron_shield_3d",
        "enchanted": "textures/misc/enchanted_item_glint"
      },
      "geometry": {
        "default": "geometry.iron_shield"
      },
      "animations": {
        "hold": "animation.iron_shield.hold",
        "blocking": "animation.iron_shield.blocking"
      },
      "scripts": {
        "animate": [
          "hold",
          { "blocking": "query.is_blocking" }
        ]
      },
      "render_controllers": [
        "controller.render.item_default"
      ]
    }
  }
}

完整案例：铁盾牌

行为包

behavior_pack/netease_items_beh/iron_shield.json：

{
  "format_version": "1.10",
  "minecraft:item": {
    "description": {
      "identifier": "mymod:iron_shield",
      "custom_item_type": "shield",
      "category": "equipment"
    },
    "components": {
      "minecraft:max_stack_size": 1,
      "minecraft:max_damage": 336,
      "minecraft:hand_equipped": true,
      "netease:shield": {
        "defence_damage_source_list": [
          "entity_attack",
          "projectile",
          "explosion"
        ],
        "undefence_damage_source_list": [],
        "is_consume_damage": true
      },
      "netease:allow_offhand": true
    }
  }
}

资源包

resource_pack/netease_items_res/iron_shield.json：

{
  "format_version": "1.10",
  "minecraft:item": {
    "description": {
      "identifier": "mymod:iron_shield",
      "texture": "iron_shield"
    }
  }
}

本地化

item.mymod:iron_shield.name=铁盾牌

TIP

建议为盾牌配置 netease:allow_offhand: true，允许玩家将盾牌放置在副手栏，与原版盾牌的使用习惯一致。

常见问题

盾牌名称与原版冲突

盾牌物品 identifier 的冒号后部分不能叫 shield，需使用其他名称避免与原版冲突。

格挡不生效

检查 defence_damage_source_list 是否包含了你想防御的伤害源。如果两个列表都为空，盾牌不会防御任何伤害。

盾牌无法放入副手

确认配置了 netease:allow_offhand: true 组件。

下一步

• 自定义基础物品 — 回顾基础物品注册流程
• 自定义 3D 物品 — 为盾牌添加 3D 模型
• 物品组件速查 — 所有物品组件一览