Content generated with AI — it may contain mistakes.

ExyliaAnalytics/GuidesUpdated in v1.3.0

Track your server's economy

Where the agent finds money moving — ExyliaLib, Vault, VaultUnlocked, PlayerPoints, ExcellentEconomy and the API — how each change is counted once, and what the Economy page makes of it.

Page 12 of 2810 min read

In a few minutes you can see whether money is piling up faster than people play: how much was created and destroyed, for which reason, who holds it, and whether the economy is inflating. The agent needs two things from each currency: what moved (money created and destroyed, and why) and what exists (the money supply). This guide shows how to get both flowing and how to read the page.

Economy is Paper and Spigot only; a proxy moves no money. Everything here is dropped at the agent when the Economy module is off.

Before you start#

  • A Paper or Spigot server linked to your workspace, see Connect your server.
  • The Economy module on. It is on by default; check it under Settings, then What the plugin collects (Remote configuration).
  • At least one economy the agent can read: an ExyliaLib currency, a Vault or VaultUnlocked economy, PlayerPoints or ExcellentEconomy. Any of them is measured on its own; for the exact money supply use an economy plugin that reports it, such as ExyliaSurvivalCore.
  • The Economy permission (view_economy) in your role to read the page.

Steps#

Check what the agent found

On the game server, run /analytics status. The Vault and VaultUnlocked lines say whether the agent stands in front of that economy, and the economy sources it hooked are listed with them. If your economy plugin is missing, see The Vault proxy.

Let a few players earn and spend

Changes are sent once a minute. Play for a few minutes: sell something, buy something, pay another player.

Open the Economy page

In the dashboard sidebar open Revenue, then the In-game economy tab. Pick the Currency at the top (the list shows how many players each one has) and, if you run several game servers, the server filter.

Read the verdict

Under Is money losing value? you get Inflating, Stable or Deflating. Then open Every reason to see which source or sink drives it.

Check that it works#

A currency appears in the Currency list with a player count, and Money added and Money removed show the trades you just made. If the page says No economy data in this range, the module is off, the server is not Paper, or no economy was found: run /analytics status and see Common problems.

The Is money losing value? verdict needs at least 3 weeks of balance snapshots; before that it says there is not enough data. That is normal on a new install.

Going further#

The sources#

Each balance change is counted once, from the first source that sees it:

SourceCurrenciesReason recorded
ExyliaLib's balance change eventEvery ExyliaLib currency, by its id.The transaction's own reason, such as shop:sell or pay:tax.
A pass-through proxy in front of VaultvaultThe reason an ExyliaLib caller gave (ExyliaLib 1.460.0 or newer); otherwise vault: and the plugin that called Vault, such as vault:shopguiplus.
The same in front of VaultUnlockedvault for the default currency, otherwise the named currencyThe same: the caller's own reason, otherwise vault: and the plugin that called it.
PlayerPoints' change eventplayerpointsplayerpoints
ExcellentEconomy's change eventEach currency by id; the primary one is vault while ExcellentEconomy is the Vault economy.excellenteconomy
Rival Credits' purchase event and /credits commandrivalcreditsrivalcredits:shop, :console (a store such as Tebex), :staff, :pay
ExyliaAnalytics.economy(...)Whatever the plugin names.Whatever the plugin says.

Currency ids are lowercased and cut to 32 characters, reasons to 64. A change of zero is ignored.

The Vault proxy#

Vault gives no event when money moves, so the agent stands in front of it: it registers its own economy at the highest priority, forwards every call untouched to the real one, and once a deposit or withdrawal has succeeded, records it with the plugin that made the call (the first plugin on the call stack that is not Vault, VaultUnlocked, ExyliaLib or the agent). Nothing it does can change the result of a payment or make one fail.

The proxy is not installed when:

  • vault-wrapper: false in the agent's config.yml;
  • the Vault economy already reports every change through ExyliaLib: ExyliaSurvivalCore, or any economy ExyliaLib knows as a currency that announces its own changes, such as ExyliaEconomy (ExyliaLib 1.372.0 or newer; with an older one it is wrapped like any other);
  • VaultUnlocked's own bridge to a Vault economy that already reports through ExyliaLib (the bridge is left unwrapped, so each payment is not counted twice);
  • the economy plugin registered itself at the highest priority first, so the proxy would sit unused.

/analytics status says which of these applies on the Vault and VaultUnlocked lines.

Plugins that keep the economy they found at startup

The proxy goes in on the first server tick, after every plugin has enabled. A plugin that looked up Vault's economy while enabling and kept it calls the real economy directly, and its payments are not seen. The agent re-checks whenever an economy registers or unregisters.

Read the page#

SectionShows
Money in circulation, Money per active player, Money added, Money removedThe headline numbers, with the sink ratio ("removed per 1 added").
Is money losing value?Money per active player over the last 8 full weeks with a fitted line: Inflating above +5% a week, Deflating below −5%, otherwise Stable. Needs at least 3 weeks of data.
Money in circulationEvery holder's balance summed, per period.
Money per active playerMoney in circulation ÷ players active in the trailing 30 days. Rising faster than play means inflation.
Money vs playersThe change of each since the period started. Money growing well above players means inflation.
Money added and removedPer period, what each reason added (above the line) and removed (below).
Every reasonEvery reason money moved for, largest impact first: Paid in, Paid out, Net, Share of total, Players, and the type (Adds money, Removes money, Transfer). Vault reasons show the calling plugin, marked via Vault.
Who holds the moneyTypical balance, Inequality (Gini), the share held by the richest 1% and 10%, and Unused money (held by players away 30 days or more).
New player progressTypical balance of new players 1, 7 and 30 days after their first session.
Top balancesEach player's latest known balance beside their highest ever and what they earned and spent through plugins since tracking began, up to 100 players.
Inflation causesWhole-season panels (not the range): who and what feeds the supply, with inflation alerts such as one player behind a money source.

The Market tab beside it covers auction houses, shops and sell commands.

What exists: supply and balances

Changes alone cannot say how much money there is. Three sources can:

SourceWhat it reportsWhen
ExyliaAnalytics.supply(...)The exact money supply: every balance summed and how many accounts hold money, per storage scope.Whenever the plugin sends it.
Balance readsOne player's balance: through Vault (unless the Vault economy reports through ExyliaLib), PlayerPoints, and each ExcellentEconomy currency other than the one read through Vault. Read off the main thread.On join and quit, at most once per player every 5 minutes.
ExyliaLib holdingsWhat a player holds in every ExyliaLib currency no source above already reports.On join, on quit, and every 10 minutes for everybody online.

The holdings matter for currencies that change without a transaction: an experience bar grows from a mob, a currency item is picked up off the floor. For those, counting what people carry is the only money supply there is. ExyliaLib takes each count on the thread that owns the player, and a count that arrives after the player left (reading as zero because the inventory is gone) is thrown away rather than recorded as an empty pocket. It needs an ExyliaLib recent enough to count off the player's thread; with an older one the status reads ExyliaLib (flows only).

Counting each change once

A server can run several of these at once, and they call each other: ExyliaLib's vault currency goes through Vault, VaultUnlocked answers through its own interface, and an economy fires its own event while Vault is moving the money. The rules:

  • A change that happens inside a proxied Vault call is the same change: every event fired during it is ignored, and the outer Vault call is the one recorded.
  • ExyliaLib's vault currency is dropped when Vault is already covered, by the proxy, by an economy that reports through ExyliaLib, or by ExcellentEconomy's own event.
  • ExyliaLib's points currency is dropped when PlayerPoints is hooked.
  • Rival Credits fires no event when a balance changes, so changes made with /credits are read as the balance a tick after the command minus the one before: refused commands report nothing, and set or reset on an offline player is not seen. Credits another plugin adds through Rival's API show only as a balance that moved with no flow. Every shop purchase is also a trade in credit_shop. New in v1.3.0
How it is sent

Changes are summed per player, currency and reason and sent once a minute as one economy.flow each: how many changes, the total gained, the total spent, and the balance after the last one. A sell wand firing a thousand times a minute costs one event. At most 50,000 of those keys are held at once; past that, new ones wait for the next minute. On shutdown the last partial minute is sent with the rest.

Definitions
MetricDefinition
Money in circulationPer period, each storage scope's latest supply report, summed over scopes. A period without a report is empty, never carried forward.
Estimated money supplyFor a currency nobody reports a supply for: the sum of every known player's latest balance (below zero counts as zero), carried forward between changes. Players not seen since tracking began are missing, so it trails the real supply; the page labels it estimated with the number of players behind it.
Reason netMoney in − money out of one reason, over every player. A payment between players cancels inside its reason.
Added / removedThe positive / negative reason nets.
Sink ratioRemoved ÷ added. Below 1 money piles up; above 1 it drains.
Adds money, removes money, transferA transfer when the net is within 5% of the larger of its gross in and out; otherwise it adds money (positive) or removes it (negative).
Latest known balanceA player's most recent balance from a change or a balance read.
Gini0 when everyone holds the same, 1 when one player holds everything.
Shared or separate economies

Every server reports the same currency ids (vault, playerpoints), whether they share one economy or each run their own. Over all servers, a player's balance is the last one reported anywhere: right for a shared economy, and one of two balances for separate ones. Read separate economies one server at a time.

Something missing on this page? Tell us on Discord