EcoBal经济API

💬 主要支持渠道（首选）

所有一般性问题、功能请求以及非紧急的错误报告都应发布到我们 Discord 服务器 的相应频道中。 我们会积极监控服务器并尽快回复。这能确保整个社区都能从讨论和解决方案中受益。

🆘 紧急私信（PM）政策

虽然我们更倾向于所有问题都先通过 Discord 服务器处理，但在特定的紧急情况下，欢迎直接私信我：

• 允许的理由： 你的服务器崩溃，或遇到与我的某个模组/插件直接相关的严重、破坏游戏的错误。
• 要求： 你必须是服务器的所有者。
• 时区： 我处于 (CET/CEST) 时区。
• 私信时间： 请仅在 (布鲁塞尔时间) 上午 10:00 至晚上 10:00 之间发送私信。

我会尽快回复你的私信，以提供帮助并尽我所能解决你的紧急问题。但请理解，无法保证立即回复，私信是一种职业礼节，而非应得的权利。 感谢你的理解与配合！

对于模组开发者，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)

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

• • 玩家经济余额的核心 API 和管理器。

• 所有函数均为静态且线程安全，可供外部模组使用。

• • 用法：通过直接调用静态方法进行集成：

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

  // 内部余额和名称映射由 EcoBal 管理和持久化。 // 它们不会作为公共字段直接暴露。 // 以下方法提供受控访问。

  // --- 数据访问 API ---

  /**

  • 获取玩家的原始余额。如果玩家没有记录的余额，则返回 0.00
  • 且不会创建新账户（非常适合外部模组拉取数据）。
  • • @param uuid 玩家的唯一 ID。
  • @return 玩家的余额，如果未找到则返回 0.00。 */ public static double getPlayerBalance(UUID uuid) { // 实现使用 balances.getOrDefault(uuid, 0.00) return 0.00; // 编译/API 可见性占位符 }

  /**

  • 从持久化缓存中获取玩家最后已知的用户名。
  • 用于显示离线玩家的名称（例如，在排行榜中）。
  • • @param uuid 玩家的唯一 ID。
  • @return 最后已知的名称，如果没有缓存名称则返回 UUID 字符串。 */ public static String getPlayerName(UUID uuid) { // 实现使用 names.getOrDefault(uuid, uuid.toString()) return uuid.toString(); // 编译/API 可见性占位符 }

  /**

  • 获取当前最高余额，按降序排序。
  • • @param count 要获取的最高余额数量。
  • @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 uuid 玩家的唯一 ID。
  • @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) { // 设置内部余额并触发持久化。 }

  // --- 实用方法 ---

  /**

  • 将原始 double 余额格式化为货币字符串（例如 "$1,000.00"）。
  • 使用配置的货币符号。
  • • @param balance 余额金额。
  • @return 格式化后的字符串。 */ public static String formatBalance(double balance) { return String.format("%s%,.2f", getCurrencySymbol(), balance); }

  // 注意：完整模组提供内部方法如 getBalance、deposit // 和 reset* 供命令使用，但如果使用静默方法， // 这些通常不需要用于外部模组集成。 }