上一页：方块模型作物.md · 下一页：../04-开发者/经济API.md 相关：../02-服主指南/经济动作.md · ../04-开发者/经济API.md · ../02-服主指南/配置文件.md
💰 经济插件对接
QCL 通过 EconomyBridge 统一对接三个经济后端：Vault、ExcellentEconomy、PlayerPoints。GUI 经济动作、经济 API 全都走这一层，你的上层配置/代码不需要关心底层装的是哪个插件。
🛟 同样遵循软依赖 + 反射桥：初始化时按序
registerOptional，只有「装了且启用」的后端才会被注册，没装就跳过，绝不影响启动。
⚖️ 三后端对比
| 维度 | Vault | ExcellentEconomy | PlayerPoints |
|---|---|---|---|
| provider id | vault | excellenteconomy（别名 ee） | playerpoints（别名 pp） |
| 货币模型 | 单货币 | 多货币（money/gold/silver…） | 单点券 |
currency 参数 | 忽略 | 每次操作必填 | 忽略 |
| 离线玩家 | ✅ 支持 | ❌ 仅在线 | ✅ 支持 |
| 数据类型 | Double | Double | 整数（Double 会四舍五入） |
| 实现方式 | 服务注册获取 net.milkbowl.vault.economy.Economy | 反射 su.nightexpress.excellenteconomy.api.ExcellentEconomyAPI | 反射 PlayerPoints.getInstance().getAPI() |
| 推荐用途 | 通用主货币、和其它插件兼容性最好 | 需要多种货币（金币/银币/点数分账）时 | 纯点券/积分体系 |
⚠️ ExcellentEconomy 的多货币是双刃剑：好处是一套插件管多种货币；代价是每次余额操作都必须指定
currencyId（如money、gold、silver），否则会报CURRENCY_REQUIRED。⚠️ PlayerPoints 是整数体系：传入的
Double会被四舍五入。别指望小数点券。
🧭 auto 选源逻辑
economy.default-provider 设为 auto（默认）时，QCL 自动挑后端，规则如下：
| 情况 | 选源优先级 |
|---|---|
指定了 currency | 优先 ExcellentEconomy（因为只有它支持多货币） |
没指定 currency | Vault > ExcellentEconomy > PlayerPoints，返回第一个可用的 |
auto + 带 currency → ExcellentEconomy 优先
auto + 不带 currency → Vault ▶ ExcellentEconomy ▶ PlayerPoints（取第一个可用）💡 装了多个经济插件、又想强制用某一个？别用
auto，直接把default-provider写死成vault/ee/pp。
⚙️ config 配置
经济相关配置在主 config（详见 ../02-服主指南/配置文件.md）：
economy:
# auto | vault | excellenteconomy(ee) | playerpoints(pp)
default-provider: auto
# 默认货币 id，仅对支持多货币的后端（ExcellentEconomy）有意义
default-currency: money| 配置键 | 取值 | 说明 |
|---|---|---|
economy.default-provider | auto / vault / excellenteconomy / ee / playerpoints / pp | 选哪个后端；auto 见上文规则 |
economy.default-currency | 货币 id（默认 money） | 不显式指定 currency 时用它；单货币后端忽略 |
📋 三种典型配法
# 1️⃣ 只有 Vault，单货币（最常见）
economy:
default-provider: vault# 2️⃣ 用 ExcellentEconomy 的多货币，默认货币设成 gold
economy:
default-provider: ee
default-currency: gold# 3️⃣ 纯点券服
economy:
default-provider: pp🔧 EconomyProvider 能力
每个后端在内部都实现 EconomyProvider 接口，能力一致：
| 方法 | 作用 |
|---|---|
id | 后端标识（vault / excellenteconomy / playerpoints） |
isAvailable | 该后端当前是否可用 |
getBalance(...) | 查余额 |
has(...) | 是否有足够余额 |
deposit(...) | 存入 |
withdraw(...) | 扣除 |
setBalance(...) | 直接设置余额 |
所有操作返回 EconomyTransactionResult：
| 字段 | 含义 |
|---|---|
success | 是否成功 |
message | 人类可读消息 |
code | 结果码（如 CURRENCY_REQUIRED） |
suggestion | 修复建议 |
provider | 实际处理的后端 |
开发者如何直接调用这些方法，见 👉 ../04-开发者/经济API.md。
🖱️ 与 GUI 经济动作的关系
服主在 GUI 里用的经济动作 give_money / take_money / set_money，底层正是调用上面的 deposit / withdraw / setBalance。也就是说：
GUI 动作 give_money/take_money/set_money
│
▼
EconomyBridge → 选中的 EconomyProvider → 真正的经济插件动作的 value 写法（金额、currency 等）见 👉 ../02-服主指南/经济动作.md。
🩺 诊断
经济相关问题，EconomyDiagnostics 会给出明确提示：
| 诊断 | 含义 |
|---|---|
unavailable() | 没有任何经济后端可用（一个都没装/没启用） |
providerMissing(id) | 你指定的 provider id 对应的插件没装 |
currencyMissing(id) | 指定的货币 id 不存在（多货币后端常见） |
可配合 /qcl status detail 一起看经济桥状态。
❓ 常见问题
Q：用了 ExcellentEconomy，操作报 CURRENCY_REQUIRED？ A：EE 是多货币后端，每次操作都得带 currency。要么在动作/调用里显式指定，要么把 economy.default-currency 配成一个有效货币（如 money）。
Q：点券出现小数 / 数额对不上？ A：PlayerPoints 是整数体系，传入的 Double 会四舍五入。改用 Vault/EE 才能保留小数。
Q：离线玩家给钱失败？ A：ExcellentEconomy 仅支持在线玩家。需要给离线玩家发钱，用 Vault 或 PlayerPoints。
Q：装了好几个经济插件，QCL 用了哪个？ A：auto 模式按「带不带 currency」走优先级（见上文）。想锁定就把 default-provider 写死成具体 id，并用 /qcl status detail 确认实际命中的 provider。
Q：一个经济插件都没装会怎样？ A：经济后端一个都不注册，相关操作返回失败（unavailable()），但不影响 QCL 及其它功能启动。
📚 继续阅读
- 🖱️ ../02-服主指南/经济动作.md —— GUI 里 give/take/set_money 的写法。
- 🧑💻 ../04-开发者/经济API.md —— 在代码里调用 EconomyBridge / EconomyProvider。
- ⚙️ ../02-服主指南/配置文件.md ——
economy.*配置项全表。 - 🧩 概览.md —— 外部插件对接总览。