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 - **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 (https://github.com/your-repo-link/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 (https://www.spigotmc.org/resources/placeholderapi.624/). - `%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 (https://docs.adventure.kyori.net/minimessage/format.html#placeholder) 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`.