跳至主要內容

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 作為僅編譯期的相依套件。執行期時，Vault 插件 JAR 必須存在於伺服器上。