使用經濟 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>()