Support and Feedback

• Report bugs, request features, or follow open issues

MeowEco Documentation Guide

Version: 26.9.1

MeowEco is a modern multi-currency economy plugin for Paper servers. It is not just a balance table; it helps server owners connect coins, points, gems, shops, menus, leaderboards, taxes, and database-backed economy control into one practical system.

🐾 Built for point shops, RPG currency systems, VIP menus, recharge flows, leaderboards, rich-tax balancing, and servers that want smooth Vault / PlaceholderAPI / TrMenu integration.

🌟 Highlights

• 🪙 Multi-Currency and Custom Currencies: run coins, points, gems, tokens, or any custom economy with independent names, symbols, precision, starting balances, and transfer tax.
• 🏪 Shop, VIP, and Menu Ready: bridge the default currency through Vault, expose balances through PlaceholderAPI, and use clean commands for TrMenu shops, exchanges, and reward buttons.
• 📊 Display-Ready Economy Data: raw, formatted, fixed, and short output styles make balances, leaderboards, and total-economy views easier to show.
• ⚖️ Rich Tax and Economy Control: schedule taxation per currency with custom thresholds and rates to slow inflation and support long-running servers.
• 🧊 Frozen Funds: freeze, unfreeze, and deduct frozen money for deposits, penalties, locked trades, quest guarantees, and custom server rules.
• ⚡ Efficient Runtime: async-heavy database work, cached balance/top lookups, and DB-level hidden-account filtering for high-frequency servers.
• 🛡️ Clear Version Baseline: compiled against the Paper 26.2 API line, guarded by a 26.1.x compatibility compile check, and emitted as Java 25 bytecode for Paper 26.1.x / 26.2 servers.

🚀 Server Owner Setup

• Plugin version: 26.9.1
• Recommended server software: Paper
• Economy bridge: works with Vault using the default currency
• Placeholder support: works with PlaceholderAPI for menus, scoreboards, chat, and HUD-style displays
• Menu integration: works well with TrMenu for shops, VIP pages, exchange buttons, and reward flows
• Current primary build target API: io.papermc.paper:paper-api:26.2.build.40-alpha
• Compatibility compile-check API: io.papermc.paper:paper-api:26.1.1.build.8-alpha
• meoweco-paper is compiled with a JDK 25 toolchain
• The plugin artifact targets Java 25 bytecode
• If you run Paper 26.1.x / 26.2, the server itself still needs Java 25 because that requirement comes from upstream Paper

✨ Best-Fit Scenarios

• 🪙 Multi-currency servers: coins, points, gems, tokens, and similar parallel economies without forcing every gameplay loop into one balance.
• 🏪 Shop and menu flows: TrMenu-driven purchases, exchanges, permission rewards, and claim buttons with simple commands and placeholders.
• 🧱 RPG and survival economy: frozen funds, rankings, rich tax, transfer tax, and exchange rates can combine into a more durable economy loop.
• 📊 Display-heavy gameplay: formatted balances, top lists, and server-wide totals are ready for menus, scoreboards, and chat displays.
• 🔧 Integrated server setups: easy to drop into servers already using Vault, PlaceholderAPI, and TrMenu without writing extra glue logic.

⚙️ Configuration Overview

Main file: plugins/MeowEco/config.yml

🧩 Core Config Example

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: "&eCoins"
    singular: "Coin"
    plural: "Coins"
    initial-balance: 100.0
    decimal-places: 2
    transfer-tax: 0.0

💸 Rich Tax Focus

• threshold: only the balance above this point is taxed
• rate: clamped between 0.0 and 1.0
• start-time: server local time in HH:mm
• interval: supports raw minutes and values like 30m, 6h, 1d
• destination.type = system: taxed funds are removed
• destination.type = player: taxed funds are redirected into a player account

Why rich tax matters:

• 🏦 helps drain excess money when the server economy starts inflating
• ⚖️ works as a soft “redistribution” tool so a few ultra-rich accounts do not dominate the whole economy
• 🧭 turns economy balancing from manual intervention into scheduled rule-based control
• 🛒 when tax goes to a player account, you can measure exactly how much tax was collected and reuse that pool for system buy-shops, public rewards, or other balancing loops

🔄 Exchange Focus

• Supports direct A -> B rates
• Supports inverse lookups
• Supports default-currency-derived exchange paths
• Good for combining coins, points, gems, or other layered currencies

🪙 Multi-Currency and Custom Currency Focus

• Supports multiple currencies at the same time
• Supports fully custom currency ids such as coins, points, gems, or token
• Each currency can define its own display name, singular/plural form, decimal precision, starting balance, and transfer tax
• Lets you separate survival money, shop points, event tokens, gems, and other economy layers
• A better fit for servers that need a structured economy instead of a single universal balance

🎨 Formatted Balance Display

• Per-currency display names
• Singular/plural support
• Decimal precision control
• Placeholder formats: raw, formatted, fixed, short
• Clean output for balances, rankings, and server totals

Formatting examples:

• Assume a player balance of 1000000
• raw: 1000000
• formatted: 1,000,000
• fixed: 1000000.00
• short: 1M

If the balance grows further, for example 1250000000, short formatting is much easier to present as something like 1.25B.

Why formatting matters:

• 📉 huge economy numbers stay readable instead of cluttering menus, chat, and scoreboards
• 👀 short output is easier for players to scan when balances become very large
• 🧾 the same formatting logic can be reused across menus, rankings, placeholders, and chat messages
• 🎯 makes economy presentation look cleaner and more intentional for both players and server owners

🧭 TrMenu Integration

MeowEco is very menu-friendly and fits well into:

• 🛒 point shops
• 👑 VIP menus
• 🔁 exchange buttons
• 🎁 reward claim flows
• 🔒 frozen-balance gameplay

Two integration styles are recommended.

1. 🪄 Short action style

If your TrMenu environment already provides MeowEco short conditions or actions, you can write:

actions:
  left:
    condition: 'meco points >= 99'
    actions:
      - 'meco-take: points 99'
      - 'console: lp user %player_name% permission set vip.level1 true'
      - 'tell: &aPurchase successful'

To give currency:

actions:
  left:
    actions:
      - 'meco-give: points 99'
      - 'tell: &aGranted 99 points'

Meaning:

• condition: 'meco points >= 99': checks whether the player has enough points
• meco-take: points 99: removes currency
• meco-give: points 99: grants currency

2. 🔧 Universal command style

If you want the safest and most portable setup, call the commands directly:

actions:
  left:
    condition: 'js: Number("%meoweco_balance_points%") >= 99'
    actions:
      - 'console: meco take %player_name% 99 points'
      - 'tell: &aPurchase successful'
    deny:
      - 'tell: &cNot enough points'

To give currency:

actions:
  left:
    actions:
      - 'console: meco give %player_name% 99 points'
      - 'tell: &aGranted 99 points'

Notes:

• console: is recommended for meco give / meco take
• Conditions can directly use %meoweco_balance_points%
• points is just an example currency id; replace it with coins, gems, or your own configured id
• Frozen-balance flows can also use console: eco freeze ..., console: eco unfreeze ..., and console: eco deductfrozen ...

⌨️ Command Overview

📌 Registered Root Commands

• /meoweco
• /money
• /pay
• /baltop
• /eco

Aliases:

• /meoweco: meco, meow
• /money: balance, bal
• /eco: economy

👤 Player Commands

Command	Description
/meco	Shows help
/meco bal [player] [currency]	Check balance
/meco money [player] [currency]	Same as bal
/meco pay <player> <amount> [currency]	Send money
/meco top [currency]	Show leaderboard
/meco baltop [currency]	Same as top
/meco exchange <amount> <from> <to>	Exchange currencies when enabled

Shortcut or legacy-compatible commands:

• /bal, /balance, /money
• /pay
• /baltop
• /moneytop
• /ecotop

🛠️ Admin Commands

Command	Description
/meco give <player> <amount> [currency]	Add funds
/meco take <player> <amount> [currency]	Remove funds
/meco set <player> <amount> [currency]	Set total balance
/meco setrate <from> <to> <rate>	Update exchange rate and save to config
/meco hide <player>	Hide player from leaderboard
/meco unhide <player>	Show player on leaderboard again
/meco refresh	Clear caches and fix unknown stored names
/meco reload	Reload config and messages
/meco checkupdate	Run update check immediately
/meco debug	Toggle debug mode
/meco debug currencies	Print loaded currencies

Additional admin economy routes implemented in EcoCommand:

Command	Description
/eco bal [player] [currency]	Balance shortcut
/eco top [currency]	Leaderboard shortcut
/eco freeze <player> <amount> [currency]	Move available funds into frozen balance
/eco unfreeze <player> <amount> [currency]	Release frozen funds
/eco deductfrozen <player> <amount> [currency]	Deduct from frozen and total balance

🔐 Permissions

Declared in 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

Notes:

• give, take, set, freeze, unfreeze, and deductfrozen can be granted through dedicated permission nodes
• setrate, refresh, hide, and unhide should remain on the stricter meoweco.admin path

🧩 PlaceholderAPI

Identifier: meoweco

🪙 Currency Metadata

• %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 Placeholders

Supported modes:

• balance
• frozen
• available

Supported formats:

• default formatted output
• raw
• formatted
• fixed
• short

Examples:

• %meoweco_balance%
• %meoweco_balance_points%
• %meoweco_balance_short_gems%
• %meoweco_frozen%
• %meoweco_frozen_fixed_coins%
• %meoweco_available_formatted_points%

🌍 Server Total Placeholders

• %meoweco_server_total_<currency>%
• %meoweco_server_total_raw_<currency>%
• %meoweco_server_total_formatted_<currency>%
• %meoweco_server_total_fixed_<currency>%
• %meoweco_server_total_short_<currency>%

🏆 Top Placeholders

• %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>%

🧪 Developer API

Service lookup:

MeowEcoAPI api = MeowEcoAPI.get();

Main methods currently exposed:

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);

⚡ Performance and Runtime Notes

• Leaderboard cache lifetime: 5 minutes
• Vault default-currency read cache lifetime: 0.5 seconds
• Placeholder balance cache lifetime: 1 second
• Placeholder top and server-total cache lifetime: 30 seconds
• Most database operations are dispatched asynchronously
• Hidden accounts are excluded from leaderboard output at the database layer
• The current build flow targets the modern Paper 26.1.x / Java 25 baseline