跳到主要内容

Vault 集成

EliteMobs 可以使用 Vault 经济提供者来代替内部货币余额。插件针对 VaultAPI 1.7 编译；请在服务器上安装兼容的 Vault 和经济插件。

对进度的影响​

EliteMobs 的进度结合了武器和护甲技能、战利品以及可选的职业训练。玩家通常通过 EliteMobs 战斗获得装备和货币。从其他经济系统引入资金会改变玩家购买装备和服务的速度。

连接外部经济之前，请检查商店价格、战利品转售价格和付费服务。

启用技能要求后，这些独立要求仍然适用。Vault 不会授予技能经验、解锁职业或跳过训练师试炼。如果启用集成，请根据 EliteMobs 商店和服务价格调整经济，避免外部收入压过战斗奖励。

前置要求​

要使用 Vault 集成，你必须具备：

  • 已启用且兼容 EliteMobs 所用 VaultAPI 调用的 Vault 插件
  • 一个向 Vault 注册 Economy 服务的经济插件
  • 两个插件都已正确配置并运行

EliteMobs 在初始化时检测已启用的 Vault，并在 useVault 为 true 时选择 Vault 经济路径。仅检测到 Vault 并不能证明已找到经济提供者。

配置​

要启用 Vault 集成：

  1. 确保服务器上已安装 Vault 插件
  2. 确保经济插件在 EliteMobs 初始化之前注册其 Vault 提供者
  3. 打开 EliteMobs 插件文件夹中的 EconomySettings.yml
  4. 设置 useVault: true
  5. 重启服务器

配置示例：

# Whether to use Vault for the economy instead of the built-in system.
# NOT RECOMMENDED! See: https://wiki.nightbreak.io/EliteMobs/vault
useVault: false

工作原理​

当 Vault 集成已启用且提供者正常工作时：

  • 后续货币操作使用 Vault 的经济提供者。EliteMobs 数据库中已有的精英币不会自动转换或转移。
  • 玩家击杀精英怪时获得的是你的经济货币，而非精英币
  • 商店交易和其他收取货币的服务使用服务器经济。修理仍消耗碎片。
  • Vault 管理货币余额；EliteMobs 仍记录赌博债务，先从 EliteMobs 收入中扣除债务，再存入剩余金额。

货币操作：

  • 存入：金钱被加入玩家的 Vault 余额
  • 取出：金钱从玩家的 Vault 余额中扣除
  • 余额查询：查询玩家的 Vault 余额
  • 直接设置余额：出于安全考虑已禁用（请使用你的经济插件）

初始化时，如果 Vault 已启用且设置了 useVault: true，EliteMobs 会先设置 VAULT_ENABLED，再查找提供者。因此，缺少提供者也可能使 Vault 模式保持启用，但没有可用的经济服务。此时余额查询会警告并返回 0；普通存款或取款可能失败，而检查交易结果的购买辅助方法会返回失败。全新启动时，如果 Vault 未安装或未启用，则继续使用内部经济。Vault 设置过程中捕获到异常也会禁用 Vault 模式。

Vault 模式启用后，运行时不会自动回退或重新绑定提供者。在接受交易之前，请修复提供者注册并重启。currencyName 仍是独立的 EliteMobs 显示设置，启用 Vault 不会自动修改它。

安全特性​

出于安全原因，EliteMobs 不支持通过 Vault 直接设置玩家的货币余额。任何此类尝试都会被阻止并记录。如有需要，请使用你的经济插件的命令直接设置余额。

示例场景​

假设奖励为 100 金币，且玩家没有赌博债务；这个金额仅用于示例，并非每只 50 级怪物的固定奖励。

不使用 Vault：

  • 玩家击杀一只 50 级精英怪
  • 获得 100 精英币（存储在 EliteMobs 数据库中）
  • 可以在 EliteMobs 商店和服务中花费精英币

使用 Vault：

  • 玩家击杀一只 50 级精英怪
  • 获得 100 [你的经济货币]（存储在 Vault/经济插件中）
  • 可以在 EliteMobs 和使用同一提供者的其他系统中花钱
  • 其他玩家能否转账取决于经济插件的功能
  • 经济在所有插件之间实现统一

外部收入可以加快获得装备和服务的速度。技能要求和职业解锁条件仍然独立适用。

故障排查​

如果 Vault 集成已启用但无法工作：

  1. 检查服务器日志中是否有：“Vault detected.”（出现在某条 EliteMobs 日志行中）

    • 如果缺失：Vault 插件未安装或未加载

  2. 检查是否有警告：“Vault preference detected. This is not the recommended setting.”

    • 当启用 Vault 集成时这是预期内的——它是一条提醒，而非错误
    • 如果 Vault 仍无法工作，请确保你的经济插件已正确向 Vault 注册

  3. 检查是否有：“Player tried to check currency when they had no economy entry”

    • 这是一条通用的空引用警告，不能证明玩家账户缺失。缓存的经济提供者本身也可能为 null。
    • 确认提供者在 EliteMobs 初始化之前注册，然后检查经济插件的账户处理和日志。

  4. 如果已启用但 EliteMobs 仍在使用精英币：

    • 确认配置键确实是：useVault: true
    • 修改配置后重启服务器
    • 检查是否有一个经济插件已向 Vault 注册

  5. 如果出现检测消息，但余额显示为 0 或交易失败：

    • 确认初始化时已有可用的提供者；检测消息只确认 Vault 本身。
    • 恢复提供者并重启。EliteMobs 不会自动连接新注册的提供者。

面向开发者​

如果你正在开发扩展或集成：

  • Vault 选择：VaultCompatibility.VAULT_ENABLED 不代表提供者可用；getEconomy() 可能为 null
  • 经济 API：使用 EconomyHandler 方法（不要直接使用 VaultCompatibility）
  • 支持的操作：增加、扣除、查询、检查交易结果的入账、检查交易结果的购买扣款和购买退款（set 已禁用）
  • 每次余额变动都必须在服务器线程上、针对 EliteMobs 数据已加载的玩家执行（EconomyHandler.isReady）；否则会抛出 IllegalStateException。
  • 对于负数或非有限金额，tryCredit、tryWithdraw 和 refundPayment 会抛出 IllegalArgumentException；当 Vault 拒绝交易，或该玩家已有另一项变动正在进行时，它们返回 false。tryCredit 会先扣除赌博债务，并且只有在 Vault 接受存款后才保存新的债务；refundPayment 不扣除债务。
  • 当提供方拒绝变动时，addCurrency 和 subtractCurrency 会抛出 IllegalStateException，而不是静默失败。
  • 货币精度：内部系统使用 2 位小数
  • 无运行时回退：当 VAULT_ENABLED 为 true 时，EconomyHandler 始终委托给 Vault；不存在自动切回内部经济的机制

源代码位置：

  • src/main/java/com/magmaguy/elitemobs/economy/VaultCompatibility.java
  • src/main/java/com/magmaguy/elitemobs/economy/EconomyHandler.java

EliteMobs 使用 VaultAPI 1.7 作为仅编译期依赖（compile-only）。运行时服务器上必须存在 Vault 插件 JAR。