Content generated with AI — it may contain mistakes.

ExyliaEconomy/GuidesUpdated in v1.4.0

Create a currency

Create stored, item, experience and display-only currencies in game, set their rules, tax and exchange rates, and give each its own command.

Page 4 of 2510 min read

You end up with a new currency that players can see in /wallet, read with its own command and pay each other in. Currencies are created and edited in game with /economyadmin; there is no currency file to edit.

Before you start#

You need exyliaeconomy.admin (operators have it) and a first currency check, see Your first currency. Decide the kind first:

KindWhat it is
StoredA balance kept in the database. Works for players who are offline or on another server. The only kind with rules, a ledger, a leaderboard, interest and banknotes.
ItemAn exact item in the player's inventory. The balance is how many they carry; paying takes them out, being paid puts them in.
Display onlyNo balance of its own: the name, symbol, decimals and format another plugin's currency is shown with, such as vault or points.

Experience is a fourth source. You do not create it, you switch it on in Economy settings: xp_levels and xp_points become currency ids a shop can price in.

Steps#

Open the list

Run /economyadmin. Every currency is listed in sort order.

Create it

Click Create currency. Type an id in chat (a-z, 0-9 and _, up to 32; it never changes later), then pick Stored, Item or Display only. For an item currency you are then asked to place the exact item.

Give it a look

Left-click your currency, then the General card. Icon, Appearance (name, plural, symbol, decimals, format, compact format) and Order are here. The summary on the edit screen shows a full and a compact preview.

Set the rules

Back to the edit screen, Rules: starting balance, balance ceiling, permission, least a player may send and transfer tax. Use Payments, Exchange, Interest and Integrations for the rest, see the list below.

Check the command

Commands holds the names, separated by commas and without the slash. The first is the command, the rest are aliases.

The edit screen is a hub of cards and shows only what the currency's kind uses. Each card opens a page of its own, with a Back button:

CardWhat it holds
GeneralIcon, appearance and sort order.
CommandsCommand names and the switch that turns the commands on or off.
RulesStarting balance, ceiling, permission, minimum, tax and where the currency exists. For an item currency, the Item card holds the item.
PaymentsTransfers switch, pay confirmation, banknotes.
ExchangeThe exchange switch and the rates.
InterestRate, interval, cap and interest while offline.
IntegrationsLeaderboard, network scope and Vault economy.

Every change is saved to the database at once, registered on this server and announced to the other servers on the same Redis, which reinstall the currency commands. If the database refuses a write you read "Could not save … to the database."

Check that it works#

Give yourself some

Run /economyadmin give <you> 500 <id>.

Read it

Run /<id> (the command you named). It shows your balance. /wallet lists every currency you may use.

Pay somebody

/<id> pay <player> 100 sends 100.

Going further#

Give a currency its own command#

Every stored currency with Commands enabled and at least one command name gets its own command, installed the moment it is saved and removed when it is turned off. For a currency called shards:

/shards                              your balance
/shards <player>                     somebody else's (needs exyliaeconomy.others)
/shards pay <player> <amount>        pay in shards (needs exyliaeconomy.pay)
/shards top [page]                   its leaderboard
/shards history [player]             its ledger
/shards exchange <amount> <to>       swap shards for another currency
/shards give|take|set <player> <amount>   administrators
/shards reset <player>                    administrators

It needs exyliaeconomy.use, plus the currency's own permission if it has one. A name another plugin already holds still answers as /exyliaeconomy:<name>, and the console says so. Item currencies keep their command names on the screen, but only stored currencies get a command.

Make a currency VIP only#

In Rules, type a permission such as economy.gems and give it to the rank in your permissions plugin, see Permissions. The editor's hint says it is "needed to use its commands". It does more: a player without it does not see the currency in their wallet or in command suggestions, cannot be handed it by /economyadmin giveall, cannot redeem its banknotes, earns no interest in it, and every command refuses them with "You may not use …". Plugins asking ExyliaLib whether a player may use a currency get the same answer.

Add a transfer tax#

In Rules, set Transfer tax from 0 to 100. The editor's hint says the tax is "kept back from every transfer". It is not: the receiver gets the full amount and the sender pays the tax on top. /pay 100 with a 5 % tax costs the sender 105, and the tax goes to nobody. See Payments.

Cap balances#

Balance ceiling is the most a balance may hold; -1, or anything not above zero, means none. A deposit that would pass it is refused whole, never cut down: "That would take the balance over its ceiling of …", or "The balance is at its ceiling of …" when it is already there. A payment refused this way charges the sender nothing.

A change for a player who is not on this server is checked against the last balance read for them. If it still lands over the ceiling (two servers paid them at once) it is cut to the ceiling as it lands: the part of a payment that did not fit goes back to the payer, and anything else is logged in the console with the amount.

Whatever the currency says, no balance can pass 1018, the largest number the database column holds with room to spare. -1 means no ceiling of the currency's own, not no ceiling at all.

Exchange rates#

In Exchange, switch it on and type the rates as other_id=rate, separated by commas: shards=0.01, gems=2 means 1 of this currency is worth 0.01 shards and 2 gems. A rate must be a positive number; anything else is refused with what could not be read. The target can be any currency the server runs: stored, item, experience or another plugin's.

Players run /economy exchange <amount> <from> <to>. It swaps at the source currency's rate and needs Exchange on the source. What is received is the amount, cut to the source's decimals, times the rate, cut to the target's decimals. Only what that costs is taken, so the fraction the target's decimals round away stays with the player. The source is taken first and a target that refuses gives it back.

Decimals#

Every amount is cut to the currency's decimals before it moves: /pay Steve 10.567 in a currency with two decimals sends 10.56. A currency with 0 decimals is whole numbers only, and an amount that rounds down to nothing is refused as not an amount.

Items and experience live on the player#

An item or experience currency only has a balance while the player is on this server. A payment to somebody who is not here, or whose inventory is full, is kept and handed over on their next join with "Delivered N payments that were waiting for you." Taking from somebody who is not here fails. An item currency is the whole item (name, lore, model and enchantments): only a stack exactly like it counts, and a renamed copy is a different item.

Delete a currency#

Right-click it in the /economyadmin list and confirm. A stored currency's balances stay in the database, unused until a currency with that id exists again. Deleting the currency published to Vault unpublishes it.

Network scope locks once balances exist

The scope decides which rows hold the balances, so it only changes while the currency holds nothing but starting balances: "… already holds balances, so it cannot switch between networked and per-server." Decide it before players earn any. See Network.

Economy settings#

Economy settings (bottom of the currency list) are the switches that belong to no single currency. They are one row in the database, shared by every server.

SettingFresh serverWhat it does
Experience levelsoffMakes xp_levels a currency.
Experience pointsonMakes xp_points a currency.
LedgeronWrites down every movement of a stored currency. See Ledger.
Ledger retention90 daysCycles through 30, 90, 180, 365 days and forever. Older lines are deleted every hour.
Vault on toponServes Vault even when another economy plugin is installed.
Vault economydollarsWhich currency is published; shown here, chosen on a stored currency's Integrations card.
Offline pay noticeonTells a player on join what they were paid while away.
Languageserver'sLanguage of the plugin's menus and messages; cycles through the server default, en, es, pt, fr, ru and tr. See messages and languages.
DebugoffMakes the log explain what the plugin does.
Every field of a currency
FieldKindsNew currencyWhat it does
Idalltyped on creationThe key balances are stored under.
IconallGOLD_INGOT; an item currency uses its itemWhat wallets and lists draw.
Name, pluralallemptyOne unit and many. Colours work, see colours.
SymbolallemptyBlank for none.
Decimalsall0; display only -10 to 8. -1 on a display-only currency keeps what the provider says.
Formatall%amount% %name%%amount%, %symbol% and %name%.
Compact formatallemptyThe same for scoreboards, where %amount% reads 1.2k.
Command namesstored, itemthe idThe first is the command, the rest its aliases. Anything not a-z, 0-9 or _ is dropped.
Sort orderallafter the last oneLower is shown first, in wallets, lists and every other plugin's currency picker.
Itemitemasked for on creationThe exact item.
Starting balancestored0What a player begins with the first time a balance is created for them.
Balance ceilingstored-1The most a balance may hold.
PermissionstoredemptyNeeded to see and use the currency at all.
Least a player may sendstored1The minimum for /pay.
Transfer taxstored0A percentage, 0 to 100, charged to the sender on top of the amount.
Exchange ratesstorednoneother_id=rate.
TransfersstoredonWhether players can pay each other.
ExchangestoredoffWhether it can be swapped at its rates.
LeaderboardstoredonWhether its top list, rank and supply work. See Leaderboards.
Network scopestoredglobalEvery server, the server's network group, or each server alone. A click cycles them.
Available onstoredeverywhereGroups or server ids the currency exists on; blank is every server. A server left out has no command, no Vault and no balance of it.
Pay confirmationstored0A /pay above it asks first; 0 never.
BanknotesstoredoffWhether /withdraw prints notes of it. See Banknotes.
IntereststorednoneRate, interval, cap and offline payout. See Interest.
Commands enabledstoredonWhether its command names exist at all.
Vault economystoredoffWhether it is the currency published to Vault. See Vault.

Something missing on this page? Tell us on Discord