经济桥接 (Economy Bridge)

不同的服务器可能用不同的经济插件——有的用 Vault，有的用 ExcellentEconomy（原 CoinsEngine）。经济桥接把这些差异屏蔽掉，让上层模块只需要调同一套接口就能完成存取款操作，不用关心底层到底对接的是哪个插件。

支持的经济提供者

提供者	插件	多货币支持	说明
vault	Vault	否	用得最广泛的经济 API，只支持单一货币
excellenteconomy	ExcellentEconomy	是	支持多货币的经济插件（原 CoinsEngine）

提供者选择逻辑

启动时，经济服务会按以下逻辑决定用哪个提供者：

1. 检查 config.yml 中是否显式指定了 economy.provider
   ├─ 是 → 使用指定的提供者
   └─ 否 → 进入自动检测
2. 自动检测（auto 模式）
   ├─ 检测 ExcellentEconomy → 已安装 → 使用 ExcellentEconomy
   └─ 检测 Vault            → 已安装 → 使用 Vault
3. 均未安装 → 经济服务不可用，相关动作会返回错误

自动检测时 ExcellentEconomy 优先级高于 Vault，因为它功能更丰富。如果你同时装了两个但想用 Vault，就需要在配置里显式指定。

配置示例

# config.yml
economy:
  # 提供者选择：auto / vault / excellenteconomy
  provider: auto

  # ExcellentEconomy 默认货币（仅 ExcellentEconomy 生效）
  excellenteconomy:
    default_currency: "coins"

提示

大多数情况下 auto 就够了。只有当服务器同时装了多个经济插件、且你需要指定优先用哪个时，才需要显式配置 provider。

从 CoinsEngine 迁移

如果你之前配置了 provider: coinsengine，需要改为 provider: excellenteconomy。动作中的 provider=coinsengine 也需要改为 provider=excellenteconomy。

在动作中使用

经济相关的动作都支持可选的 provider 和 currency 参数，不写就用默认的。

givemoney — 给予金币

actions:
  # 使用默认提供者和货币
  - "givemoney amount=100"

  # 指定提供者
  - "givemoney amount=100 provider=vault"

  # 指定 ExcellentEconomy 的特定货币
  - "givemoney amount=50 provider=excellenteconomy currency=gems"

takemoney — 扣除金币

actions:
  # 扣除 50 金币（默认提供者）
  - "takemoney amount=50"

  # 余额不足时动作会失败并中断后续动作链
  # 加 @ignore_failure 可以跳过失败继续往下走
  - "@ignore_failure takemoney amount=9999"
  - "sendmessage message=<yellow>扣款尝试完成"

注意

takemoney 在余额不足时会返回 ECONOMY_INSUFFICIENT 错误并中断动作链。如果你希望余额不足时不影响后续动作，记得加 @ignore_failure 前缀。

setmoney — 设置余额

actions:
  # 将余额设置为 1000
  - "setmoney amount=1000"

  # 指定提供者和货币
  - "setmoney amount=500 provider=excellenteconomy currency=points"

参数说明

参数	必填	说明
amount	是	金额（支持小数）
provider	否	经济提供者（vault / excellenteconomy），不写就用配置里的默认值
currency	否	货币类型（仅 ExcellentEconomy 有效），不写就用 default_currency

自定义提供者注册

如果你用的经济插件不在内置支持列表里，可以自己注册一个提供者：

EconomyService economyService = EmakiServiceRegistry.get(EconomyService.class);

economyService.registerProvider("my_economy", new EconomyProvider() {
    @Override
    public double getBalance(Player player, String currency) {
        return MyEconomyAPI.getBalance(player);
    }

    @Override
    public boolean deposit(Player player, double amount, String currency) {
        return MyEconomyAPI.deposit(player, amount);
    }

    @Override
    public boolean withdraw(Player player, double amount, String currency) {
        if (MyEconomyAPI.getBalance(player) < amount) {
            return false;
        }
        return MyEconomyAPI.withdraw(player, amount);
    }

    @Override
    public boolean setBalance(Player player, double amount, String currency) {
        return MyEconomyAPI.setBalance(player, amount);
    }

    @Override
    public String getDefaultCurrency() {
        return "default";
    }
});

注册之后就可以在动作里通过 provider=my_economy 来使用了：

actions:
  - "givemoney amount=100 provider=my_economy"

提示

自定义提供者应该在插件的 onEnable 阶段注册，确保在其他模块用到经济动作之前就绑定好。withdraw 方法在余额不足时要返回 false，系统会自动把它转成 ECONOMY_INSUFFICIENT 错误。