Developer API

For pro!

XPlayersTokens provides a powerful and easy-to-use static API, allowing other developers to integrate token management into their own plugins without hassle.

---

Dependency Setup

To use the API, you must add the XPlayersTokens.jar to your project's build path (as a dependency).

If you are using plugin.yml, make sure to add XPlayersTokens as a dependency or soft-dependency to ensure your plugin loads after ours:

yamlCopydepend: [XPlayersTokens]  
# OR  
softdepend: [XPlayersTokens]  

---

Accessing the API

The API is designed to be static, meaning you don't need to fetch the plugin instance manually. You can access all features through the XPlayersTokensAPI class.

API Class

    /**
     * Gets tokens from a player
     */
    public static int getTokens(UUID uuid) {
        try {
            return database.getPlayersTokens(uuid);
        } catch (SQLException e) {
            Bukkit.getLogger().log(Level.SEVERE, "[XPlayersTokensAPI] Error in retrieving tokens.", e);
            return 0;
        }
    }

    /**
     * Adds tokens to a player
     */
    public static void addTokens(UUID uuid, int amount) {
        try {
            database.addPlayersTokens(uuid, amount);
        } catch (SQLException e) {
            Bukkit.getLogger().log(Level.SEVERE, "[XPlayersTokensAPI] Error adding tokens.", e);
        }
    }

    /**
     * Remove tokens from a player
     */
    public static boolean removeTokens(UUID uuid, int amount) {
        try {
            return database.removePlayersTokens(uuid, amount);
        } catch (SQLException e) {
            Bukkit.getLogger().log(Level.SEVERE, "[XPlayersTokensAPI] Error when withdrawing tokens.", e);
            return false;
        }
    }

    /**
     * Sets a player's tokens
     */
    public static void setTokens(UUID uuid, int amount) {
        try {
            database.setPlayersTokens(uuid, amount);
        } catch (SQLException e) {
            Bukkit.getLogger().log(Level.SEVERE, "[XPlayersTokensAPI] Error while defining tokens.", e);
        }
    }

    /**
     * Check if a player has enough tokens
     */
    public static boolean hasEnough(UUID uuid, int amount) {
        try {
            return database.hasEnoughTokens(uuid, amount);
        } catch (SQLException e) {
            return false;
        }
    }

---

Common Methods

Here are the primary methods available in the XPlayersTokensAPI class:

1. Get Player Balance Retrieve the current amount of tokens a player has.

int tokens = XPlayersTokensAPI.getTokens(playerUUID);  

2. Add Tokens Add a specific amount of tokens to a player.

XPlayersTokensAPI.addTokens(playerUUID, 100);  

3. Remove Tokens Remove tokens from a player. This method returns a boolean indicating if the transaction was successful (e.g., if the player had enough tokens).

boolean success = XPlayersTokensAPI.removeTokens(playerUUID, 50);  

4. Set Tokens Set a player's balance to a specific value.

XPlayersTokensAPI.setTokens(playerUUID, 500);  

5. Check Balance Check if a player has at least a certain amount of tokens.

if (XPlayersTokensAPI.hasEnough(playerUUID, 200)) {  
    // Do something  
}  

Example of code

@Override
    public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {

        Player player = (Player) sender;
        UUID uuid = player.getUniqueId();

        if (command.getName().equalsIgnoreCase("checktokens")) {
            // Récupérer le solde de tokens du joueur
            int balance = XPlayersTokensAPI.getTokens(uuid);
            player.sendMessage("Your current token balance is: " + balance);
            return true;
        }

        return false;
    }

    public boolean transferTokens(UUID fromUUID, UUID toUUID, int amount) {
        if (!XPlayersTokensAPI.hasEnough(fromUUID, amount)) {
            getLogger().info("Player does not have enough tokens.");
            return false;
        }

        boolean removed = XPlayersTokensAPI.removeTokens(fromUUID, amount);
        if (!removed) {
            getLogger().info("Failed to remove tokens from sender.");
            return false;
        }

        XPlayersTokensAPI.addTokens(toUUID, amount);
        getLogger().info("Transferred " + amount + " tokens successfully.");
        return true;
    }

---

Important Notes

• Asynchronous Operations: While the API handles database calls, it is highly recommended to call these methods from an asynchronous task if you are performing a large number of operations to avoid blocking the main server thread.

• Error Handling: The API includes internal error handling and will log issues to the console if a database connection fails, returning default values (like 0 or false) to prevent your plugin from crashing.