# MeowEco Economy [![Modrinth 下载](https://img.shields.io/badge/Modrinth_⬇️-下载-E53935?style=flat&logo=modrinth&logoColor=white)](https://modrinth.com/plugin/meoweco/versions) [![GitHub Wiki 文档](https://img.shields.io/badge/GitHub_📚-Wiki_文档-E53935?style=flat&logo=github&logoColor=white)](https://github.com/xiaoyiluck666/MeowEco/wiki) [![GitHub 源码](https://img.shields.io/badge/GitHub_💻-源码-E53935?style=flat&logo=github&logoColor=white)](https://github.com/xiaoyiluck666/MeowEco) [![GitHub 提交 Issue](https://img.shields.io/badge/GitHub_📝-提交_Issue-E53935?style=flat&logo=github&logoColor=white)](https://github.com/xiaoyiluck666/MeowEco/issues/new/choose) **🧊 Measure inflation. Tune policy. Keep every balance change explainable.** MeowEco is a Paper-first, multi-currency economy for servers that want an economy they can operate, not just a number they can display. It gives staff a practical loop for keeping progression healthy. Give new players a useful starting balance while keeping the remaining grant separate from earned money. Configure whether grants can enter player trades, preserve their source through currency exchanges, and let integrated shops refund a payment once with its original source intact. **📊 Measure → ⚙️ Adjust → 🧾 Verify** - **📊 Measure supply and concentration** with `/meco policy report`: total supply, circulating balance, account count, richest-account share, and Top 10 concentration. - **⚙️ Adjust the money policy** with per-currency rich tax, transfer tax, exchange rates, and frozen funds for sinks, locked deposits, penalties, and progression gates. - **🧾 Verify every result** with transaction-level audit history, before/after balances, actor, source, and shared transaction IDs. You still get everything a modern server economy needs: 💰 coins, points, gems, tokens, and custom currencies; 🏪 Classic Vault and VaultUnlocked v2 compatibility; menu integrations; 📈 leaderboards; 🔄 safe migration; and 🛡️ SQLite/MySQL storage. The project is focused exclusively on the Paper plugin, with a current runtime target of Paper 26.1.x / 26.2 / 26.3 on Java 25. Chinese server: set `messages.language: "zh_CN"` in `plugins/MeowEco/config.yml`, then run `/meco reload`. ## Runtime - Server: Paper 26.1.x / 26.2 / 26.3 - Java: 25 - Optional integrations: Classic Vault, VaultUnlocked v2, PlaceholderAPI, TrMenu via commands/placeholders - Optional signed-identity grants: your server's MeowIdentity bridge plus PlaceholderAPI; neither is bundled - Storage: SQLite by default; MySQL supports multiple Paper instances sharing one database ## Build ```powershell .\gradlew.bat :meoweco-paper:check .\gradlew.bat :meoweco-paper:shadowJar ``` These commands are for contributors and CI verification. **服务器用户请只从 Modrinth 下载构建好的插件 JAR**： [⬇️ 下载 MeowEco（Modrinth）](https://modrinth.com/plugin/meoweco/versions) ## Main Features - 🎁 **Tracked starting funds:** keep a remaining-grant ledger alongside the total balance; allow personal spending while controlling direct player transfers. - 🛒 **Trade and refund APIs:** atomically check eligible funds, debit with a persistent reference, and refund once to the original wallet with its original grant labels. - 🪪 **Optional identity grants:** new wallets receive an offline base amount, then a verified premium session receives its supplement once. Existing wallets are not reset or retroactively granted money. - 🔔 **Compatible update notices:** only consider releases for the running Minecraft version and Paper, including correct handling of local build metadata. - 🧊 **Anti-inflation policy loop:** measure supply and wealth concentration, apply targeted tax or fund controls, then compare the next report and audit trail. - 📉 **Controlled sinks and locked funds:** rich tax can remove or redirect balances above a threshold, while transfer tax and frozen funds shape how money enters, moves through, and leaves the economy. - 🧾 **Accountability by default:** deposits, withdrawals, payments, exchanges, admin edits, API/Vault writes, taxes, and migrations record who changed what and why. - 🪙 Multi-currency accounts with custom names, symbols, precision, starting balances, and transfer tax. - 🔌 Classic Vault bridge for the default currency, plus an optional VaultUnlocked v2 provider with UUID accounts, multiple currencies, transfers, and async operations. - 🧩 PlaceholderAPI placeholders for balances, frozen balances, total balance, and leaderboard-style displays. - 🏪 Menu-friendly command flows for shops, VIP pages, exchanges, and reward systems. - 🧊 Admin tools for give, take, set, freeze, unfreeze, deduct frozen funds, hide/unhide, reload, and debug. - 📊 SQLite and MySQL storage with indexed balance queries for leaderboard and tax workflows, including consistent balances across multiple Paper instances sharing MySQL. - ⚖️ Progressive rich-tax and transfer-tax tiers per currency, applying marginal rates to slow runaway inflation without manual spreadsheet work. - 🔄 Dry-run migration from live Vault providers, EssentialsX userdata, or CSV with automatic pre-import backups. - 🧾 Transaction audit history for commands, transfers, exchanges, Vault/API writes, tax cycles, and migrations. ## Policy Loop: Measure → Adjust → Verify ### 📊 Measure Run `/meco policy report` to inspect each currency's total supply, circulating balance, account count, richest-account share, Top 10 concentration, and active rich-tax settings. ### ⚙️ Adjust - **Progressive rich tax** removes or redirects balances through configurable marginal wealth brackets. - **Progressive transfer tax** turns high-volume transfers into a controlled sink with the same bracket model. - **Frozen funds** reserve deposits, support penalties, and gate progression. - **Exchange rates** keep currencies independent while defining deliberate conversion paths. - **Multiple currencies** separate rewards, premium tokens, and event economies. ### 🧾 Verify Use `/meco audit [currency] [limit]` or `/meco audit export [limit]` to review the result. Audit entries include the operation, source, actor, amount, before/after balances, timestamp, and transaction ID; related sides of a payment or exchange share one transaction ID. MeowEco does not promise fixed prices or automatic protection from every inflation source. It gives staff the measurements and policy levers to make deliberate changes and verify their effect. ## New in 26.11.0: Starting Funds and Safe Refunds This feature release adds grant-source tracking, optional signed-identity starting balances, persistent payment receipts, and a fix for 26.x servers being offered the Minecraft 1.21.11 backport. ### Configure how starting funds can be used ```yaml initial-funds: allow-player-transfer: false spending-order: GIFT_FIRST ``` - The default blocks the remaining tracked grant from direct player payments while allowing ordinary personal spending. Set `allow-player-transfer: true` to permit grant transfers. - `GIFT_FIRST` spends grants before earned funds; `EARNED_FIRST` reverses that order. Changes take effect with `/meco reload`. - New configured starting balances and future signed-identity supplements are tracked. Existing balances with unknown sources are not relabeled. - Exchanges and permitted direct transfers preserve grant labels. Frozen funds also reduce the earned amount eligible for transfer. - A rejected `/pay` explains when the available money is restricted starting funds. ### Optional signed-identity starting balances ```yaml identity-initial-balance: enabled: false balances: coins: offline: 100.0 premium: 1000.0 ``` Enable this only when your server provides the MeowIdentity signed-session bridge and PlaceholderAPI. These integrations are not included in MeowEco. Amounts must fit currency precision, with `premium >= offline >= 0`. A newly eligible wallet receives the offline amount first. When a signed session confirms premium status, MeowEco adds the difference once without replacing later earnings, spending, or frozen funds. Missing or unresolved identity data remains pending. Existing wallets are not backfilled, and pending grants retain the amounts recorded when the wallet was created. ### Integrate player shops and refunds `MeowEcoAPI` exposes `getInitialGiftBalance`, `getTransferableBalance`, and atomic `withdrawForPlayerTrade`. For a payment that may need a refund, use `debitWithReceipt(uuid, currency, amount, reference, playerTrade)`, `getReceiptState`, and `refundReceipt`. Use a unique persistent reference per payment. Retrying the same debit does not charge twice; refunding it restores the original wallet and source labels once. Keep receipts to preserve duplicate protection. **Generic Vault withdrawals do not identify the counterparty or transaction purpose.** Existing Vault shops keep ordinary spending behavior. A player shop must explicitly integrate the player-trade API to enforce grant restrictions; a plain Vault deposit refund is treated as earned money. MeowEco cannot automatically enforce these rules across every third-party shop. ### Upgrade notes Back up the database and configuration before upgrading. This release adds grant, source-audit, and payment-receipt tables without rewriting historical wallet balances. Signed-identity grants are disabled by default; source tracking and the transfer policy apply to new qualifying grants. If you need to relax grant restrictions, change the policy on this version. An older JAR does not maintain source labels or receipts, so transactions made during a downgrade require reconciliation before source restrictions are enabled again. ## Compatibility Matrix | Server | Java | Status | | --- | --- | --- | | Paper 26.1.1 | 25 | Compile-tested | | Paper 26.1.2 | 25 | Compile-tested | | Paper 26.2 | 25 | Compatibility compile-tested | | Paper 26.3 | 25 | Primary build target | | Purpur based on the supported Paper lines | 25 | Expected compatible | ## Commands | Command | Purpose | | --- | --- | | `/meoweco` / `/meco` / `/meow` | Unified command entry | | `/money [player] [currency]` | Check balance | | `/money exchange ` | Exchange currencies | | `/pay [currency]` | Pay another player | | `/baltop [currency]` | Show balance leaderboard | | `/eco [currency]` | Admin balance operations | | `/eco [currency]` | Admin frozen-fund operations | | `/eco setrate ` | Update exchange rate | ## Permissions | Permission | Default | Purpose | | --- | --- | --- | | `meoweco.balance` | true | Check own balance | | `meoweco.balance.other` | op | Check another player's balance | | `meoweco.pay` | true | Pay players | | `meoweco.top` | true | View leaderboard | | `meoweco.take` | op | Use `/take` | | `meoweco.reload` | op | Reload config and language files | | `meoweco.eco.give` | op | Admin give | | `meoweco.eco.take` | op | Admin take | | `meoweco.eco.set` | op | Admin set | | `meoweco.eco.freeze` | op | Freeze funds | | `meoweco.eco.unfreeze` | op | Unfreeze funds | | `meoweco.eco.deductfrozen` | op | Deduct frozen funds | | `meoweco.debug` | op | Toggle debug mode | | `meoweco.admin` | op | Parent admin permission | ## Configuration Primary config: `meoweco-paper/src/main/resources/config.yml` Important sections: - `storage`: choose `sqlite` or `mysql`. - `default-currency`: currency used by Vault and default command behavior. - `exchange-rates`: enable/disable and define rates. - `rich-tax`: configure per-currency periodic tax rules. - `currencies`: define currency ids, symbols, names, initial balances, and transfer tax. - `initial-funds`: control player transfers of tracked starting funds and the spending order. - `identity-initial-balance`: optionally set signed-identity starting amounts for new wallets. ## Release Notes **Latest: 26.11.0** — [中文更新日志](https://github.com/xiaoyiluck666/MeowEco/blob/main/docs/release/CHANGELOG_26.11.0_CN.md) · [English release notes](https://github.com/xiaoyiluck666/MeowEco/blob/main/docs/release/CHANGELOG_26.11.0_EN.md). See [CHANGELOG.md](https://github.com/xiaoyiluck666/MeowEco/blob/main/CHANGELOG.md) for release details. Releases are distributed through [Modrinth](https://modrinth.com/plugin/meoweco/versions); GitHub hosts the source code, CI status, and [Wiki documentation](https://github.com/xiaoyiluck666/MeowEco/wiki).

MeowEco Economy

Compatibility

Minecraft: Java Edition

Platforms

Links

Tags

Creators

Details