Item Cookbook

Belongs to: Server Owner Guide　·　Related: Item Definition · Item Types · Action System

QI ships with around 140 example items, covering the typical way to write each type. This page is their complete index + per-category annotations + ready-to-use recipes. All examples live in plugins/QinhItems/items/<type>.yml, and you can grab any for reference directly with /qi give <ID>.

💡 Learning path: first grab a few in-game with /qi give to see the effect, then open the corresponding items/*.yml and compare it against the annotations on this page, and finally copy and tweak them into your own.

📚 Detailed Sub-pages (full per-item YAML, line by line)

This page is the overview + index + representative recipes. The full line-by-line annotation of each item is split into three sub-pages:

Examples - Equipment —— Armor / Helmet / Chestplate / Leggings / Boots / Bow / Crossbow / Trident / Ammunition / Shield / Wand / Horse Armor (47 items)
Examples - Accessories & Consumables —— Accessory / Ring / Necklace / Bracelet / Food / Scroll / Seed / Bait / Material / Tool / Fishing Rod (41 items)
Examples - Misc —— Currency / Token / Trophy / Skull / Prop / Mount (22 items)

The line-by-line annotations for weapons / consumables / gems / misc are below in §2–§5 on this page.

1. Complete Item Index

Grouped by type file, listing each example's ID and the feature it demonstrates.

Combat Equipment

Type File	Item ID	Demonstrated Feature
weapon.yml	`demo_iron_blade`	Simplest weapon (appearance + attributes)
	`demo_flame_saber`	Rare + glow + crit attribute
	`demo_void_reaver`	Legendary, pure high-end appearance
	`demo_thunder_edge`	Left-click trigger + 3s cooldown + title & sound
	`demo_warden_greatsword`	On-hit trigger + level restriction + bind on acquire
bow.yml	`demo_hunter_bow` `demo_gale_bow` `demo_starfall_bow` `demo_piercing_longbow`	Bow: charge aiming, shoot trigger
crossbow.yml	`demo_siege_crossbow` `demo_repeater_crossbow` `demo_aiming_crossbow` `demo_piercing_crossbow`	Crossbow
trident.yml	`demo_tide_trident` `demo_storm_trident` `demo_surge_trident` `demo_abyss_trident`	Trident (throwing + skills)
projectile.yml	`demo_keen_arrow` `demo_spectral_bolt` `demo_thunder_arrow` `demo_soul_piercer`	Ammunition
shield.yml	`demo_oak_bulwark` `demo_tower_bulwark` `demo_aegis_guard` `demo_bastion_wall`	Shield (with SET ability)
wand.yml	`demo_apprentice_wand` `demo_archmage_staff` `demo_flame_wand` `demo_arcane_wand`	Wand (skills + gem sockets)

Armor (armor and its subtypes)

Type File	Item ID	Demonstrated Feature
armor.yml	`demo_guard_plate` `demo_aegis_plate` `demo_dragonscale_plate`	Generic armor (defense + health attributes)
helmet.yml	`demo_iron_helm` `demo_crystal_helm` `demo_sentinel_helm` `demo_royal_crown`	Helmet
chestplate.yml	`demo_iron_cuirass` `demo_dragon_cuirass` `demo_guardian_plate` `demo_titan_aegis`	Chestplate
leggings.yml	`demo_iron_greaves` `demo_storm_greaves` `demo_guardian_greaves` `demo_warden_greaves`	Leggings
boots.yml	`demo_iron_treads` `demo_swift_treads` `demo_gale_striders` `demo_stormrunner_boots`	Boots
horse_armor.yml	`demo_iron_barding` `demo_diamond_barding` `demo_golden_barding` `demo_dragonhide_barding`	Horse armor

Accessories

Type File	Item ID	Demonstrated Feature
accessory.yml	`demo_lucky_charm`	Simplest accessory (passive attribute)
	`demo_void_talisman`	Legendary glow with dual attributes
	`demo_guardian_pendant`	Equip trigger + feedback
	`demo_sunfire_emblem`	equip + unequip dual trigger + level restriction
ring.yml	`demo_jade_ring` `demo_ruby_ring` `demo_crit_band` `demo_arcane_loop`	Ring (gem sockets)
necklace.yml	`demo_jade_pendant` `demo_phoenix_pendant` `demo_star_amulet` `demo_amethyst_charm`	Necklace
bracelet.yml	`demo_bone_bangle` `demo_copper_bangle` `demo_gilded_cuff` `demo_warding_bangle`	Bracelet

Consumable / Food

Type File	Item ID	Demonstrated Feature
consumable.yml	`demo_heal_potion` `demo_mana_potion` `demo_elixir`	Potion (appearance + stacking)
	`demo_berserk_brew`	Drink trigger (consume) + grant buff
	`demo_recall_scroll`	Left-click use + self:1 self-consume + cooldown
food.yml	`demo_traveler_bread` `demo_roast_feast` `demo_golden_treat`	Food (food component)
scroll.yml	`demo_teleport_scroll` `demo_identify_scroll` `demo_return_scroll` `demo_blessing_scroll`	Scroll (skill consumable)
seed.yml	`demo_wheat_seed` `demo_mystic_seed` `demo_spirit_melon_seed`	Seed
bait.yml	`demo_river_bait` `demo_glow_bait` `demo_lucky_bait`	Bait

Gem / Material / Tool

Type File	Item ID	Demonstrated Feature
gem.yml	`demo_amethyst_gem` `demo_emerald_gem` `demo_diamond_gem`	Inlay stone (appearance, stacks to 64)
	`demo_radiant_gem`	Interactive gem (left-click to examine)
material.yml	`demo_iron_fragment` `demo_copper_fragment` `demo_gold_fragment` `demo_mystic_essence`	Material (with SET)
tool.yml	`demo_miner_pick` `demo_lumber_axe` `demo_prospector_pick` `demo_forester_axe`	Tool
fishing_rod.yml	`demo_angler_rod` `demo_deepsea_rod` `demo_harvest_rod` `demo_lucky_koi_rod`	Fishing rod (with SET)

Misc / Special

Type File	Item ID	Demonstrated Feature
currency.yml	`demo_gold_coin` `demo_jade_note` `demo_exchange_token`	Currency
token.yml	`demo_event_token` `demo_arena_token` `demo_kit_voucher` `demo_legend_voucher`	Token (consumable)
trophy.yml	`demo_champion_cup` `demo_victory_emblem` `demo_dragon_skull`	Trophy
skull.yml	`demo_creeper_trophy` `demo_skeleton_trophy` `demo_hero_head` `demo_summon_skull`	Skull
prop.yml	`demo_pocket_watch` `demo_seeker_compass` `demo_recall_stone` `demo_far_spyglass`	Prop (skills + consume)
horse.yml	`demo_war_saddle` `demo_swift_lead` `demo_summon_steed_egg` `demo_celestial_mount_egg`	Mount

misc.yml — Comprehensive Ability Showcase

Item ID	Demonstrated Feature
`prefixed_sword`	Section prefix & suffix (sharp_prefix + heavy_suffix) + inline combat:swing
`random_affix_weapon`	Random affix pool (weapon_affix_pool)
`direct_affix_item`	Directly attached affix (legendary_weapon_affix)
`legendary_sword` `epic_sword` `rare_sword` `uncommon_sword`	Quality prefix pool (quality_prefix_pool picks prefix by tier)
`suffix_armor`	Armor suffix pool
`rare_weapon`	Quality prefix + affix pool combination
`enchant_limit_custom`	Custom enchant cap (enchant_max_total_level: 15)
`enchant_limit_auto`	Auto enchant cap (min(type, quality)=40)
`warrior_helmet/chestplate/leggings/boots/sword`	Warrior set pieces (prefix matching)
`mage_robe/hat/staff/amulet`	Mage set pieces

2. Per-Category Annotation · Weapons (weapon.yml)

Recipe 1: Simplest weapon (appearance + attributes only)

yaml

demo_iron_blade:
  type: weapon
  material: iron_sword
  display_name: "<white>Iron War Blade</white>"
  item_name: "Iron War Blade"
  lore:
    - ""
    - "<gray>A reliable companion for the novice adventurer</gray>"
  providers:
    ap:
      value: '{"attack_damage":8}'        # handed to AttributePlus to apply
  options:
    unbreakable: true

Minimal usable template: material + name + attribute + unbreakable durability.

Recipe 2: Rare glow + crit

yaml

demo_flame_saber:
  type: weapon
  material: diamond_sword
  display_name: "<gold>Flame Saber</gold>"
  tier: RARE
  providers:
    ap:
      value: '{"attack_damage":18,"crit_rate":0.1}'
  options:
    unbreakable: true
    glow: true                            # fake-enchant glow effect

Recipe 3: Left-click triggered skill (Thunder Edge)

yaml

demo_thunder_edge:
  type: weapon
  material: golden_sword
  display_name: "<yellow>Thunder Edge</yellow>"
  tier: EPIC
  providers:
    ap:
      value: '{"attack_damage":22,"crit_rate":0.12}'
  options:
    unbreakable: true
    glow: true
  actions:
    triggers:
      left_click:                         # left-click is the most reliable
        trigger:
          atom: left_click
        cooldown: 3s
        refs:
          - handler: qi:title
            payload: "<yellow>⚡ Thunder ⚡</yellow>||<gray>The roar echoes</gray>||3||30||10"
          - handler: qi:sound
            payload: "minecraft:entity.lightning_bolt.thunder;1;1.2"

⚠️ right_click does not always trigger against air; weapons generally use left_click.

Recipe 4: On-hit trigger + restriction + binding (Warden Greatsword)

yaml

demo_warden_greatsword:
  type: weapon
  material: netherite_sword
  display_name: "<dark_aqua>Warden Greatsword</dark_aqua>"
  tier: LEGENDARY
  providers:
    ap:
      value: '{"attack_damage":32,"crit_rate":0.2}'
  options:
    unbreakable: true
    glow: true
    bind_on_acquire: true                 # soul-bind on acquire
    restrictions:
      - "level:20"                        # requires level 20
  actions:
    triggers:
      on_hit:                             # when hitting an entity
        trigger:
          atom: on_hit
        refs:
          - handler: qi:sound
            payload: "minecraft:entity.warden.sonic_boom;0.6;1"
          - handler: qi:action_bar
            payload: "<dark_aqua>The Warden's gaze...</dark_aqua>"

3. Per-Category Annotation · Consumables (consumable.yml)

Recipe 1: Drink trigger (consume) —— suited to potion / food materials

yaml

demo_berserk_brew:
  type: consumable
  material: potion                        # the consume trigger requires an edible material
  display_name: "<dark_red>Berserker Brew</dark_red>"
  tier: EPIC
  options:
    max_stack_size: 8
  actions:
    triggers:
      consume:                            # when drunk
        trigger:
          atom: consume
        cooldown: 30s
        refs:
          - handler: qi:command
            payload: "effect give {player} minecraft:strength 20 1"
          - handler: qi:title
            payload: "<dark_red>Berserk!</dark_red>||<gray>Power boils in the blood</gray>||3||30||10"
          - handler: qi:sound
            payload: "minecraft:entity.ravager.roar;1;1"

Recipe 2: Non-edible materials use left_click + self:1 (Recall Scroll)

yaml

demo_recall_scroll:
  type: consumable
  material: paper                         # paper cannot be "drunk", use left_click instead
  display_name: "<aqua>Recall Scroll</aqua>"
  tier: UNCOMMON
  options:
    max_stack_size: 16
  actions:
    triggers:
      left_click:
        trigger:
          atom: left_click
        cooldown: 5s
        consume:
          - "self:1"                      # consumes 1 of itself on use
        refs:
          - handler: qi:command
            payload: "spawn"
          - handler: qi:action_bar
            payload: "<aqua>The scroll turns to starlight, carrying you home...</aqua>"
          - handler: qi:sound
            payload: "minecraft:entity.enderman.teleport;1;1"

🔑 Key technique: non-edible materials (paper/redstone...) have no consume gesture, so use left_click + consume:["self:1"] to simulate "consume one on use".

4. Per-Category Annotation · Gems (gem.yml)

Gems usually carry no actions, relying mainly on appearance + inlay:

yaml

demo_amethyst_gem:
  type: gem
  material: amethyst_shard
  display_name: "<light_purple>Amethyst Gem</light_purple>"
  lore:
    - ""
    - "<gray>An amethyst that can be inlaid into equipment</gray>"
  options:
    max_stack_size: 64                    # gems are generally stackable in large amounts

Only an interactive "playable" gem adds left_click (see demo_radiant_gem). For the gem socket system, see Gem Sockets.

5. Per-Category Annotation · misc.yml Comprehensive Showcase

misc.yml is QI's "ability showcase ground" — strongly recommended for close reading.

Section prefix & suffix

yaml

prefixed_sword:
  material: diamond_sword
  display_name: "<white>Sword of Trials</white>"
  sections:
    - sharp_prefix          # prepends "Sharp" to the name
    - heavy_suffix          # appends "of Power" to the name
  actions:
    triggers:
      left_click:
        trigger: { atom: left_click }
        cooldown: 1s
        refs:
          - handler: combat:swing
            payload: "light"

Random affix pool

yaml

random_affix_weapon:
  material: netherite_sword
  display_name: "<gradient:#FFD700:#FF4500>Random Affix Weapon</gradient>"
  sections:
    - weapon_affix_pool     # rolls one random affix on each acquisition
  options:
    unbreakable: true
    glow: true

Quality prefix (auto-selected by tier)

yaml

legendary_sword:
  material: iron_sword
  display_name: "<white>Legendary Sword</white>"
  tier: LEGENDARY
  sections:
    - quality_prefix_pool   # tier=LEGENDARY → automatically uses legendary_prefix
  providers:
    ap:
      value: '{"attack_damage":50,"critical_rate":0.1}'

With the same quality_prefix_pool section, epic_sword/rare_sword/uncommon_sword show different prefixes because of their different tiers. For section definitions, see Sections and Built-in Content List.

Enchant cap

yaml

enchant_limit_custom:
  material: diamond_sword
  tier: RARE
  enchant_max_total_level: 15    # explicit cap, overrides auto-calculation

enchant_limit_auto:
  material: netherite_sword
  tier: LEGENDARY
  # omit enchant_max_total_level → auto min(weapon=50, LEGENDARY=40)=40

See Enchant Cap.

Set pieces (named prefix matching)

yaml

warrior_helmet:    { material: diamond_helmet,     tier: RARE, display_name: "<white>Warrior Helmet</white>" }
warrior_sword:     { material: diamond_sword,      tier: RARE, display_name: "<white>Warrior Sword</white>", options: { glow: true } }
# the warrior_ prefix automatically matches the belonging_pieces of the warrior_bloodlust set in sets/sets.yml

For set definitions, see Sets and Built-in Content List.

6. Quickly Find a Recipe by Need

I want to...	Which example to look at	Section
The simplest weapon with attributes	`demo_iron_blade`	This page §2
Cast a skill on left-click	`demo_thunder_edge`	Action System
On-hit / on-kill trigger	`demo_warden_greatsword`	Triggers
Drink a potion to trigger a buff	`demo_berserk_brew`	This page §3
Scroll / one-time consumable	`demo_recall_scroll`	This page §3
Equip / unequip trigger	`demo_sunfire_emblem` (accessory)	Triggers
Random prefix / affix	`random_affix_weapon` / `legendary_sword`	Sections / Affixes
Set	`warrior_` / `mage_`	Sets
Bound item	`demo_warden_greatsword`	Soul Binding
Gem	`demo_amethyst_gem`	Gem Sockets
Food	items in food.yml	Item Definition → food

Next Steps

Item Definition: full field reference
Action System: triggers + handlers
Built-in Content List: full tables of built-in qualities / sections / sets

Item Cookbook ​

📚 Detailed Sub-pages (full per-item YAML, line by line) ​

1. Complete Item Index ​

Combat Equipment ​

Armor (armor and its subtypes) ​

Accessories ​

Consumable / Food ​

Gem / Material / Tool ​

Misc / Special ​

misc.yml — Comprehensive Ability Showcase ​

2. Per-Category Annotation · Weapons (weapon.yml) ​

Recipe 1: Simplest weapon (appearance + attributes only) ​

Recipe 2: Rare glow + crit ​

Recipe 3: Left-click triggered skill (Thunder Edge) ​

Recipe 4: On-hit trigger + restriction + binding (Warden Greatsword) ​

3. Per-Category Annotation · Consumables (consumable.yml) ​

Recipe 1: Drink trigger (consume) —— suited to potion / food materials ​

Recipe 2: Non-edible materials use left_click + self:1 (Recall Scroll) ​

4. Per-Category Annotation · Gems (gem.yml) ​

5. Per-Category Annotation · misc.yml Comprehensive Showcase ​

Section prefix & suffix ​

Random affix pool ​

Quality prefix (auto-selected by tier) ​

Enchant cap ​

Set pieces (named prefix matching) ​

6. Quickly Find a Recipe by Need ​

Next Steps ​

Item Cookbook

📚 Detailed Sub-pages (full per-item YAML, line by line)

1. Complete Item Index

Combat Equipment

Armor (armor and its subtypes)

Accessories

Consumable / Food

Gem / Material / Tool

Misc / Special

misc.yml — Comprehensive Ability Showcase

2. Per-Category Annotation · Weapons (weapon.yml)

Recipe 1: Simplest weapon (appearance + attributes only)

Recipe 2: Rare glow + crit

Recipe 3: Left-click triggered skill (Thunder Edge)

Recipe 4: On-hit trigger + restriction + binding (Warden Greatsword)

3. Per-Category Annotation · Consumables (consumable.yml)

Recipe 1: Drink trigger (consume) —— suited to potion / food materials

Recipe 2: Non-edible materials use left_click + self:1 (Recall Scroll)

4. Per-Category Annotation · Gems (gem.yml)

5. Per-Category Annotation · misc.yml Comprehensive Showcase

Section prefix & suffix

Random affix pool

Quality prefix (auto-selected by tier)

Enchant cap

Set pieces (named prefix matching)

6. Quickly Find a Recipe by Need

Next Steps