API

On this page, you will find everything you need to know about our API.

#API

Read and change balances in any currency from your own plugin, online or offline.

#Maven Repository

<repositories>
    <repository>
        <id>phoenixplugins</id>
        <url>https://repo.phoenixplugins.com/</url>
    </repository>
</repositories>

#Dependency

<dependency>
    <groupId>com.phoenixplugins.phoenixcurrencies</groupId>
    <artifactId>api</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

#Getting started

Add PhoenixCurrencies to your plugin.yml so your plugin loads after it.

depend: [PhoenixCurrencies]

Use softdepend instead if your plugin should still work without it, and check PhoenixCurrenciesAPI.isAvailable() before calling anything.

if (!PhoenixCurrenciesAPI.isAvailable()) {
    return;
}

CurrenciesService currencies = PhoenixCurrenciesAPI.get();

Method	Returns
`getCurrencies()`	Every currency
`getCurrency(String id)`	One currency by its id, as an `Optional`
`getBalance(UUID player, String currency)`	The player's balance
`deposit(UUID player, String currency, double amount, String reason)`	Adds to the balance
`withdraw(UUID player, String currency, double amount, String reason)`	Takes from the balance
`setBalance(UUID player, String currency, double amount, String reason)`	Sets the balance
`earn(UUID player, String currency, double amount, String reason)`	Adds to the balance, multiplied by the player's booster
`transfer(UUID from, UUID to, String currency, double amount, String reason)`	Moves an amount from one player to another
`has(UUID player, String currency, double amount)`	Whether the player has at least that much
`findPlayer(String name)`	The UUID of a player who has joined before, as an `Optional`
`getCachedBalance(UUID player, String currency)`	The balance if the plugin already has it in memory, without waiting
`getTop(String currency, int limit)`	The leaderboard, as entries with the rank, UUID, name and balance
`getRank(UUID player, String currency)`	The player's place on the leaderboard
`getBoost(UUID player, String currency)`	The player's current booster multiplier
`isUsableBy(Player player, String currency)`	Whether the player may use the currency where they are
`getBankAccount(String bankId)`	The account UUID of a bank, to use in the calls above

Every call works on offline players. Calls that touch the database return a CompletableFuture, so they never block the main thread. The reason is shown in the transaction log.

currencies.withdraw(player.getUniqueId(), "gems", 50, "Bought a kit").thenAccept(result -> {
    if (result.isSuccess()) {
        giveKit(player);
    }
});

The future completes off the main thread. Go back to it with the Bukkit scheduler before touching the world or the player.

#Results

`TransactionResult`	Means
`SUCCESS`	The change went through.
`NOT_ENOUGH_MONEY`	The player cannot pay that much.
`MAX_BALANCE`	The change would go past the currency's maximum balance.
`INVALID_AMOUNT`	The amount is not a positive number.
`UNKNOWN_CURRENCY`	No currency has that id.
`FAILED`	The database refused the change. The console has the details.

#The Currency

Method	Returns
`getId()`, `getDisplayName()`, `getSymbol()`	The currency's names
`getDecimals()`, `getStartingBalance()`, `getMaxBalance()`	Its limits. A maximum of -1 is unlimited.
`isTransferable()`	Whether players can pay it to each other
`format(double amount)`, `formatCompact(double amount)`	The amount written the currency's way, in full or short

Last updated about 2 hours ago