Vault3

繁體中文 · English

A complete economy system for Spigot and Paper that registers itself as the Vault economy provider. Plugins that depend: [Vault] and call net.milkbowl.vault.economy.Economy keep working exactly as before — you do not need to install Vault.jar alongside it.

Why another economy plugin

Most economy plugins are fine until your server gets busy. Vault3 is built around the two things that actually break at scale: main-thread blocking and losing money.

Nothing touches the main thread

A transaction marks the account dirty and returns. Writes happen asynchronously, debounced, and only for the balances that actually changed — never the whole table.

On a 200-player server, a shop purchase used to mean a 200-row batch upsert while the server waited on the database. Now it means one row, off-thread.

Transactions are atomic

withdrawPlayer and depositPlayer are single atomic operations on the account. Two plugins hitting the same balance at the same time — a shop and a daily-reward task, for example — cannot overwrite each other. Under an 8-thread stress test of 200,000 concurrent withdrawals, the final balance is exact to the cent.

Your data survives a bad day

• Clean shutdown writes every balance synchronously before the connection pool closes, and retries a failed write three times.
• Database unreachable? Balances are dumped to balances-emergency-<timestamp>.yml instead of being lost.
• Next startup automatically applies that dump, writes it back to MySQL, and archives it so it can never be applied twice. If the database is still down, the file is kept for the attempt after that.

Features

Commands

Placeholders

%vault_balance%                     %vault_balance_formatted%
%vault_eco_balance_short%           %vault_eco_balance_commas%
%vault_ecobalance<0-8>dp%           %vault_currency_symbol%
%vault_balance_<player>%            %vault_balance_formatted_<player>%
%vault_top%                         %vault_top_name_<n>%   %vault_top_amount_<n>%

Setup

1. Drop the jar into plugins/ and start the server.
2. Open plugins/Vault/config.yml, set your language and currency.
3. For MySQL, set storage.use_mysql: true and fill in the connection details.

Two config keys are easy to get wrong, and getting them wrong fails silently — the plugin falls back to defaults without an error:

storage:
  mysql:
    # the key is "params", not "properties"
    params: useSSL=false&serverTimezone=UTC
    # these must be nested under "pool:", not flat under "mysql:"
    pool:
      max: 10
      min_idle: 2
      connection_timeout_ms: 10000

Tuning durability

storage:
  save_on_transaction: true          # persist shortly after each transaction
  transaction_flush_delay_ticks: 20  # debounce window; lower = safer, more writes
  autosave_seconds: 60               # periodic safety net
  recover_emergency_dumps: true      # set false if several servers share one database

With the defaults, an unexpected process kill loses at most about one second of transactions.

Compatibility

• Server: Spigot / Paper. Builds for Java 21 and Java 17 are provided.
• Optional hooks: PlaceholderAPI, LuckPerms, SkinsRestorer, Essentials (import only).
• Do not install Vault.jar as well — both register the plugin name Vault and one of them will fail to load.

繁體中文

Vault3 是相容 Vault API 的獨立經濟插件，會直接註冊成 Vault 的經濟提供者， 其他插件的 depend: [Vault] 照常運作，不需要另外安裝 Vault.jar。

設計重點

• 交易不碰主執行緒：只標記變更並立即返回，寫入為非同步、去抖動，且只寫變動過的餘額
• 交易具原子性：兩個插件同時操作同一個帳戶不會互相覆寫
• 關服完整存檔：同步寫入全部餘額並重試三次
• 資料庫不可用時：寫出 balances-emergency-<時間戳>.yml,下次啟動自動補寫回資料庫並封存

支援 MySQL 或平面檔、GUI 付款選單、請款、貸款系統、富豪榜、PlaceholderAPI 與 11 種語言。

設定檔有兩個鍵名容易寫錯且不會報錯:連線參數是 params 而非 properties; 連線池參數必須巢狀在 pool: 底下。寫錯會靜默套用預設值。