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

• Emerald-Based Economy: Uses physical Emeralds for deposits and withdrawals.
• Virtual Bank: Securely store your emeralds in a virtual bank account, safe from inventory loss.
• Interactive GUI: A modern and easy-to-use GUI for all common actions, accessible via /emerald.
  • Main Menu: Shows a summary of your account balance.
  • Bank GUI: 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.
• Vault Integration: Can act as the primary economy provider for any Vault-compatible plugin.
• PlaceholderAPI Support: A full set of placeholders to display economic data on scoreboards, chat, etc.
• Developer API: A clean, asynchronous API for other plugins to interact with the economy.
• Async & Performant: 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 MiniMessage 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.

Example Usage: Paying a Player

Code (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!" ) ;
            }
        } ) ;
    }
}