Karta EmeraldCurrency

KartaEmeraldCurrency

KartaEmeraldCurrency is a modern, high-performance economy plugin for PaperMC servers that uses the vanilla Emerald item as its core currency. It features a virtual bank system, interactive GUIs, and a powerful developer API, making it a versatile and stable choice for any server.

Built to be efficient and safe, all database operations are handled asynchronously to prevent server lag.

Compatibility: PaperMC 1.21 – 1.21.8 (Java 21+)

Features

- Configurable: Uses physical Emeralds for deposits and withdrawals. - Configurable: Securely store your emeralds in a virtual bank account, safe from inventory loss. - Configurable: A modern and easy-to-use GUI for all common actions, accessible via `/emerald`. - Configurable: Shows a summary of your account balance. - Configurable: A dedicated interface for depositing and withdrawing emeralds. You can deposit all emeralds from your inventory with one click, or deposit/withdraw a custom amount by entering the value in chat. - Configurable: Can act as the primary economy provider for any Vault-compatible plugin. - Configurable: A full set of placeholders to display economic data on scoreboards, chat, etc. - Configurable: A clean, asynchronous API for other plugins to interact with the economy. - Configurable: All database I/O is asynchronous to ensure your server remains lag-free. - Configurable: Almost every aspect, from fees to messages, can be customized.

Installation

1. Download the latest release from the Releases page. 2. Place the `KartaEmeraldCurrency-x.x.x.jar` file into your server's `/plugins` directory. 3. Restart your server. The default configuration files will be generated in `/plugins/KartaEmeraldCurrency/`.

Commands & Permissions

User Commands (`/emerald` or `/kec`)

The primary way to interact with the economy is through the main GUI (`/emerald`). While some direct commands may exist, the GUI provides access to all features, including the Bank, Transfers, and Leaderboards.

| Command | Permission | Description | |---|---|---| | `/emerald` | `kec.gui` | Opens the main interactive GUI. | | `/emerald balance` | `kec.balance` | Shows your current bank, wallet, and total balance. | | `/emerald pay <player> <amount>` | `kec.pay` | Pays another player from your bank account. | | `/emerald deposit <amount>` | `kec.deposit` | Deposits physical emeralds into your bank. | | `/emerald withdraw <amount>` | `kec.withdraw` | Withdraws emeralds from your bank to your inventory. | | `/emerald top` | `kec.top` | Shows the leaderboard of the richest players. | | `/emerald help` | `kec.help` | Displays a help message. |

Admin Commands (`/emeraldadmin` or `/kecadmin`)

All admin commands require the base permission `kec.admin` or granular permissions.

| Command | Permission | Description | |---|---|---| | `/kecadmin set <player> <amount>` | `kec.admin.set` | Sets a player's bank balance. | | `/kecadmin add <player> <amount>` | `kec.admin.add` | Adds to a player's bank balance. | | `/kecadmin remove <player> <amount>` | `kec.admin.remove` | Removes from a player's bank balance. | | `/kecadmin give <player> <amount>` | `kec.admin.give` | Gives a player physical emeralds. | | `/kecadmin take <player> <amount>` | `kec.admin.take` | Takes physical emeralds from a player. | | `/kecadmin reload` | `kec.admin.reload` | Reloads the configuration files. | | `/kecadmin migrate <source_type>` | `kec.admin.migrate` | Migrates data from one storage type to another (e.g., SQLITE to MYSQL). |

Placeholders

Requires PlaceholderAPI.

- `%kartaemerald_balance%` - Player's total bank balance. - `%kartaemerald_balance_formatted%` - Player's bank balance, formatted with suffixes (e.g., 1.2k). - `%kartaemerald_balance_comma%` - Player's bank balance, formatted with commas (e.g., 1,234,567). - `%kartaemerald_bank%` - An alias for `%kartaemerald_balance%`. - `%kartaemerald_wallet%` - Player's physical emerald count in their inventory. - `%kartaemerald_top_<1-10>_name%` - (Not yet implemented) Name of the Nth player on the leaderboard. - `%kartaemerald_top_<1-10>_amount%` - (Not yet implemented) Balance of the Nth player on a leaderboard.

Note on custom placeholders: In configuration files (`gui.yml`, `messages.yml`), you can use context-specific placeholders. These use the `<placeholder_name>` format, which is compatible with the Note on custom placeholders: library. For example, in the leaderboard GUI, you can use `<rank>`, `<player_name>`, and `<balance>`.

Developer API

KartaEmeraldCurrency provides a clean, easy-to-use API for developers. All data-related methods are asynchronous and return a `CompletableFuture`.

Accessing the API

First, get the service from Bukkit's `ServicesManager`.

```java import com.minekarta.kec.api.KartaEmeraldService; import org.bukkit.Bukkit; import org.bukkit.plugin.RegisteredServiceProvider;

public class MyPlugin { private KartaEmeraldService economyService;

public void onEnable() { RegisteredServiceProvider<KartaEmeraldService> rsp = Bukkit.getServicesManager().getRegistration(KartaEmeraldService.class); if (rsp != null) { this.economyService = rsp.getProvider(); } } } ```

Example Usage: Paying a Player

```java import com.minekarta.kec.api.TransferReason;

public void rewardPlayer(Player player, long amount) { if (economyService != null) { // Transfer from no one (server) by using a null UUID for the 'from' parameter is not supported. // Instead, use the addBankBalance method for server-to-player transactions. economyService.addBankBalance(player.getUniqueId(), amount).thenAccept(success -> { if (success) { player.sendMessage("You have been rewarded " + amount + " emeralds!"); } }); } } ```