使用經濟 API

經濟 API 將所有經濟插件統一於單一 API。這意味著任何使用了經濟 API 的插件將相容於所有實作了該 API 的經濟插件。本頁面將逐步引導你在你的插件中使用經濟 API。

載入經濟服務(EconomyService)

為了使用經濟 API,你必須先透過使用 ServiceManager 來載入 EconomyService 類別。

警告

請注意你需要在使用經濟 API 等服務時注意不同的遊戲狀態,這些狀態包含伺服器啟動、停止與運行。參閱 服務 頁面以取得更多資訊。

範例:載入 EconomyService

import org.spongepowered.api.service.economy.EconomyService;
import org.spongepowered.api.Sponge;

Optional<EconomyService> serviceOpt = Sponge.getServiceManager().provide(EconomyService.class);
if (!serviceOpt.isPresent()) {
    // handle there not being an economy implementation
}
EconomyService economyService = serviceOpt.get();

警告

將此服務保留在區域變數而非成員變數,因為對應的提供者(實作)隨時可能改變。如果你需要將其放於成員變數,無論如何,使用 ChangeServiceProviderEvent 來保持對應的實作能夠被更新。

備註

與其他服務不太一樣,你需要試著使用 ServiceManager#provide(java.lang.Class) 而非 ServiceManager#provideUnchecked(java.lang.Class),因為 Sponge 並未提供 EconomyService 的預設實作,也無法保證它存在。

使用經濟服務(EconomyService)

在載入 EconomyService 並將其賦值至變數後,你就準備好存取經濟 API 的所有功能了。

範例:取得玩家餘額

import org.spongepowered.api.entity.living.player.Player;
import org.spongepowered.api.service.economy.EconomyService;
import org.spongepowered.api.service.economy.account.UniqueAccount;
import java.math.BigDecimal;
import java.util.Optional;

Optional<UniqueAccount> uOpt = economyService.getOrCreateAccount(player.getUniqueId());
if (uOpt.isPresent()) {
    UniqueAccount acc = uOpt.get();
    BigDecimal balance = acc.getBalance(economyService.getDefaultCurrency());
}

有些 Account 方法會要求諸如以下的變數:

  • 貨幣(Currency):交易所涉及的貨幣

  • 發生原因(Cause):是什麼導致了帳戶的變動

  • 情境(Context):交易發生的情境

這些參數是為了更進階的使用而設計的,然而我們仍然必須填寫。以下是可接受的預設值清單:

  • 貨幣(Currency):EconomyService#getDefaultCurrency()

  • 事件原因:Cause.of(EventContext.builder().add(EventContextKeys.PLUGIN, plugin).build(), plugin)

  • 情境(Context):new HashSet<Context>()