🎯 统一物品源引用（核心页）
这是 QCL 最重磅、服主最常用的功能。一句话：不管物品来自原版还是任何外部插件，都用同一套字符串语法去引用它。本页把这套引用讲到可以照抄。
💡 概念：为什么要统一？
服务器上的物品来源五花八门——原版材料、QinhItems、MMOItems、NeigeItems、MythicMobs、CraftEngine、CustomFishing、MagicGem、ItemsAdder、Nexo……每个插件都有自己的取物 API 和写法。
QCL 的 ItemSourceManager 把这些全部抹平成一种引用字符串：你只写 源:物品ID（或 源-物品ID），QCL 负责解析成 (源, 物品ID, 可选JSON参数) 并构建出真正的 ItemStack。
这样带来的好处：
- 服主只学一套语法，到处都能用（QI 配置、CustomBlock、GUI、API）。
- 新增一个源（比如以后接 ItemsAdder/Nexo），所有调用方自动支持，子插件无需改动。
🔧 通用解析规则
| 规则 | 写法 | 说明 |
|---|---|---|
| 冒号分隔 | 别名:物品id | 如 qi:神剑 |
| 破折号分隔 | 别名-物品id | 如 ni-blade |
| 追加 JSON 参数 | 引用::{json} | :: 后跟 JSON，传给源 |
| 无分隔符 | 物品id | 默认当成原版 vanilla 材料 |
⚠️ 注意
::（两个冒号）专门用来追加 JSON 参数，和源分隔用的单个:不冲突。
📚 10 种源逐一讲解
1️⃣ 原版 Vanilla
| 项 | 内容 |
|---|---|
| 别名 | vanilla、minecraft、mc、v、material、type |
| 语法 | vanilla:材料名 或直接 材料名 |
| 示例 | DIAMOND_SWORD、vanilla:STONE |
| 依赖 | 无（原版即可） |
📌 物品 id 是 Bukkit Material 枚举名，全大写。无前缀时默认就是 vanilla，所以 DIAMOND_SWORD 等价于 vanilla:DIAMOND_SWORD。
2️⃣ QinhItems（QI）
| 项 | 内容 |
|---|---|
| 别名 | qinhitems、qi |
| 语法 | qi:物品id |
| 示例 | qi:神剑 |
| 依赖 | QinhItems |
📌 冒号分隔。
3️⃣ MMOItems
| 项 | 内容 |
|---|---|
| 别名 | mmoitems、mi |
| 语法 | mi-类型-物品id（内部转为 类型:物品id） |
| 示例 | mi-SWORD-烈焰剑 |
| 依赖 | MMOItems |
📌 必须两段：类型 + id。MMOItems 物品天然带「类型」（如 SWORD、ARMOR），缺一不可。
4️⃣ NeigeItems（NI）
| 项 | 内容 |
|---|---|
| 别名 | neigeitems、ni |
| 语法 | ni-物品id 或 ni-物品id::{JSON} |
| 示例 | ni-blade、ni-blade::{"品质":"传说"} |
| 依赖 | NeigeItems |
📌 NI 支持 :: 后传 JSON 参数（如指定品质、随机词条等）。
5️⃣ MythicMobs（MM）
| 项 | 内容 |
|---|---|
| 别名 | mythicmobs、mm、mythic |
| 语法 | mm-物品id |
| 示例 | mm-龙剑（支持中文 id） |
| 依赖 | MythicMobs |
6️⃣ CraftEngine（CE）
| 项 | 内容 |
|---|---|
| 别名 | craftengine、ce、craft-engine |
| 语法 | ce-命名空间_id 或 ce-命名空间:id |
| 示例 | ce-包名_物品、ce-包名:物品 |
| 依赖 | CraftEngine |
📌 首个下划线会自动转成冒号，所以 ce-包名_物品 等价于 ce-包名:物品。
7️⃣ CustomFishing（CF）
| 项 | 内容 |
|---|---|
| 别名 | customfishing、cf |
| 语法 | cf-物品id |
| 示例 | cf-宝箱 |
| 依赖 | CustomFishing |
8️⃣ MagicGem（MG）
| 项 | 内容 |
|---|---|
| 别名 | magicgem、mg、magic-gem |
| 语法 | mg-宝石id |
| 示例 | mg-钻石宝石 |
| 依赖 | MagicGem |
9️⃣ ItemsAdder（IA）
| 项 | 内容 |
|---|---|
| 别名 | itemsadder、ia |
| 语法 | ia-命名空间_id 或 ia-命名空间:id |
| 示例 | ia-包名_物品 |
| 依赖 | ItemsAdder |
📌 同 CraftEngine，首个下划线自动转冒号。
🔟 Nexo（NX）
| 项 | 内容 |
|---|---|
| 别名 | nexo、nx |
| 语法 | nx-id 或 nx-命名空间:id（取冒号后部分） |
| 示例 | nx-自定义剑 |
| 依赖 | Nexo |
📌 若写 nx-命名空间:id，实际取冒号后的 id 部分。
📊 总表速查
| 源 | 别名 | 引用语法 | 示例 |
|---|---|---|---|
| 原版 Vanilla | vanilla, minecraft, mc, v, material, type | vanilla:材料名 或直接 材料名 | DIAMOND_SWORD / vanilla:STONE |
| QinhItems | qinhitems, qi | qi:物品id | qi:神剑 |
| MMOItems | mmoitems, mi | mi-类型-物品id | mi-SWORD-烈焰剑 |
| NeigeItems | neigeitems, ni | ni-物品id 或 ni-物品id::{JSON} | ni-blade::{"品质":"传说"} |
| MythicMobs | mythicmobs, mm, mythic | mm-物品id | mm-龙剑 |
| CraftEngine | craftengine, ce, craft-engine | ce-命名空间_id 或 ce-命名空间:id | ce-包名:物品 |
| CustomFishing | customfishing, cf | cf-物品id | cf-宝箱 |
| MagicGem | magicgem, mg, magic-gem | mg-宝石id | mg-钻石宝石 |
| ItemsAdder | itemsadder, ia | ia-命名空间_id 或 ia-命名空间:id | ia-包名:物品 |
| Nexo | nexo, nx | nx-id 或 nx-命名空间:id | nx-自定义剑 |
🗒️ 20+ 即用引用示例清单
直接照抄改名即可：
# —— 原版 ——
DIAMOND_SWORD
vanilla:STONE
v:GOLDEN_APPLE
minecraft:OAK_LOG
material:NETHERITE_INGOT
# —— QinhItems ——
qi:神剑
qinhitems:回血药
# —— MMOItems ——
mi-SWORD-烈焰剑
mmoitems-ARMOR-龙鳞甲
# —— NeigeItems ——
ni-blade
ni-blade::{"品质":"传说"}
neigeitems-staff
# —— MythicMobs ——
mm-龙剑
mythic-神圣法杖
# —— CraftEngine ——
ce-包名_物品
ce-包名:物品
# —— CustomFishing ——
cf-宝箱
customfishing-金鱼
# —— MagicGem ——
mg-钻石宝石
magicgem-红宝石
# —— ItemsAdder ——
ia-包名_物品
ia-包名:物品
# —— Nexo ——
nx-自定义剑
nexo-命名空间:特殊盾✅ 可用性与错误码
每个源只有在对应插件装了且对应模块启用时才可用，否则该引用解析失败并返回错误码：
| 错误码 | 含义 | 怎么办 |
|---|---|---|
PARSE_FAILED | 引用格式写错 | 检查分隔符（冒号/破折号）、段数 |
MATERIAL_NOT_FOUND | 原版材料不存在 | 核对 Bukkit Material 枚举名（全大写） |
SOURCE_NOT_FOUND | 源未注册（插件没装或模块禁用） | 确认对应插件已安装、对应模块未被禁用 |
ITEM_NOT_FOUND | 源里没有这个物品 | 核对物品 id 是否正确、是否已在对应插件里配置 |
🔗 完整错误码见 诊断码。
🩺 诊断方法
/qcl status 末尾有「物品引用诊断」一项，它会实际测试解析 vanilla:stone。
- 诊断码
OK→ 物品源管道正常。 - 摘要里还会列出已注册的物品源数量 + 列表，可据此确认你的某个源是否被识别。
🩺 逐项解读见 诊断与排错。
👷 谁在用这套引用？
| 调用方 | 用法 |
|---|---|
| QinhItems | material 底物 / consume 消耗物 / give 给物 |
| QCL CustomBlock | item_sources 字段 |
| GUI | GUI 里的物品引用 |
| 开发者 | ItemManagerAPI.getHookItem(ref) |
🌟 关键设计：新增 ItemsAdder / Nexo 等源后，上述所有调用方自动支持，无需任何子插件改动。
📖 继续阅读
- ➡️ 下一页：诊断与排错 — 引用失败时如何排查
- 🔗 物品API —
ItemManagerAPI.getHookItem(ref)等接口 - 🔗 外部插件对接 · 物品类插件 — 各物品插件接入说明
- 📚 诊断码 · FAQ