上一页：../02-服主指南/诊断与排错.md　·　下一页：物品类插件.md 相关：物品类插件.md · 方块模型作物.md · 经济插件.md · ../02-服主指南/物品源引用.md

🧩 外部插件对接 · 概览

QinhCoreLib（QCL）可以和服务器上的一大批第三方插件协作：让别的插件的物品能被 QI/GUI/CustomBlock/API 统一引用，让方块、模型、作物、经济这些能力直接复用。本页讲清楚对接的设计哲学、如何确认接上了，并给出一张全插件总矩阵。逐插件细节分散在三个细分页。

🛟 设计哲学：软依赖 + 反射桥，未装就跳过

QCL 对所有第三方插件的对接都遵循同一套规矩，可以用三句话概括：

原则	含义
软依赖（softdepend）	QCL 不硬依赖任何第三方插件。没装也能正常启动，绝不报「缺少依赖」而拒绝加载。
反射桥（reflection bridge）	QCL 不在编译期 import 第三方插件的类，而是运行时通过反射调用。这样即便对方插件没装、或换了版本，QCL 自身也不会因为「找不到类」而崩溃。
降级而非崩溃	没装对应插件时，桥的 `isAvailable()` 返回 `false`，各能力方法返回 `null` / `false`。调用方拿到空结果，按「该物品源不可用」处理，而不是抛异常炸服。

💡 一句话：装了就自动接上，没装就静默跳过。你不需要为「我没装某插件」去删配置或改任何东西。

🔌 桥是什么时候探测的？

每个桥都在对应模块 load 时做一次探测（检测目标类是否存在、能否反射到关键方法）。探测成功，会在启动摘要里以 hookedBridge 登记，并写入 BridgeStatusRegistry（桥接状态注册表）。

text

# 启动摘要里会看到类似这样的「已挂接桥」登记
hookedBridge: MMOItems
hookedBridge: CraftEngine
hookedBridge: Vault

🔍 如何确认接上了

装好第三方插件、重启服务器后，用一条命令即可确认：

text

/qcl status detail

这条详细状态会逐桥列出对接情况，从 BridgeStatusRegistry 读取。你应当关注：

你想确认的事	看哪里
某个桥是否可用	该桥这一行的 `isAvailable` 状态
MythicMobs 接的是现代版还是遗留版	该桥诊断里的 `bindMode`（双绑定，下文物品页详述）
经济后端实际选了谁	经济相关行 + `economy.default-provider` 配置

⚠️ 如果你装了插件，但 /qcl status detail 里对应桥仍然显示不可用：
确认第三方插件自己先加载成功（看它自己的启动日志）。
确认插件版本没有大改类名 —— 反射桥已尽量做多版本兼容，但极端情况下仍可能探测失败。
用 /qcl reload 重载后再看一次（重载会刷新外部物品模块）。

🗺️ 全插件总矩阵

下表涵盖 QCL 当前对接的全部第三方插件 —— 物品类、方块/模型/作物类、经济类。

🎒 物品类（提供取物品能力，配合统一物品源引用）

插件	桥类	引用前缀	主要能力
MMOItems	`MMOItemsBridge`	`mi-类型-id`	按「类型 + id」取物品
NeigeItems	`NeigeItemsBridge`	`ni-id`	按 id 取物品
MythicMobs	`MythicMobsBridge`	`mm-id`	按 id 取物品（可带数量）
MagicGem	`MagicGemBridge`	`mg-id`	取宝石物品、判断宝石是否存在
CustomFishing	`CustomFishingBridge`	`cf-id`	构建物品（可带数量）
ItemsAdder	`ItemsAdderBridge`	`ia-命名空间_id`	构建物品堆叠
Nexo	`NexoBridge`	`nx-id`	构建物品堆叠
CraftEngine	`CraftEngineBridge`	`ce-命名空间_id`	构建物品 + 方块/家具（见方块页）
QinhItems	内部 `QinhItemsItemSource`	`qi:id`	反射 `QinhItemRegistry.create(id,数量)`

这些桥让对应物品能通过统一引用语法被 QI / GUI / CustomBlock / API 引用。逐插件细节见 👉 物品类插件.md。

🧱 方块 / 模型 / 作物类

插件	桥类	用途
CraftEngine	`CraftEngineBridge` / `CraftEngineManager`	自定义物品 / 方块放置识别 / 家具放置识别
（抽象层）	`CustomBlockBridge` + `CustomBlockProvider`	统一的「自定义方块」抽象，内置 CraftEngine 提供者
ModelEngine	`ModelEngineBridge` / `Manager`	模型化实体、播放动画、骨骼持物
CustomCrops	`CustomCropsBridge` / `Manager`	作物识别 / 收获 / 种植 / 生长 / 骨粉

细节见 👉 方块模型作物.md。

💰 经济类

后端	provider id	货币模型	实现方式
Vault	`vault`	单货币	服务注册获取
ExcellentEconomy	`excellenteconomy`（`ee`）	多货币	反射 API
PlayerPoints	`playerpoints`（`pp`）	单点券（整数）	反射 API

全部由 EconomyBridge 统一管理，按序注册「装了且启用」的后端。细节见 👉 经济插件.md。

🧰 共同的兼容基座：ReflectionBridge

所有桥能做到「多版本兼容、缺类不崩」，靠的是底层一套通用反射工具：

ReflectionBridge：isClassAvailable(类名) —— 判断某个类在当前运行环境是否存在（桥探测的第一步）。
ReflectionCache：缓存方法/字段查找，避免重复反射开销，提供 getClazz / getMethod / getDeclaredMethod / findMethodByName / getField / findFieldInHierarchy / invoke / invokeStatic / get / set / safeCall 等工具。

正因为有这层封装，桥才能在「同一个插件的不同大版本类名不同」时仍然找到正确的方法签名。开发者侧细节见 ../04-开发者/工具集.md。

✅ 接入第三方插件的标准流程

把第三方插件正常装好（确认它自己能加载）。
重启服务器（或先启 QCL、再 /qcl reload）。
执行 /qcl status detail，确认对应桥 isAvailable 为真、启动摘要里有 hookedBridge 登记。
物品类：到物品源引用.md 用对应前缀引用试试；方块/模型/作物：见对应页；经济：配 economy.default-provider 后用 GUI 经济动作或 API 验证。

📚 继续阅读

🎒 物品类插件.md —— 九个物品桥逐一详解、引用前缀与示例。
🧱 方块模型作物.md —— CraftEngine / ModelEngine / CustomCrops。
💰 经济插件.md —— 三后端对比、auto 选源、config 配法。
🔗 ../02-服主指南/物品源引用.md —— 统一物品源引用语法总览。
🔧 ../04-开发者/工具集.md —— ReflectionBridge / ReflectionCache 开发者 API。

🧩 外部插件对接 · 概览 ​

🛟 设计哲学：软依赖 + 反射桥，未装就跳过 ​

🔌 桥是什么时候探测的？ ​

🔍 如何确认接上了 ​

🗺️ 全插件总矩阵 ​

🎒 物品类（提供取物品能力，配合统一物品源引用） ​

🧱 方块 / 模型 / 作物类 ​

💰 经济类 ​

🧰 共同的兼容基座：ReflectionBridge ​

✅ 接入第三方插件的标准流程 ​

📚 继续阅读 ​