EcoBal - Robust & Configurable Fabric Economy API

EcoBal is a powerful, standalone server-side Fabric economy mod designed to serve as a core API layer for other mods (like ShopShelves) and provide a complete, feature-rich economy experience out of the box. It manages player balances, persistence, administrative commands, and offers advanced, configurable in-game message formatting.

📧 Contact Me & Support Information

💬 Primary Support Channel (Preferred)

All general questions, feature requests, and non-urgent bug reports should be posted in the appropriate channels on our Discord Server. We actively monitor the server and will respond as soon as possible. This ensures that the whole community can benefit from the discussion and solutions.

🆘 Urgent Private Messaging (PM) Policy

While we prefer all issues to be handled via the Discord server first, you are welcome to PM me directly under specific urgent circumstances:

• Allowed Reason: Your server is crashing or experiencing critical, game-breaking errors directly related to one of my mods/plugins.
• Requirement: You must be the owner of the server.
• Time Zone: I am operating in the (CET/CEST) Time Zone.
• PM Hours: Please only send private messages between 10:00 AM and 10:00 PM (Brussels Time).

I will endeavor to answer your PM as soon as I can to be helpful and see what I can do to resolve your urgent issue. However, please understand that immediate responses are not guaranteed, and private messaging is a professional courtesy, not an entitlement. Thank you for your understanding and cooperation!

---

🛠️ API Integration Guide: The EconomyManager

For mod developers, EcoBal offers all core economy functions via the static EconomyManager class. Use the silentDeposit and silentWithdraw methods to manage funds without triggering EcoBal's built-in messages, allowing your mod to use its own custom feedback.

API Location: me.andy.ecobal.api.EconomyManager

package me.andy.ecobal.api;

import me.andy.ecobal.config.MessageFormattingData;

import java.util.Collections; import java.util.LinkedHashMap; import java.util.Map; import java.util.UUID;

// NOTE: This version is simplified for API documentation. // The full implementation in the mod includes file persistence logic.

/**

• • =========================================================================

• ECOBAL CORE ECONOMY API (ECONOMYMANAGER)

• =========================================================================

• • The core API and manager for player economy balances.

• All functions are static and thread-safe for external mod use.

• • Usage: Integrate by calling the static methods directly:

• {@code EconomyManager.silentDeposit(uuid, amount);} */ public class EconomyManager {

  // Internal balance and name maps are managed and persisted by EcoBal. // They are not directly exposed as public fields. // The following methods provide controlled access.

  // --- Data Access API ---

  /**

  • Gets a player's raw balance. Returns 0.00 if the player has no recorded balance
  • and does NOT create a new account (ideal for external mods pulling data).
  • • @param uuid The player's unique ID.
  • @return The player's balance, or 0.00 if not found. */ public static double getPlayerBalance(UUID uuid) { // Implementation uses balances.getOrDefault(uuid, 0.00) return 0.00; // Placeholder for compilation/API visibility }

  /**

  • Gets a player's last known username from the persistent cache.
  • Used for displaying names of offline players (e.g., in leaderboards).
  • • @param uuid The player's unique ID.
  • @return The last known name, or the UUID string if no name is cached. */ public static String getPlayerName(UUID uuid) { // Implementation uses names.getOrDefault(uuid, uuid.toString()) return uuid.toString(); // Placeholder for compilation/API visibility }

  /**

  • Gets the current top balances, sorted descending.
  • • @param count The number of top balances to retrieve.
  • @return A LinkedHashMap of UUID and Balance, sorted by value descending. */ public static LinkedHashMap<UUID, Double> getTopBalances(int count) { // Implementation streams balances, sorts, and limits to 'count'. return new LinkedHashMap<>(); // Placeholder for compilation/API visibility }

  /**

  • Gets an unmodifiable copy of the entire map of all player balances.
  • Useful for complex external sorting, synchronization, or full database access.
  • • @return An unmodifiable Map of all player UUIDs and their balances. */ public static Map<UUID, Double> getAllBalances() { // Implementation uses Collections.unmodifiableMap(balances) return Collections.emptyMap(); // Placeholder for compilation/API visibility }

  /**

  • Gets the raw configured currency symbol (e.g., "$", "€", "C").
  • • @return The configured currency symbol. */ public static String getCurrencySymbol() { return MessageFormattingData.get().currencySymbol(); }

  // --- Transaction API (Silent & Non-Silent) ---

  /**

  • Adds an amount to a player's balance silently (API Deposit/Give).
  • Does NOT trigger EcoBal's internal player notifications.
  • • @param uuid The player's unique ID.
  • @param amount The amount to add (must be > 0). */ public static void silentDeposit(UUID uuid, double amount) { // Calls the internal deposit logic. }

  /**

  • Subtracts an amount from a player's balance silently (API Withdraw/Take).
  • Does NOT trigger EcoBal's internal player notifications.
  • • @param uuid The player's unique ID.
  • @param amount The amount to subtract (must be > 0).
  • @return True if the transaction was successful (player had enough money), false otherwise. */ public static boolean silentWithdraw(UUID uuid, double amount) { // Calls the internal withdraw logic. return true; // Placeholder for compilation/API visibility }

  /**

  • Sets a player's balance to a specific amount (cannot be negative).
  • • @param uuid The player's unique ID.
  • @param amount The new balance amount (max(0.00, amount) is used). */ public static void setBalance(UUID uuid, double amount) { // Sets the internal balance and triggers persistence. }

  // --- Utility Methods ---

  /**

  • Formats a raw double balance into a currency string (e.g., "$1,000.00").
  • Uses the configured currency symbol.
  • • @param balance The balance amount.
  • @return The formatted string. */ public static String formatBalance(double balance) { return String.format("%s%,.2f", getCurrencySymbol(), balance); }

  // NOTE: The full mod provides internal methods like getBalance, deposit, // and reset* for command use, but these are typically not needed for // external mod integration if silent methods are used. }

Features

Seamless Backend Integration

• Dedicated API: Exposes core methods (getBalance, silentDeposit, silentWithdraw) in a stable, static EconomyManager class for easy integration into other mods.
• Silent Transactions: silentDeposit and silentWithdraw allow developers to manage funds without triggering EcoBal's built-in chat messages, enabling the use of their own custom in-game feedback.
• Leaderboard Data: New API methods (getTopBalances, getAllBalances) allow external mods (e.g., scoreboard, tab-list mods) to pull raw, sorted balance data.

Configurable Economy Core

• Balance Persistence: All player balances and last known usernames are automatically loaded on server startup and saved on shutdown, ensuring offline player names display correctly in /baltop.
• Configurable Defaults: Set the default starting_balance and currency_symbol via the JSON configuration file, adjustable by admin commands in-game.
• BalTop System: Implements /baltop with configurable header, footer, top-3 formats, and dynamic pagination up to 10 players per page.

Advanced Message Formatting

• Rich Text Support: All in-game messages (chat, errors, action bar) support standard legacy color codes (&c) and modern hex color codes (&#RRGGBB).
• Interactive Messages: Supports complex text features like Hover Text ({text}) and Click Actions (<action:type,value>) within all configurable messages.
• Custom Message Delivery: Players can choose their preferred message mode: Chat, Action Bar, or Both, which is configurable via /ecobal mode.
• Full Config Customization: Every single economy message (balance check, payment success/failure, admin actions) is stored in a customizable JSON file (message_formatting.json) with separate formats for chat and actionbar.

Robust Permissions

• Fabric Permissions API v0: Uses the standard Fabric Permissions API for permission checks, with a built-in fallback to vanilla OP levels if no permissions plugin is detected.
• OP Fallback Logic: If the permissions API is not present, public commands (/bal, /pay, /baltop, /ecobal) are open to everyone (OP Level 0), while all administrative commands require OP Level 2.
• Granular Control: Separates permissions for every command: /bal, /pay, /baltop, /eco, and /ecobal help.

---

Commands

Player Commands

• /balance, /bal (Check your own balance or another player's balance)
• /pay <player> <amount> (Transfer money to another player)
• /balancetop, /baltop, /ecotop [page] (View the richest players)

Admin & Configuration Commands (Requires ecobal.eco permission or OP Level 2)

• /eco give <player> <amount> (Add money to a player's balance)
• /eco take <player> <amount> (Remove money from a player's balance)
• /eco set <player> <amount> (Set a player's balance exactly)
• /eco start <amount> (Set the default starting balance for new players)
• /eco symbol <symbol> (Set the global currency symbol, e.g., '$')
• /ecobal reload (Reloads all configuration files without restarting the server)
• /ecobal mode [mode] (Checks or sets the message delivery mode: CHAT, ACTIONBAR, BOTH)
• /ecobal reset (Globally resets ALL player balances to the starting balance)
• /eco reset <player> (Resets a single player's balance to the starting balance)

---

Permissions

• ecobal.command.use: Allows usage of the /ecobal and /eb help commands.
• ecobal.bal: Allows usage of the /balance and /bal commands.
• ecobal.pay: Allows usage of the /pay command.
• ecobal.top: Allows usage of the /balancetop and /baltop commands.
• ecobal.eco: Allows usage of all administrative /eco commands and configuration commands.

---

Modpack Policy

• You ARE PERMITTED to include EcoBal in any modpack.
• Credit is appreciated but not strictly required.
• Please do not modify the mod's JAR file directly.
• The modpack itself, or access to this mod within the modpack, must not be sold.