超级经济

UltraEconomy 是一个简化经济模组的模组。

💰 UltraEconomy

🧱 Minecraft 高级多货币经济系统(Fabric 1.21.1)

Minecraft Java License

UltraEconomy 是一款专为现代 Minecraft 服务器设计的高性能多货币经济系统。基于 Fabric 构建,具备多数据库持久化、自动备份、用于查看日志与备份的游戏内图形界面(GUI),以及内置的带安全 HTTP API 的 Web 服务器。


⚙️ 主要功能

  • 💱 多货币支持
    可定义任意数量的货币!每种货币均可高度配置(自定义符号、格式化模式、单数/复数名称以及短后缀格式)。
  • 🗄️ 多数据库兼容
    支持 SQLite(默认)、MongoDB、MySQL 以及通用 SQL 数据库,适用于跨服 setups。
  • 🌐 内置 Web UI 与 HTTP API
    内置 Jetty Web 服务器,可托管仪表盘或从外部查询经济数据。具备速率限制、IP 自动封禁以及 Bearer Token 认证功能。
  • 🔁 经济迁移支持
    可轻松将其他模组或插件(如 Impactor)的余额迁移至 UltraEconomy。
  • 📦 自动备份与恢复
    每小时自动备份,支持可配置的保留策略以及可视化的游戏内恢复管理器。
  • 🧩 Placeholder 集成
    兼容标准 Placeholder API,可在菜单、计分板和玩家列表(tab)中显示玩家统计信息。
  • ⚡ 高性能缓存
    使用 Caffeine Cache 减少数据库操作,保证亚毫秒级响应时间。
  • 🪟 丰富的游戏内 GUI
    包含专用 GUI 菜单,可查看交易日志、浏览/恢复备份以及查看余额排行榜。

📁 配置结构

配置文件创建于 config/ultraeconomy/ 目录下。

1. 主配置 (config.json)

{
  "debug": false,
  "notifications": true,
  "queueMessages": false,
  "commandCooldown": "500ms",
  "retentionBackUps": "7d",
  "betweenMessagesDelay": "1s",
  "lang": "en_us",
  "commands": [
    "money",
    "balance",
    "bal",
    "eco",
    "ultraeconomy"
  ],
  "database": {
    "type": "SQLITE",
    "url": "jdbc:sqlite:./config/ultraeconomy/ultraeconomy.db",
    "user": "",
    "password": "",
    "poolSize": 10
  },
  "migration": {
    "active": false,
    "migrations": [
      {
        "economyId": "IMPACTOR",
        "migrationFromCurrencyId": "impactor:dollars",
        "migrationToCurrencyId": "dollars"
      }
    ]
  },
  "limitTopPlayers": 10,
  "adjustmentShortName": 3,
  "balTopCooldown": "10s",
  "cacheTtlSeconds": 60,
  "web": false,
  "webSecurity": {
    "enabled": true,
    "port": 8080,
    "apiToken": "YOUR-RANDOM-API-TOKEN-HERE",
    "apiRateLimit": 20,
    "apiBurstCapacity": 40,
    "staticRateLimit": 60,
    "staticBurstCapacity": 120,
    "banThreshold": 10,
    "banDurationMinutes": 15,
    "trustProxy": false,
    "idleTimeoutSeconds": 30,
    "maxRequestBodyBytes": 8192
  }
}

2. 货币配置 (currencys/<currency_id>.json)

每个货币文件位于 config/ultraeconomy/currencys/。例如,dollars.json:

{
  "primary": true,
  "transferable": true,
  "defaultBalance": 500.00,
  "decimals": 2,
  "symbol": "$",
  "format": "<symbol>&6<amount> <name>",
  "singular": "Dollar",
  "plural": "Dollars",
  "suffixes": ["", "K", "M", "B", "T"],
  "currencyIds": [
    "impactor:dollars"
  ]
}

💬 命令与权限

玩家命令

命令 描述 权限
/<cmd> [player] 查看自己或他人的余额 ultraeconomy.command.balance
ultraeconomy.command.balance.other
/pay <currency> <amount> <player> 向其他玩家支付指定金额 ultraeconomy.command.pay
/baltop [currency] [page] 在聊天中查看某货币的排行榜 ultraeconomy.command.baltop
/baltopmenu [currency] 在 GUI 菜单中打开排行榜 ultraeconomy.command.baltopmenu
/withdraw <amount> [currency] 从账户中取出金额 ultraeconomy.command.withdraw
/deposit <amount> [currency] 向账户中存入金额 ultraeconomy.command.deposit
/set <amount> [currency] 设置自己的余额 ultraeconomy.command.set
/reset [currency] 将自己的余额重置为默认值 ultraeconomy.command.reset

管理员命令(权限:ultraeconomy.admin / OP 2)

  • /eco admin reload - 重新加载所有配置和货币文件。
  • /eco admin deposit <player> <amount> [currency] - 向玩家账户存入货币。
  • /eco admin withdraw <player> <amount> [currency] - 从玩家账户取出货币。
  • /eco admin set <player> <amount> [currency] - 设置玩家余额。
  • /eco admin reset <player> [currency] - 重置玩家余额。
  • /eco admin transactions <player> - 打开 GUI 查看玩家的交易记录。(权限:ultraeconomy.admin.transactions)
  • /eco admin backup <create/restore/list> - 管理数据库备份。/list 会在游戏内打开 GUI 菜单。(权限:ultraeconomy.admin.backup)

🧩 Placeholder

使用以下 Placeholder(通过 Placeholder API)显示经济统计数据:

  • %ultraeconomy:balance <currency_id>% - 返回格式化后的余额(例如 $1,250.50 Dollars)。
  • %ultraeconomy:symbol <currency_id>% - 返回货币符号(例如 $)。
  • %ultraeconomy:amount <currency_id>% - 返回不含符号的原始格式化金额(例如 1,250.50)。
  • %ultraeconomy:short_amount <currency_id>% - 返回带后缀的缩写金额(例如 1.2K、5.4M)。

🧠 开发者 API

将 UltraEconomy 添加到你的依赖项中,即可通过编程方式与经济系统交互。

API 使用示例

import com.kingpixel.ultraeconomy.api.UltraEconomyApi;
import com.kingpixel.ultraeconomy.models.Account;
import com.kingpixel.ultraeconomy.models.Currency;
import net.minecraft.server.network.ServerPlayerEntity;

import java.math.BigDecimal;
import java.util.UUID;

public class EconomyExample {
    
    public void handleEconomy(ServerPlayerEntity player, UUID targetPlayerUUID) {
        UUID playerId = player.getUuid();
        String currencyId = "dollars";

        // 1. 获取玩家余额
        BigDecimal balance = UltraEconomyApi.getBalance(playerId, currencyId);

        // 2. 检查玩家是否有足够金钱
        boolean hasEnough = UltraEconomyApi.hasEnoughBalance(playerId, currencyId, new BigDecimal("100.00"));

        if (hasEnough) {
            // 3. 取出金钱
            boolean successWithdraw = UltraEconomyApi.withdraw(playerId, currencyId, new BigDecimal("100.00"));
            
            // 4. 存入金钱
            boolean successDeposit = UltraEconomyApi.deposit(targetPlayerUUID, currencyId, new BigDecimal("100.00"));
        }

        // 5. 直接在玩家账户之间转账(内部处理线程安全与死锁问题)
        boolean successTransfer = UltraEconomyApi.transfer(playerId, targetPlayerUUID, currencyId, new BigDecimal("50.00"));

        // 6. 直接设置余额
        UltraEconomyApi.setBalance(playerId, currencyId, new BigDecimal("1000.00"));

        // 7. 获取货币对象并使用玩家客户端语言区域格式化数值
        Currency currency = UltraEconomyApi.getCurrency(currencyId);
        String formatted = currency.format(new BigDecimal("15000.50"), UltraEconomyApi.getLocale(player)); // 输出示例:"$15,000.50 Dollars"
        
        // 8. 访问原始 Account 模型
        Account account = UltraEconomyApi.getAccount(playerId);
        if (account != null) {
            System.out.println("Player account name: " + account.getPlayerName());
        }
    }
}