Skip to content
Rosti Studios

RS-Economy documentation · v2.0.0

Developer API

Read and change balances from your own mod, so your players keep one wallet instead of three.

Another mod can use the same balances RS-Economy does. A shop mod, a quest mod, a custom reward: they all draw from and pay into the same number, so players never juggle currencies that disagree.

#The class

Text
org.rseconomy.rs_economy.api.EconomyAPI

All methods are static and take a player's UUID.

Method Returns Does
getBalance(UUID id) double the player's balance, 0.0 if the economy is not running
addBalance(UUID id, double amount) void add money
subtractBalance(UUID id, double amount) boolean take money; false if the player cannot afford it
getBounty(UUID id) double the total bounty on that player, 0.0 if none

subtractBalance is the safe way to charge a player: it checks and takes in one call. It only ever returns true when the money was actually taken.

#Rules

  • Call it after the server has started (for example from a server-started event or a command). Before that the economy is not loaded.
  • getBalance, subtractBalance and getBounty return a safe default when RS-Economy is not ready. addBalance throws a NullPointerException before the server has started, so call it only once the server is running.
  • Run it on the server thread, like any other game state.
  • It does not check permissions or whether a feature is switched on. That is your mod's job.

#Example

Java
import org.rseconomy.rs_economy.api.EconomyAPI;

public static boolean buyPerk(ServerPlayer player, double price) {
    if (!EconomyAPI.subtractBalance(player.getUUID(), price)) {
        player.sendSystemMessage(Component.literal("Not enough money."));
        return false;
    }
    // ... give the perk ...
    return true;
}

public static void rewardQuest(ServerPlayer player) {
    EconomyAPI.addBalance(player.getUUID(), 250);
}

#Depending on it

Declare RS-Economy as an optional dependency in your mod's metadata so your mod still loads without it, and guard calls to the API with a check that the mod is present.

The API is small on purpose. If you need something it does not offer, tell us on Discord.

#What the API does not do

It moves money. It does not create shops, bounties or trades; those are player-facing features with their own rules. Money you add through the API is new money, so count it as a source in How money flows.

Something missing or wrong? Tell us on Discord. This documentation describes v2.0.0.