物品定义（item YAML 全字段）

所属：服主指南　·　相关：物品类型 · 属性与数值 · 动作系统

这是 QI 最核心的一章：如何用 YAML 描述一件物品。读完你能看懂、写出任意复杂度的物品。

📦 想要现成配方直接抄？看物品示例库（~140 件内置示例）。　🩺 报错了？看校验报错速查。

1. 文件布局：按类型分组

物品定义放在 plugins/QinhItems/items/ 下，文件名即类型：weapon.yml 里的物品默认 type: weapon，ring.yml 里默认 type: ring。

每个文件里，每个顶层键就是一个物品 ID，键下面是它的定义：

yaml

# items/weapon.yml
demo_iron_blade:        # ← 物品 ID
  material: iron_sword
  display_name: "<white>铁制战刃</white>"
  # …

demo_thunder_edge:      # ← 另一个物品
  material: golden_sword
  # …

这叫分组布局（grouped layout），是推荐写法。QI 也兼容旧的单文件单物品布局（物品带显式 id: 字段），重载时会自动迁移到分组布局并删除旧文件。负责这套逻辑的是 TypeGroupedItemFiles。

物品 ID 规范

小写、字母数字 + 下划线 / 连字符。
引用时裸 ID，不带前缀（demo_iron_blade，不是 qi:demo_iron_blade）。
内部会经过 QinhItemIds.normalize()：自动剥掉 qinhitems- / qinhitems: / qi- / qi: 前缀、转小写、非字母数字转下划线。所以查找是大小写不敏感的。

2. 顶层字段总表

下表是 QinhItemDefinition 的全部字段及其 YAML 键。加粗为常用字段。

YAML 键	类型	默认	含义
（顶层键）	String	—	物品 ID（唯一）
`type`	String	从文件名推断 / `misc`	物品类型，见物品类型
`material`	String	必填	基础材质或外部物品源引用
`display_name`	String?	null	物品名，MiniMessage 或传统 `&` 颜色码
`item_name`	String?	null	备用名（用于搜索 / 物品源索引）
`lore`	List<String>	空	描述行（每行一条）
`tier`	String?	null	品质（大写，如 `EPIC`），见品质
`providers`	Map	空	数据提供者（属性 `ap`、绑定效果等），见下文 §4
`variables`	Map<String,String>	空	变量，见变量
`base_values`	Map<String,Double>	空	基础值（编译进 `ap`），见属性
`enchantments`	Map<String,Int>	空	附魔：`键=等级`
`enchant_max_total_level`	Int?	null	该物品的附魔总等级上限，见附魔上限
`gem-sockets`	List<String>	空	宝石孔类型 ID 列表，见宝石孔
`gem-state`	Map	空	各孔当前镶嵌状态
`gem-lore-override`	List<String>	空	自定义宝石孔 Lore（覆盖默认）
`sections`	List<String>	空	引用的段 ID
`affixes`	List<String>	空	引用的词缀 ID
`fragments`	List<String>	空	引用的碎片 ID
`resource_pack`	段	null	资源包 / 自定义模型
`options`	段	—	物品选项（见下文 §3）
`actions`	段	—	动作 / 触发器（见动作系统）
`update.version`	Int	1	配置 schema 版本（迁移用）

还有两个由系统维护、你一般不用手写的字段：contentHash（内容哈希，变更检测用）、sourceFile（来源文件名）。

3. `options` 选项段

options 控制物品的 meta 标志、视觉、食物组件、自定义 NBT 等。全部可选。

yaml

my_item:
  material: diamond_sword
  options:
    # —— 耐久 / 堆叠 ——
    unbreakable: true            # 无限耐久
    max_stack_size: 1            # 最大堆叠（1–99）
    max_durability: 1000         # 自定义最大耐久

    # —— 显示标志 ——
    hide_attributes: true        # 隐藏属性提示（默认 true）
    hide_enchants: false         # 隐藏附魔提示
    glow: true                   # 假附魔光效（自动配 HIDE_ENCHANTS）
    item_flags:                  # 额外 ItemFlag
      - "HIDE_UNBREAKABLE"
      - "HIDE_ARMOR_TRIM"

    # —— 视觉 ——
    custom_model_data: 10001     # 自定义模型数据（若 resource_pack.custom_model_data 设了则以那个为准）
    color: "#FF00FF"             # 皮革 / 药水染色（十六进制或 "R,G,B"）
    skull_owner: "username"      # 头颅皮肤所有者（用户名或 UUID）
    armor_trim:                  # 盔甲纹饰（1.20+）
      material: "minecraft:copper"
      pattern: "minecraft:coast"
    model_data:                  # 1.20.5+ 高级模型组件
      floats: [1.5, 2.0]
      flags: [true, false]
      strings: ["custom_string"]
      colors: ["#FF0000", "0,255,0"]

    # —— 药水效果（穿戴时常驻见 providers.perm_effects；这里是物品自带药水）——
    potion_effects:
      - "STRENGTH:200:1:false:true:true"   # 类型:时长tick:等级:ambient:粒子:图标
      - "SPEED:200:0"                       # 后三项可省略

    # —— 食物组件 ——
    food:
      nutrition: 8               # 饱食度（0–20）
      saturation: 4.5            # 饱和度
      can-always-eat: false      # 满饱食也能吃
      eat-seconds: 1.6           # 进食时长（秒）

    # —— 约束 / 绑定 ——
    restrictions:                # 使用限制
      - "level:20"               # 需要等级 20
      - "permission:vip.use"     # 需要权限
    bind_on_acquire: true        # 拾取时灵魂绑定，见 灵魂绑定

    # —— 自定义 NBT ——
    nbt:
      "custom:key1": "value1"
      "custom:number": 42
      "custom:bool": true

`restrictions` 限制语法

写在 options.restrictions 列表里，装备 / 使用时校验，不满足会在 Lore 上标红并阻止使用（通过 canUse / QinhItemUseCheckEvent）：

写法	含义	谁来判
`level:20`	需要玩家等级 ≥ 20	QI 原生
`permission:xxx`	需要权限	QI 原生
`world:world_name`	需要在指定世界	QI 原生
`class:战士,法师`	需要职业	委托给 `QinhItemUseCheckEvent`（第三方实现）
自定义 `xxx:yyy`	自定义	委托给事件

详见 API 参考 → canUse。

4. `providers` 提供者段

Provider 是挂在物品上的「外部系统载荷」。键名是系统 ID，值是载荷（通常用 value 作为载荷键，也支持 raw / data / payload）。

yaml

my_item:
  providers:
    ap:                          # ① AttributePlus 属性
      value: '{"attack_damage":18,"crit_rate":0.12}'
    perm_effects:                # ② 穿戴常驻药水效果
      value: '{"strength":1,"speed":0}'
    legendinlay:                 # ③ Legendinlay 宝石孔元数据
      value: '{"set":"qi_blade_trio","slot":"weapon","sockets":["normal"]}'
    magicgem:                    # ④ MagicGem 宝石孔元数据
      value: '{...}'

ap — 战斗属性。详见属性与数值。
perm_effects — 穿戴时常驻的药水效果：{"效果名":放大等级}，0=I 级。
legendinlay / magicgem — 宝石孔载荷，通常由 GUI / gem-sockets 自动同步生成，详见宝石孔。

Provider 也可以写成多载体键的子段形式，开发者细节见 Provider 与桥。允许的载体键：value / raw / data / payload。

5. `material` 材质

material 决定物品的底层 ItemStack，两种写法：

不含 : 或 - → 当作原版 Material 名解析（如 diamond_sword、golden_apple）。
含 : 或 - → 当作外部物品源引用，把 CraftEngine / ItemsAdder / Nexo / MMOItems 等插件的成品物品整个拿来当底模（连同它自带的模型 / CMD / 组件）。

5.1 外部物品源引用（CraftEngine / ItemsAdder / Nexo 等）

解析交由 QinhCoreLib 的统一物品源系统（ItemSourceManager → ItemManagerAPI）。支持的前缀（别名）：

物品源	可用前缀
原版	`vanilla` / `minecraft` / `mc` / `v` / `material` / `type`
CraftEngine	`craftengine` / `ce` / `craft-engine`
ItemsAdder	`itemsadder` / `ia`
Nexo	`nexo` / `nx`
MMOItems	`mmoitems` / `mi`
NeigeItems	`neigeitems` / `ni`
MythicMobs	`mythicmobs` / `mm` / `mythic`
MagicGem	`magicgem` / `mg` / `magic-gem`
CustomFishing	`customfishing` / `cf`
QinhItems（自己）	`qinhitems` / `qi`

语法（ItemReferenceParser）：

yaml

material: ce:my_custom_sword       # 冒号写法
material: ce-my_custom_sword       # 短横写法（前缀必须在第一个 - 之前）
material: nexo:ruby_blade
material: ia:iron_katana
material: mi-SWORD-Legendary        # MMOItems 特例：mi-<类型>-<ID>
material: ni-blade::{"品质":"传说"} # 末尾 ::{json} 给后端传参

要点：

冒号 : 与短横 - 等价：ce:x ≡ ce-x。短横写法里，第一个 - 之前是前缀，之后是物品 ID。
接外部源时通常不用再配 resource_pack.custom_model_data——外部物品本身已带模型。CMD / 资源包路线见资源包与自定义模型。
后端插件没装 / 物品 ID 不存在 → 解析失败 → 物品 unhealthy。可用 /qi diagnose 看具体原因（SOURCE_NOT_FOUND = 前缀没注册即插件没装；ITEM_NOT_FOUND = 该插件里没这个物品）。
编辑器里改材质时也支持这些引用，输入提示即 例: iron_sword / craftengine:xxx。

这些前缀由 QinhCoreLib 统一提供，QI / QinhSkills 等全生态通用。完整说明见跨模块对接 → QI ↔ CoreLib。

材质解析失败会导致物品 unhealthy，在 /qi status / /qi diagnose 里报问题。

6. 完整注解示例

把上面所有要素拼在一起的一个真实复杂物品（武器，雷霆之刃风格）：

yaml

demo_thunder_edge:
  type: weapon
  material: golden_sword
  display_name: "<yellow>雷霆之刃</yellow>"
  item_name: "雷霆之刃"
  tier: EPIC
  lore:
    - ""
    - "<gray>左键挥动，召唤雷鸣</gray>"
    - "<dark_gray>冷却 3 秒</dark_gray>"
  providers:
    ap:
      value: '{"attack_damage":22,"crit_rate":0.12}'
  variables:
    star: "3"
  enchantments:
    sharpness: 3
    knockback: 1
  gem-sockets:
    - 绿色
    - qi_weapon
  sections:
    - quality_prefix_pool
  affixes:
    - legendary_weapon_affix
  options:
    unbreakable: true
    glow: true
    bind_on_acquire: false
    restrictions:
      - "level:20"
  resource_pack:
    custom_model_data: 12345
  actions:
    triggers:
      left_click:
        trigger:
          atom: left_click
        cooldown: 3s
        consume:
          - "item:minecraft-redstone:1"
        refs:
          - handler: qi:title
            payload: "<yellow>⚡ 雷霆 ⚡</yellow>||<gray>轰鸣回荡</gray>||3||30||10"
          - handler: qi:sound
            payload: "minecraft:entity.lightning_bolt.thunder;1;1.2"
  update:
    version: 1

🖼️ [图片占位] 上述雷霆之刃在游戏内的物品提示框（hover）截图，标注各 Lore 段对应哪个字段　·　建议 assets/item-anatomy.png

7. 物品健康检查

每次 /qi reload，QI 会对每个物品跑 healthIssues() 校验。常见报错：

报错原因	怎么修
`id` / `type` / `material` / `sourceFile` 为空	补齐必填字段
`display_name` 和 `lore` 同时缺失	至少给一个
`max_stack_size <= 0`	改成 1–99
类型未知	`type` 必须在 `item_types.yml` 里存在
材质未知	`material` 用合法原版材质名或外部源引用

不健康的物品仍会被加载，但会在 /qi status / /qi diagnose / /qi problems 里列出。

8. 重载与保存

改完 YAML → /qi reload 重新编译并热刷新在线玩家物品。
GUI 编辑保存 → EditorSaveGuard 先跑 PolicyEngine 校验，再写回 sourceFile，并热重载动作表。

校验规则（保存时你可能遇到的报错）详见资源包与开发者向的约束系统说明。

下一步

看有哪些类型可用、各能加什么 → 物品类型
给物品上属性 → 属性与数值
让物品有主动技能 → 动作系统

物品定义（item YAML 全字段） ​

1. 文件布局：按类型分组 ​

物品 ID 规范 ​

2. 顶层字段总表 ​

3. options 选项段 ​

restrictions 限制语法 ​

4. providers 提供者段 ​

5. material 材质 ​

5.1 外部物品源引用（CraftEngine / ItemsAdder / Nexo 等） ​

6. 完整注解示例 ​

7. 物品健康检查 ​

8. 重载与保存 ​

下一步 ​

物品定义（item YAML 全字段）

1. 文件布局：按类型分组

物品 ID 规范

2. 顶层字段总表

3. `options` 选项段

`restrictions` 限制语法

4. `providers` 提供者段

5. `material` 材质

5.1 外部物品源引用（CraftEngine / ItemsAdder / Nexo 等）

6. 完整注解示例

7. 物品健康检查

8. 重载与保存

下一步