💰 UltraEconomy

🧱 Advanced Multi-Currency Economy System for Minecraft (Fabric 1.21.1)

UltraEconomy is a high-performance, multi-currency economy system designed for modern Minecraft servers. Built on Fabric, it features multi-database persistence, automated backups, an in-game graphical interface (GUI) for logs and backups, and a built-in web server with a secure HTTP API.

---

⚙️ Key Features

• 💱 Multi-Currency Support
  Define as many currencies as you want! Each currency is highly configurable (custom symbols, formatting patterns, singular/plural names, and short suffix formatting).
• 🗄️ Multi-Database Compatibility
  Supports SQLite (default), MongoDB, MySQL, and generic SQL databases for cross-server setups.
• 🌐 Built-in Web UI & HTTP API
  Includes a built-in Jetty web server to host a dashboard or query economy data externally. Features rate-limiting, IP auto-banning, and bearer-token authentication.
• 🔁 Economy Migration Support
  Easily migrate balances from other mods or plugins (e.g., Impactor) directly into UltraEconomy.
• 📦 Automated Backup & Restore
  Automated hourly backups with configurable retention policies and a visual in-game restore manager.
• 🧩 Placeholders Integration
  Compatible with the standard Placeholder API to display player stats on menus, scoreboards, and tab lists.
• ⚡ High-Performance Caching
  Uses Caffeine Cache to minimize database operations and guarantee sub-millisecond response times.
• 🪟 Rich In-Game GUIs
  Includes dedicated GUI menus to view transaction logs, browse/restore backups, and view the balance leaderboards.

---

📁 Configuration Structure

The configuration files are created under config/ultraeconomy/.

1. Main Configuration (config.json)

{
  "debug": false,
  "notifications": true,
  "queueMessages": false,
  "commandCooldown": "500ms",
  "retentionBackUps": "7d",
  "betweenMessagesDelay": "1s",
  "lang": "en_us",
  "commands": [
    "money",
    "balance",
    "bal",
    "eco",
    "ultraeconomy"
  ],
  "database": {
    "type": "SQLITE",
    "url": "jdbc:sqlite:./config/ultraeconomy/ultraeconomy.db",
    "user": "",
    "password": "",
    "poolSize": 10
  },
  "migration": {
    "active": false,
    "migrations": [
      {
        "economyId": "IMPACTOR",
        "migrationFromCurrencyId": "impactor:dollars",
        "migrationToCurrencyId": "dollars"
      }
    ]
  },
  "limitTopPlayers": 10,
  "adjustmentShortName": 3,
  "balTopCooldown": "10s",
  "cacheTtlSeconds": 60,
  "web": false,
  "webSecurity": {
    "enabled": true,
    "port": 8080,
    "apiToken": "YOUR-RANDOM-API-TOKEN-HERE",
    "apiRateLimit": 20,
    "apiBurstCapacity": 40,
    "staticRateLimit": 60,
    "staticBurstCapacity": 120,
    "banThreshold": 10,
    "banDurationMinutes": 15,
    "trustProxy": false,
    "idleTimeoutSeconds": 30,
    "maxRequestBodyBytes": 8192
  }
}

2. Currencies Config (currencys/<currency_id>.json)

Each currency file lives in config/ultraeconomy/currencys/. For example, dollars.json:

{
  "primary": true,
  "transferable": true,
  "defaultBalance": 500.00,
  "decimals": 2,
  "symbol": "$",
  "format": "<symbol>&6<amount> <name>",
  "singular": "Dollar",
  "plural": "Dollars",
  "suffixes": ["", "K", "M", "B", "T"],
  "currencyIds": [
    "impactor:dollars"
  ]
}

---

💬 Commands & Permissions

Player Commands

Command	Description	Permission
/<cmd> [player]	Check your balance or another player's balance	ultraeconomy.command.balance ultraeconomy.command.balance.other
/pay <currency> <amount> <player>	Pay another player a specific amount	ultraeconomy.command.pay
/baltop [currency] [page]	View the leaderboard for a currency in chat	ultraeconomy.command.baltop
/baltopmenu [currency]	Open the leaderboard in a GUI menu	ultraeconomy.command.baltopmenu
/withdraw <amount> [currency]	Withdraw money from your account	ultraeconomy.command.withdraw
/deposit <amount> [currency]	Deposit money to your account	ultraeconomy.command.deposit
/set <amount> [currency]	Set your own balance	ultraeconomy.command.set
/reset [currency]	Reset your balance to default	ultraeconomy.command.reset

Admin Commands (Permission: ultraeconomy.admin / OP 2)

• /eco admin reload - Reloads all configuration and currency files.
• /eco admin deposit <player> <amount> [currency] - Deposits currency into a player's account.
• /eco admin withdraw <player> <amount> [currency] - Withdraws currency from a player's account.
• /eco admin set <player> <amount> [currency] - Sets a player's balance.
• /eco admin reset <player> [currency] - Resets a player's balance.
• /eco admin transactions <player> - Opens the GUI to view a player's transaction history. (Permission: ultraeconomy.admin.transactions)
• /eco admin backup <create/restore/list> - Manage database backups. /list opens a GUI menu in-game. (Permission: ultraeconomy.admin.backup)

---

🧩 Placeholders

Use these Placeholders (via Placeholder API) to display economy stats:

• %ultraeconomy:balance <currency_id>% - Returns the formatted balance (e.g. $1,250.50 Dollars).
• %ultraeconomy:symbol <currency_id>% - Returns the currency symbol (e.g. $).
• %ultraeconomy:amount <currency_id>% - Returns the raw formatted amount without the symbol (e.g. 1,250.50).
• %ultraeconomy:short_amount <currency_id>% - Returns the shortened amount with suffixes (e.g. 1.2K, 5.4M).

---

🧠 Developer API

Add UltraEconomy to your dependencies to interact with the economy programmatically.

API Usage Example

import com.kingpixel.ultraeconomy.api.UltraEconomyApi;
import com.kingpixel.ultraeconomy.models.Account;
import com.kingpixel.ultraeconomy.models.Currency;
import net.minecraft.server.network.ServerPlayerEntity;

import java.math.BigDecimal;
import java.util.UUID;

public class EconomyExample {
    
    public void handleEconomy(ServerPlayerEntity player, UUID targetPlayerUUID) {
        UUID playerId = player.getUuid();
        String currencyId = "dollars";

        // 1. Get a player's balance
        BigDecimal balance = UltraEconomyApi.getBalance(playerId, currencyId);

        // 2. Check if player has enough money
        boolean hasEnough = UltraEconomyApi.hasEnoughBalance(playerId, currencyId, new BigDecimal("100.00"));

        if (hasEnough) {
            // 3. Withdraw money
            boolean successWithdraw = UltraEconomyApi.withdraw(playerId, currencyId, new BigDecimal("100.00"));
            
            // 4. Deposit money
            boolean successDeposit = UltraEconomyApi.deposit(targetPlayerUUID, currencyId, new BigDecimal("100.00"));
        }

        // 5. Transfer directly between player accounts (handles thread-safety and deadlocks internally)
        boolean successTransfer = UltraEconomyApi.transfer(playerId, targetPlayerUUID, currencyId, new BigDecimal("50.00"));

        // 6. Set balance directly
        UltraEconomyApi.setBalance(playerId, currencyId, new BigDecimal("1000.00"));

        // 7. Get currency object and format values using the player's client language locale
        Currency currency = UltraEconomyApi.getCurrency(currencyId);
        String formatted = currency.format(new BigDecimal("15000.50"), UltraEconomyApi.getLocale(player)); // Output example: "$15,000.50 Dollars"
        
        // 8. Access the raw Account model
        Account account = UltraEconomyApi.getAccount(playerId);
        if (account != null) {
            System.out.println("Player account name: " + account.getPlayerName());
        }
    }
}