Skip to main content

Vault Integration

EliteMobs can use a Vault economy provider instead of its internal currency balance. The plugin compiles against VaultAPI 1.7; install compatible Vault and economy plugins on the server.

Progression considerations​

EliteMobs progression combines weapon and armor skills, loot, and optional class training. Players normally earn gear and currency through EliteMobs combat. Bringing in money from another economy changes how quickly they can buy gear and services.

Review shop prices, loot resale values and paid services before connecting an outside economy.

The separate skill requirements still apply when enabled. Vault does not award skill XP, unlock classes, or bypass trainer trials. If you enable integration, tune your economy around EliteMobs shop and service prices so outside income does not overwhelm the rewards from combat.

Requirements​

To use Vault integration, you must have:

  • An enabled Vault plugin compatible with EliteMobs' VaultAPI calls
  • An economy plugin that registers a Vault Economy service
  • Both plugins properly configured and running

EliteMobs detects enabled Vault during initialization and selects its economy path when useVault is true. Detection alone does not prove that an economy provider was found.

Configuration​

To enable Vault integration:

  1. Ensure Vault plugin is installed on your server
  2. Ensure your economy plugin registers its Vault provider before EliteMobs initializes
  3. Open EconomySettings.yml in the EliteMobs plugin folder
  4. Set useVault: true
  5. Restart the server

Example configuration:

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

How It Works​

When Vault integration is active with a working provider:

  • Future currency operations use the Vault economy provider. Existing Elite Coins in the EliteMobs database are not automatically converted or transferred.
  • Players earn your economy currency instead of Elite Coins when killing Elite Mobs
  • Shop transactions and other services that charge currency use your server's economy. Repairs still consume scrap.
  • Vault owns the money balance; EliteMobs still tracks gambling debt and deducts it from incoming EliteMobs earnings before depositing the remainder.

Currency operations:

  • Deposits: Money is added to player's Vault balance
  • Withdrawals: Money is removed from player's Vault balance
  • Balance checks: Queries player's Vault balance
  • Direct balance setting: DISABLED for safety (use your economy plugin)

At initialization, enabled Vault plus useVault: true sets VAULT_ENABLED before looking up the provider. A missing provider can therefore leave Vault mode active with no usable economy. Balance queries then warn and return zero; ordinary deposits or withdrawals can fail, while checked purchase helpers return failure. With Vault absent or disabled on a fresh startup, the internal economy remains in use. An exception caught during Vault setup also disables Vault mode.

Once Vault mode is active, there is no automatic fallback or provider rebinding at runtime. Fix the provider registration and restart before accepting transactions. currencyName remains a separate EliteMobs display setting; enabling Vault does not automatically rename it.

Security Features​

For security reasons, EliteMobs does NOT support directly setting a player's currency balance through Vault. Any attempt to do so will be blocked and logged. Use your economy plugin's commands to set balances directly if needed.

Example Scenario​

Assume a reward pays 100 coins and the player has no gambling debt; this is an illustrative amount, not a fixed payout for every level 50 mob.

Without Vault:

  • Player kills level 50 Elite Mob
  • Receives 100 Elite Coins (stored in EliteMobs database)
  • Can spend Elite Coins in EliteMobs shops and services

With Vault:

  • Player kills level 50 Elite Mob
  • Receives 100 [your economy currency] (stored in Vault/economy plugin)
  • Can spend money in EliteMobs and other systems using that provider
  • Transfers from other players depend on the economy plugin's features
  • Economy is unified across all plugins

Outside income can accelerate access to gear and services. Skill requirements and class unlocks still apply independently.

Troubleshooting​

If Vault integration is enabled but not working:

  1. Check server logs for: "Vault detected." (in an EliteMobs log line)

    • If missing: Vault plugin is not installed or not loading

  2. Check for warning: "Vault preference detected. This is not the recommended setting."

    • This is expected when Vault integration is enabled - it's a reminder, not an error
    • If Vault still isn't working, ensure your economy plugin is properly registered with Vault

  3. Check for: "Player tried to check currency when they had no economy entry"

    • This is a generic null-reference warning, not proof of a missing player account. The cached economy provider itself may be null.
    • Check that the provider was registered before EliteMobs initialized, then inspect the economy plugin's account handling and logs.

  4. If enabled but EliteMobs still uses Elite Coins:

    • Verify config key is exactly: useVault: true
    • Restart server after config change
    • Check that an economy plugin is registered with Vault

  5. If balances show zero or transactions fail despite the detection message:

    • Confirm a provider was available during initialization; the detection message only confirms Vault itself.
    • Restore the provider and restart. EliteMobs does not automatically reconnect to a newly registered provider.

For Developers​

If you're developing an addon or integration:

  • Vault selection: VaultCompatibility.VAULT_ENABLED does not prove provider availability; getEconomy() can be null
  • Economy API: Use EconomyHandler methods (not VaultCompatibility directly)
  • Supported operations: add, subtract, check, checked credit, checked purchase withdrawal and purchase refund (set is disabled)
  • Every balance change must run on the server thread for a player whose EliteMobs data is loaded (EconomyHandler.isReady); otherwise it throws IllegalStateException.
  • tryCredit, tryWithdraw and refundPayment throw IllegalArgumentException for a negative or non-finite amount, and return false when Vault rejects the transaction or another change for that player is already in progress. tryCredit collects gambling debt first and saves the new debt only after Vault accepts the deposit; refundPayment bypasses debt collection.
  • addCurrency and subtractCurrency throw IllegalStateException when the provider rejects the change, instead of failing silently.
  • Currency precision: Internal system uses 2 decimal places
  • No runtime fallback: when VAULT_ENABLED is true, EconomyHandler always delegates to Vault; there is no automatic switch back to the internal economy

Source code location:

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

EliteMobs uses VaultAPI 1.7 as a compile-only dependency. The Vault plugin JAR must be present on the server at runtime.