ShadowEconomy

On update, this file (like every other file of the plugin) is moved to the new version automatically: it is rebuilt from the new one and everything you had changed or added is carried into it. The old files are kept in backup/<date>/, and if something needs your attention you will find PORTING-<version>.txt in this folder, saying what to fix.

A wrong value blocks nothing: it is replaced by the factory one and reported in the console at start-up, with the path and what was expected.

Everything here - keys, sections and comments - is English, because it is read by whoever runs the server, wherever in the world that is. The words players see live in lang/, and are English by default; Italian ships too (messages.default-locale below).

The bank gives money somewhere to live that is not a chest.

Three things: - an ACCOUNT that earns interest, at a rate that falls as the balance

rises. The tiers are the whole point: a flat rate on any amount is
a machine for making the already rich richer, and on a server you
see it inside a week.

- TERM DEPOSITS, which pay more in exchange for not touching the

money until a date. Breaking one costs.

- LOANS, with a limit worked out from what the player actually has,

instalments taken automatically, and a default that shuts the door
until they settle up.

A bank balance is NOT a new table: it is an ordinary account with an id derived from the player's. So it is saved, tracked in /eco audit and synchronised between servers by the same code as the wallets, and it stays out of /baltop.

IN ITALIAN: the same file with Italian names and descriptions is in esempi/it_IT/currencies.yml inside this plugin's folder. Copy it over this one to use it: the plugin never reads it on its own.

The currencies of the server. The one named in "default" is what Vault uses, what every command without an explicit currency uses, and what a shop price means when it does not name one.

The id of a currency is typed by players, so keep it in English. Only "display", "plural" and "symbol" are shown to them, and those are the ones meant to be translated.

decimals: digits after the point. 0 for a "token" style currency. max-balance: 0 means no ceiling. payable: false takes the currency out of /pay (usual for premium ones). baltop: false takes it out of the leaderboard.

IN ITALIAN: the same file with Italian names and descriptions is in esempi/it_IT/district.yml inside this plugin's folder. Copy it over this one to use it: the plugin never reads it on its own.

The shopping district: the building the server owner puts up, divided into shops that players rent.

How a plot is made:

1. /market admin wand
2. left click one corner, right click the opposite one
3. /market admin create shop-1 shop
4. /market admin panel shop-1  ->  set the door and the visit point

From then on the plot shows up in /market and anybody can rent it.

The exchange: five cryptocurrencies and the companies players found.

Four of the five are the ones everybody has heard of, so a player understands what they are looking at without being taught. The fifth, ShadowCoin, is the server's own and the only one that can also be produced: it comes out of the mining rigs and goes back into the crypto shop, where it is burned.

Prices move with geometric brownian motion - the standard way markets are simulated - plus two things that make it a game and not a

screensaver:
  - player pressure (buying pushes up, selling pushes down)
  - market events, announced in chat.

volatility is annualised: 0.9 is a wild crypto, 0.2 a quiet index. Changing tick-interval does not change the character of an asset.

If you prefer, the four real coins can follow their real price on Binance instead: see finance.real-prices below. Off by default.

Two things in one file, because they are the two ways players sell to each other:

- the auction house (/ah), to sell to anybody without being there;
- chest shops, to sell from your own base.

IN ITALIAN: the same file with Italian names and descriptions is in esempi/it_IT/mining.yml inside this plugin's folder. Copy it over this one to use it: the plugin never reads it on its own.

Mining rigs: a block that opens like a case, with a mainboard, a processor, a power supply, cooling and graphics cards inside.

A rig produces crypto, draws power paid for in real currency, gets hot and wears out. It is not free money: the electricity is paid every hour, difficulty rises with the number of rigs running on the server, and what comes out is crypto, which has to be sold on the exchange before it is money.

To give somebody a part:   /rig give <id> [amount] [player]
For the list of parts:     /rig parts

IN ITALIAN: the same file with Italian names and descriptions is in esempi/it_IT/shop.yml inside this plugin's folder. Copy it over this one to use it: the plugin never reads it on its own.

The server shop, ready to use.

This is not a sample to fill in: fourteen categories, priced against each other, meant for a SkyBlock. Players earn by selling what their islands produce - cobblestone, sugar cane, melons, iron, mob drops - and spend on decorative blocks, gear, and things that cannot be farmed.

THE SCALE IS LOW, AND THAT IS ON PURPOSE

An economy breaks when the shop pays big numbers for things produced by the stack: the first player with an automatic farm makes ten million in a week, and from then on money means nothing to anybody. Here wheat is worth 3.50 and a diamond 10: you earn slowly, and what you earn counts.

The fixed points everything else follows from:

cobblestone       0.50     the generator never runs out
log               2.00     a tree is time spent
wheat             3.50     one plant, one wheat
potato / carrot   1.50     the same plant gives two or three
iron ingot        4.00
diamond          10.00     the dearest of the ordinary things

The wheat-against-potato rule holds for the whole catalogue: it is not the item that is priced, it is the HARVEST. Sugar cane grows and is cut by itself, so 0.50. A melon slice is one ninth of a melon, so 0.25.

THE BUYING PRICE

Not one multiplier. The rarer a thing is, the worse buying it should be compared with going and getting it:

x3      under 1 sell value   cobble, dirt, sand, leaves, seeds
x2.5    up to 4              logs, crops, wool
x6      from 4 up            ingots, glass, machines, tools
x15     valuable             obsidian, pearls, blaze rods
x100    rare                 diamond, emerald, netherite

A log sells for 2 and costs 5. A diamond sells for 10 and costs 1000: the shop buys it off you gladly, but it is not the place to kit yourself out. That is the difference between a shop that serves an economy and one that replaces it.

THE RULE THAT DOES NOT MOVE

Nothing craftable is worth more than the parts it is made of. A piston is worth its three planks, four cobble, one ingot and one redstone, and not a coin more. Without that rule an auto crafter running in a loop prints money and nobody notices.

The deliberate exception is smelting: cobblestone becoming stone is worth double, raw ore smelted into an ingot gains. That is progression, not a hole - it is what makes an island build furnaces.

If you change a price, look at what that item is crafted into. Raising a sell price on its own is the classic way to open a printer inside your own shop.

WHAT YOU CAN CHANGE WITHOUT THINKING

display / description / icon    how a category looks
slot                            where it sits on the screen
limit-buy-per-day               how many a day, per player
permission                      to hide it from those without it

Every entry has:

id                  unique identifier (used by the database and the API)
material            the material, or "item" with a serialised item
buy                 what it costs the player. 0 = cannot be bought
sell                what it pays the player. 0 = cannot be sold
dynamic             true = the price moves with demand (on by default)
limit-buy-per-day   0 = no limit
limit-sell-per-day  0 = no limit
permission          if present, that permission is needed to see it
lore                extra lines in the description

Display names and descriptions are the only text meant for players, so they are the part to translate. Everything else - keys, ids and these comments - is English, because it is read by whoever runs the server, anywhere in the world.

To add or fix an entry without touching this file: /shop edit

IN ITALIAN: the same file with Italian names and descriptions is in esempi/it_IT/tokens.yml inside this plugin's folder. Copy it over this one to use it: the plugin never reads it on its own.

A token is money with a body: it has a balance like any currency, and it can leave the account as an item - held in the hand, given away, put in a chest, sold in a shop, and brought back to the counter to become a balance again.

TWO FORMS, and one line picks between them:

currency: coins   -> it is a BANKNOTE of a currency that already
                     exists. Cashing it gives coins back.
currency: none    -> it is a CURRENCY OF ITS OWN. The plugin registers
                     it as one, so /balance, /pay, /baltop, the shop
                     and the auction house understand it with no
                     further configuration.

TWO WAYS OF BEING AN ITEM, and this is the choice that matters:

serialized: false -> TO THE BEARER. It stacks, it is convenient, and

it is copyable in exactly the way a diamond is
copyable. Fine for small change.

serialized: true -> REGISTERED. Every item carries a number that

exists once in the database and is cashed once.
Copying the item copies the number, and the
second one to arrive is refused. Use this for
anything worth anything.

The 3D model is set with item-model - a name, not a number, so two plugins cannot fight over "shadow:banknote". It needs a resource pack that defines that model; without one the item is simply the material you chose, and it works just the same.

The id of a token is typed by players and used by other plugins, so keep it in English. "display", the item name and its lore are the parts meant to be translated.

WHAT SHIPS

One token, and on purpose. A server that starts with four of them has four things nobody has decided what to do with yet, and they all show up in /balance. The one below is the event token: its own currency, earned at events, spent in /tokenshop.

To add another, copy its block and change the two lines that matter - "currency" and "serialized" - as described above. A banknote of coins is currency: coins with serialized: false; a cheque is currency: coins with value: 0 and serialized: true.

Trading between two players: items, money and experience, in one window that both of them are looking at.

HOW A TRADE IS KEPT HONEST

Every trade scam is the same trick. The thief waits for the other player to read the offer, and swaps something in the moment between the reading and the accepting. Three rules here make that moment not exist, and none of them can be switched off:

1. any change to either side cancels BOTH acceptances, not only the
   acceptance of whoever made the change;
2. once both have accepted the offer FREEZES, and a countdown runs
   during which nothing at all can be altered by anybody;
3. only then do the confirm buttons appear, and each shows the whole
   deal - what leaves, what arrives - in its own tooltip.

On top of that the right hand side of the screen describes every incoming item by what it really is: a renamed block says its real name, a shulker box says whether it is empty, a worn tool says how worn. That is where the rest of the scams live.

WHAT IS WRITTEN DOWN

Every completed trade goes into the database, in words, and is read back with "/trade log <player>". When two players tell two different stories, that row is the answer.

Items being offered have already left their owner's inventory, so they are written down too, and anything a crash leaves behind is handed back at the next login. Nothing is ever dropped on the ground.

Colours are written with & codes: &a &c &7, &l for bold, &#FF8800 for an exact colour. <gray> style tags work too if you prefer them: the plugin understands both, everywhere.

Placeholders are written <like-this> and are NOT colours: <amount>, <player>, <prefix>. Leave them as they are. This file is the final fallback: a key missing everywhere else is looked up here, so keep it complete.

A message is always one line. Sound, channel and cooldown are written as neighbouring keys, the same name plus a suffix:

paid: "&aDone."
paid-sound: entity.experience_orb.pickup
paid-channel: ACTION_BAR     # CHAT | ACTION_BAR | TITLE | SUBTITLE | NONE
paid-cooldown: "2s"          # per player anti spam
paid-volume: 0.7
paid-pitch: 0.8

That way the message key stays the message: a translator touches only that, and anyone looking a key up finds it where it is written.

Lists are multi line descriptions (the lore of a GUI item).

The shopping district, /market.

Tiers and plots live in district.yml: only the size and the frame of the screens are decided here.

The exchange, /crypto and /stocks.

The assets live in finance.yml, each with its own icon: size and frame are decided here.

The auction house, /ah.

Titles and descriptions live in lang/, because they follow the player's language. Size and frame are decided here.

The rigs, /rig.

Components and their icons live in mining.yml: the size and frame of the list are decided here.

The front screen of the shop, /shop.

The categories and where they sit live in shop.yml, each with its own "slot": only the frame and the service buttons are decided here.

The texts are empty on purpose: empty means the language file, in the language of each player (shop.main-title, shop.sell-all.title and .lore, shop.editor.button and .button-lore). A text written here is shown as it is to every player, whatever their language.

The wallet, /wallet.

Size, filler and button positions are decided here. The text of the translated entries lives in lang/, because it changes with the player's language; what is written here is the same for everybody. That is why the title and the button names below are empty: empty means the language file (wallet.title, wallet.buttons.*).

Slots: 0 is top left, then left to right, row by row. With 5 rows the slots run from 0 to 44.