Content generated with AI — it may contain mistakes.

ExyliaEconomy/GuidesUpdated in v1.4.0

Print banknotes

Let players turn money into a paper item with /withdraw and cash it back with right-click or /deposit, safe against copies.

Page 6 of 255 min read

A banknote is money printed as paper. Players run /withdraw <amount> [currency] and get a note they can give, drop, trade and keep in chests like any item. Whoever right-clicks it, or runs /deposit while holding it, gets the money.

Before you start#

You need a stored currency, see Create a currency. Only stored currencies print notes; item, experience and display-only currencies have no switch. A new currency has banknotes off, so a fresh server prints none until you turn one on.

Steps#

Open the currency

Run /economyadmin and left-click the currency.

Turn banknotes on

Click Payments, then Banknotes. It now reads on.

Let players use it

/withdraw needs exyliaeconomy.withdraw, given to everyone by default. Redeeming needs no permission, see Permissions.

Check that it works#

Print one

With some balance, run /withdraw 100 <currency>. You get a paper item named BANKNOTE with the amount; without a currency word the default currency is used.

Cash it

Right-click with the note in either hand. You read "Redeemed a banknote of …" and the balance is back. /deposit does the same while you hold it.

Going further#

When a withdrawal is refused#

It is refused, before anything is taken, when the currency's Banknotes switch is off ("… cannot be withdrawn as a banknote."), when the amount is not positive or rounds to nothing in the currency's decimals, when the balance is still loading, or when the player cannot afford it.

With a full inventory the withdrawal still works: the note is queued and handed over when a slot frees up or on the next join. Two withdrawals closer than half a second are one.

What a note is#

The item is drawn from the banknote section of plugins/ExyliaEconomy/lang/en/messages.yml (lang/es/messages.yml for Spanish), so you can change its material, name and lore. See colours and messages and languages.

plugins/ExyliaEconomy/lang/en/messages.yml
yaml
banknote:
  material: PAPER
  name: '{primary}&lBANKNOTE &8[{success}%amount%&8]'
  lore:
    - ''
    - '{secondary}Information:'
    - ' {letters_black}▎ {letters}Currency {letters_black}» {highlight}%currency%'
    - ' {letters_black}▎ {letters}Signed by {letters_black}» {highlight}%issuer%'
    - ' {letters_black}▎ {letters}Issued {letters_black}» {info}%date%'
    - ''
    - '{warning}➥ Right-click to redeem'
    - ''

%amount% is the formatted amount, %currency% the currency's plural name, %issuer% who printed it and %date% the day it was printed. The note always glows and never stacks.

What a note is worth is not on the item. The item carries only the note's id; the amount, currency and issuer are a row in exylia_banknotes, written before the money is taken. Renaming or editing the item changes nothing.

Redeeming#

Right-click with a note in either hand, at the air or at a block, or run /deposit while holding one (main hand first, then off hand). Right-clicking needs no permission; /deposit needs exyliaeconomy.use. Either needs the currency's own permission when it names one.

The note leaves the hand before anything else happens, then its row is claimed in the database, then the money is paid:

What the database saysWhat the player sees
Not redeemed yet"Redeemed a banknote of …": the money is theirs.
Already redeemed, or no such note"This banknote was already redeemed or is not valid." The item is gone.
The currency refused the payment (its ceiling)The note comes back, unredeemed, with the reason.
The database did not answerThe note comes back: "The banknote could not be processed right now."
A copied note pays once

A duplicated stack, a creative clone, the same note redeemed on two servers at once: only one claim on the row can win, so the money is paid exactly once on the whole network and every other copy disappears.

Per-server currencies#

A note remembers which balance it was printed from. A currency kept per server or per network group (see Network) only redeems its notes where that balance is the same: anywhere else the redeem is refused and the note comes back with "This banknote can only be redeemed on the server that printed it." A note of a global currency redeems anywhere.

Kept out of crafting and trading#

A note is paper, and vanilla would turn paper into books, maps and rockets, or trade it to a librarian. Any inventory holding a note refuses to produce a result: crafting tables, the inventory grid, crafters, anvils, grindstones, smithing tables, looms, cartography tables, stonecutters and villager trades.

In the ledger#

A note's two halves are two ledger lines: note:withdraw on the issuer and note:redeem on whoever redeemed it. A rollback never reverts either, because the other half is a note somebody may still hold. See Ledger.

Fixing a stuck note

The note is recorded in the database first, then the money is taken and the note handed over in the same tick. If the money cannot be taken after all, the record is discarded and nothing is handed out.

If a payment is refused and the database then fails to mark the note unredeemed again, the note comes back to the player but stays marked redeemed, and the console names its id. Set redeemed_at to 0 on that row of exylia_banknotes to make it redeemable again. A player who leaves before a refused note can be handed back is logged the same way, with the row to pay by hand.

Something missing on this page? Tell us on Discord