lilend's Simple Economy

lilend's Simple Economy (LSE) Version: 1.0 Language: Kotlin (JVM 21) Platform: Paper / Purpur 1.21+ Author: lilenddd API: LSEAPI, Vault, PlaceholderAPI A lightweight, secure, modern economy plugin for Minecraft Paper 1.21+ servers. Written entirely in Kotlin with thread-safe concurrent data structures, atomic transactions, and a modular architecture. Features - Player balances with YAML persistence - Physical check items (right-click to redeem via GUI) - Player-to-player payments with confirmation GUI - Balance leaderboard (/baltop) - Admin commands (add, remove, set balances) - Transaction tax system (configurable rate & per-feature) - Auto-save mechanism (configurable interval) - Vault API hook (QuickShop, ChestShop, GriefPrevention, etc.) - PlaceholderAPI expansion (%lse_balance%, %lse_balancetop_1%, etc.) - Public developer API (LSEAPI object) - Fully customizable messages with & color codes and placeholders - Per-command permissions (default true or op) - Toggleable features (checks, transfers, tax) - Transaction logging with daily rotation - Security validation (overflow protection, NaN checks, balance caps) Commands /balance or /bal | Show your balance | lse.balance /balance <player> | Show another player's balance | lse.balance.others /pay <player> <amount> | Send money to a player | lse.pay /check <amount> | Create a physical check | lse.check /baltop or /top | Balance leaderboard | lse.baltop /lse add <player> <amount> | Add money to a player | lse.lse.add /lse remove <player> <amount> | Remove money from a player | lse.lse.remove /lse set <player> <amount> | Set a player's balance | lse.lse.set /lse balance [player] | View any player's balance | lse.lse.balance Permissions lse.balance | true | Check your balance lse.balance.others | true | Check others' balances lse.pay | true | Send money to players lse.check | true | Create physical checks lse.baltop | true | View balance leaderboard lse.lse | op | Admin commands base lse.lse.add | op | Add money to a player lse.lse.remove | op | Remove money from a player lse.lse.set | op | Set a player's balance lse.lse.balance | op | View any balance via /lse lse.tax.exempt | op | Exempt from transaction taxes lse.admin | op | All admin permissions (inherits all lse.lse.*) Check System 1. Run /check <amount> to create a Paper item with PersistentDataContainer metadata. 2. The check item name shows the value in bold gold with configurable lore. 3. Right-click the check (main hand) to open the confirmation GUI. 4. Click green glass to approve, red glass to cancel. 5. Anti-double-redeem: each check has a unique UUID tracked in a ConcurrentHashMap. 6. On redeem, the check is consumed (1 removed from stack) and the amount is added to the player's balance. Transfer System 1. Run /pay <player> <amount>. 2. A 9-slot confirmation GUI opens with cancel (slot 0), info (slot 4), approve (slot 8). 3. On approval, money moves atomically from sender to receiver. 4. Both parties receive a notification. 5. If tax is enabled and applies to transfers, tax is deducted from the sent amount. Tax System Fully configurable transaction tax system: yaml <br> tax: <br> enabled: false <br> rate: 5.0 # percentage (0.0 - 100.0) <br> applies-to: <br> transfers: true # /pay transactions <br> checks: false # check creation fee <br> How it works: - Transfers: Sender specifies amount X. Receiver gets X - tax%. Tax disappears from the economy (deflationary). - Checks: Player pays amount + tax to create a check worth amount. Tax charged on top. - Players with lse.tax.exempt permission are not taxed. - Total collected tax is tracked and available via PlaceholderAPI (%lse_tax_collected%). PlaceholderAPI Expansion When PlaceholderAPI is installed, the following placeholders are available: %lse_balance% | Formatted balance of the player (e.g., $1,234.50) %lse_balance_raw% | Raw balance value (e.g., 1234.50) %lse_balance_<player>% | Formatted balance of another player %lse_balancetop_<rank>% | Top balance at rank (e.g., "lilenddd: $5,000.00") %lse_currency_symbol% | Currency symbol ($) %lse_currency_name% | Currency name (Dollar) %lse_version% | Plugin version | %lse_tax_collected% | Formatted total tax collected %lse_tax_collected_raw% | Raw total tax collected Developer API (LSEAPI) Add LilendsSimpleEconomy.jar as a dependency and use the singleton API object: kotlin <br> import com.lilend.lse.api.LSEAPI <br> <br> LSEAPI.getBalance(player) // → Double <br> LSEAPI.getBalance(playerId) // → Double <br> LSEAPI.getFormattedBalance(player) // → "$1,234.50" <br> LSEAPI.getFormattedBalance(playerId) // → "$1,234.50" <br> LSEAPI.getFormattedAmount(500.0) // → "$500.00" <br> LSEAPI.getRawFormattedAmount(500.0) // → "500.00" <br> LSEAPI.setBalance(player, 1000.0) // → Unit <br> LSEAPI.setBalance(playerId, 1000.0) // → Unit <br> LSEAPI.addBalance(player, 100.0) // → Unit <br> LSEAPI.addBalance(playerId, 100.0) // → Unit <br> LSEAPI.removeBalance(player, 50.0) // → Boolean <br> LSEAPI.removeBalance(playerId, 50.0) // → Boolean <br> LSEAPI.hasBalance(player, 25.0) // → Boolean <br> LSEAPI.hasBalance(playerId, 25.0) // → Boolean <br> LSEAPI.getCurrencySymbol() // → "$" <br> LSEAPI.getCurrencyName() // → "Dollar" <br> All API methods are null-safe and return default values if the plugin is not loaded. Vault API Integration Place Vault.jar in your plugins/ folder and LSE hooks automatically via ServiceManager. Compatible with: - QuickShop / QuickShop-Hikari - ChestShop - GriefPrevention - Any plugin using Vault Economy interface Banks are not supported (returns NOT_IMPLEMENTED). Configuration All files are in plugins/LilendsSimpleEconomy/. config.yml yaml <br> currency: <br> symbol: "$" <br> name: "Dollar" <br> <br> settings: <br> default-balance: 0.0 <br> max-check-amount: 1000000.0 <br> auto-save-interval: 300 # seconds between auto-saves (min 30) <br> <br> baltop: <br> max: 10 <br> <br> format: <br> commas: true # $1,000,000.50 vs $1000000.50 <br> <br> features: <br> transfers: <br> enabled: true <br> checks: <br> enabled: true <br> <br> tax: <br> enabled: false <br> rate: 5.0 # percentage (0-100) <br> applies-to: <br> transfers: true # /pay taxed <br> checks: false # check creation taxed <br> messages.yml All messages use & color codes. Placeholders vary per message: yaml <br> prefix: "&8[&6LSE&8] &r" <br> <br> balance: <br> self: "&aBalance: &6%balance%" <br> other: "&e%player%&a's balance: &6%balance%" <br> others-no-perm: "&cYou don't have permission to view others' balances." <br> <br> pay: <br> sent: "&aYou sent &6%amount% &ato &e%target%" <br> received: "&aYou received &6%amount% &afrom &e%sender%" <br> insufficient: "&cInsufficient funds! Your balance: &6%balance%" <br> self: "&cYou cannot pay yourself!" <br> disabled: "&cTransfers are disabled on this server." <br> confirm-title: "&8&lSend &6%amount% &8&lto &e%target%&8&l?" <br> confirm-accept: "&a&lApprove" <br> confirm-cancel: "&c&lCancel" <br> tax-applied: "&7Transaction tax: &c-%tax%" <br> <br> check: <br> created: "&aYou created a check worth &6%amount%" <br> created-tax: "&aYou created a check worth &6%amount% &7(-%tax% tax)" <br> redeemed: "&aYou redeemed a check worth &6%amount%" <br> disabled: "&cChecks are disabled on this server." <br> invalid-amount: "&cInvalid amount! Max check: &6%max%" <br> no-balance: "&cYou don't have enough money to create a check worth &6%amount%" <br> no-balance-tax: "&cInsufficient funds! Check: &6%amount% &c+ Tax: &6%tax% &c= &6%total%" <br> confirm-title: "&8&lRedeem this check?" <br> confirm-accept: "&a&lApprove" <br> confirm-cancel: "&c&lCancel" <br> item-name: "&6&l%amount% &e&lCheck" <br> item-lore: <br> - "&7Created by: &f%creator%" <br> - "&7Value: &6%amount%" <br> <br> lse: <br> added: "&aAdded &6%amount% &ato &e%player%" <br> removed: "&aRemoved &6%amount% &afrom &e%player%" <br> set: "&aSet &e%player%'s &abalance to &6%amount%" <br> balance: "&e%player%'s &abalance: &6%balance%" <br> insufficient: "&cThat player doesn't have enough money!" <br> <br> baltop: <br> header: "&8&m----------&8[ &6&lTop Balances &8]&m----------" <br> entry: "&6%rank%. &e%player% &8- &6%balance%" <br> footer: "&8&m------------------------------------" <br> empty: "&cNo balances to display." <br> <br> errors: <br> player-only: "&cOnly players can use this command." <br> invalid-player: "&cPlayer not found!" <br> invalid-amount: "&cInvalid amount!" <br> no-permission: "&cYou don't have permission to use this command." <br> not-enough-money: "&cYou don't have enough money!" <br> invalid-syntax: "&cInvalid syntax! Usage: &e%usage%" <br> Technical Architecture Package Structure <br> com.lilend.lse/ <br> LSEPlugin.kt # Main plugin class (JavaPlugin) <br> BalanceManager.kt # Thread-safe balance storage (ConcurrentHashMap + YAML) <br> ConfigManager.kt # Configuration wrapper <br> Messages.kt # Message system with & color codes + placeholders <br> TaxManager.kt # Tax calculation and tracking <br> api/ <br> LSEAPI.kt # Public developer API (singleton object) <br> commands/ <br> BalanceCommand.kt # /balance command <br> BaltopCommand.kt # /baltop command <br> CheckCommand.kt # /check command (physical items) <br> MoneyCommand.kt # /lse admin command <br> PayCommand.kt # /pay command (with GUI confirmation) <br> gui/ <br> ConfirmationGUI.kt # Reusable confirmation GUI (Listener-based) <br> hook/ <br> PlaceholderHook.kt # PlaceholderAPI expansion <br> UpdateChecker.kt # GitHub releases version check <br> listeners/ <br> CheckListener.kt # Check item interaction handler <br> security/ <br> SecurityManager.kt # Amount validation, rounding, overflow protection <br> TransactionLogger.kt # Daily rotating CSV-style transaction logs <br> vault/ <br> VaultHook.kt # Vault Economy interface implementation <br> Data Persistence - balances.yml: YAML file with UUID -> Double mapping. Loaded on enable, saved on disable + auto-save every N seconds. - Log files: logs/transactions-YYYY-MM-DD.log in the plugin data folder. Auto-rotated daily. - Plugin data folder: plugins/LilendsSimpleEconomy/ Installation 1. Download LilendsSimpleEconomy-1.0.jar 2. Place it in your server's plugins/ folder 3. (Optional) Install Vault.jar for cross-plugin economy support 4. (Optional) Install PlaceholderAPI for placeholder expansion 5. Restart or reload your server 6. Edit config.yml and messages.yml to your liking 7. Run /balance to verify