EcoBal - 健壮且可配置的 Fabric 经济 API
EcoBal 是一款功能强大的独立服务端 Fabric 经济模组,旨在作为其他模组(如 ShopShelves)的 核心 API 层,并提供开箱即用的完整、丰富的经济体验。它管理玩家余额、持久化存储、管理员命令,并提供高级、可配置的游戏内消息格式化功能。
? 联系我与支持信息
? 主要支持渠道(推荐)
所有一般性问题、功能请求和非紧急的错误报告都应发布在我们 Discord 服务器 的相关频道中。 我们会积极监控该服务器并尽快回复。这确保了整个社区都能从讨论和解决方案中受益。
? 紧急私聊 (PM) 政策
虽然我们建议所有问题优先通过 Discord 服务器处理,但在特定的紧急情况下,欢迎您直接给我发送私聊:
- 允许的原因: 您的服务器因我的某个模组/插件而崩溃或出现严重的、破坏游戏平衡的错误。
- 要求: 您必须是服务器的所有者。
- 时区: 我处于 (CET/CEST) 时区。
- 私聊时间: 请仅在 上午 10:00 至晚上 10:00(布鲁塞尔时间) 之间发送私聊消息。
我会尽力尽快回复您的私聊以提供协助,并查看我能做些什么来解决您的紧急问题。然而,请理解即时回复无法保证,且私聊是一种职业礼貌,而非一种权利。感谢您的理解与合作!
?️ API 集成指南:EconomyManager
对于模组开发者而言,EcoBal 通过静态 EconomyManager 类提供所有核心经济功能。使用 silentDeposit 和 silentWithdraw 方法来管理资金,而不会触发 EcoBal 内置的消息,从而允许您的模组使用自定义反馈。
API 位置: 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;
// 注意:此版本为 API 文档简化版。
// 模组中的完整实现包含文件持久化逻辑。
/**
-
- =========================================================================
-
ECOBAL 核心经济 API (ECONOMYMANAGER)
-
=========================================================================
-
-
所有函数均为静态且线程安全,供外部模组使用。
-
-
{@code EconomyManager.silentDeposit(uuid, amount);}
*/
public class EconomyManager {
// 内部余额和名称映射由 EcoBal 管理和持久化。
// 它们不作为公共字段直接暴露。
// 以下方法提供受控访问。
// --- 数据访问 API ---
/**
- 获取玩家的原始余额。如果玩家没有记录的余额则返回 0.00,
- 并且不会创建新账户(非常适合外部模组拉取数据)。
-
- @return 玩家的余额,如果未找到则返回 0.00。
*/
public static double getPlayerBalance(UUID uuid) {
// 实现使用 balances.getOrDefault(uuid, 0.00)
return 0.00; // 用于编译/API 可见性的占位符
}
/**
- 从持久化缓存中获取玩家的最后已知用户名。
- 用于显示离线玩家的名称(例如在排行榜中)。
-
- @return 最后已知的名称,如果没有缓存名称则返回 UUID 字符串。
*/
public static String getPlayerName(UUID uuid) {
// 实现使用 names.getOrDefault(uuid, uuid.toString())
return uuid.toString(); // 用于编译/API 可见性的占位符
}
/**
- 获取当前按降序排列的最高余额。
-
- @return 按值降序排列的 UUID 和余额的 LinkedHashMap。
*/
public static LinkedHashMap<UUID, Double> getTopBalances(int count) {
// 实现流式处理余额,排序并限制为 'count'。
return new LinkedHashMap<>(); // 用于编译/API 可见性的占位符
}
/**
- 获取所有玩家余额映射的不可修改副本。
- 适用于复杂的外部排序、同步或完整的数据库访问。
-
- @return 所有玩家 UUID 及其余额的不可修改 Map。
*/
public static Map<UUID, Double> getAllBalances() {
// 实现使用 Collections.unmodifiableMap(balances)
return Collections.emptyMap(); // 用于编译/API 可见性的占位符
}
/**
- 获取原始配置货币符号(例如 "$", "€", "C")。
-
- @return 配置的货币符号。
*/
public static String getCurrencySymbol() {
return MessageFormattingData.get().currencySymbol();
}
// --- 交易 API (静默与非静默) ---
/**
- 静默地向玩家余额中添加金额(API 存款/给予)。
- 不会触发 EcoBal 的内部玩家通知。
-
- @param amount 要添加的金额(必须 > 0)。
*/
public static void silentDeposit(UUID uuid, double amount) {
// 调用内部存款逻辑。
}
/**
* 静默地从玩家余额中扣除金额(API 提现/取款)。
* 不会触发 EcoBal 的内部玩家通知。
* * @param uuid 玩家的唯一 ID。
* @param amount 要扣除的金额(必须 > 0)。
* @return 如果交易成功(玩家有足够的钱)则返回 True,否则返回 false。
*/
public static boolean silentWithdraw(UUID uuid, double amount) {
// 调用内部取款逻辑。
return true; // 用于编译/API 可见性的占位符
}
/**
* 将玩家余额设置为特定金额(不能为负数)。
* * @param uuid 玩家的唯一 ID。
* @param amount 新的余额金额(使用 max(0.00, amount))。
*/
public static void setBalance(UUID uuid, double amount) {
// 设置内部余额并触发持久化。
}
// --- 工具方法 ---
/**
* 将原始双精度余额格式化为货币字符串(例如,“$1,000.00”)。
* 使用配置的货币符号。
* * @param balance 余额金额。
* @return 格式化后的字符串。
*/
public static String formatBalance(double balance) {
return String.format("%s%,.2f", getCurrencySymbol(), balance);
}
// 注意:完整的模组提供了诸如 getBalance、deposit 和 reset*
// 等内部方法以用于命令执行,但如果使用静默方法,
// 这些方法通常不需要用于外部模组集成。
}
功能特性
无缝后端集成
- 专用 API: 在稳定的静态
EconomyManager 类中暴露核心方法(getBalance、silentDeposit、silentWithdraw),便于其他模组集成。
- 静默交易:
silentDeposit 和 silentWithdraw 允许开发者管理资金而无需触发 EcoBal 内置的聊天消息,从而可以使用自定义的游戏内反馈。
- 排行榜数据: 新的 API 方法(
getTopBalances、getAllBalances)允许外部模组(如记分板、标签列表模组)获取原始排序的余额数据。
可配置的经济核心
- 余额持久化: 所有玩家余额和最后已知用户名会在服务器启动时自动加载,并在关闭时保存,确保离线玩家在
/baltop 中正确显示名称。
- 可配置默认值: 通过 JSON 配置文件设置默认的
starting_balance(起始余额)和 currency_symbol(货币符号),可通过游戏内的管理员命令进行调整。
- BalTop 系统: 实现
/baltop 命令,支持可配置的头尾文本、前 3 名格式以及每页最多 10 名玩家的动态分页。
高级消息格式化
- 富文本支持: 所有游戏内消息(聊天、错误、动作栏)均支持标准的 旧版颜色代码(
&c)和现代的 十六进制颜色代码(&#RRGGBB)。
- 交互式消息: 支持在所有可配置消息中使用复杂的文本功能,如 悬停文本(
{text})和 点击操作(<action:type,value>)。
- 自定义消息传递: 玩家可以选择他们偏好的消息模式:聊天、动作栏或两者,可通过
/ecobal mode 进行配置。
- 完全自定义配置: 每一个经济相关消息(余额查询、支付成功/失败、管理员操作)都存储在可自定义的 JSON 文件(
message_formatting.json)中,分别提供 chat(聊天)和 actionbar(动作栏)的格式。
强大的权限控制
- Fabric Permissions API v0: 使用标准的 Fabric Permissions API 进行权限检查,如果没有检测到权限插件,则内置回退到原版 OP 等级。
- OP 回退逻辑: 如果不存在权限 API,公共命令(
/bal、/pay、/baltop、/ecobal)将对所有人开放(OP Level 0),而所有管理命令需要 OP Level 2。
- 细粒度控制: 为每个命令分离权限:
/bal、/pay、/baltop、/eco 和 /ecobal help。
命令
玩家命令
/balance, /bal (查看自己的余额或其他玩家的余额)
/pay <player> <amount> (向其他玩家转账)
/balancetop, /baltop, /ecotop [page] (查看最富有的玩家)
管理与配置命令(需要 ecobal.eco 权限或 OP Level 2)
/eco give <player> <amount> (向玩家余额中添加金钱)
/eco take <player> <amount> (从玩家余额中移除金钱)
/eco set <player> <amount> (精确设置玩家余额)
/eco start <amount> (设置新玩家的默认起始余额)
/eco symbol <symbol> (设置全局货币符号,例如 '$')
/ecobal reload (重新加载所有配置文件,无需重启服务器)
/ecobal mode [mode] (检查或设置消息传递模式:CHAT、ACTIONBAR、BOTH)
/ecobal reset (将所有玩家余额全局重置为起始余额)
/eco reset <player> (将单个玩家的余额重置为起始余额)
权限
ecobal.command.use:允许使用 /ecobal 和 /eb 帮助命令。
ecobal.bal:允许使用 /balance 和 /bal 命令。
ecobal.pay:允许使用 /pay 命令。
ecobal.top:允许使用 /balancetop 和 /baltop 命令。
ecobal.eco:允许使用所有管理 /eco 命令和配置命令。
整合包政策
- 允许在任何整合包中包含 EcoBal。
- 署名是受欢迎的,但不是严格必需的。
- 请勿直接修改模组的 JAR 文件。
- 整合包本身,或通过整合包访问此模组,不得出售。
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.
评论 0
登录后参与评分
还没有评论,来抢沙发吧