🔌API Access

LightCoins comes with a comprehensive API that you can access.

We have three data objects: AccountData, CoinsData, and VirtualData. Both CoinsData and VirtualData are stored within the AccountData object, with VirtualData being stored as a List<VirtualData>.

Use LightCoins as a maven dependency

<repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
</repository>

<dependency>
    <groupId>com.github.lightPlugins</groupId>
    <artifactId>lightCcins</artifactId>
    <!-- Make sure you are using the latest version! -->
    <version>CurrentVersion</version>
    <scope>provided</scope>
</dependency>

Use LightCoins as a gradle dependency

repositories {
	mavenCentral()
	maven { url 'https://jitpack.io' }
}

dependencies {
        implementation 'com.github.lightPlugins:lightCoins:Tag'
}

Some examples of how to use the API

First, let's understand how LightCoins works and how it is structured.

public class SomeEconomyClass {
    
    /**
     * Get the LightCoinsAPI instance
     * Do not create a new instance of LightCoinsAPI, use this method instead
     * @return The LightCoinsAPI instance
     */
    public LightCoinsAPI getLightCoinsAPI() {
        return LightCoins.instance.getLightCoinsAPI();
    }
    
    /**
     * Get the account data of a player
     * @param playerName The name of the player. Can be a UUID, String or OfflinePlayer object.
     * @return The account data object of the target player. Can be null!
     */
    public AccountData getAccountData(String playerName) {
        return getLightCoinsAPI().getAccountData(playerName);
    }
    
    /**
     * Get the coins data of a player (Default Currency)
     * @param playerName The name of the player. Can be a UUID, String or OfflinePlayer object.
     * @return The coins data object of the target player. Can be null!
     */
    public CoinsData getCoinsData(String playerName) {
        return getAccountData(playerName).getCoinsData();
    }
    
    /**
     * Get the virtual data of a player (Virtual Currency)
     * @param playerName The name of the player. Can be a UUID, String or OfflinePlayer object.
     * @return The virtual data object of the target player. Can be null!
     */
    public List<VirtualData> getVirtualData(String playerName) {
        return getAccountData(playerName).getVirtualCurrencies();
    }
    
    /**
     * Get the specified virtual data of a player (Virtual Currency)
     * @param playerName The name of the player. Can be a UUID, String or OfflinePlayer object.
     * @param currencyName The name of the virtual currency
     * @return The virtual data object of the target player. Can be null!
     */
    public VirtualData getSomeCustomCurrency(UUID uuid, String currencyName) {
        return getAccountData(uuid).getVirtualCurrencyByName(currencyName);
    }
}

Lets do some transaction with the default Currency (Vault). In this case we add some amount of coins to a specified player.

/**
 * Add coins to a player
 * @param uuid The uuid of the player. Can be a UUID, String(playername) 
 *             or OfflinePlayer object.
 * @param amount The amount of coins to add
 * @return The economy response object
 */
public EconomyResponse addCoinsToPlayer(UUID uuid, BigDecimal amount) {
    return getCoinsData(uuid).addCoins(amount);
}


public void someMethode(Player player) {
    
    UUID uuid = player.getUniqueId();
    BigDecimal amount = BigDecimal.valueOf(100);
    
    EconomyResponse response = addCoinsToPlayer(uuid, amount);
    
    if(response.transactionSuccess()) {
        // transaction was successful
    } else {
        // transaction failed
        player.sendMessage("Transaction failed: " + response.errorMessage);
    }
}

Let's interact with a custom currency. In this case, we are looking for "gems" and want to remove some of them. Here is an example of how it works

/**
 * Remove coins from a player
 * @param uuid The uuid of the player.
 * @param amount The amount of coins to remove
 * @return The economy response object
 */
public VirtualResponse removeCoinsFromPlayer(UUID uuid, String gemsCurrency, BigDecimal amount) {
    // Get the virtual data of the player
    VirtualData virtualData = getAccountData(uuid).getVirtualCurrencyByName(gemsCurrency);
    // Check if the currency exists
    if(virtualData != null) {
        // Remove the balance from the player
        return virtualData.removeBalance(amount);
    }
    // return a new virtual response with a custom failure message
    return new VirtualResponse(new BigDecimal(0), new BigDecimal(0), 
            VirtualResponse.VirtualResponseType.FAILURE, "Currency not found");
    
}

public void anotherMethode(Player player) {

    UUID uuid = player.getUniqueId();
    BigDecimal amount = BigDecimal.valueOf(100);

    VirtualResponse response = removeCoinsFromPlayer(uuid, "gems", amount);

    if(response.transactionSuccess()) {
        // transaction was successful
    } else {
        // transaction failed, for e.g the player does not have enough gems
        player.sendMessage("Transaction failed: " + response.errorMessage);
    }
}

LightCoins comes also with Events. There are 2 Events currently. These events are only for the default currency (vault).

Custom Events

• LightCoinsDepositEvent

• LightCoinsWithdrawEvent