Previous: ../02-服主指南/诊断与排错.md　·　Next: 物品类插件.md Related: 物品类插件.md · 方块模型作物.md · 经济插件.md · ../02-服主指南/物品源引用.md

🧩 External Plugin Integration · Overview

QinhCoreLib (QCL) can cooperate with a large set of third-party plugins on the server: it lets items from other plugins be referenced uniformly by QI/GUI/CustomBlock/API, and lets capabilities like blocks, models, crops, and economy be reused directly. This page explains the design philosophy of the integration, how to confirm it's connected, and provides a master matrix of all plugins. Per-plugin details are spread across three sub-pages.

---

🛟 Design philosophy: soft dependency + reflection bridge, skip if not installed

QCL follows the same set of rules for integration with all third-party plugins, which can be summed up in three sentences:

Principle	Meaning
Soft dependency (softdepend)	QCL does not hard-depend on any third-party plugin. It starts up normally even if none are installed, and never reports "missing dependency" and refuses to load.
Reflection bridge	QCL does not import third-party plugin classes at compile time; instead it calls them at runtime via reflection. This way, even if the other plugin isn't installed or has changed versions, QCL itself won't crash because it "can't find a class".
Degrade rather than crash	When the corresponding plugin isn't installed, the bridge's isAvailable() returns false, and each capability method returns null / false. The caller gets an empty result and treats it as "that item source is unavailable", rather than throwing an exception and blowing up the server.

💡 In one sentence: installed = automatically connected, not installed = silently skipped. You don't need to delete config or change anything just because "I haven't installed some plugin".

🔌 When is a bridge probed?

Each bridge probes once when its corresponding module loads (detecting whether the target class exists and whether the key methods can be reflected). On a successful probe, it is registered as hookedBridge in the startup summary and written into the BridgeStatusRegistry.

# In the startup summary you'll see "hooked bridge" entries like these
hookedBridge: MMOItems
hookedBridge: CraftEngine
hookedBridge: Vault

---

🔍 How to confirm it's connected

After installing the third-party plugin and restarting the server, one command confirms it:

/qcl status detail

This detailed status lists the integration situation bridge by bridge, read from the BridgeStatusRegistry. You should pay attention to:

What you want to confirm	Where to look
Whether a given bridge is available	The isAvailable status on that bridge's row
Whether MythicMobs is connecting to the modern or legacy version	The bindMode in that bridge's diagnostics (dual binding, detailed on the items page below)
Which economy backend was actually chosen	The economy-related row + the economy.default-provider config

⚠️ If you've installed a plugin but its bridge still shows as unavailable in /qcl status detail:

1. Confirm the third-party plugin itself loaded successfully first (check its own startup log).
2. Confirm the plugin version didn't drastically change class names — the reflection bridge does its best for multi-version compatibility, but in extreme cases the probe can still fail.
3. Reload with /qcl reload and check again (a reload refreshes the external item modules).

---

🗺️ Master matrix of all plugins

The table below covers all third-party plugins QCL currently integrates with — item types, block/model/crop types, and economy types.

🎒 Items (provide item-fetching capability, paired with unified item source references)

Plugin	Bridge class	Reference prefix	Main capability
MMOItems	MMOItemsBridge	mi-type-id	Fetch item by "type + id"
NeigeItems	NeigeItemsBridge	ni-id	Fetch item by id
MythicMobs	MythicMobsBridge	mm-id	Fetch item by id (amount optional)
MagicGem	MagicGemBridge	mg-id	Fetch gem item, check whether a gem exists
CustomFishing	CustomFishingBridge	cf-id	Build item (amount optional)
ItemsAdder	ItemsAdderBridge	ia-namespace_id	Build item stack
Nexo	NexoBridge	nx-id	Build item stack
CraftEngine	CraftEngineBridge	ce-namespace_id	Build item + block/furniture (see blocks page)
QinhItems	internal QinhItemsItemSource	qi:id	Reflect QinhItemRegistry.create(id, amount)

These bridges let the corresponding items be referenced by QI / GUI / CustomBlock / API through the unified reference syntax. For per-plugin details see 👉 物品类插件.md.

🧱 Blocks / models / crops

Plugin	Bridge class	Purpose
CraftEngine	CraftEngineBridge / CraftEngineManager	Custom items / block-placement recognition / furniture-placement recognition
(abstraction layer)	CustomBlockBridge + CustomBlockProvider	A unified "custom block" abstraction, with a built-in CraftEngine provider
ModelEngine	ModelEngineBridge / Manager	Modeled entities, playing animations, bone item-holding
CustomCrops	CustomCropsBridge / Manager	Crop recognition / harvest / planting / growth / bone meal

For details see 👉 方块模型作物.md.

💰 Economy

Backend	provider id	Currency model	Implementation
Vault	vault	Single currency	Obtained via service registration
ExcellentEconomy	excellenteconomy (ee)	Multiple currencies	Reflection API
PlayerPoints	playerpoints (pp)	Single point currency (integer)	Reflection API

All managed uniformly by EconomyBridge, which registers the "installed and enabled" backends in order. For details see 👉 经济插件.md.

---

🧰 The shared compatibility base: ReflectionBridge

All bridges achieve "multi-version compatibility, no crash on missing class" thanks to a common underlying set of reflection utilities:

• ReflectionBridge: isClassAvailable(className) — determines whether a given class exists in the current runtime environment (the first step of a bridge probe).
• ReflectionCache: caches method/field lookups to avoid repeated reflection overhead, providing utilities like getClazz / getMethod / getDeclaredMethod / findMethodByName / getField / findFieldInHierarchy / invoke / invokeStatic / get / set / safeCall.

Precisely because of this wrapper layer, a bridge can still find the correct method signature when "different major versions of the same plugin have different class names". For the developer-side details see ../04-开发者/工具集.md.

---

✅ Standard procedure for integrating a third-party plugin

1. Install the third-party plugin normally (confirm it can load on its own).
2. Restart the server (or start QCL first, then /qcl reload).
3. Run /qcl status detail, and confirm the corresponding bridge's isAvailable is true and that there's a hookedBridge entry in the startup summary.
4. Items: go to 物品源引用.md and try referencing with the corresponding prefix; blocks/models/crops: see the corresponding page; economy: configure economy.default-provider then verify via a GUI economy action or the API.

---

📚 Continue reading

• 🎒 物品类插件.md — detailed walkthrough of the nine item bridges, reference prefixes, and examples.
• 🧱 方块模型作物.md — CraftEngine / ModelEngine / CustomCrops.
• 💰 经济插件.md — comparison of the three backends, auto source selection, config setup.
• 🔗 ../02-服主指南/物品源引用.md — overview of the unified item source reference syntax.
• 🔧 ../04-开发者/工具集.md — ReflectionBridge / ReflectionCache developer API.