5 分钟快速上手
本页带你从零造出一把有属性、左键放技能效果、史诗品质的剑，两条路任选：手写 YAML 或 游戏内 GUI。
路线 A：手写 YAML（推荐先理解结构）
第 1 步：新建 / 打开类型文件
物品按类型分文件存放在 plugins/QinhItems/items/，文件名即类型。武器就编辑 items/weapon.yml。每个顶层键就是一个物品 ID。
第 2 步：粘贴一个物品
yaml
my_first_sword: # ← 物品 ID（小写、下划线）
type: weapon # 物品类型
material: diamond_sword # 基础材质（原版材质名）
display_name: "<gold>试炼之刃</gold>" # 名称，支持 MiniMessage
tier: EPIC # 品质（见 item_tiers.yml）
lore:
- ""
- "<gray>左键挥动，迸发火花</gray>"
- "<dark_gray>冷却 3 秒</dark_gray>"
providers:
ap:
value: '{"attack_damage":18,"crit_rate":0.12}' # 属性（交给 AttributePlus）
options:
unbreakable: true # 无限耐久
glow: true # 附魔光效
actions:
triggers:
left_click: # 左键触发
trigger:
atom: left_click
cooldown: 3s # 冷却 3 秒
refs: # 按顺序执行的处理器
- handler: qi:title
payload: "<gold>⚡ 火花 ⚡</gold>||<gray>剑刃震鸣</gray>||3||30||10"
- handler: qi:sound
payload: "minecraft:entity.player.attack.crit;1;1.2"第 3 步：重载并领取
/qi reload
/qi give my_first_sword左键挥剑，你会看到标题与音效，并触发 3 秒冷却。属性会在装备到手上时由 AttributePlus 接管（前提是装了 AP）。
✅ 完成！ 接下来你可以：
路线 B：游戏内 GUI（不碰 YAML）
第 1 步：打开编辑器
/qi editor打开类型浏览器。详细导航见 编辑器概览。
第 2 步：选类型 → 新建物品
- 点击 Weapon（武器） 类型。
- 点「新建物品」，在聊天框输入物品 ID（如
my_first_sword）。 - 进入物品编辑器主界面。
第 3 步：逐字段编辑
在物品编辑器里点击对应按钮（详见 物品编辑器）：
- 材质 → 聊天输入
diamond_sword - 品质 → 聊天输入
EPIC - 显示名 → 聊天输入
<gold>试炼之刃</gold> - 属性 → 进入属性编辑器，添加
attack_damage = 18 - 动作/技能 → 进入动作编辑器，在
left_click标签下添加qi:title/qi:sound处理器
第 4 步：保存
点右下角保存按钮（绿宝石，槽位 53）。QI 会校验并写回 YAML，然后热重载动作表。
🖼️ [图片占位] 物品编辑器主界面（标注各字段按钮） · 建议
assets/editor-item-main.png
两条路线对比
| 手写 YAML | GUI 编辑器 | |
|---|---|---|
| 上手速度 | 中（需懂结构） | 快 |
| 批量操作 | 强（复制粘贴） | 弱 |
| 复杂动作 / 套装 | 灵活 | 引导式、不易出错 |
| 适合 | 老手、批量配装 | 新手、单件精修 |
两者完全互通：GUI 编辑后保存的就是同一份 YAML，反之手写后 /qi reload 也能在 GUI 里打开。
常见第一坑
- 属性不上身？ 你没装 AttributePlus，或
combat.enabled关了，进入纯物品库模式。见 属性与数值。 - 动作不触发？ 动作只在
/qi reload时载入；改了 YAML 记得重载。 - 品质名不显示？
tier要大写（EPIC），且必须存在于item_tiers.yml。见 品质与显示。 material报错？ 用原版材质名（如diamond_sword）；带:或-的会被当成外部物品源引用。
下一步 → 核心概念与架构