Example Library · Equipment

Belongs to: Server Admin Guide → Item Example Library · Equipment　·　Related: Item Types · Attributes & Values · Action System

This page walks through QI's built-in equipment example items one by one. Each file's name (e.g. armor) is the item type, and each top-level key is an item ID. After editing any yml you must run /qi reload for it to take effect—actions are only loaded on reload / restart.

Values are applied by providers.ap.value (a chunk of attribute JSON) through AttributePlus; QI itself does not bundle values. See Attributes & Values for details.

🖼️ [Image placeholder] Equipment chapter example items overview (armor / weapons / shields / staves display)　·　suggested assets/equipment-gallery.png

---

Armor armor.yml

General / chestplate armor. Worn items, focusing on equip / unequip feedback; swing-type atoms are generally not used.

demo_guard_plate

Simplest armor: appearance + defensive attributes only, no actions.

demo_guard_plate:
  type: armor
  material: iron_chestplate
  display_name: "<white>Guardian Plate</white>"
  item_name: "Guardian Plate"
  lore:
    - ""
    - "<gray>Sturdy and durable standard armor</gray>"
  providers:
    ap:
      value: '{"defense":8,"health":40}'
  options:
    unbreakable: true

• Entry-level baseline: providers.ap.value provides defense / health (Attributes & Values), unbreakable prevents durability loss. With no tier, it defaults to COMMON (Quality & Display).

demo_aegis_plate

Epic armor: glow + high defense + large health.

demo_aegis_plate:
  type: armor
  material: diamond_chestplate
  display_name: "<aqua>Aegis Armor</aqua>"
  item_name: "Aegis Armor"
  tier: EPIC
  lore:
    - ""
    - "<gray>Armor imbued with the power of protection</gray>"
  providers:
    ap:
      value: '{"defense":16,"health":100}'
  options:
    unbreakable: true
    glow: true

• tier: EPIC combined with glow: true forms an epic appearance (Quality & Display).

demo_dragonscale_plate

Dragonscale chestplate: legendary quality, awakens the dragon soul when worn (equip triggers a prompt + sound effect).

demo_dragonscale_plate:
  type: armor
  material: diamond_chestplate
  display_name: "<gold>Dragonscale Chestplate</gold>"
  item_name: "Dragonscale Chestplate"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>Forged from ancient dragon scales, it guards and empowers</gray>"
    - "<dark_gray>Awakens the dragon soul when worn</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>Dragon Soul Awakened · Empowered Defense</gold>"
          - handler: qi:sound
            payload: "minecraft:entity.player.levelup;1;1"

• The first armor with actions: the equip trigger drives the qi:action_bar + qi:sound handlers; the sound format in payload is sound key;volume;pitch.

---

Helmet helmet.yml

Head armor. Helmets are worn on the head, mainly sensing equip/unequip via equip / unequip.

demo_iron_helm

Simplest helmet: appearance + defensive attributes.

demo_iron_helm:
  type: helmet
  material: iron_helmet
  display_name: "<white>Iron Helmet</white>"
  item_name: "Iron Helmet"
  lore:
    - ""
    - "<gray>Basic gear protecting the head</gray>"
  providers:
    ap:
      value: '{"defense":4}'
  options:
    unbreakable: true

• Entry-level baseline, only defense:4 (Attributes & Values).

demo_crystal_helm

Rare helmet: glow + defense / health attributes.

demo_crystal_helm:
  type: helmet
  material: diamond_helmet
  display_name: "<aqua>Crystal Crown</aqua>"
  item_name: "Crystal Crown"
  tier: RARE
  lore:
    - ""
    - "<gray>A crystal crown that refracts light</gray>"
  providers:
    ap:
      value: '{"defense":8,"health":20}'
  options:
    unbreakable: true
    glow: true

• tier: RARE + glow (Quality & Display).

demo_sentinel_helm

Sentinel helmet: epic quality, shows a prompt and plays a horn when worn (equip trigger).

demo_sentinel_helm:
  type: helmet
  material: netherite_helmet
  display_name: "<gold>Sentinel Helmet</gold>"
  item_name: "Sentinel Helmet"
  tier: EPIC
  lore:
    - ""
    - "<gray>When worn, your vision sharpens</gray>"
    - "<dark_gray>Triggers on equip</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>The Sentinel's Eye is open</gold>"
          - handler: qi:sound
            payload: "minecraft:item.armor.equip_netherite;1;1"

• equip trigger → qi:action_bar + qi:sound (netherite equip sound effect) handlers.

demo_royal_crown

Golden crown: legendary quality, coronation when worn (equip + 2s cooldown), curtain-fall when removed (unequip), dual triggers.

demo_royal_crown:
  type: helmet
  material: golden_helmet
  display_name: "<yellow>Golden Crown</yellow>"
  item_name: "Golden Crown"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>Crowned when worn, dethroned when removed</gray>"
    - "<dark_gray>Equip / unequip each have a prompt</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>👑 Coronation 👑</yellow>||<gray>The king returns</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>You removed the Golden Crown.</gray>"

• Demonstrates multiple triggers on one item: equip has cooldown: 2s and uses qi:title (format title||subtitle||fade-in||stay||fade-out); unequip uses qi:message (trigger · handler).

---

Chestplate chestplate.yml

Chest armor. Worn on the body, it does not respond to clicks; triggers are mainly equip / unequip / on_damage.

demo_iron_cuirass

Simplest chestplate: appearance + defensive attributes.

demo_iron_cuirass:
  type: chestplate
  material: iron_chestplate
  display_name: "<white>Iron Cuirass</white>"
  item_name: "Iron Cuirass"
  lore:
    - ""
    - "<gray>A thick cuirass guarding the vitals</gray>"
  providers:
    ap:
      value: '{"defense":8}'
  options:
    unbreakable: true

• Entry-level baseline (Attributes & Values).

demo_dragon_cuirass

Epic chestplate: glow + high defense + health.

demo_dragon_cuirass:
  type: chestplate
  material: diamond_chestplate
  display_name: "<red>Dragonscale Cuirass</red>"
  item_name: "Dragonscale Cuirass"
  tier: EPIC
  lore:
    - ""
    - "<gray>Armor forged from dragon scales</gray>"
  providers:
    ap:
      value: '{"defense":16,"health":60}'
  options:
    unbreakable: true
    glow: true

• tier: EPIC + glow (Quality & Display).

demo_guardian_plate

Guardian chestplate: legendary quality, holy light surrounds you when worn (equip triggers title + beacon sound).

demo_guardian_plate:
  type: chestplate
  material: netherite_chestplate
  display_name: "<aqua>Guardian Chestplate</aqua>"
  item_name: "Guardian Chestplate"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>Holy light surrounds your body when worn</gray>"
    - "<dark_gray>Triggers on equip</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>✦ Guardian Activated ✦</aqua>||<gray>Holy light surrounds your body</gray>||5||30||10"
          - handler: qi:sound
            payload: "minecraft:block.beacon.activate;1;1"

• equip trigger → qi:title + beacon activation sound handlers.

demo_titan_aegis

Titan Bulwark: dual equip/unequip triggers + level restriction + bind on acquire.

demo_titan_aegis:
  type: chestplate
  material: netherite_chestplate
  display_name: "<gold>Titan Bulwark</gold>"
  item_name: "Titan Bulwark"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>Don it and become an unbreakable bulwark</gray>"
    - "<dark_gray>Requires level 20 · Binds on acquire</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>Titan Bulwark · Protected</gold>;1;YELLOW;PROGRESS_6;60"
          - handler: qi:action_bar
            payload: "<gold>Unbreakable form…</gold>"
      unequip:
        trigger:
          atom: unequip
        refs:
          - handler: qi:action_bar
            payload: "<gray>Bulwark removed, mind your protection</gray>"

• bind_on_acquire: true Soul Binds on acquire; restrictions: level:20 restricts use to level 20. equip uses qi:bossbar (format text;progress;color;style;duration in ticks), and unequip prompts removal (trigger · handler).

---

Leggings leggings.yml

Leg armor. Passive armor, mainly using equip / unequip for equip/unequip feedback.

demo_iron_greaves

Simplest leggings: appearance + defensive attributes.

demo_iron_greaves:
  type: leggings
  material: iron_leggings
  display_name: "<white>Iron Greaves</white>"
  item_name: "Iron Greaves"
  lore:
    - ""
    - "<gray>Standard guards protecting the legs</gray>"
  providers:
    ap:
      value: '{"defense":6}'
  options:
    unbreakable: true

• Entry-level baseline (Attributes & Values).

demo_storm_greaves

Rare leggings: glow + high defense.

demo_storm_greaves:
  type: leggings
  material: diamond_leggings
  display_name: "<blue>Gale Greaves</blue>"
  item_name: "Gale Greaves"
  tier: RARE
  lore:
    - ""
    - "<gray>Greaves as light as the wind</gray>"
  providers:
    ap:
      value: '{"defense":12}'
  options:
    unbreakable: true
    glow: true

• tier: RARE + glow (Quality & Display).

demo_guardian_greaves

Guardian greaves: epic quality, awakens guardian power when worn (equip triggers title + sound).

demo_guardian_greaves:
  type: leggings
  material: netherite_leggings
  display_name: "<gold>Guardian Greaves</gold>"
  item_name: "Guardian Greaves"
  tier: EPIC
  lore:
    - ""
    - "<gray>Awakens guardian power when worn</gray>"
    - "<dark_gray>Triggers on equip</dark_gray>"
  providers:
    ap:
      value: '{"defense":20}'
  options:
    unbreakable: true
    glow: true
  actions:
    triggers:
      equip:
        trigger:
          atom: equip
        refs:
          - handler: qi:title
            payload: "<gold>✦ Guardian ✦</gold>||<gray>Greaves in place</gray>||3||30||10"
          - handler: qi:sound
            payload: "minecraft:item.armor.equip_netherite;1;1"

• equip trigger → qi:title + equip sound handlers.

demo_warden_greaves

Warden greaves: dual equip-prompt / unequip-prompt triggers + level restriction + bind on acquire.

demo_warden_greaves:
  type: leggings
  material: netherite_leggings
  display_name: "<dark_aqua>Warden Greaves</dark_aqua>"
  item_name: "Warden Greaves"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>When worn, your legs become like solid rock</gray>"
    - "<dark_gray>Requires level 20 · Binds on acquire</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>Warden's power surrounds your legs…</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>Protection withdrawn</gray>"

• bind_on_acquire Soul Bind + restrictions: level:20; equip / unequip dual triggers each fire qi:action_bar (handler).

---

Boots boots.yml

Foot armor. Worn on the feet, left-click / hit-type atoms are generally not used; mainly uses equip / unequip.

demo_iron_treads

Simplest boots: appearance + defensive attributes.

demo_iron_treads:
  type: boots
  material: iron_boots
  display_name: "<white>Iron Treads</white>"
  item_name: "Iron Treads"
  lore:
    - ""
    - "<gray>Steady, solid war boots</gray>"
  providers:
    ap:
      value: '{"defense":4}'
  options:
    unbreakable: true

• Entry-level baseline (Attributes & Values).

demo_swift_treads

Rare boots: glow + movement speed attribute.

demo_swift_treads:
  type: boots
  material: diamond_boots
  display_name: "<green>Swift Treads</green>"
  item_name: "Swift Treads"
  tier: RARE
  lore:
    - ""
    - "<gray>Makes your stride swifter</gray>"
  providers:
    ap:
      value: '{"defense":8,"movement_speed":0.05}'
  options:
    unbreakable: true
    glow: true

• Introduces the movement_speed attribute (Attributes & Values), tier: RARE + glow.

demo_gale_striders

Gale Striders: epic quality, wind at your feet when worn (equip) + unequip prompt (unequip).

demo_gale_striders:
  type: boots
  material: golden_boots
  display_name: "<aqua>Gale Striders</aqua>"
  item_name: "Gale Striders"
  tier: EPIC
  lore:
    - ""
    - "<gray>Wind rises at your feet when worn</gray>"
    - "<dark_gray>Both equip / unequip give feedback</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>Gale surrounds you, wind at your feet…</aqua>"
          - handler: qi:sound
            payload: "minecraft:entity.player.levelup;0.6;1.5"
      unequip:
        trigger:
          atom: unequip
        refs:
          - handler: qi:action_bar
            payload: "<gray>The wind dies down, your stride returns to normal</gray>"

• equip / unequip dual triggers each fire qi:action_bar, with equip adding a sound effect (handlers).

demo_stormrunner_boots

Stormrunner Boots: legendary quality, equip trigger + level restriction + bind on acquire.

demo_stormrunner_boots:
  type: boots
  material: netherite_boots
  display_name: "<dark_purple>Stormrunner Boots</dark_purple>"
  item_name: "Stormrunner Boots"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>Summons surging winds when equipped</gray>"
    - "<dark_gray>Requires level 20 · Binds on acquire</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>Stormrunner</dark_purple>||<gray>Surging winds</gray>||3||30||10"
          - handler: qi:sound
            payload: "minecraft:entity.ender_dragon.flap;0.8;1"

• Highest movement speed 0.12, bind_on_acquire Soul Bind + restrictions: level:20; the equip trigger fires qi:title + dragon wing-flap sound (handlers).

---

Bow bow.yml

Ranged shooting. right_click drawing the bow does not always trigger; for ranged prompts generally use left_click + on_hit.

demo_hunter_bow

Simplest bow: appearance + attack attributes.

demo_hunter_bow:
  type: bow
  material: bow
  display_name: "<white>Hunter's Longbow</white>"
  item_name: "Hunter's Longbow"
  lore:
    - ""
    - "<gray>The longbow favored by hunters</gray>"
  providers:
    ap:
      value: '{"attack_damage":6}'
  options:
    unbreakable: true

• Entry-level baseline, attack_damage:6 (Attributes & Values).

demo_gale_bow

Rare bow: glow + high attack.

demo_gale_bow:
  type: bow
  material: bow
  display_name: "<aqua>Gale Bow</aqua>"
  item_name: "Gale Bow"
  tier: RARE
  lore:
    - ""
    - "<gray>Arrows like the wind, ever forward</gray>"
  providers:
    ap:
      value: '{"attack_damage":12}'
  options:
    unbreakable: true
    glow: true

• tier: RARE + glow (Quality & Display).

demo_starfall_bow

Starfall Bow: epic quality, left-click to gather focus and aim (left_click + 2s cooldown). Introduces crit_rate (critical hit rate).

demo_starfall_bow:
  type: bow
  material: bow
  display_name: "<gold>Starfall Bow</gold>"
  item_name: "Starfall Bow"
  tier: EPIC
  lore:
    - ""
    - "<gray>Left-click to gather focus and take aim</gray>"
    - "<dark_gray>Cooldown 2 seconds</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>◎ Taking aim…</gold>"
          - handler: qi:sound
            payload: "minecraft:item.crossbow.loading_start;1;1.3"

• left_click trigger (the most reliable gesture) + cooldown: 2s, with the crit_rate critical hit rate attribute (Attributes & Values).

demo_piercing_longbow

Piercing Longbow: legendary quality, arrows tear through the target on hit (on_hit) + level restriction + bind on acquire.

demo_piercing_longbow:
  type: bow
  material: bow
  display_name: "<dark_purple>Piercing Longbow</dark_purple>"
  item_name: "Piercing Longbow"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>Arrows tear through the target on hit</gray>"
    - "<dark_gray>Requires level 20 · Binds on acquire</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>Arrow pierces through!</dark_purple>"

• on_hit trigger (when the arrow hits an entity), bind_on_acquire Soul Bind + restrictions: level:20.

---

Crossbow crossbow.yml

Ranged shooting. right_click against air does not always trigger; generally use left_click together with on_hit.

demo_siege_crossbow

Simplest crossbow: appearance + attack attributes.

demo_siege_crossbow:
  type: crossbow
  material: crossbow
  display_name: "<white>Siege Crossbow</white>"
  item_name: "Siege Crossbow"
  lore:
    - ""
    - "<gray>A heavy crossbow of astonishing power</gray>"
  providers:
    ap:
      value: '{"attack_damage":10}'
  options:
    unbreakable: true

• Entry-level baseline (Attributes & Values).

demo_repeater_crossbow

Rare crossbow: glow + higher attack.

demo_repeater_crossbow:
  type: crossbow
  material: crossbow
  display_name: "<gold>Repeater Crossbow</gold>"
  item_name: "Repeater Crossbow"
  tier: RARE
  lore:
    - ""
    - "<gray>A finely crafted crossbow with faster fire rate</gray>"
  providers:
    ap:
      value: '{"attack_damage":14}'
  options:
    unbreakable: true
    glow: true

• tier: RARE + glow (Quality & Display).

demo_aiming_crossbow

Eagle-Eye Aiming Crossbow: epic quality, left-click swing to enter aiming (left_click + 2s cooldown).

demo_aiming_crossbow:
  type: crossbow
  material: crossbow
  display_name: "<yellow>Eagle-Eye Crossbow</yellow>"
  item_name: "Eagle-Eye Crossbow"
  tier: EPIC
  lore:
    - ""
    - "<gray>Left-click swing to focus and aim</gray>"
    - "<dark_gray>Cooldown 2 seconds</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>◎ Taking aim…</yellow>"
          - handler: qi:sound
            payload: "minecraft:item.crossbow.loading_middle;1;1.2"

• left_click trigger + cooldown: 2s, includes crit_rate (Attributes & Values).

demo_piercing_crossbow

Penetrating Crossbow: legendary quality, the bolt penetrates on hit (on_hit) + level restriction + bind on acquire.

demo_piercing_crossbow:
  type: crossbow
  material: crossbow
  display_name: "<dark_aqua>Penetrating Crossbow</dark_aqua>"
  item_name: "Penetrating Crossbow"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>The bolt penetrates the enemy on hit</gray>"
    - "<dark_gray>Requires level 20 · Binds on acquire</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>Penetrate!</dark_aqua>"

• on_hit trigger, bind_on_acquire Soul Bind + restrictions: level:20.

---

Trident trident.yml

Throwing / melee. right_click against air does not always trigger; generally use left_click / on_hit.

demo_tide_trident

Simplest trident: appearance + attack attributes.

demo_tide_trident:
  type: trident
  material: trident
  display_name: "<aqua>Tide Trident</aqua>"
  item_name: "Tide Trident"
  lore:
    - ""
    - "<gray>Imbued with the power of the tides</gray>"
  providers:
    ap:
      value: '{"attack_damage":12}'
  options:
    unbreakable: true

• Entry-level baseline (Attributes & Values).

demo_storm_trident

Epic trident: glow + high-end attributes.

demo_storm_trident:
  type: trident
  material: trident
  display_name: "<blue>Storm Trident</blue>"
  item_name: "Storm Trident"
  tier: EPIC
  lore:
    - ""
    - "<gray>A legendary trident that summons thunderstorms</gray>"
  providers:
    ap:
      value: '{"attack_damage":20}'
  options:
    unbreakable: true
    glow: true

• tier: EPIC + glow (Quality & Display).

demo_surge_trident

Surge Javelin: rare quality, left-click swing to stir the waves (left_click + 3s cooldown).

demo_surge_trident:
  type: trident
  material: trident
  display_name: "<dark_aqua>Surge Javelin</dark_aqua>"
  item_name: "Surge Javelin"
  tier: RARE
  lore:
    - ""
    - "<gray>Left-click swing to stir the waves</gray>"
    - "<dark_gray>Cooldown 3 seconds</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>Surge Rises</dark_aqua>||<gray>The tide answers your call</gray>||3||30||10"
          - handler: qi:sound
            payload: "minecraft:item.trident.riptide_3;1;1"

• left_click trigger + cooldown: 3s, qi:title + riptide sound handlers.

demo_abyss_trident

Abyssal Piercing Spike: legendary quality, draws a deep-sea cold current on hit (on_hit) + level restriction + bind on acquire.

demo_abyss_trident:
  type: trident
  material: trident
  display_name: "<blue>Abyssal Piercing Spike</blue>"
  item_name: "Abyssal Piercing Spike"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>Draws a deep-sea cold current on hit</gray>"
    - "<dark_gray>Requires level 20 · Binds on acquire</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>An abyssal cold current pierces through…</blue>"

• on_hit trigger, bind_on_acquire Soul Bind + restrictions: level:20.

---

Projectile projectile.yml

Arrow type. Arrows are mostly appearance + a small amount of interaction; on_hit hit triggering is the main battlefield for this type. Note that arrow types use max_stack_size rather than unbreakable.

🖼️ [Image placeholder] Comparison of three projectile materials (arrow / spectral_arrow / tipped_arrow)　·　suggested assets/projectile-types.png

demo_keen_arrow

Simplest arrow: pure appearance baseline, no attributes, max_stack_size: 64.

demo_keen_arrow:
  type: projectile
  material: arrow
  display_name: "<white>Keen Arrow</white>"
  item_name: "Keen Arrow"
  lore:
    - ""
    - "<gray>An arrow whittled exceptionally sharp</gray>"
  options:
    max_stack_size: 64

• Only has max_stack_size: 64, no providers, no tier (defaults to COMMON).

demo_spectral_bolt

Glowing arrow: appearance baseline, glow + stack 64.

demo_spectral_bolt:
  type: projectile
  material: spectral_arrow
  display_name: "<yellow>Spectral Bolt</yellow>"
  item_name: "Spectral Bolt"
  lore:
    - ""
    - "<gray>Emits a ghostly light after hitting</gray>"
  options:
    glow: true
    max_stack_size: 64

• material: spectral_arrow + glow (Quality & Display).

demo_thunder_arrow

Thunder Arrow: rare quality, cracks with thunder on hit (on_hit + 2s cooldown).

demo_thunder_arrow:
  type: projectile
  material: tipped_arrow
  display_name: "<aqua>Thunder Arrow</aqua>"
  item_name: "Thunder Arrow"
  tier: RARE
  lore:
    - ""
    - "<gray>Cracks with a bolt of thunder when it hits the target</gray>"
    - "<dark_gray>Cooldown 2 seconds</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>⚡ Thunder pierces the target ⚡</aqua>"

• on_hit trigger + cooldown: 2s, no providers, relying solely on action effects (handlers).

demo_soul_piercer

Soul Piercer: epic quality, tears the soul on hit (on_hit) + level restriction 15, carries a small amount of damage attribute.

demo_soul_piercer:
  type: projectile
  material: spectral_arrow
  display_name: "<dark_purple>Soul Piercer</dark_purple>"
  item_name: "Soul Piercer"
  tier: EPIC
  lore:
    - ""
    - "<gray>Tears the target's soul on hit</gray>"
    - "<dark_gray>Requires level 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>Soul Devour</dark_purple>||<gray>The soul is torn</gray>||3||25||8"

• The only arrow with providers (attack_damage:6, Attributes & Values), restrictions: level:15, on_hit fires qi:title (trigger · handler).

---

Shield shield.yml

Blocking defense. Shields provide block damage reduction via AP's defense; actions are mostly used for atmosphere / prompts. right_click raising the shield against air does not always trigger, so use with caution.

demo_oak_bulwark

Simplest shield: appearance + defensive attributes.

demo_oak_bulwark:
  type: shield
  material: shield
  display_name: "<white>Oak Bulwark</white>"
  item_name: "Oak Bulwark"
  lore:
    - ""
    - "<gray>A wooden shield that withstands impacts</gray>"
  providers:
    ap:
      value: '{"defense":10}'
  options:
    unbreakable: true

• Entry-level baseline (Attributes & Values).

demo_tower_bulwark

Epic shield: glow + high defense.

demo_tower_bulwark:
  type: shield
  material: shield
  display_name: "<gold>Tower Bulwark</gold>"
  item_name: "Tower Bulwark"
  tier: EPIC
  lore:
    - ""
    - "<gray>As impregnable as a city wall</gray>"
  providers:
    ap:
      value: '{"defense":20}'
  options:
    unbreakable: true
    glow: true

• tier: EPIC + glow (Quality & Display).

demo_aegis_guard

Aegis Guard: rare quality, prompt + metal clash sound when the shield is raised (equip).

demo_aegis_guard:
  type: shield
  material: shield
  display_name: "<aqua>Aegis Guard</aqua>"
  item_name: "Aegis Guard"
  tier: RARE
  lore:
    - ""
    - "<gray>A guarding aura bursts forth when held</gray>"
    - "<dark_gray>Triggers on equip</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>🛡 Guard in place</aqua>"
          - handler: qi:sound
            payload: "minecraft:item.shield.block;1;0.8"

• equip trigger → qi:action_bar + shield block sound handlers.

demo_bastion_wall

Bastion Wall: legendary quality, echoes the sound of blocking when struck (on_damage + 2s cooldown) + level restriction + bind on acquire.

demo_bastion_wall:
  type: shield
  material: shield
  display_name: "<dark_aqua>Bastion Wall</dark_aqua>"
  item_name: "Bastion Wall"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>Echoes the sound of blocking when taking a blow</gray>"
    - "<dark_gray>Requires level 20 · Binds on acquire</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>The bastion stands unmoved…</dark_aqua>"

• Demonstrates the on_damage when-struck trigger + cooldown: 2s, bind_on_acquire Soul Bind + restrictions: level:20.

---

Wand wand.yml

Casting implement. right_click against air does not always trigger; for casting generally use left_click. Wands usually do not set unbreakable, relying on glow to convey a magical appearance.

demo_apprentice_wand

Simplest wand: appearance + attack attributes + glow.

demo_apprentice_wand:
  type: wand
  material: blaze_rod
  display_name: "<gold>Apprentice Wand</gold>"
  item_name: "Apprentice Wand"
  lore:
    - ""
    - "<gray>An entry-level wand for beginners</gray>"
  providers:
    ap:
      value: '{"attack_damage":6}'
  options:
    glow: true

• Entry-level baseline, only glow, no unbreakable (Attributes & Values).

demo_archmage_staff

Legendary wand: pure appearance, high-end stats, material: breeze_rod.

demo_archmage_staff:
  type: wand
  material: breeze_rod
  display_name: "<light_purple>Archmage's Staff</light_purple>"
  item_name: "Archmage's Staff"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>A staff imbued with vast magical power</gray>"
  providers:
    ap:
      value: '{"attack_damage":16}'
  options:
    glow: true

• tier: LEGENDARY high-end stats with no actions (Quality & Display).

demo_flame_wand

Flame Wand: rare quality, left-click to chant a fire spell (left_click + 3s cooldown + title + sound + bossbar full casting effect).

demo_flame_wand:
  type: wand
  material: blaze_rod
  display_name: "<red>Flame Wand</red>"
  item_name: "Flame Wand"
  tier: RARE
  lore:
    - ""
    - "<gray>Left-click swing to chant a fire spell</gray>"
    - "<dark_gray>Cooldown 3 seconds</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>Fire Spell</red>||<gold>Flames rise</gold>||3||30||10"
          - handler: qi:sound
            payload: "minecraft:entity.blaze.shoot;1;1"
          - handler: qi:bossbar
            payload: "<gold>Casting…</gold>;1;YELLOW;PROGRESS_6;40"

• Three handlers chained together: qi:title + qi:sound + qi:bossbar, left_click trigger + cooldown: 3s.

demo_arcane_wand

Arcane Wand: epic quality, left-click to release an arcane pulse, consuming 1 redstone each time (left_click + consume + cooldown + level restriction).

demo_arcane_wand:
  type: wand
  material: stick
  display_name: "<aqua>Arcane Wand</aqua>"
  item_name: "Arcane Wand"
  tier: EPIC
  lore:
    - ""
    - "<gray>Left-click to release an arcane pulse</gray>"
    - "<dark_gray>Consumes 1 redstone each time · Cooldown 2 seconds</dark_gray>"
    - "<dark_gray>Requires level 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>Arcane pulse bursts forth</aqua>"
          - handler: qi:sound
            payload: "minecraft:block.amethyst_block.chime;1;1.4"
          - handler: qi:action_bar
            payload: "<aqua>Magic surges…</aqua>"

• The only equipment that demonstrates consume (item:redstone:1 consumes 1 redstone as a mana stone on release), paired with cooldown: 2s + restrictions: level:15, including the qi:subtitle handler (trigger).

---

Horse Armor horse_armor.yml

Mount armor, mainly appearance. For barding / unbarding prompts prefer equip / unequip; you can also use left_click for wiping / inspecting.

demo_iron_barding

Simplest horse armor: appearance + defensive attributes, no options.

demo_iron_barding:
  type: horse_armor
  material: iron_horse_armor
  display_name: "<white>Iron Barding</white>"
  item_name: "Iron Barding"
  lore:
    - ""
    - "<gray>Iron armor protecting the mount</gray>"
  providers:
    ap:
      value: '{"defense":10}'

• Entry-level baseline, not even an options block (Attributes & Values).

demo_diamond_barding

Rare horse armor: glow + high defense.

demo_diamond_barding:
  type: horse_armor
  material: diamond_horse_armor
  display_name: "<aqua>Diamond Barding</aqua>"
  item_name: "Diamond Barding"
  tier: RARE
  lore:
    - ""
    - "<gray>Sturdy and ornate mount armor</gray>"
  providers:
    ap:
      value: '{"defense":20}'
  options:
    glow: true

• tier: RARE + glow (Quality & Display).

demo_golden_barding

Golden Barding: epic quality, horns sound long when barding the mount (equip) + unequip prompt (unequip).

demo_golden_barding:
  type: horse_armor
  material: golden_horse_armor
  display_name: "<gold>Golden Barding</gold>"
  item_name: "Golden Barding"
  tier: EPIC
  lore:
    - ""
    - "<gray>Horns sound long when barding the mount</gray>"
  providers:
    ap:
      value: '{"defense":16}'
  options:
    glow: true
  actions:
    triggers:
      equip:
        trigger:
          atom: equip
        refs:
          - handler: qi:action_bar
            payload: "<gold>Barding equipped —— the mount is fully armored</gold>"
          - handler: qi:sound
            payload: "minecraft:item.armor.equip_gold;1;1"
      unequip:
        trigger:
          atom: unequip
        refs:
          - handler: qi:action_bar
            payload: "<gray>Barding removed</gray>"

• equip / unequip dual triggers demonstrate barding / unbarding prompts (handlers).

demo_dragonhide_barding

Dragonhide Barding: legendary quality, left-click to wipe (left_click + 3s cooldown) + equip horn (equip), binds on acquire. Introduces the max_health attribute.

demo_dragonhide_barding:
  type: horse_armor
  material: diamond_horse_armor
  display_name: "<dark_purple>Dragonhide Barding</dark_purple>"
  item_name: "Dragonhide Barding"
  tier: LEGENDARY
  lore:
    - ""
    - "<gray>Forged from dragon scales, hard to pierce</gray>"
    - "<dark_gray>Left-click to wipe and make the scales gleam anew</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>You wipe the dragon scales, and they gleam with a cold light</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>Dragonhide Barding</dark_purple>||<gray>The mount is now guarded by dragon power</gray>||10||40||10"
          - handler: qi:sound
            payload: "minecraft:entity.ender_dragon.growl;0.8;1"

• Dual triggers: left_click (wipe, with cooldown: 3s) + equip (barding horn). The max_health attribute (Attributes & Values), bind_on_acquire Soul Binds on acquire (no restrictions set here).

---

Next Steps

• Examples - Accessories & Consumables——examples of accessories, consumables, dishes, and other types
• Examples - Miscellaneous——examples of tools, blocks, and miscellaneous types
• Item Example Library Overview——return to the example library directory