原创 开源 经济 MeowEco —— 高效、轻量、多货币且高度兼容的经济插件！原生支持trmenu 26.7.4

[MD] # MeowEco 文档指南 版本：`26.7.4` MeowEco 是一个为 Paper 服务器设计的现代多货币经济插件，强调多货币、强配置、稳定兼容和高频场景下的实际可用性。 > 🐾 适合做点券系统、RPG 多货币、VIP 菜单、充值商城、服务器税收体系，以及需要和 Vault / PlaceholderAPI / TrMenu 联动的玩法。 ## 🌟 核心特色 - 💰 `富人税系统`：支持按计划时间自动征税，可按货币单独设置门槛和税率，还能决定税收直接回收进系统，或者流向指定玩家。 - 🔄 `多货币汇率`：支持货币之间的直接汇率、反向汇率和基于默认货币的推导汇率，适合做点券、金币、宝石等互通体系。 - 🎨 `格式化显示`：支持 `raw`、`formatted`、`fixed`、`short` 等多种显示方式，大额余额会被优化成更易读的短格式，适合经济膨胀型服务器。 - 🧭 `TrMenu 友好联动`：可以直接在菜单里写简洁条件和扣款逻辑，也能走命令模式，方便做 VIP 购买、兑换按钮和商城菜单。 - ⚡ `高效实现`：大多数数据库操作走异步线程，余额和排行有缓存，隐藏账户会在数据库层直接排除，适合高频查询场景。 - 🪙 `多货币与自定义货币`：支持同时维护多种货币，每种货币都能独立配置名称、格式、小数位、初始余额和转账税，方便你自由设计服务器经济体系。 - 🛡️ `多版本兼容`：当前按 `Paper 26.1.1` API 构建，使用 JDK 25 toolchain，但插件仍输出 Java 17 字节码，尽量兼容旧版已支持的 Paper 服务器。 ## 🚀 服主接入方式 - 插件版本：`26.7.4` - 推荐服务端：`Paper` - 经济桥接：可配合 `Vault` 使用默认货币对接其他生态插件 - 变量支持：可配合 `PlaceholderAPI` 在菜单、计分板、聊天等位置显示余额 - 菜单联动：可配合 `TrMenu` 做商城、VIP、兑换、奖励领取等按钮逻辑 - 当前构建目标 API：`io.papermc.paper:paper-api:26.1.1.build.14-alpha` - `meoweco-paper` 构建使用 JDK 25 toolchain - 插件产物继续输出 Java 17 字节码，用于兼容旧版已支持的 Paper 服务端 - 若服务器使用 `Paper 26.1.x / 26.1.1`，服务端本身仍需运行在 Java 25 上，这是 Paper 的上游要求 ## ✨ 适合哪些场景 - 🪙 `多货币服务器`：金币、点券、宝石、代币各自独立管理 - 🏪 `商城 / 菜单购买`：配合 TrMenu 做购买、兑换、权限发放 - 🧱 `RPG / 生存经济`：支持冻结资金、排行榜和富人税调控 - 📊 `展示型玩法`：排行榜、全服总量、余额格式化展示都已经准备好 - 🔧 `生态服接入`：需要 Vault、PlaceholderAPI、TrMenu 联动的服可以直接落地 ## ⚙️ 配置概览 主配置文件：`plugins/MeowEco/config.yml` ### 🧩 核心配置示例 ```yaml messages: language: "zh_CN" storage: type: sqlite mysql: host: localhost port: 3306 database: meoweco username: root password: password use-ssl: false update-checker: enabled: true interval: 24 slug: "meoweco" default-currency: "coins" exchange-rates: enabled: true coins: points: 0.1 gems: 0.01 rich-tax: enabled: false threshold: 100000.0 rate: 0.05 start-time: "03:00" interval: "24h" destination: type: "system" player: "Admin" currencies: coins: display-name: "&e金币" singular: "金币" plural: "金币" initial-balance: 100.0 decimal-places: 2 transfer-tax: 0.0 ``` ### 💸 富人税重点 - `threshold`：只对超过阈值的部分征税 - `rate`：会被限制在 `0.0` 到 `1.0` - `start-time`：服务器本地时间，格式 `HH:mm` - `interval`：支持纯分钟和 `30m`、`6h`、`1d` 这类写法 - `destination.type = system`：税款直接回收 - `destination.type = player`：税款进入指定玩家账户 富人税带来的好处： - 🏦 可以在服务器经济膨胀时持续回收高额资金，减轻通货膨胀 - ⚖️ 可以变相实现“劫富济贫”，降低少数超高资产玩家对经济系统的挤压 - 🧭 让经济调控从“手动干预”变成“自动按规则运行” - 🛒 当税款流向指定玩家时，你可以量化收到多少税，再把这些税款投入系统收购商店、活动奖励或公共资金池，用来平衡经济循环 ### 🔄 汇率重点 - 支持 `A -> B` 直接汇率 - 支持读取反向汇率 - 支持通过默认货币自动推导汇率 - 适合搭建 `coins`、`points`、`gems` 这类多层经济系统 ### 🪙 多货币与自定义货币重点 - 支持同时加载多种货币 - 支持完全自定义货币 id，例如 `coins`、`points`、`gems`、`token` - 每种货币都可独立配置显示名、单复数、小数位、初始余额、转账税 - 可以把不同货币定位成生存货币、商城点券、活动代币、宝石等不同用途 - 适合做“多层经济”而不是只有单一金币 ### 🎨 显示格式化余额 - 每种货币可独立配置显示名 - 支持单数 / 复数名称 - 支持小数位精度控制 - Placeholder 支持 `raw`、`formatted`、`fixed`、`short` - 排行榜、余额、全服总量都能直接格式化输出 显示格式示例： - 假设某个玩家的余额是 `1000000` - `raw`：`1000000` - `formatted`：`1,000,000` - `fixed`：`1000000.00` - `short`：`1M` 如果余额继续变大，例如 `1250000000`，短格式会更适合展示成 `1.25B` 这类更紧凑的效果。 格式化显示带来的好处： - 📉 当服务器经济膨胀后，超大数字不会把菜单、计分板、聊天消息挤得很难看 - 👀 短格式更利于玩家快速读数，比如大额余额可以显示成更紧凑的形式 - 🧾 同一套格式可同时服务于菜单、排行榜、Placeholder 和聊天提示，减少你自己二次处理文本的成本 - 🎯 对玩家来说更直观，对服主来说更容易做统一风格展示 ## 🧭 TrMenu 联动 MeowEco 对 TrMenu 菜单场景非常友好，适合做： - 🛒 点券商店 - 👑 VIP 菜单 - 🔁 兑换按钮 - 🎁 奖励领取 - 🔒 冻结或扣除资金的特殊玩法 推荐两种接入方式。 ### 1. 🪄 简洁动作写法 如果你的 TrMenu 环境已经注册了 MeowEco 的简写条件 / 动作，可以直接这样写： ```yaml actions: left: condition: 'meco points >= 99' actions: - 'meco-take: points 99' - 'console: lp user %player_name% permission set vip.level1 true' - 'tell: &a购买成功' ``` 给予货币时： ```yaml actions: left: actions: - 'meco-give: points 99' - 'tell: &a已发放 99 点券' ``` 说明： - `condition: 'meco points >= 99'`：判断玩家 `points` 是否足够 - `meco-take: points 99`：扣除货币 - `meco-give: points 99`：给予货币 ### 2. 🔧 通用命令写法 如果你想用最稳、最通用的方式，可以直接调用命令： ```yaml actions: left: condition: 'js: Number("%meoweco_balance_points%") >= 99' actions: - 'console: meco take %player_name% 99 points' - 'tell: &a购买成功' deny: - 'tell: &c你的点券不足' ``` 给予货币： ```yaml actions: left: actions: - 'console: meco give %player_name% 99 points' - 'tell: &a已发放 99 点券' ``` 说明： - 推荐优先用 `console:` 执行 `meco give` / `meco take` - 条件判断可直接用 `%meoweco_balance_points%` - `points` 只是示例货币 id，可替换成 `coins`、`gems` 或你自己的货币 - 冻结类玩法也可以用 `console: eco freeze ...`、`console: eco unfreeze ...`、`console: eco deductfrozen ...` ## ⌨️ 命令总览 ### 📌 已注册根命令 - `/meoweco` - `/money` - `/pay` - `/baltop` - `/eco` 别名： - `/meoweco`：`meco`、`meow` - `/money`：`balance`、`bal` - `/eco`：`economy` ### 👤 玩家命令 | 命令 | 说明 | | :--- | :--- | | `/meco` | 查看帮助 | | `/meco bal [player] [currency]` | 查询余额 | | `/meco money [player] [currency]` | 同 `bal` | | `/meco pay <player> <amount> [currency]` | 转账 | | `/meco top [currency]` | 查看排行榜 | | `/meco baltop [currency]` | 同 `top` | | `/meco exchange <amount> <from> <to>` | 在启用兑换时进行货币兑换 | 快捷或兼容旧写法的命令： - `/bal`、`/balance`、`/money` - `/pay` - `/baltop` - `/moneytop` - `/ecotop` ### 🛠️ 管理员命令 | 命令 | 说明 | | :--- | :--- | | `/meco give <player> <amount> [currency]` | 增加余额 | | `/meco take <player> <amount> [currency]` | 扣除余额 | | `/meco set <player> <amount> [currency]` | 直接设置总余额 | | `/meco setrate <from> <to> <rate>` | 修改汇率并写回配置 | | `/meco hide <player>` | 从排行榜隐藏玩家 | | `/meco unhide <player>` | 恢复排行榜显示 | | `/meco refresh` | 清缓存并尝试修复未知玩家名 | | `/meco reload` | 重载配置与语言文件 | | `/meco checkupdate` | 立即检查更新 | | `/meco debug` | 切换调试模式 | | `/meco debug currencies` | 输出已加载货币 | `EcoCommand` 里还实现了以下管理操作： | 命令 | 说明 | | :--- | :--- | | `/eco bal [player] [currency]` | 余额查询快捷方式 | | `/eco top [currency]` | 排行榜快捷方式 | | `/eco freeze <player> <amount> [currency]` | 冻结可用余额 | | `/eco unfreeze <player> <amount> [currency]` | 解冻冻结余额 | | `/eco deductfrozen <player> <amount> [currency]` | 从冻结余额中直接扣除 | ## 🔐 权限 `plugin.yml` 中已声明： - `meoweco.admin` - `meoweco.balance` - `meoweco.balance.other` - `meoweco.pay` - `meoweco.take` - `meoweco.reload` - `meoweco.top` - `meoweco.eco.give` - `meoweco.eco.take` - `meoweco.eco.set` - `meoweco.eco.freeze` - `meoweco.eco.unfreeze` - `meoweco.eco.deductfrozen` - `meoweco.debug` 说明： - `give`、`take`、`set`、`freeze`、`unfreeze`、`deductfrozen` 可按独立权限节点分配 - `setrate`、`refresh`、`hide`、`unhide` 仍建议只分配给 `meoweco.admin` ## 🧩 PlaceholderAPI 标识符：`meoweco` ### 🪙 货币信息 - `%meoweco_currency_singular%` - `%meoweco_currency_plural%` - `%meoweco_currency_display%` - `%meoweco_currency_id%` - `%meoweco_currency_singular_<currency>%` - `%meoweco_currency_plural_<currency>%` - `%meoweco_currency_display_<currency>%` - `%meoweco_currency_id_<currency>%` ### 💳 余额类变量 支持的模式： - `balance` - `frozen` - `available` 支持的格式： - 默认格式：带千分位数字 - `raw` - `formatted` - `fixed` - `short` 示例： - `%meoweco_balance%` - `%meoweco_balance_points%` - `%meoweco_balance_short_gems%` - `%meoweco_frozen%` - `%meoweco_frozen_fixed_coins%` - `%meoweco_available_formatted_points%` ### 🌍 全服总量变量 - `%meoweco_server_total_<currency>%` - `%meoweco_server_total_raw_<currency>%` - `%meoweco_server_total_formatted_<currency>%` - `%meoweco_server_total_fixed_<currency>%` - `%meoweco_server_total_short_<currency>%` ### 🏆 排行榜变量 - `%meoweco_top_<rank>_name_<currency>%` - `%meoweco_top_<rank>_raw_<currency>%` - `%meoweco_top_<rank>_formatted_<currency>%` - `%meoweco_top_<rank>_fixed_<currency>%` - `%meoweco_top_<rank>_short_<currency>%` - `%meoweco_top_<rank>_balance_<currency>%` ## 🧪 开发者 API 服务获取方式： ```java MeowEcoAPI api = MeowEcoAPI.get(); ``` 当前开放的方法： ```java Collection<Currency> getRegisteredCurrencies(); Currency getCurrency(String id); double getBalance(UUID uuid, String currencyId); boolean deposit(UUID uuid, String currencyId, double amount); boolean withdraw(UUID uuid, String currencyId, double amount); double getFrozenBalance(UUID uuid, String currencyId); double getAvailableBalance(UUID uuid, String currencyId); boolean freeze(UUID uuid, String currencyId, double amount); boolean unfreeze(UUID uuid, String currencyId, double amount); boolean deductFrozen(UUID uuid, String currencyId, double amount); ``` ## ⚡ 性能与实现细节 - 排行榜缓存时长：5 分钟 - Placeholder 余额缓存时长：1 秒 - Placeholder 排行榜和全服总量缓存时长：30 秒 - 大多数数据库操作都在异步线程执行 - 被隐藏的账户会在数据库层面排除出排行榜 - 当前构建链已覆盖新版 Paper 构建和旧兼容编译校验，降低版本升级时的回归风险 [/MD]