Coins & stock market

The economy module gives every player a coins account that is the same on all servers – or, with clusters, one per group of servers. The market builds on it: a stock market in the dashboard where players use their coins to bet on rising or falling item prices.

Enabling

The economy preset enables core, inventory-sync, item-tracking, locks, economy and market. See Modules & Presets.

Coins

One account per player and cluster in the database (eternal_wallets, amounts stored internally in cents, i.e. two decimal places). Every transaction is recorded in eternal_transactions. Debits are atomic – an account cannot go negative.

config.yml

economy:
  enabled: true
  currency-name: Coin
  currency-name-plural: Coins
  symbol: "$"
  starting-balance: 100     # starting balance of new accounts
  max-pay: 1000000          # maximum amount per /pay

The same values are in the economy: section of api.yml – there for display and the market in the dashboard. Keep both places identical.

Commands

Coins below the name

Players can turn on Coins unter dem Namen ("Coins below the name") in /settings (updated every minute):

Staff with eternal.economy.see-hidden see hidden balances in red; this can be turned off in /settings → Team → Versteckte Coins sehen ("See hidden coins"). For this they get their own scoreboard, which is mirrored from the main scoreboard every 2 s (teams, sidebar and tab of other plugins are preserved).

See Settings.

Vault and other plugins

The EconomyService is registered as a Bukkit service. If Vault is on the server, Eternal additionally registers itself as the Vault economy – without a compile-time dependency on the Vault API. Shop, jobs or land-claim plugins then see the Eternal coins.

Dashboard: Coins & Markt → Coins

Visible to every logged-in player:

• your own balance and your own transactions
• transfers to other players
• top list
• other players' balances with eternal.economy.balance.others
• admin transactions (give, take, set) with eternal.economy.admin
• choosing the cluster when there are several

Clusters

A cluster is a group of servers that share the same accounts. For example, all CityBuild servers share one balance while the minigame servers have their own coins (or their own currency, such as "Gems"). A player has a separate account in each cluster.

• Members are server names and/or cloud tasks. A task covers every one of its services (<task>-<n>, e.g. citybuild-1, citybuild-2). If a server is listed by name in one cluster and its task in another, the name wins.
• Default cluster (default): every server that no cluster lists belongs to it. That includes all accounts from before clusters – the update moves or deletes nothing.
• Currency per cluster (optional): name, plural, symbol and starting balance. Empty fields use the values from economy: in the server's config.yml.
• A server determines its cluster on start and checks for changes every 30 s. All transactions – /money, /pay, /baltop, /eco, Vault, AdminShop, MagicItems, clans, /trade, plots – run in the server's cluster. /pay only reaches accounts in the same cluster.
• Stored network-wide in eternal_shared_config (economy-clusters.json). Accounts and transactions are keyed by the pair (cluster, player).

Dashboard: Coins & Markt → Cluster

With eternal.economy.admin: create clusters (name + ID; the ID is fixed afterwards), rename them, set currency and starting balance, assign servers and cloud tasks (suggestions from the servers and tasks that reported in, free input possible) and delete them. The right-hand side shows which cluster each reported server ends up in. A server assigned to a cluster leaves its previous cluster.

On Coins and Geld-Statistik ("Money statistics") you pick the cluster at the top right (only visible when there is more than the default cluster).

• Stock market: It belongs to one cluster, typically CityBuild. You set it on that cluster with Börse ("Stock market"). Stakes and payouts use that cluster's wallets and currency, wherever someone trades from. Without a mark, the default cluster is used.
• Clan bank: Every cluster has its own clan bank. /clan bank shows and books the bank of the cluster whose server you are on. The bank from before clusters is in the default cluster.
• AdminShop quota: There is one network-wide quota for all clusters. Payouts go to the cluster of the server where the sale happens.

Transfers between clusters

A transfer moves money into another cluster: into your own wallet there or, where allowed, to another player. Without a rule no route is open. You maintain the rules under Coins & Markt → Überweisungsregeln ("Transfer rules", eternal.economy.admin), where the main switch is too.

How players transfer:

• In game with /transfer: without arguments it lists the routes from the current cluster with fee and times. /transfer <cluster> <amount> [player] shows a preview, /transfer confirm books it (valid for 30 seconds).
• In the dashboard under Coins & Markt → Überweisen ("Transfer"): balances per cluster, a live quote while typing and all routes.

Debit and credit happen in one database transaction: both or nothing.

Stock market

Every material known to item tracking gets a price every minute. The price depends on stock, supply and trading:

Price = base value × (stock+1)^-0.35 × 60 × (new24h+1)^-0.25 × 2.5 × (trade24h+1)^0.45 / 3
then smoothed: 65 % old price + 35 % new value

Positions

• LONG (bets on a rising price) or SHORT (bets on a falling price), stake in coins, at least 1.00.
• Payout on closing: long = stake × current price ÷ purchase price; short = stake × (2 − current price ÷ purchase price), never below 0.
• Permission: eternal.market.trade (default level All).
• Price history: 30 days.

Dashboard: Coins & Markt → Aktienmarkt ("Stock market") – list of all materials, detail page with chart and your own position. There is no market command in-game.

AdminShop (module shop)

Trader NPCs that players can sell blocks to and buy from – based on the old Adam shop (builder, miner, categories, quantities 1/8/16/32/64). On first start, Eternal creates exactly these shops with the old prices (converted to per-unit prices).

• Placing traders: /adminshop spawn <shop> at your own position; /adminshop remove removes the nearest trader; /adminshop list shows shops and quota; /adminshop reload reloads immediately.
• Opening: right-click the trader or /shop [shop] (can be disabled with shop.command: false in config.yml).
• Trading: left-click buys, right-click sells, the hopper sells everything of this item. Only unmodified items are bought (no name, no lore, no enchantment, not locked).

Prices: fixed or dynamic

Every item has a sell price and a buy price per unit (0 = not offered) and a mode:

Quota

The quota limits how much money the shop pays out network-wide: an amount per period (daily, weekly, monthly or manual only). When it is empty, sales are blocked – the menu shows „Kontingent leer“ ("quota empty"); buying still works. Optionally, purchases refill the quota; there is also a limit per player and day. The debit is atomic in the database: even if several servers sell at the same time, no more is ever paid out than is left. If a payout cannot be covered, the player gets their items back immediately.

Dashboard: Coins & Markt → AdminShop

Quota (balance, refill, set/add amount), revenue 24 h / 7 d, all shops with categories and items (mode, prices, bounds, elasticity, market trend, current price) and the history of all sales. Servers pick up changes within ≤ 10 s.

Money statistics

Coins & Markt → Geld-Statistik ("Money statistics", eternal.web.economy.stats): money in circulation, number of accounts, average, median, share of the top 10, richest account, history (measured hourly, 7 days to 1 year) and all money flows by type (AdminShop, stock market, admin, /pay, clans …) for 24 h, 7 d and 30 d.

Permissions

Common pitfalls

• „Coins-Modul ist aus“ ("Coins module is off") when buying a MagicItem or using the clan bank: economy is not active on this server.
• Market stays empty: item-tracking is not running, or the API cannot see the tracking data (same MySQL database required).
• Different currency names in the game and in the dashboard: align economy: in config.yml and api.yml.
• „… zeigt sein Guthaben nicht“ ("… does not show their balance") on /money <Spieler>: the player has turned off „Coins für andere sichtbar“.
• Balance "gone" after assigning a cluster: the server now books in the new cluster; the old balance is still in the previous one (usually default). Switch the cluster under Coins in the dashboard; move money with an admin transaction.
• Which cluster applies here? The server console logs Economy-Cluster: <name> (<id>) on start and on every change.