示例库 · 装备篇

所属：服主指南 → 物品示例库 · 装备篇　·　相关：物品类型 · 属性与数值 · 动作系统

本页逐件讲解 QI 内置的装备类示例物品。每个文件的文件名（如 armor）即物品 type，每个顶层键即一件物品 ID。改完任意 yml 后需执行 /qi reload 才生效——动作只在 reload / 重启时加载。

数值由 providers.ap.value（一段属性 JSON）交 AttributePlus 应用，QI 本身不内置数值。详见 属性与数值。

🖼️ [图片占位] 装备篇示例物品总览（护甲 / 武器 / 盾牌 / 法杖陈列）　·　建议 assets/equipment-gallery.png

---

护甲 armor.yml

通用 / 胸甲护甲。穿戴类物品，主打 equip / unequip 反馈，挥动类原子一般用不上。

demo_guard_plate

最简护甲：只有外观 + 防御属性，无动作。

demo_guard_plate:
  type: armor
  material: iron_chestplate
  display_name: "<white>卫士板甲</white>"
  item_name: "卫士板甲"
  lore:
    - ""
    - "<gray>坚固耐用的标准护甲</gray>"
  providers:
    ap:
      value: '{"defense":8,"health":40}'
  options:
    unbreakable: true

• 入门基线：providers.ap.value 提供 defense / health（属性与数值），unbreakable 不掉耐久。无 tier 时默认 COMMON（品质与显示）。

demo_aegis_plate

史诗护甲：发光 + 高防御 + 大生命。

demo_aegis_plate:
  type: armor
  material: diamond_chestplate
  display_name: "<aqua>神盾铠甲</aqua>"
  item_name: "神盾铠甲"
  tier: EPIC
  lore:
    - ""
    - "<gray>蕴含守护之力的铠甲</gray>"
  providers:
    ap:
      value: '{"defense":16,"health":100}'
  options:
    unbreakable: true
    glow: true

• tier: EPIC 配 glow: true 形成史诗外观（品质与显示）。

demo_dragonscale_plate

龙鳞胸甲：传说品质，穿上时唤醒龙魂（equip 触发提示 + 音效）。

demo_dragonscale_plate:
  type: armor
  material: diamond_chestplate
  display_name: "<gold>龙鳞胸甲</gold>"
  item_name: "龙鳞胸甲"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>以远古龙鳞锻造，护体生威</gray>"
    - "<dark_gray>穿戴时唤醒龙魂</dark_gray>"
  providers:
    ap:
      value: '{"defense":24,"health":140}'
  options:
    unbreakable: true
    glow: true
  actions:
    triggers:
      equip:
        trigger:
          atom: equip
        refs:
          - handler: qi:action_bar
            payload: "<gold>龙魂觉醒 · 护体生威</gold>"
          - handler: qi:sound
            payload: "minecraft:entity.player.levelup;1;1"

• 首个带动作的护甲：equip 触发器 驱动 qi:action_bar + qi:sound 处理器，payload 中音效格式为 声音键;音量;音调。

---

头盔 helmet.yml

头部护甲。头盔戴在头上，主要靠 equip / unequip 感知穿脱。

demo_iron_helm

最简头盔：外观 + 防御属性。

demo_iron_helm:
  type: helmet
  material: iron_helmet
  display_name: "<white>铁制头盔</white>"
  item_name: "铁制头盔"
  lore:
    - ""
    - "<gray>保护头部的基础装备</gray>"
  providers:
    ap:
      value: '{"defense":4}'
  options:
    unbreakable: true

• 入门基线，仅 defense:4（属性与数值）。

demo_crystal_helm

稀有头盔：发光 + 防御 / 生命属性。

demo_crystal_helm:
  type: helmet
  material: diamond_helmet
  display_name: "<aqua>水晶头冠</aqua>"
  item_name: "水晶头冠"
  tier: RARE
  lore:
    - ""
    - "<gray>折射光芒的水晶头冠</gray>"
  providers:
    ap:
      value: '{"defense":8,"health":20}'
  options:
    unbreakable: true
    glow: true

• tier: RARE + glow（品质与显示）。

demo_sentinel_helm

守望头盔：史诗品质，戴上时提示并奏号角（equip 触发）。

demo_sentinel_helm:
  type: helmet
  material: netherite_helmet
  display_name: "<gold>守望头盔</gold>"
  item_name: "守望头盔"
  tier: EPIC
  lore:
    - ""
    - "<gray>戴上时，视野更加锐利</gray>"
    - "<dark_gray>装备即触发</dark_gray>"
  providers:
    ap:
      value: '{"defense":12,"health":30}'
  options:
    unbreakable: true
    glow: true
  actions:
    triggers:
      equip:
        trigger:
          atom: equip
        refs:
          - handler: qi:action_bar
            payload: "<gold>守望之眼已开启</gold>"
          - handler: qi:sound
            payload: "minecraft:item.armor.equip_netherite;1;1"

• equip 触发器 → qi:action_bar + qi:sound（下界合金装备音效）处理器。

demo_royal_crown

黄金王冠：传说品质，戴上加冕（equip + 冷却 2s）、摘下落幕（unequip），双触发器。

demo_royal_crown:
  type: helmet
  material: golden_helmet
  display_name: "<yellow>黄金王冠</yellow>"
  item_name: "黄金王冠"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>戴上加冕，摘下落幕</gray>"
    - "<dark_gray>装备 / 卸下各有提示</dark_gray>"
  providers:
    ap:
      value: '{"defense":10,"health":40}'
  options:
    unbreakable: true
    glow: true
  actions:
    triggers:
      equip:
        trigger:
          atom: equip
        cooldown: 2s
        refs:
          - handler: qi:title
            payload: "<yellow>👑 加冕 👑</yellow>||<gray>王者归来</gray>||5||40||10"
          - handler: qi:sound
            payload: "minecraft:ui.toast.challenge_complete;1;1"
      unequip:
        trigger:
          atom: unequip
        refs:
          - handler: qi:message
            payload: "<gray>你摘下了黄金王冠。</gray>"

• 演示一物多触发：equip 带 cooldown: 2s，用 qi:title（格式 标题||副标题||淡入||停留||淡出）；unequip 用 qi:message（触发器 · 处理器）。

---

胸甲 chestplate.yml

胸部护甲。穿在身上不响应点击，触发以 equip / unequip / on_damage 为主。

demo_iron_cuirass

最简胸甲：外观 + 防御属性。

demo_iron_cuirass:
  type: chestplate
  material: iron_chestplate
  display_name: "<white>铁制胸甲</white>"
  item_name: "铁制胸甲"
  lore:
    - ""
    - "<gray>护住要害的厚实胸甲</gray>"
  providers:
    ap:
      value: '{"defense":8}'
  options:
    unbreakable: true

• 入门基线（属性与数值）。

demo_dragon_cuirass

史诗胸甲：发光 + 高防御 + 生命。

demo_dragon_cuirass:
  type: chestplate
  material: diamond_chestplate
  display_name: "<red>龙鳞胸甲</red>"
  item_name: "龙鳞胸甲"
  tier: EPIC
  lore:
    - ""
    - "<gray>以龙鳞锻造的护甲</gray>"
  providers:
    ap:
      value: '{"defense":16,"health":60}'
  options:
    unbreakable: true
    glow: true

• tier: EPIC + glow（品质与显示）。

demo_guardian_plate

守护者胸甲：传说品质，穿上时圣光环绕（equip 触发 title + 信标音效）。

demo_guardian_plate:
  type: chestplate
  material: netherite_chestplate
  display_name: "<aqua>守护者胸甲</aqua>"
  item_name: "守护者胸甲"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>穿戴时圣光环绕周身</gray>"
    - "<dark_gray>装备触发</dark_gray>"
  providers:
    ap:
      value: '{"defense":24,"health":80}'
  options:
    unbreakable: true
    glow: true
  actions:
    triggers:
      equip:
        trigger:
          atom: equip
        refs:
          - handler: qi:title
            payload: "<aqua>✦ 守护启动 ✦</aqua>||<gray>圣光环绕周身</gray>||5||30||10"
          - handler: qi:sound
            payload: "minecraft:block.beacon.activate;1;1"

• equip 触发器 → qi:title + 信标激活音效 处理器。

demo_titan_aegis

泰坦壁垒：穿/脱双触发 + 等级限制 + 获得即绑定。

demo_titan_aegis:
  type: chestplate
  material: netherite_chestplate
  display_name: "<gold>泰坦壁垒</gold>"
  item_name: "泰坦壁垒"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>穿上即化身不破壁垒</gray>"
    - "<dark_gray>需要 20 级 · 获得即绑定</dark_gray>"
  providers:
    ap:
      value: '{"defense":32,"health":120}'
  options:
    unbreakable: true
    glow: true
    bind_on_acquire: true
    restrictions:
      - "level:20"
  actions:
    triggers:
      equip:
        trigger:
          atom: equip
        refs:
          - handler: qi:bossbar
            payload: "<gold>泰坦壁垒 · 护体</gold>;1;YELLOW;PROGRESS_6;60"
          - handler: qi:action_bar
            payload: "<gold>不破之躯…</gold>"
      unequip:
        trigger:
          atom: unequip
        refs:
          - handler: qi:action_bar
            payload: "<gray>壁垒卸下，注意防护</gray>"

• bind_on_acquire: true 获得即 灵魂绑定；restrictions: level:20 限制 20 级使用。equip 用 qi:bossbar（格式 文本;进度;颜色;样式;时长tick），unequip 提示卸下（触发器 · 处理器）。

---

护腿 leggings.yml

腿部护甲。被动护甲，主要靠 equip / unequip 做穿脱反馈。

demo_iron_greaves

最简护腿：外观 + 防御属性。

demo_iron_greaves:
  type: leggings
  material: iron_leggings
  display_name: "<white>铁制护腿</white>"
  item_name: "铁制护腿"
  lore:
    - ""
    - "<gray>护住双腿的标准护具</gray>"
  providers:
    ap:
      value: '{"defense":6}'
  options:
    unbreakable: true

• 入门基线（属性与数值）。

demo_storm_greaves

稀有护腿：发光 + 高防。

demo_storm_greaves:
  type: leggings
  material: diamond_leggings
  display_name: "<blue>疾风护腿</blue>"
  item_name: "疾风护腿"
  tier: RARE
  lore:
    - ""
    - "<gray>轻盈如风的护腿</gray>"
  providers:
    ap:
      value: '{"defense":12}'
  options:
    unbreakable: true
    glow: true

• tier: RARE + glow（品质与显示）。

demo_guardian_greaves

守护护腿：史诗品质，穿上唤醒守护之力（equip 触发 title + 音效）。

demo_guardian_greaves:
  type: leggings
  material: netherite_leggings
  display_name: "<gold>守护护腿</gold>"
  item_name: "守护护腿"
  tier: EPIC
  lore:
    - ""
    - "<gray>穿戴时唤醒守护之力</gray>"
    - "<dark_gray>装备触发</dark_gray>"
  providers:
    ap:
      value: '{"defense":20}'
  options:
    unbreakable: true
    glow: true
  actions:
    triggers:
      equip:
        trigger:
          atom: equip
        refs:
          - handler: qi:title
            payload: "<gold>✦ 守护 ✦</gold>||<gray>护腿已就位</gray>||3||30||10"
          - handler: qi:sound
            payload: "minecraft:item.armor.equip_netherite;1;1"

• equip 触发器 → qi:title + 装备音效 处理器。

demo_warden_greaves

监守者护腿：穿提示 / 脱提示双触发 + 等级限制 + 获得即绑定。

demo_warden_greaves:
  type: leggings
  material: netherite_leggings
  display_name: "<dark_aqua>监守者护腿</dark_aqua>"
  item_name: "监守者护腿"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>穿戴时令双腿如磐石</gray>"
    - "<dark_gray>需要 20 级 · 获得即绑定</dark_gray>"
  providers:
    ap:
      value: '{"defense":28}'
  options:
    unbreakable: true
    glow: true
    bind_on_acquire: true
    restrictions:
      - "level:20"
  actions:
    triggers:
      equip:
        trigger:
          atom: equip
        refs:
          - handler: qi:action_bar
            payload: "<dark_aqua>监守者之力环绕双腿…</dark_aqua>"
          - handler: qi:sound
            payload: "minecraft:item.armor.equip_netherite;0.8;1"
      unequip:
        trigger:
          atom: unequip
        refs:
          - handler: qi:action_bar
            payload: "<gray>守护已撤去</gray>"

• bind_on_acquire 灵魂绑定 + restrictions: level:20，equip / unequip 双 触发器 各发 qi:action_bar（处理器）。

---

靴子 boots.yml

脚部护甲。穿在脚上，左键 / 命中类原子一般用不到，主用 equip / unequip。

demo_iron_treads

最简靴子：外观 + 防御属性。

demo_iron_treads:
  type: boots
  material: iron_boots
  display_name: "<white>铁制战靴</white>"
  item_name: "铁制战靴"
  lore:
    - ""
    - "<gray>稳健踏实的战靴</gray>"
  providers:
    ap:
      value: '{"defense":4}'
  options:
    unbreakable: true

• 入门基线（属性与数值）。

demo_swift_treads

稀有靴子：发光 + 移速属性。

demo_swift_treads:
  type: boots
  material: diamond_boots
  display_name: "<green>疾行战靴</green>"
  item_name: "疾行战靴"
  tier: RARE
  lore:
    - ""
    - "<gray>令步伐更加迅捷</gray>"
  providers:
    ap:
      value: '{"defense":8,"movement_speed":0.05}'
  options:
    unbreakable: true
    glow: true

• 引入 movement_speed 移速属性（属性与数值），tier: RARE + glow。

demo_gale_striders

疾风之靴：史诗品质，穿上脚步生风（equip）+ 卸下提示（unequip）。

demo_gale_striders:
  type: boots
  material: golden_boots
  display_name: "<aqua>疾风之靴</aqua>"
  item_name: "疾风之靴"
  tier: EPIC
  lore:
    - ""
    - "<gray>穿上时脚步生风</gray>"
    - "<dark_gray>装备 / 卸下均有反馈</dark_gray>"
  providers:
    ap:
      value: '{"defense":10,"movement_speed":0.08}'
  options:
    unbreakable: true
    glow: true
  actions:
    triggers:
      equip:
        trigger:
          atom: equip
        refs:
          - handler: qi:action_bar
            payload: "<aqua>疾风环绕，脚步生风…</aqua>"
          - handler: qi:sound
            payload: "minecraft:entity.player.levelup;0.6;1.5"
      unequip:
        trigger:
          atom: unequip
        refs:
          - handler: qi:action_bar
            payload: "<gray>风势散去，步伐归于平常</gray>"

• equip / unequip 双 触发器 各发 qi:action_bar，equip 附音效（处理器）。

demo_stormrunner_boots

逐风者战靴：传说品质，装备触发 + 等级限制 + 获得即绑定。

demo_stormrunner_boots:
  type: boots
  material: netherite_boots
  display_name: "<dark_purple>逐风者战靴</dark_purple>"
  item_name: "逐风者战靴"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>装备时召来奔涌的劲风</gray>"
    - "<dark_gray>需要 20 级 · 获得即绑定</dark_gray>"
  providers:
    ap:
      value: '{"defense":16,"movement_speed":0.12}'
  options:
    unbreakable: true
    glow: true
    bind_on_acquire: true
    restrictions:
      - "level:20"
  actions:
    triggers:
      equip:
        trigger:
          atom: equip
        refs:
          - handler: qi:title
            payload: "<dark_purple>逐风者</dark_purple>||<gray>劲风奔涌</gray>||3||30||10"
          - handler: qi:sound
            payload: "minecraft:entity.ender_dragon.flap;0.8;1"

• 最高移速 0.12，bind_on_acquire 灵魂绑定 + restrictions: level:20，equip 触发器 发 qi:title + 龙翼振翅音效（处理器）。

---

弓 bow.yml

远程射击。right_click 拉弓不一定触发，远程提示一般用 left_click + on_hit。

demo_hunter_bow

最简弓：外观 + 攻击属性。

demo_hunter_bow:
  type: bow
  material: bow
  display_name: "<white>猎手长弓</white>"
  item_name: "猎手长弓"
  lore:
    - ""
    - "<gray>猎人惯用的长弓</gray>"
  providers:
    ap:
      value: '{"attack_damage":6}'
  options:
    unbreakable: true

• 入门基线，attack_damage:6（属性与数值）。

demo_gale_bow

稀有弓：发光 + 高攻。

demo_gale_bow:
  type: bow
  material: bow
  display_name: "<aqua>疾风之弓</aqua>"
  item_name: "疾风之弓"
  tier: RARE
  lore:
    - ""
    - "<gray>箭如疾风，一往无前</gray>"
  providers:
    ap:
      value: '{"attack_damage":12}'
  options:
    unbreakable: true
    glow: true

• tier: RARE + glow（品质与显示）。

demo_starfall_bow

星辰猎弓：史诗品质，左键聚气瞄准（left_click + 冷却 2s）。引入 crit_rate 暴击率。

demo_starfall_bow:
  type: bow
  material: bow
  display_name: "<gold>星辰猎弓</gold>"
  item_name: "星辰猎弓"
  tier: EPIC
  lore:
    - ""
    - "<gray>左键聚气，凝神瞄准</gray>"
    - "<dark_gray>冷却 2 秒</dark_gray>"
  providers:
    ap:
      value: '{"attack_damage":18,"crit_rate":0.1}'
  options:
    unbreakable: true
    glow: true
  actions:
    triggers:
      left_click:
        trigger:
          atom: left_click
        cooldown: 2s
        refs:
          - handler: qi:action_bar
            payload: "<gold>◎ 凝神瞄准…</gold>"
          - handler: qi:sound
            payload: "minecraft:item.crossbow.loading_start;1;1.3"

• left_click 触发器（最可靠的手势）+ cooldown: 2s，crit_rate 暴击率属性（属性与数值）。

demo_piercing_longbow

贯穿长弓：传说品质，箭矢命中撕裂目标（on_hit）+ 等级限制 + 获得即绑定。

demo_piercing_longbow:
  type: bow
  material: bow
  display_name: "<dark_purple>贯穿长弓</dark_purple>"
  item_name: "贯穿长弓"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>箭矢命中时撕裂目标</gray>"
    - "<dark_gray>需要 20 级 · 获得即绑定</dark_gray>"
  providers:
    ap:
      value: '{"attack_damage":26,"crit_rate":0.18}'
  options:
    unbreakable: true
    glow: true
    bind_on_acquire: true
    restrictions:
      - "level:20"
  actions:
    triggers:
      on_hit:
        trigger:
          atom: on_hit
        refs:
          - handler: qi:sound
            payload: "minecraft:entity.arrow.hit_player;0.8;1"
          - handler: qi:action_bar
            payload: "<dark_purple>箭矢贯体！</dark_purple>"

• on_hit 触发器（箭矢命中实体时），bind_on_acquire 灵魂绑定 + restrictions: level:20。

---

弩 crossbow.yml

远程射击。right_click 对空气不一定触发，一般用 left_click 配合 on_hit。

demo_siege_crossbow

最简弩：外观 + 攻击属性。

demo_siege_crossbow:
  type: crossbow
  material: crossbow
  display_name: "<white>攻城之弩</white>"
  item_name: "攻城之弩"
  lore:
    - ""
    - "<gray>威力惊人的重型弩</gray>"
  providers:
    ap:
      value: '{"attack_damage":10}'
  options:
    unbreakable: true

• 入门基线（属性与数值）。

demo_repeater_crossbow

稀有弩：发光 + 更高攻击。

demo_repeater_crossbow:
  type: crossbow
  material: crossbow
  display_name: "<gold>连发劲弩</gold>"
  item_name: "连发劲弩"
  tier: RARE
  lore:
    - ""
    - "<gray>射速更快的精巧劲弩</gray>"
  providers:
    ap:
      value: '{"attack_damage":14}'
  options:
    unbreakable: true
    glow: true

• tier: RARE + glow（品质与显示）。

demo_aiming_crossbow

鹰眼瞄准弩：史诗品质，左键挥动进入瞄准（left_click + 冷却 2s）。

demo_aiming_crossbow:
  type: crossbow
  material: crossbow
  display_name: "<yellow>鹰眼瞄准弩</yellow>"
  item_name: "鹰眼瞄准弩"
  tier: EPIC
  lore:
    - ""
    - "<gray>左键挥动，凝神瞄准</gray>"
    - "<dark_gray>冷却 2 秒</dark_gray>"
  providers:
    ap:
      value: '{"attack_damage":18,"crit_rate":0.1}'
  options:
    unbreakable: true
    glow: true
  actions:
    triggers:
      left_click:
        trigger:
          atom: left_click
        cooldown: 2s
        refs:
          - handler: qi:action_bar
            payload: "<yellow>◎ 凝神瞄准…</yellow>"
          - handler: qi:sound
            payload: "minecraft:item.crossbow.loading_middle;1;1.2"

• left_click 触发器 + cooldown: 2s，含 crit_rate（属性与数值）。

demo_piercing_crossbow

洞穿强弩：传说品质，弩矢命中洞穿（on_hit）+ 等级限制 + 获得即绑定。

demo_piercing_crossbow:
  type: crossbow
  material: crossbow
  display_name: "<dark_aqua>洞穿强弩</dark_aqua>"
  item_name: "洞穿强弩"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>弩矢命中时洞穿敌人</gray>"
    - "<dark_gray>需要 20 级 · 获得即绑定</dark_gray>"
  providers:
    ap:
      value: '{"attack_damage":24,"crit_rate":0.18}'
  options:
    unbreakable: true
    glow: true
    bind_on_acquire: true
    restrictions:
      - "level:20"
  actions:
    triggers:
      on_hit:
        trigger:
          atom: on_hit
        refs:
          - handler: qi:sound
            payload: "minecraft:item.crossbow.hit;0.8;1"
          - handler: qi:action_bar
            payload: "<dark_aqua>洞穿！</dark_aqua>"

• on_hit 触发器，bind_on_acquire 灵魂绑定 + restrictions: level:20。

---

三叉戟 trident.yml

投掷 / 近战。right_click 对空气不一定触发，一般用 left_click / on_hit。

demo_tide_trident

最简三叉戟：外观 + 攻击属性。

demo_tide_trident:
  type: trident
  material: trident
  display_name: "<aqua>潮汐三叉戟</aqua>"
  item_name: "潮汐三叉戟"
  lore:
    - ""
    - "<gray>蕴含海潮之力</gray>"
  providers:
    ap:
      value: '{"attack_damage":12}'
  options:
    unbreakable: true

• 入门基线（属性与数值）。

demo_storm_trident

史诗三叉戟：发光 + 高配属性。

demo_storm_trident:
  type: trident
  material: trident
  display_name: "<blue>风暴三叉戟</blue>"
  item_name: "风暴三叉戟"
  tier: EPIC
  lore:
    - ""
    - "<gray>召唤雷暴的传说之戟</gray>"
  providers:
    ap:
      value: '{"attack_damage":20}'
  options:
    unbreakable: true
    glow: true

• tier: EPIC + glow（品质与显示）。

demo_surge_trident

怒涛投枪：稀有品质，左键挥动激荡水波（left_click + 冷却 3s）。

demo_surge_trident:
  type: trident
  material: trident
  display_name: "<dark_aqua>怒涛投枪</dark_aqua>"
  item_name: "怒涛投枪"
  tier: RARE
  lore:
    - ""
    - "<gray>左键挥动，激荡水波</gray>"
    - "<dark_gray>冷却 3 秒</dark_gray>"
  providers:
    ap:
      value: '{"attack_damage":16}'
  options:
    unbreakable: true
    glow: true
  actions:
    triggers:
      left_click:
        trigger:
          atom: left_click
        cooldown: 3s
        refs:
          - handler: qi:title
            payload: "<dark_aqua>怒涛涌动</dark_aqua>||<gray>海潮回应你的呼唤</gray>||3||30||10"
          - handler: qi:sound
            payload: "minecraft:item.trident.riptide_3;1;1"

• left_click 触发器 + cooldown: 3s，qi:title + 激流音效 处理器。

demo_abyss_trident

深渊贯穿之刺：传说品质，命中引动深海寒流（on_hit）+ 等级限制 + 获得即绑定。

demo_abyss_trident:
  type: trident
  material: trident
  display_name: "<blue>深渊贯穿之刺</blue>"
  item_name: "深渊贯穿之刺"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>命中时引动深海寒流</gray>"
    - "<dark_gray>需要 20 级 · 获得即绑定</dark_gray>"
  providers:
    ap:
      value: '{"attack_damage":26}'
  options:
    unbreakable: true
    glow: true
    bind_on_acquire: true
    restrictions:
      - "level:20"
  actions:
    triggers:
      on_hit:
        trigger:
          atom: on_hit
        refs:
          - handler: qi:sound
            payload: "minecraft:item.trident.thunder;0.7;1"
          - handler: qi:action_bar
            payload: "<blue>深渊寒流贯体而过…</blue>"

• on_hit 触发器，bind_on_acquire 灵魂绑定 + restrictions: level:20。

---

弹药 projectile.yml

箭矢类。箭多为外观 + 少量交互，on_hit 命中触发是本类型主战场。注意箭类用 max_stack_size 而非 unbreakable。

🖼️ [图片占位] 三种弹药材质对比（arrow / spectral_arrow / tipped_arrow）　·　建议 assets/projectile-types.png

demo_keen_arrow

最简箭矢：纯外观基线，无属性，max_stack_size: 64。

demo_keen_arrow:
  type: projectile
  material: arrow
  display_name: "<white>锐利之箭</white>"
  item_name: "锐利之箭"
  lore:
    - ""
    - "<gray>削得格外锋利的箭矢</gray>"
  options:
    max_stack_size: 64

• 仅有 max_stack_size: 64，无 providers、无 tier（默认 COMMON）。

demo_spectral_bolt

发光箭矢：外观基线，glow + 堆叠 64。

demo_spectral_bolt:
  type: projectile
  material: spectral_arrow
  display_name: "<yellow>幽光之箭</yellow>"
  item_name: "幽光之箭"
  lore:
    - ""
    - "<gray>命中后散发幽光</gray>"
  options:
    glow: true
    max_stack_size: 64

• material: spectral_arrow + glow（品质与显示）。

demo_thunder_arrow

雷鸣之箭：稀有品质，命中炸响惊雷（on_hit + 冷却 2s）。

demo_thunder_arrow:
  type: projectile
  material: tipped_arrow
  display_name: "<aqua>雷鸣之箭</aqua>"
  item_name: "雷鸣之箭"
  tier: RARE
  lore:
    - ""
    - "<gray>命中目标时炸响一道惊雷</gray>"
    - "<dark_gray>冷却 2 秒</dark_gray>"
  options:
    glow: true
    max_stack_size: 64
  actions:
    triggers:
      on_hit:
        trigger:
          atom: on_hit
        cooldown: 2s
        refs:
          - handler: qi:sound
            payload: "minecraft:entity.lightning_bolt.thunder;0.8;1.4"
          - handler: qi:action_bar
            payload: "<aqua>⚡ 惊雷贯穿目标 ⚡</aqua>"

• on_hit 触发器 + cooldown: 2s，无 providers 仅靠动作表现（处理器）。

demo_soul_piercer

噬魂之箭：史诗品质，命中撕裂魂魄（on_hit）+ 等级限制 15 级，带少量伤害属性。

demo_soul_piercer:
  type: projectile
  material: spectral_arrow
  display_name: "<dark_purple>噬魂之箭</dark_purple>"
  item_name: "噬魂之箭"
  tier: EPIC
  lore:
    - ""
    - "<gray>命中时撕裂目标的魂魄</gray>"
    - "<dark_gray>需要 15 级</dark_gray>"
  providers:
    ap:
      value: '{"attack_damage":6}'
  options:
    glow: true
    max_stack_size: 64
    restrictions:
      - "level:15"
  actions:
    triggers:
      on_hit:
        trigger:
          atom: on_hit
        refs:
          - handler: qi:sound
            payload: "minecraft:entity.vex.charge;0.7;0.8"
          - handler: qi:title
            payload: "<dark_purple>噬魂</dark_purple>||<gray>魂魄被撕裂</gray>||3||25||8"

• 唯一带 providers 的箭（attack_damage:6，属性与数值），restrictions: level:15，on_hit 发 qi:title（触发器 · 处理器）。

---

盾牌 shield.yml

格挡防御。盾牌靠 AP 的 defense 提供格挡减伤，动作多用于氛围 / 提示。right_click 举盾对空气不一定触发，慎用。

demo_oak_bulwark

最简盾牌：外观 + 防御属性。

demo_oak_bulwark:
  type: shield
  material: shield
  display_name: "<white>橡木壁盾</white>"
  item_name: "橡木壁盾"
  lore:
    - ""
    - "<gray>抵御冲击的木制盾牌</gray>"
  providers:
    ap:
      value: '{"defense":10}'
  options:
    unbreakable: true

• 入门基线（属性与数值）。

demo_tower_bulwark

史诗盾牌：发光 + 高防御。

demo_tower_bulwark:
  type: shield
  material: shield
  display_name: "<gold>塔卫巨盾</gold>"
  item_name: "塔卫巨盾"
  tier: EPIC
  lore:
    - ""
    - "<gray>如城墙般坚不可摧</gray>"
  providers:
    ap:
      value: '{"defense":20}'
  options:
    unbreakable: true
    glow: true

• tier: EPIC + glow（品质与显示）。

demo_aegis_guard

守护神盾：稀有品质，上盾时提示 + 金属碰撞声（equip）。

demo_aegis_guard:
  type: shield
  material: shield
  display_name: "<aqua>守护神盾</aqua>"
  item_name: "守护神盾"
  tier: RARE
  lore:
    - ""
    - "<gray>持盾时迸发守护气息</gray>"
    - "<dark_gray>装备时触发</dark_gray>"
  providers:
    ap:
      value: '{"defense":16}'
  options:
    unbreakable: true
    glow: true
  actions:
    triggers:
      equip:
        trigger:
          atom: equip
        refs:
          - handler: qi:action_bar
            payload: "<aqua>🛡 守护已就位</aqua>"
          - handler: qi:sound
            payload: "minecraft:item.shield.block;1;0.8"

• equip 触发器 → qi:action_bar + 盾牌格挡音效 处理器。

demo_bastion_wall

壁垒之墙：传说品质，受击回荡格挡之音（on_damage + 冷却 2s）+ 等级限制 + 获得即绑定。

demo_bastion_wall:
  type: shield
  material: shield
  display_name: "<dark_aqua>壁垒之墙</dark_aqua>"
  item_name: "壁垒之墙"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>承受打击时回荡格挡之音</gray>"
    - "<dark_gray>需要 20 级 · 获得即绑定</dark_gray>"
  providers:
    ap:
      value: '{"defense":30}'
  options:
    unbreakable: true
    glow: true
    bind_on_acquire: true
    restrictions:
      - "level:20"
  actions:
    triggers:
      on_damage:
        trigger:
          atom: on_damage
        cooldown: 2s
        refs:
          - handler: qi:sound
            payload: "minecraft:item.shield.block;0.7;1"
          - handler: qi:action_bar
            payload: "<dark_aqua>壁垒岿然不动…</dark_aqua>"

• 演示 on_damage 受击 触发器 + cooldown: 2s，bind_on_acquire 灵魂绑定 + restrictions: level:20。

---

法杖 wand.yml

施法器。right_click 对空气不一定触发，施法一般用 left_click。法杖一般不写 unbreakable，靠 glow 体现魔力外观。

demo_apprentice_wand

最简法杖：外观 + 攻击属性 + 发光。

demo_apprentice_wand:
  type: wand
  material: blaze_rod
  display_name: "<gold>学徒法杖</gold>"
  item_name: "学徒法杖"
  lore:
    - ""
    - "<gray>初学者的入门法杖</gray>"
  providers:
    ap:
      value: '{"attack_damage":6}'
  options:
    glow: true

• 入门基线，仅 glow、无 unbreakable（属性与数值）。

demo_archmage_staff

传说法杖：纯外观高配，material: breeze_rod。

demo_archmage_staff:
  type: wand
  material: breeze_rod
  display_name: "<light_purple>大法师之杖</light_purple>"
  item_name: "大法师之杖"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>蕴含磅礴魔力的法杖</gray>"
  providers:
    ap:
      value: '{"attack_damage":16}'
  options:
    glow: true

• tier: LEGENDARY 高配无动作（品质与显示）。

demo_flame_wand

烈焰法杖：稀有品质，左键吟唱烈焰术（left_click + 冷却 3s + title + 音效 + bossbar 完整施法表现）。

demo_flame_wand:
  type: wand
  material: blaze_rod
  display_name: "<red>烈焰法杖</red>"
  item_name: "烈焰法杖"
  tier: RARE
  lore:
    - ""
    - "<gray>左键挥动，吟唱烈焰术</gray>"
    - "<dark_gray>冷却 3 秒</dark_gray>"
  providers:
    ap:
      value: '{"attack_damage":12}'
  options:
    glow: true
  actions:
    triggers:
      left_click:
        trigger:
          atom: left_click
        cooldown: 3s
        refs:
          - handler: qi:title
            payload: "<red>烈焰术</red>||<gold>火焰升腾</gold>||3||30||10"
          - handler: qi:sound
            payload: "minecraft:entity.blaze.shoot;1;1"
          - handler: qi:bossbar
            payload: "<gold>施法中…</gold>;1;YELLOW;PROGRESS_6;40"

• 三段 处理器 串联：qi:title + qi:sound + qi:bossbar，left_click 触发器 + cooldown: 3s。

demo_arcane_wand

秘法法杖：史诗品质，左键释放秘法脉冲，每次消耗 1 颗红石（left_click + consume + 冷却 + 等级限制）。

demo_arcane_wand:
  type: wand
  material: stick
  display_name: "<aqua>秘法法杖</aqua>"
  item_name: "秘法法杖"
  tier: EPIC
  lore:
    - ""
    - "<gray>左键释放秘法脉冲</gray>"
    - "<dark_gray>每次消耗 1 颗红石 · 冷却 2 秒</dark_gray>"
    - "<dark_gray>需要 15 级</dark_gray>"
  providers:
    ap:
      value: '{"attack_damage":14}'
  options:
    glow: true
    restrictions:
      - "level:15"
  actions:
    triggers:
      left_click:
        trigger:
          atom: left_click
        cooldown: 2s
        consume:
          - "item:redstone:1"
        refs:
          - handler: qi:subtitle
            payload: "<aqua>秘法脉冲迸发</aqua>"
          - handler: qi:sound
            payload: "minecraft:block.amethyst_block.chime;1;1.4"
          - handler: qi:action_bar
            payload: "<aqua>魔力涌动…</aqua>"

• 唯一演示 consume（item:redstone:1 释放时消耗 1 颗红石作法力石）的装备，配 cooldown: 2s + restrictions: level:15，含 qi:subtitle 处理器（触发器）。

---

马铠 horse_armor.yml

坐骑护甲，外观为主。披甲 / 卸甲提示首选 equip / unequip，也可用 left_click 做擦拭 / 检视。

demo_iron_barding

最简马铠：外观 + 防御属性，无 options。

demo_iron_barding:
  type: horse_armor
  material: iron_horse_armor
  display_name: "<white>铁制马铠</white>"
  item_name: "铁制马铠"
  lore:
    - ""
    - "<gray>保护坐骑的铁甲</gray>"
  providers:
    ap:
      value: '{"defense":10}'

• 入门基线，连 options 块都没有（属性与数值）。

demo_diamond_barding

稀有马铠：发光 + 高防御。

demo_diamond_barding:
  type: horse_armor
  material: diamond_horse_armor
  display_name: "<aqua>钻石马铠</aqua>"
  item_name: "钻石马铠"
  tier: RARE
  lore:
    - ""
    - "<gray>坚固华丽的坐骑护甲</gray>"
  providers:
    ap:
      value: '{"defense":20}'
  options:
    glow: true

• tier: RARE + glow（品质与显示）。

demo_golden_barding

黄金战甲：史诗品质，为坐骑披甲时号角长鸣（equip）+ 卸下提示（unequip）。

demo_golden_barding:
  type: horse_armor
  material: golden_horse_armor
  display_name: "<gold>黄金战甲</gold>"
  item_name: "黄金战甲"
  tier: EPIC
  lore:
    - ""
    - "<gray>为坐骑披甲时号角长鸣</gray>"
  providers:
    ap:
      value: '{"defense":16}'
  options:
    glow: true
  actions:
    triggers:
      equip:
        trigger:
          atom: equip
        refs:
          - handler: qi:action_bar
            payload: "<gold>战甲已披挂 —— 坐骑全副武装</gold>"
          - handler: qi:sound
            payload: "minecraft:item.armor.equip_gold;1;1"
      unequip:
        trigger:
          atom: unequip
        refs:
          - handler: qi:action_bar
            payload: "<gray>战甲已卸下</gray>"

• equip / unequip 双 触发器 演示披甲 / 卸甲提示（处理器）。

demo_dragonhide_barding

龙鳞战铠：传说品质，左键擦拭（left_click + 冷却 3s）+ 装备号角（equip），获得即绑定。引入 max_health 属性。

demo_dragonhide_barding:
  type: horse_armor
  material: diamond_horse_armor
  display_name: "<dark_purple>龙鳞战铠</dark_purple>"
  item_name: "龙鳞战铠"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>以龙鳞锻造，刀枪难入</gray>"
    - "<dark_gray>左键擦拭可令鳞片重焕光泽</dark_gray>"
  providers:
    ap:
      value: '{"defense":30,"max_health":10}'
  options:
    unbreakable: true
    glow: true
    bind_on_acquire: true
  actions:
    triggers:
      left_click:
        trigger:
          atom: left_click
        cooldown: 3s
        refs:
          - handler: qi:action_bar
            payload: "<dark_purple>你擦拭龙鳞，鳞片泛起寒光</dark_purple>"
          - handler: qi:sound
            payload: "minecraft:block.beacon.activate;0.6;1.4"
      equip:
        trigger:
          atom: equip
        refs:
          - handler: qi:title
            payload: "<dark_purple>龙鳞战铠</dark_purple>||<gray>坐骑已被神龙之力护佑</gray>||10||40||10"
          - handler: qi:sound
            payload: "minecraft:entity.ender_dragon.growl;0.8;1"

• 双 触发器：left_click（擦拭，带 cooldown: 3s）+ equip（披甲号角）。max_health 属性（[属性与数值](属性与数值.md）），bind_on_acquire 获得即 灵魂绑定（此处不配 restrictions）。

---

下一步

• 示例-饰品消耗篇——饰品、消耗品、料理等类型示例
• 示例-杂项篇——工具、方块、杂项类型示例
• 物品示例库总览——返回示例库目录