Content generated with AI — it may contain mistakes.

ExyliaEconomy/How it worksUpdated in v1.4.0

Network

Sharing balances across servers: who writes a balance, what happens to a change for a player somewhere else, global, group and per-server currencies, server ids and Redis.

Page 11 of 254 min read

Every server that points at the same database shares the same currencies, the same economy settings and the same balances. There is nothing to configure beyond the database itself; Redis makes it immediate.

Who writes a balance#

Ownership, not synchronisation. A player's balance is claimed by the server they join, loaded into memory, and written by that server alone while they are there. When they leave, their last balance is written and the claim let go.

A server the player joins waits up to five seconds for the previous one to finish its last write and let go, then takes the balance over. A write by a server that lost the balance in between is never written over the new owner's: it is queued for it instead. Two servers can never save two different totals.

Until a player's balance is claimed — the first moment after joining — a deposit to them is queued and applied right after, and anything that would spend their money is refused with "Your balance is still loading."

A change for somebody elsewhere#

A deposit, withdrawal or set for a player who is offline, or online on another server, is not written to their balance. It is queued in the database for whoever holds them:

ChangeWhen it lands
DepositAlways, in full, up to the ceiling. Anything the ceiling cuts from a payment goes back to the payer.
WithdrawalFloored at zero: it cannot overdraw somebody it cannot see.
Set, resetReplaces the balance.

Queued changes land oldest first, each exactly once however many servers hear about it:

  • a player online elsewhere has it folded in by that server at once when Redis is on, and within a minute otherwise;
  • an offline player has it folded in when they next join, on whichever server.

Changes made while a server was unreachable are retried every second, and a change that cannot be written at all is logged in the console with everything needed to apply it by hand.

Network scope of a currency#

Network scope, on a stored currency's Integrations page, decides which servers share a player's balance:

ScopeOne balance forStored asLeaderboard, banknotes, interest
Global (default)Every server on the database<id>One for the network; notes redeem anywhere; paid once per player
GroupThe servers of one network group<id>#<group>One per group; notes redeem inside the group; paid per group
ServerEach server alone<id>@<server-id>One per server; notes redeem where printed; paid by each server

The group is the server's network-group in ExyliaLib's config.yml, said once for every plugin: two survivals in group survival share a balance while a boxpvp server keeps another. A group currency on a server with no group is kept per server, and the console warns once. Changes queued for a group or per-server balance are only ever claimed by a server it belongs to.

Available on lists the groups or server ids a currency exists on; blank is every server. On a server left out the currency is not registered at all: no command, no Vault, no balance of it.

The scope is refused once the currency holds any balance other than the starting one, because the balances it holds would be left behind under the other key. Decide before players earn any.

Server ids#

Ownership is recorded by server-id, set under redis in each server's database.yml even when Redis itself is off:

plugins/ExyliaEconomy/database.yml
yaml
database:
  redis:
    enabled: true
    host: 10.0.0.6
    server-id: survival-1

It is server-1 on every server that never set it. Two servers sharing balances under the same id both believe they hold the player and overwrite each other. When the plugin sees the default id together with Redis or a networked database, it warns once at start: "this server's id is the default 'server-1' while balances are shared…". Give every server its own.

The id is also what a per-server currency is keyed by (and, with a group, the network group): renaming a server's id moves it onto a new, empty set of per-server balances.

With and without Redis#

With RedisWithout Redis
A change for a player on another serverLands at onceLands within a minute
A currency edited in /economyadminEvery server reads it again at onceOther servers keep the old settings until /economyadmin reload or a restart
Balances, queued changes, flagsShared through the databaseShared through the database

Redis is optional, and configured once in database.yml. See the library's database page.

Stopping a server#

When a server stops, every player's last balance is written and handed back, and the plugin waits up to ten seconds for writes still on their way. Writes still pending after that are logged with their amount. Deposits gather for half a second before they are written; withdrawals are written at once.

Something missing on this page? Tell us on Discord