Описание
# 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](https://modrinth.com/mod/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** (``) 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 ` (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 ` (Add money to a player's balance)
* `/eco take ` (Remove money from a player's balance)
* `/eco set ` (Set a player's balance exactly)
* `/eco start ` (Set the default starting balance for new players)
* `/eco 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 ` (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**.