Previous: Commands & Permissions　·　Next: Diagnostics & Troubleshooting

🎯 Unified Item-Source Reference (Core Page)

This is QCL's flagship feature and the one server owners use most often. In one sentence: no matter whether an item comes from vanilla or any external plugin, you reference it with the same string syntax. This page explains the reference grammar thoroughly enough to copy verbatim.

---

💡 Concept: Why unify?

Items on a server come from all over the place — vanilla materials, QinhItems, MMOItems, NeigeItems, MythicMobs, CraftEngine, CustomFishing, MagicGem, ItemsAdder, Nexo… Each plugin has its own item-retrieval API and notation.

QCL's ItemSourceManager flattens all of these into one reference string: you just write source:itemID (or source-itemID), and QCL parses it into (source, itemID, optional JSON parameters) and builds the real ItemStack.

The benefits of this:

• Server owners learn only one syntax, usable everywhere (QI config, CustomBlock, GUI, API).
• Adding a new source (e.g. wiring up ItemsAdder/Nexo later) is automatically supported by every caller, with no changes needed in the sub-plugins.

---

🔧 General parsing rules

Rule	Notation	Description
Colon separator	alias:itemID	e.g. qi:神剑
Dash separator	alias-itemID	e.g. ni-blade
Append JSON parameters	reference::{json}	JSON after ::, passed to the source
No separator	itemID	Treated as a vanilla material by default

⚠️ Note that :: (two colons) is dedicated to appending JSON parameters and does not conflict with the single : used as a source separator.

---

📚 The 10 sources explained one by one

1️⃣ Vanilla

Item	Content
Aliases	vanilla, minecraft, mc, v, material, type
Syntax	vanilla:materialName or just materialName
Example	DIAMOND_SWORD, vanilla:STONE
Dependency	None (vanilla suffices)

📌 The item ID is the Bukkit Material enum name, in all uppercase. With no prefix it defaults to vanilla, so DIAMOND_SWORD is equivalent to vanilla:DIAMOND_SWORD.

---

2️⃣ QinhItems (QI)

Item	Content
Aliases	qinhitems, qi
Syntax	qi:itemID
Example	qi:神剑
Dependency	QinhItems

📌 Colon separator.

---

3️⃣ MMOItems

Item	Content
Aliases	mmoitems, mi
Syntax	mi-type-itemID (internally converted to type:itemID)
Example	mi-SWORD-烈焰剑
Dependency	MMOItems

📌 Must be two segments: type + id. MMOItems items inherently carry a "type" (such as SWORD, ARMOR); neither can be omitted.

---

4️⃣ NeigeItems (NI)

Item	Content
Aliases	neigeitems, ni
Syntax	ni-itemID or ni-itemID::{JSON}
Example	ni-blade, ni-blade::{"品质":"传说"}
Dependency	NeigeItems

📌 NI supports passing JSON parameters after :: (such as specifying quality, random affixes, etc.).

---

5️⃣ MythicMobs (MM)

Item	Content
Aliases	mythicmobs, mm, mythic
Syntax	mm-itemID
Example	mm-龙剑 (Chinese IDs supported)
Dependency	MythicMobs

---

6️⃣ CraftEngine (CE)

Item	Content
Aliases	craftengine, ce, craft-engine
Syntax	ce-namespace_id or ce-namespace:id
Example	ce-包名_物品, ce-包名:物品
Dependency	CraftEngine

📌 The first underscore is automatically converted to a colon, so ce-包名_物品 is equivalent to ce-包名:物品.

---

7️⃣ CustomFishing (CF)

Item	Content
Aliases	customfishing, cf
Syntax	cf-itemID
Example	cf-宝箱
Dependency	CustomFishing

---

8️⃣ MagicGem (MG)

Item	Content
Aliases	magicgem, mg, magic-gem
Syntax	mg-gemID
Example	mg-钻石宝石
Dependency	MagicGem

---

9️⃣ ItemsAdder (IA)

Item	Content
Aliases	itemsadder, ia
Syntax	ia-namespace_id or ia-namespace:id
Example	ia-包名_物品
Dependency	ItemsAdder

📌 Same as CraftEngine, the first underscore is automatically converted to a colon.

---

🔟 Nexo (NX)

Item	Content
Aliases	nexo, nx
Syntax	nx-id or nx-namespace:id (takes the part after the colon)
Example	nx-自定义剑
Dependency	Nexo

📌 If you write nx-namespace:id, it actually takes the id part after the colon.

---

📊 Quick-reference master table

Source	Aliases	Reference syntax	Example
Vanilla	vanilla, minecraft, mc, v, material, type	vanilla:materialName or just materialName	DIAMOND_SWORD / vanilla:STONE
QinhItems	qinhitems, qi	qi:itemID	qi:神剑
MMOItems	mmoitems, mi	mi-type-itemID	mi-SWORD-烈焰剑
NeigeItems	neigeitems, ni	ni-itemID or ni-itemID::{JSON}	ni-blade::{"品质":"传说"}
MythicMobs	mythicmobs, mm, mythic	mm-itemID	mm-龙剑
CraftEngine	craftengine, ce, craft-engine	ce-namespace_id or ce-namespace:id	ce-包名:物品
CustomFishing	customfishing, cf	cf-itemID	cf-宝箱
MagicGem	magicgem, mg, magic-gem	mg-gemID	mg-钻石宝石
ItemsAdder	itemsadder, ia	ia-namespace_id or ia-namespace:id	ia-包名:物品
Nexo	nexo, nx	nx-id or nx-namespace:id	nx-自定义剑

---

🗒️ A ready-to-use list of 20+ reference examples

Just copy and rename:

# —— Vanilla ——
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-命名空间:特殊盾

---

✅ Availability and error codes

Each source is only available when its corresponding plugin is installed and its corresponding module is enabled; otherwise the reference fails to resolve and returns an error code:

Error code	Meaning	What to do
PARSE_FAILED	The reference format is written incorrectly	Check the separators (colon/dash) and the number of segments
MATERIAL_NOT_FOUND	The vanilla material does not exist	Verify the Bukkit Material enum name (all uppercase)
SOURCE_NOT_FOUND	The source is not registered (plugin not installed or module disabled)	Confirm the corresponding plugin is installed and the corresponding module is not disabled
ITEM_NOT_FOUND	The source does not contain this item	Verify the item ID is correct and that it has been configured in the corresponding plugin

🔗 For the complete list of error codes see Diagnostic Codes.

---

🩺 Diagnostic method

The end of /qcl status has an "Item Reference Diagnostics" item that actually tests parsing vanilla:stone.

• Diagnostic code OK → the item-source pipeline is working.
• The summary also lists the number of registered item sources + the list, so you can confirm whether one of your sources is recognized.

🩺 For a line-by-line interpretation see Diagnostics & Troubleshooting.

---

👷 Who uses this reference system?

Caller	Usage
QinhItems	material base item / consume item / give item
QCL CustomBlock	the item_sources field
GUI	item references in the GUI
Developers	ItemManagerAPI.getHookItem(ref)

🌟 Key design: After adding a source such as ItemsAdder / Nexo, all of the callers above support it automatically, with no changes required in any sub-plugin.

---

📖 Continue reading

• ➡️ Next: Diagnostics & Troubleshooting — how to troubleshoot when a reference fails
• 🔗 Item API — interfaces such as ItemManagerAPI.getHookItem(ref)
• 🔗 External Plugin Integration · Item Plugins — integration notes for each item plugin
• 📚 Diagnostic Codes　·　FAQ