EcoBal Economy API

模组

· 作者 official.andy

EcoBal 是一个面向 Fabric 模组的经济 API。

0 本站下载 0 关注 更新于 2 个月前

需要前置:Fabric API

最新 1.0.2 · 26.3 · Fabric

一键开服(送7天)

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)

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

    • 玩家经济余额的核心 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) {
    // 设置内部余额并触发持久化。
}

// --- 工具方法 ---

/**
 * 将原始双精度余额格式化为货币字符串(例如,“$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 文件。
  • 整合包本身,或通过整合包访问此模组,不得出售。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源