Skip to content

Configuration

The config is plugins/xMoney/config.yml, written on first start. Apply changes with /xmoney reload; only storage and network need a restart.

Section What it covers
theme The prefix and colours xMoney’s messages share: see the theme.
messages What players and staff are told, and shared errors under messages.error.
currency The currency’s names, symbol, decimals and how amounts are written.
starting-balance What a player has the first time they join.
max-balance The most one account can hold.
commands Each command’s switch, aliases and permission; the least /pay sends, when it asks to confirm, and /baltop’s page size.
ledger How long ledger lines are kept: a year by default.
storage Where balances are kept: SQLite in the plugin’s folder (money.db), or MySQL/MariaDB.
network Sharing balances between servers.
update-checker Checks Modrinth for a new version once a day: Privacy.

format is how every amount is written, by xMoney and by any plugin that asks Vault: {symbol}{amount} gives $1,234.50, and {amount} {name} gives 1,234.50 dollars (or 1 dollar). decimals is how many decimal places amounts are shown with, from 0 to 4, and how many an amount typed into a command may have. Amounts from other plugins always keep four places, so a shop that charges 0.995 and then 0.005 takes exactly 1.00, and with decimals: 0 a 0.4 charge still takes 0.4 rather than nothing. Past four places, money paid in is rounded down and money taken is rounded up, so rounding never makes money. Lowering decimals later keeps the parts of balances it no longer shows, so nothing is lost.

Every change to every balance is a line in the ledger, saved together with the balance it changed, so the two always agree, even after a crash. Lines older than keep-days are deleted a minute after startup and then once a day, a slice at a time so payments never wait. 0 keeps them all. Balances never depend on old lines.

type: sqlite needs nothing set up. Use type: mysql (it works with MariaDB too) and fill in mysql to keep balances on a database server. Every balance is read once when the server starts, before anyone can join or any plugin can ask, so a change here applies on restart. Balances aren’t copied between databases.

Network mode is experimental in 1.0. It never loses or makes money, but on a busy network with a slow or unreliable database, some shop purchases may be refused; see below. A single server isn’t affected by any of this.

For servers that share balances, such as a lobby and a survival server:

  1. Give every server the same storage settings, type: mysql, the same database and the same table-prefix.
  2. Turn network.enabled on, on each server, and restart them.

Each server keeps every balance in memory as usual, and reads again whatever another server changed within check-every seconds (3 by default). Anything that takes money (a payment, a shop purchase, /eco take) is decided by the database itself, so two servers can never spend the same money twice. On a network that costs one trip to the database, a millisecond or two on the same machine or LAN, for each payment.

Why it’s experimental: a shop asks Vault on the server thread and needs an answer on the spot, so the server waits for the database. That wait is kept short:

  • A withdrawal made on a server thread waits at most network-wait-ms (50 by default, 250 at most) for the database to take it up. If it hasn’t, it’s refused and nothing is taken, then or later. Commands and xMoney’s API don’t hold a server thread, so they wait up to 5 seconds.
  • While the database is failing (a save failed and none has worked since), withdrawals are refused at once. Deposits still work and are saved once it’s back.
  • Once the database has taken a payment up, the server waits for its answer, a few milliseconds normally. If the payment hasn’t reached its commit within a second, it’s undone and refused, with nothing taken; with one slow reply still to wait out, that’s about 4 seconds at most. The commit itself waits at most 3 more. xMoney’s own connection to the database gives up on connecting, or on any one reply, after 3 seconds, whatever storage.mysql.properties says, and while the database is away it tries again every 2 seconds.
  • If the database closed xMoney’s connection while the server was quiet (MySQL’s wait_timeout), the connection is checked and replaced before the next payment, not tried and failed.

If the database dies at the moment a withdrawal commits, the calling thread waits until the database answers again. Whether the money was taken is never guessed: a payment reported as failed was never charged. On the main thread that can freeze the server, which is why network mode is experimental. Leases, planned for 1.1 (#66), remove the case: each online player’s balance is decided by the server they’re on, in memory.

A burst of deposits (thousands in one moment, from a plugin paying everyone) is saved together, and a withdrawal that arrives meanwhile waits for that save; on a server thread it’s refused after network-wait-ms, with nothing taken.

Deposits are made at once and saved after, as on one server. max-balance is checked against what each server knows, so on a network it’s a soft limit. If a server’s checks for the others’ changes stop working for a while, it reads every balance again once they work. An import on one server is set in steps of a hundred balances or 20 milliseconds, whichever comes first, with payments between, and the other servers read every balance again once it’s done.

plugins/xMoney/config.yml
# xMoney: the economy, and Vault, in one plugin.
# Docs: https://docs.xenastudios.co/xmoney/configuration/
#
# Apply changes with /xmoney reload. A bad value falls back to its default with a
# warning in the console; xMoney never stops over config. Messages are MiniMessage:
# https://docs.xenastudios.co/start/formatting/
# Managed by the plugin, to carry your settings forward on updates. Don't edit it.
config-version: 1
# The look xMoney's messages share. The default messages use these as tags, so changing
# a colour here restyles them all. Write a style as MiniMessage tags: <gray>,
# <#10AC79>, or <gold><bold>.
theme:
# <prefix> starts the default messages. Make it your server's name, such as
# "<dark_gray>[<gradient:#B48CFF:#5EE08A>MyServer</gradient>]</dark_gray> ", or blank for none.
prefix: "<#10AC79>»</#10AC79> "
# The colour of message text that has no tag of its own.
base: "<gray>"
# <highlight>: names and values, such as a player or a speed.
highlight: "<#10AC79>"
# <success>: something turned on or done.
success: "<#5EE08A>"
# <error>: something refused or turned off.
error: "<#FF6B6B>"
# What players and staff are told.
messages:
error:
# The console or a command block ran a command only players can use.
player-only: "<prefix><error>Only players can use this command."
# The sender lacks the command's permission.
no-permission: "<prefix><error>You don't have permission to do that."
# No online player has that name. <player> is the name typed.
player-not-found: "<prefix><error>No player named <highlight><player></highlight> is online."
# The command was typed wrong. <usage> is how to type it.
usage: "<prefix><error>Usage:</error> <usage>"
# The command hit an error. The console has the details.
failed: "<prefix><error>Something went wrong. The console has the details."
# /balance.
balance:
# Your own. <balance> is formatted, as is every amount in messages.
own: "<prefix>Balance: <highlight><balance>"
# Someone else's. <player> is their name.
other: "<prefix><highlight><player></highlight>'s balance: <highlight><balance>"
# Nobody by that name has played here. <player> is the name typed.
unknown: "<prefix><error><highlight><player></highlight> has never played here."
# /pay.
pay:
# To the payer. <amount>, <player>, and <balance>: what they have left.
sent: "<prefix><success>Sent</success> <highlight><amount></highlight> to <highlight><player></highlight>. You have <balance> left."
# To whoever is paid, if they're online. <amount>, <player>: who paid.
received: "<prefix><success>Received</success> <highlight><amount></highlight> from <highlight><player></highlight>."
self: "<prefix><error>You can't pay yourself."
# Below the minimum. <minimum>.
too-little: "<prefix><error>The least you can send is <highlight><minimum></highlight>."
# The payer hasn't got it. <amount>, <balance>.
not-enough: "<prefix><error>You don't have <highlight><amount></highlight>. You have <balance>."
# A payment of confirm-above or more asks first. <command> runs it, confirmed; put it
# in a click.
confirm: "<prefix>Send <highlight><amount></highlight> to <highlight><player></highlight>? <click:run_command:'<command>'><hover:show_text:'<command>'><success>[Confirm]</success></hover></click>"
# It would take them over max-balance. <player>.
limit: "<prefix><error><highlight><player></highlight> can't hold that much."
# Another plugin refused it.
cancelled: "<prefix><error>That payment was refused."
# On a network, the shared database didn't answer in time. Nothing was sent.
unavailable: "<prefix><error>The bank can't be reached right now. Nothing was sent; try again in a moment."
# /baltop.
baltop:
# Above the list. <total> is every player's money added up, <count> how many players.
header: "<prefix>Richest players. <gray>All <count>: <total>"
# One player. <rank>, <player>, <balance>.
line: "<gray>#<rank></gray> <highlight><player></highlight> <balance>"
empty: "<prefix>Nobody has any money yet."
# Below a page, when there's more than one. <page>, <pages>, and <next>/<previous>: the commands.
footer: "<gray>Page <page> of <pages></gray><has_previous> <click:run_command:'<previous>'><hover:show_text:'<previous>'><highlight>« Previous</highlight></hover></click></has_previous><has_next> <click:run_command:'<next>'><hover:show_text:'<next>'><highlight>Next »</highlight></hover></click></has_next>"
# /eco and /eco history.
eco:
# <amount>, <player>, and <balance>: what they have now.
given: "<prefix><success>Gave</success> <highlight><player></highlight> <amount>. They have <balance>."
taken: "<prefix><success>Took</success> <amount> from <highlight><player></highlight>. They have <balance>."
set: "<prefix><success>Set</success> <highlight><player></highlight>'s balance to <balance>."
reset: "<prefix><success>Reset</success> <highlight><player></highlight>'s balance to <balance>."
# /eco take for more than they have. <player>, <balance>.
not-enough: "<prefix><error><highlight><player></highlight> only has <balance>."
# It would take them over max-balance. <player>.
limit: "<prefix><error><highlight><player></highlight> can't hold that much."
# Another plugin refused it.
cancelled: "<prefix><error>Another plugin refused that change."
# On a network, the shared database didn't answer in time. Nothing changed.
unavailable: "<prefix><error>The shared database can't be reached right now. Nothing changed."
# Sent while the history is read from the database.
working: "<prefix><gray>Looking..."
# Above a page of history. <player>, <count>: how many changes in all.
history-header: "<prefix>History of <highlight><player></highlight>: <count> changes"
# One change. <ago>: how long ago, <change>: + or - the amount, <what>: what it was,
# <balance>: the balance after.
history-line: "<gray><ago> ago</gray> <change> <what> <gray>→ <balance>"
# The player has no history.
history-empty: "<prefix><highlight><player></highlight> has no history."
history-footer: "<gray>Page <page> of <pages></gray><has_previous> <click:run_command:'<previous>'><hover:show_text:'<previous>'><highlight>« Previous</highlight></hover></click></has_previous><has_next> <click:run_command:'<next>'><hover:show_text:'<next>'><highlight>Next »</highlight></hover></click></has_next>"
# How <change> looks when money came in, and when it went out. <amount>.
change-in: "<success>+<amount></success>"
change-out: "<error>-<amount></error>"
# The words <what> shows for each kind of change. <other>: the other player, <source>: who did it, <reason>.
words:
start: "starting balance"
paid-to: "paid <other>"
paid-by: "from <other>"
given: "given by <source>"
taken: "taken by <source>"
set: "set by <source>"
# A plugin's change, without and with a reason.
plugin: "<source>"
plugin-reason: "<source>: <reason>"
imported: "imported from <source>"
# /xmoney import.
imports:
# A dry run: what an import would do, changing nothing. <source>, <count> accounts,
# <total>: their money added up, <skipped> that can't be imported, <command>: the import, confirmed.
dry-run: "<prefix><highlight><source></highlight> has <highlight><count></highlight> balances, <total> in all (<skipped> can't be imported). Importing sets each of those players' balance here to theirs. <click:run_command:'<command>'><hover:show_text:'<command>'><success>[Import]</success></hover></click>"
# <count> balances set from <source>, <skipped> skipped.
done: "<prefix><success>Imported</success> <highlight><count></highlight> balances from <source>. <skipped> skipped."
# There's nothing to import. <source>, <reason>.
nothing: "<prefix><error>Nothing to import from <source>: <reason>"
# The other plugin's data couldn't be read. <source>, <reason>.
failed: "<prefix><error>Couldn't read <source>: <reason>"
running: "<prefix><error>An import is already running."
reading: "<prefix><gray>Reading <source>..."
# Some of the accounts have changed in xMoney since (payments, /eco, other plugins), and
# importing would set them back. <count> of them, <source>, <command>: the import anyway.
overwrite: "<prefix><error><highlight><count></highlight> of these accounts have changed here since, and importing sets them back to <source>'s balances. <click:run_command:'<command>'><hover:show_text:'<command>'><error>[Import anyway]</error></hover></click>"
# Amounts typed into commands.
amount:
# Not a number. <amount> is what was typed.
invalid: "<prefix><error><highlight><amount></highlight> isn't an amount. Try 250, 12.5 or 1.5k."
# More decimals than the currency has. <decimals>.
too-precise: "<prefix><error>Amounts have at most <highlight><decimals></highlight> decimals."
# Past the most an account can hold.
too-large: "<prefix><error>That's more than an account can hold."
# How money looks. Other plugins show it this way too, through Vault's format. Changes
# apply on /xmoney reload.
currency:
# The currency's name for one, and for more than one.
singular: "dollar"
plural: "dollars"
symbol: "$"
# Decimal places: 2 for cents, 0 for whole coins. At most 4. Amounts are shown with
# these, and amounts typed into commands rounded to them. Other plugins' amounts keep
# 4 places, so a payment split in two costs what it would whole. Lowering it later
# keeps the parts of balances it no longer shows.
decimals: 2
# How an amount is written. {amount} is the number, {symbol} the symbol, and {name}
# the singular or plural name: "{amount} {name}" gives "12.50 dollars".
format: "{symbol}{amount}"
# Put between thousands, as in 1,000,000. Blank for none.
thousands-separator: ","
decimal-separator: "."
# The short form's thousands, millions, billions and trillions, as in 1.2k.
short-suffixes: ["k", "M", "B", "T"]
# What a player has the first time they join. Players who already have an account keep
# theirs.
starting-balance: 0
# The most one account can hold. Payments that would take a balance over it are refused.
# At most 100,000,000,000,000.
max-balance: 1000000000000
# Each command can be turned off (enabled: false, so another plugin can have its name),
# given other aliases, or need another permission. A blank permission lets everyone use it.
commands:
# /balance [player]: a player's balance. Someone else's needs permission-others.
balance:
enabled: true
aliases: ["bal", "money"]
permission: ""
permission-others: "xmoney.balance.others"
# /pay <player> <amount>: send money to another player, online or not.
pay:
enabled: true
aliases: []
permission: ""
# The least one payment can be.
minimum: 0.01
# Payments of this much or more ask the player to confirm first. 0 never asks.
confirm-above: 0
# /baltop [page]: the richest players.
baltop:
enabled: true
aliases: ["balancetop", "moneytop"]
permission: ""
per-page: 10
# /eco give|take|set|reset|history: staff commands. Each part has its own permission:
# xmoney.eco.give, .take, .set, .reset and .history.
eco:
enabled: true
aliases: ["economy"]
permission: "xmoney.eco"
# The ledger: every change to every balance, for /eco history.
ledger:
# Delete ledger rows older than this many days, checked at startup and once a day. 0
# keeps them all. Balances never depend on old rows.
keep-days: 365
# Where balances and the ledger are kept. sqlite needs nothing set up. Changes apply on a
# restart; balances aren't copied from one to the other.
storage:
# sqlite keeps everything in one file in the plugin's folder, with nothing to set up.
# mysql (or MariaDB) is for networks, or servers with a lot of history.
type: "sqlite"
# Put in front of every table's name, so plugins and servers can share one database.
table-prefix: "xmoney_"
# Only for type: mysql.
mysql:
host: "localhost"
port: 3306
database: "minecraft"
username: "minecraft"
password: ""
# Extra connection settings, as in a JDBC URL: useSSL=true&serverTimezone=UTC.
properties: ""
# For several servers sharing balances through one MySQL or MariaDB database. Every
# server must use the same storage settings and table-prefix. Applies on a restart.
# Experimental in 1.0: a withdrawal is decided by the shared database, so a shop's Vault
# call waits for it on the server thread (see network-wait-ms), and while the database
# is away, withdrawals are refused. Money is never lost or made either way.
network:
# On when several servers share this plugin's MySQL or MariaDB database, so a change
# made on one (a ban, a payment) reaches the others within a few seconds.
# Leave it off for a single server: it does nothing on SQLite.
enabled: false
# Seconds between checks for the other servers' changes.
check-every: 3
# On a network: the longest, in milliseconds, a withdrawal made on a server thread (a
# shop's Vault call) waits for the shared database to take it up. If it hasn't, it's
# refused and nothing is taken. At most 250, so a slow database can't stall the server.
# Commands and xMoney's API don't hold a server thread, so they wait up to 5 seconds.
network-wait-ms: 50
# Tells you when a new version is out.
update-checker:
# Ask Modrinth for the newest version at startup and every 24 hours. It sends
# only the plugin version, the platform and the Minecraft version.
enabled: true
# Logged, and shown to admins when they join, when a newer version is out.
# <plugin>, <current>, <latest> and <url> are filled in.
message: "<prefix><plugin> <highlight><latest></highlight> is out (you have <current>): <click:open_url:'<url>'><hover:show_text:'Open on Modrinth'><highlight><underlined><url>"