EcoBal Economy API

Minecraft 版本： 26.2

平台： fabric

标签： economy game-mechanics management

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](https://discord.gg/48sZCbdHzJ).** 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 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 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.