物品示例库（Cookbook）

所属：服主指南　·　相关：物品定义 · 物品类型 · 动作系统

QI 自带约 140 件示例物品，覆盖每个类型的典型写法。本页是它们的完整索引 + 逐类注解 + 即用配方。所有示例都在 plugins/QinhItems/items/<类型>.yml 里，可直接 /qi give <ID> 领取参考。

💡 学习路径：先在游戏里 /qi give 领几件看效果，再打开对应 items/*.yml 对照本页注解，最后复制改成你自己的。

📚 分篇详解（每件物品逐条完整 YAML）

本页是总览 + 索引 + 代表配方。每件物品的逐条完整注解拆到三个分篇：

示例-装备篇 —— 护甲 / 头盔 / 胸甲 / 护腿 / 靴子 / 弓 / 弩 / 三叉戟 / 弹药 / 盾牌 / 法杖 / 马铠（47 件）
示例-饰品消耗篇 —— 饰品 / 戒指 / 项链 / 手镯 / 食物 / 卷轴 / 种子 / 鱼饵 / 材料 / 工具 / 钓竿（41 件）
示例-杂项篇 —— 货币 / 代币 / 奖杯 / 头颅 / 道具 / 坐骑（22 件）

武器 / 消耗品 / 宝石 / misc 的逐条注解在本页下方 §2–§5。

一、完整物品索引

按类型文件分组，列出每件示例的 ID 与它演示的特性。

战斗装备

类型文件	物品 ID	演示特性
weapon.yml	`demo_iron_blade`	最简武器（外观 + 属性）
	`demo_flame_saber`	稀有 + 发光 + 暴击属性
	`demo_void_reaver`	传说纯外观高配
	`demo_thunder_edge`	左键触发 + 3秒冷却 + 标题音效
	`demo_warden_greatsword`	命中触发 + 等级限制 + 获得即绑定
bow.yml	`demo_hunter_bow` `demo_gale_bow` `demo_starfall_bow` `demo_piercing_longbow`	弓：聚气瞄准、射击触发
crossbow.yml	`demo_siege_crossbow` `demo_repeater_crossbow` `demo_aiming_crossbow` `demo_piercing_crossbow`	弩
trident.yml	`demo_tide_trident` `demo_storm_trident` `demo_surge_trident` `demo_abyss_trident`	三叉戟（投射 + 技能）
projectile.yml	`demo_keen_arrow` `demo_spectral_bolt` `demo_thunder_arrow` `demo_soul_piercer`	弹药
shield.yml	`demo_oak_bulwark` `demo_tower_bulwark` `demo_aegis_guard` `demo_bastion_wall`	盾牌（含 SET 能力）
wand.yml	`demo_apprentice_wand` `demo_archmage_staff` `demo_flame_wand` `demo_arcane_wand`	法杖（技能 + 宝石孔）

护甲（armor 及子类型）

类型文件	物品 ID	演示特性
armor.yml	`demo_guard_plate` `demo_aegis_plate` `demo_dragonscale_plate`	通用护甲（防御 + 生命属性）
helmet.yml	`demo_iron_helm` `demo_crystal_helm` `demo_sentinel_helm` `demo_royal_crown`	头盔
chestplate.yml	`demo_iron_cuirass` `demo_dragon_cuirass` `demo_guardian_plate` `demo_titan_aegis`	胸甲
leggings.yml	`demo_iron_greaves` `demo_storm_greaves` `demo_guardian_greaves` `demo_warden_greaves`	护腿
boots.yml	`demo_iron_treads` `demo_swift_treads` `demo_gale_striders` `demo_stormrunner_boots`	靴子
horse_armor.yml	`demo_iron_barding` `demo_diamond_barding` `demo_golden_barding` `demo_dragonhide_barding`	马铠

饰品

类型文件	物品 ID	演示特性
accessory.yml	`demo_lucky_charm`	最简饰品（被动属性）
	`demo_void_talisman`	传说发光双属性
	`demo_guardian_pendant`	装备触发 + 反馈
	`demo_sunfire_emblem`	equip + unequip 双触发 + 等级限制
ring.yml	`demo_jade_ring` `demo_ruby_ring` `demo_crit_band` `demo_arcane_loop`	戒指（宝石孔）
necklace.yml	`demo_jade_pendant` `demo_phoenix_pendant` `demo_star_amulet` `demo_amethyst_charm`	项链
bracelet.yml	`demo_bone_bangle` `demo_copper_bangle` `demo_gilded_cuff` `demo_warding_bangle`	手镯

消耗 / 食物

类型文件	物品 ID	演示特性
consumable.yml	`demo_heal_potion` `demo_mana_potion` `demo_elixir`	药剂（外观 + 堆叠）
	`demo_berserk_brew`	喝下触发（consume）+ 给 buff
	`demo_recall_scroll`	左键使用 + self:1 自扣 + 冷却
food.yml	`demo_traveler_bread` `demo_roast_feast` `demo_golden_treat`	食物（food 组件）
scroll.yml	`demo_teleport_scroll` `demo_identify_scroll` `demo_return_scroll` `demo_blessing_scroll`	卷轴（技能消耗品）
seed.yml	`demo_wheat_seed` `demo_mystic_seed` `demo_spirit_melon_seed`	种子
bait.yml	`demo_river_bait` `demo_glow_bait` `demo_lucky_bait`	鱼饵

宝石 / 材料 / 工具

类型文件	物品 ID	演示特性
gem.yml	`demo_amethyst_gem` `demo_emerald_gem` `demo_diamond_gem`	镶嵌石（外观，可堆叠 64）
	`demo_radiant_gem`	可交互宝石（左键端详）
material.yml	`demo_iron_fragment` `demo_copper_fragment` `demo_gold_fragment` `demo_mystic_essence`	材料（含 SET）
tool.yml	`demo_miner_pick` `demo_lumber_axe` `demo_prospector_pick` `demo_forester_axe`	工具
fishing_rod.yml	`demo_angler_rod` `demo_deepsea_rod` `demo_harvest_rod` `demo_lucky_koi_rod`	钓竿（含 SET）

杂项 / 特殊

类型文件	物品 ID	演示特性
currency.yml	`demo_gold_coin` `demo_jade_note` `demo_exchange_token`	货币
token.yml	`demo_event_token` `demo_arena_token` `demo_kit_voucher` `demo_legend_voucher`	代币（可消耗）
trophy.yml	`demo_champion_cup` `demo_victory_emblem` `demo_dragon_skull`	奖杯
skull.yml	`demo_creeper_trophy` `demo_skeleton_trophy` `demo_hero_head` `demo_summon_skull`	头颅
prop.yml	`demo_pocket_watch` `demo_seeker_compass` `demo_recall_stone` `demo_far_spyglass`	道具（技能 + 消耗）
horse.yml	`demo_war_saddle` `demo_swift_lead` `demo_summon_steed_egg` `demo_celestial_mount_egg`	坐骑

misc.yml — 综合能力演示场

物品 ID	演示特性
`prefixed_sword`	段前后缀（sharp_prefix + heavy_suffix）+ 内联 combat:swing
`random_affix_weapon`	随机词缀池（weapon_affix_pool）
`direct_affix_item`	直接挂词缀（legendary_weapon_affix）
`legendary_sword` `epic_sword` `rare_sword` `uncommon_sword`	品质前缀池（quality_prefix_pool 按 tier 选前缀）
`suffix_armor`	防具后缀池
`rare_weapon`	品质前缀 + 词缀池组合
`enchant_limit_custom`	自定义附魔上限（enchant_max_total_level: 15）
`enchant_limit_auto`	自动附魔上限（min(类型,品质)=40）
`warrior_helmet/chestplate/leggings/boots/sword`	战士套装件（前缀匹配）
`mage_robe/hat/staff/amulet`	法师套装件

二、逐类注解 · 武器（weapon.yml）

配方 1：最简武器（只有外观 + 属性）

yaml

demo_iron_blade:
  type: weapon
  material: iron_sword
  display_name: "<white>铁制战刃</white>"
  item_name: "铁制战刃"
  lore:
    - ""
    - "<gray>新手冒险者的可靠伙伴</gray>"
  providers:
    ap:
      value: '{"attack_damage":8}'        # 交 AttributePlus 应用
  options:
    unbreakable: true

最小可用模板：材质 + 名 + 属性 + 无限耐久。

配方 2：稀有发光 + 暴击

yaml

demo_flame_saber:
  type: weapon
  material: diamond_sword
  display_name: "<gold>烈焰军刀</gold>"
  tier: RARE
  providers:
    ap:
      value: '{"attack_damage":18,"crit_rate":0.1}'
  options:
    unbreakable: true
    glow: true                            # 假附魔光效

配方 3：左键触发技能（雷霆之刃）

yaml

demo_thunder_edge:
  type: weapon
  material: golden_sword
  display_name: "<yellow>雷霆之刃</yellow>"
  tier: EPIC
  providers:
    ap:
      value: '{"attack_damage":22,"crit_rate":0.12}'
  options:
    unbreakable: true
    glow: true
  actions:
    triggers:
      left_click:                         # 左键最可靠
        trigger:
          atom: left_click
        cooldown: 3s
        refs:
          - handler: qi:title
            payload: "<yellow>⚡ 雷霆 ⚡</yellow>||<gray>轰鸣回荡</gray>||3||30||10"
          - handler: qi:sound
            payload: "minecraft:entity.lightning_bolt.thunder;1;1.2"

⚠️ right_click 对空气不一定触发，武器一般用 left_click。

配方 4：命中触发 + 限制 + 绑定（监守者巨剑）

yaml

demo_warden_greatsword:
  type: weapon
  material: netherite_sword
  display_name: "<dark_aqua>监守者巨剑</dark_aqua>"
  tier: LEGENDARY
  providers:
    ap:
      value: '{"attack_damage":32,"crit_rate":0.2}'
  options:
    unbreakable: true
    glow: true
    bind_on_acquire: true                 # 获得即灵魂绑定
    restrictions:
      - "level:20"                        # 需要 20 级
  actions:
    triggers:
      on_hit:                             # 命中实体时
        trigger:
          atom: on_hit
        refs:
          - handler: qi:sound
            payload: "minecraft:entity.warden.sonic_boom;0.6;1"
          - handler: qi:action_bar
            payload: "<dark_aqua>监守者的注视…</dark_aqua>"

三、逐类注解 · 消耗品（consumable.yml）

配方 1：喝下触发（consume）—— 适合 potion / 食物材质

yaml

demo_berserk_brew:
  type: consumable
  material: potion                        # consume 触发要求可食用材质
  display_name: "<dark_red>狂战士药剂</dark_red>"
  tier: EPIC
  options:
    max_stack_size: 8
  actions:
    triggers:
      consume:                            # 喝下时
        trigger:
          atom: consume
        cooldown: 30s
        refs:
          - handler: qi:command
            payload: "effect give {player} minecraft:strength 20 1"
          - handler: qi:title
            payload: "<dark_red>狂暴！</dark_red>||<gray>力量在血脉中沸腾</gray>||3||30||10"
          - handler: qi:sound
            payload: "minecraft:entity.ravager.roar;1;1"

配方 2：非食用材质用 left_click + self:1（回城卷轴）

yaml

demo_recall_scroll:
  type: consumable
  material: paper                         # paper 不能"喝"，改用 left_click
  display_name: "<aqua>回城卷轴</aqua>"
  tier: UNCOMMON
  options:
    max_stack_size: 16
  actions:
    triggers:
      left_click:
        trigger:
          atom: left_click
        cooldown: 5s
        consume:
          - "self:1"                      # 使用即自扣 1 个
        refs:
          - handler: qi:command
            payload: "spawn"
          - handler: qi:action_bar
            payload: "<aqua>卷轴化作星光，带你回家…</aqua>"
          - handler: qi:sound
            payload: "minecraft:entity.enderman.teleport;1;1"

🔑 关键技巧：非食用材质（paper/redstone…）没有 consume 手势，用 left_click + consume:["self:1"] 模拟"使用即消耗一个"。

四、逐类注解 · 宝石（gem.yml）

宝石通常不挂 actions，靠外观 + 镶嵌为主：

yaml

demo_amethyst_gem:
  type: gem
  material: amethyst_shard
  display_name: "<light_purple>紫晶宝石</light_purple>"
  lore:
    - ""
    - "<gray>可镶嵌于装备的紫晶</gray>"
  options:
    max_stack_size: 64                    # 宝石一般可大量堆叠

需要"可把玩"的交互宝石才加 left_click（见 demo_radiant_gem）。宝石孔系统见宝石孔。

五、逐类注解 · misc.yml 综合演示

misc.yml 是 QI 的「能力展示场」，强烈建议精读。

段前后缀

yaml

prefixed_sword:
  material: diamond_sword
  display_name: "<white>试炼之剑</white>"
  sections:
    - sharp_prefix          # 名前加"锋利的"
    - heavy_suffix          # 名后加"之力"
  actions:
    triggers:
      left_click:
        trigger: { atom: left_click }
        cooldown: 1s
        refs:
          - handler: combat:swing
            payload: "light"

随机词缀池

yaml

random_affix_weapon:
  material: netherite_sword
  display_name: "<gradient:#FFD700:#FF4500>随机词缀武器</gradient>"
  sections:
    - weapon_affix_pool     # 每次获得随机一个词缀
  options:
    unbreakable: true
    glow: true

品质前缀（按 tier 自动选）

yaml

legendary_sword:
  material: iron_sword
  display_name: "<white>传说之剑</white>"
  tier: LEGENDARY
  sections:
    - quality_prefix_pool   # tier=LEGENDARY → 自动用 legendary_prefix
  providers:
    ap:
      value: '{"attack_damage":50,"critical_rate":0.1}'

同一个 quality_prefix_pool 段，epic_sword/rare_sword/uncommon_sword 因 tier 不同而显示不同前缀。段定义见段与内置内容清单。

附魔上限

yaml

enchant_limit_custom:
  material: diamond_sword
  tier: RARE
  enchant_max_total_level: 15    # 显式上限，覆盖自动计算

enchant_limit_auto:
  material: netherite_sword
  tier: LEGENDARY
  # 不写 enchant_max_total_level → 自动 min(weapon=50, LEGENDARY=40)=40

见附魔上限。

套装件（命名前缀匹配）

yaml

warrior_helmet:    { material: diamond_helmet,     tier: RARE, display_name: "<white>战士头盔</white>" }
warrior_sword:     { material: diamond_sword,      tier: RARE, display_name: "<white>战士长剑</white>", options: { glow: true } }
# warrior_ 前缀自动匹配 sets/sets.yml 里 warrior_bloodlust 套装的 belonging_pieces

套装定义见套装与内置内容清单。

六、按需求快速找配方

我想要…	看哪个示例	章节
最简单的带属性武器	`demo_iron_blade`	本页 §2
左键放技能	`demo_thunder_edge`	动作系统
命中 / 击杀触发	`demo_warden_greatsword`	触发器
喝药触发 buff	`demo_berserk_brew`	本页 §3
卷轴 / 一次性消耗品	`demo_recall_scroll`	本页 §3
装备 / 卸下触发	`demo_sunfire_emblem`（accessory）	触发器
随机前缀 / 词缀	`random_affix_weapon` / `legendary_sword`	段 / 词缀
套装	`warrior_` / `mage_`	套装
绑定物品	`demo_warden_greatsword`	灵魂绑定
宝石	`demo_amethyst_gem`	宝石孔
食物	food.yml 各项	物品定义 → food

下一步

物品定义：字段全解
动作系统：触发器 + 处理器
内置内容清单：内置品质 / 段 / 套装全表

物品示例库（Cookbook） ​

📚 分篇详解（每件物品逐条完整 YAML） ​

一、完整物品索引 ​

战斗装备 ​

护甲（armor 及子类型） ​

饰品 ​

消耗 / 食物 ​

宝石 / 材料 / 工具 ​

杂项 / 特殊 ​

misc.yml — 综合能力演示场 ​

二、逐类注解 · 武器（weapon.yml） ​

配方 1：最简武器（只有外观 + 属性） ​

配方 2：稀有发光 + 暴击 ​

配方 3：左键触发技能（雷霆之刃） ​

配方 4：命中触发 + 限制 + 绑定（监守者巨剑） ​

三、逐类注解 · 消耗品（consumable.yml） ​

配方 1：喝下触发（consume）—— 适合 potion / 食物材质 ​

配方 2：非食用材质用 left_click + self:1（回城卷轴） ​

四、逐类注解 · 宝石（gem.yml） ​

五、逐类注解 · misc.yml 综合演示 ​

段前后缀 ​

随机词缀池 ​

品质前缀（按 tier 自动选） ​

附魔上限 ​

套装件（命名前缀匹配） ​

六、按需求快速找配方 ​

下一步 ​

物品示例库（Cookbook）

📚 分篇详解（每件物品逐条完整 YAML）

一、完整物品索引

战斗装备

护甲（armor 及子类型）

饰品

消耗 / 食物

宝石 / 材料 / 工具

杂项 / 特殊

misc.yml — 综合能力演示场

二、逐类注解 · 武器（weapon.yml）

配方 1：最简武器（只有外观 + 属性）

配方 2：稀有发光 + 暴击

配方 3：左键触发技能（雷霆之刃）

配方 4：命中触发 + 限制 + 绑定（监守者巨剑）

三、逐类注解 · 消耗品（consumable.yml）

配方 1：喝下触发（consume）—— 适合 potion / 食物材质

配方 2：非食用材质用 left_click + self:1（回城卷轴）

四、逐类注解 · 宝石（gem.yml）

五、逐类注解 · misc.yml 综合演示

段前后缀

随机词缀池

品质前缀（按 tier 自动选）

附魔上限

套装件（命名前缀匹配）

六、按需求快速找配方

下一步