MCSkylines-Economy

Configuration defaults: Values shown for operator-configurable settings are the bundled defaults, and can be changed in the module’s configuration or definitions. The server’s active settings take precedence, so costs, speeds, ranges, durations, chances, effects, recipes, limits and enabled features may differ. Command examples illustrate syntax; fixed mechanics and validation bounds are not configuration defaults.

Economy provides wallets, checking, cards, transfers, banks, loans, debt, taxes, government payroll, businesses, chest shops, analytics and player-priced stocks. The detailed sections distinguish cash, bank liabilities, and recoverable payment states.

Accounting model

• All values are stored as integer minor units. Floating-point values never become authoritative balances.

• Player and institutional spending accounts cannot go negative.

• Every balance mutation produces an immutable ledger record with a type, time, source, destination, actor/integration identity, correlation key, memo, and metadata.

• Administrative issuance, destruction, transfers, and balance corrections are separately audited.

• Checking balances are bank liabilities. Deposits move wallet cash to bank reserves and create the matching checking liability; withdrawals redeem the liability against reserves. A bank's business account automatically backstops reserve shortfalls before a withdrawal fails.

• If reserve and business liquidity are both exhausted during a withdrawal, wire, or debit-card purchase, the operation fails, the incident is audited, and the bank plus its accounts are frozen as DISTRESSED until authorized staff resolve it.

• Vault represents wallet money only. Checking accounts require the Economy API or a signed debit card.

Player lifecycle and circulation

Configurable starter.immediate, starter.vested and starter.vest-after in config.yml default to $1,000 immediately, then $4,000 after 30 minutes of recorded playtime. Server settings can change both amounts and the waiting time.

After the configurable dormancy.reap-after period (default 60 days) without joining, all wallet and checking balances are settled into the Staff account. Up to the configured $5,000 starter grant is then destroyed from that reaped value. If the player returns, a new starter cycle begins and the player is told to contact staff concerning the prior balance. These movements are auditable.

Money owed for fines, taxes, and loans is collected immediately from checking accounts and then the wallet. Any remainder becomes a debt that garnishes future credits at the configured percentage. The default priority is fines, taxes, then loans, at 100% garnishment.

Death losses and cards

Wallet death loss follows a configurable Gaussian distribution (default mean 5%, standard deviation 1%). PvP losses go to the killer; environmental losses go to Staff. Repeated victim/killer pairs inside the anti-farming cooldown cause no loss.

Debit cards contain no balance. They carry a signed serial that maps to one server-side checking account. On death, all duplicate items with the same serial are collapsed into one chance roll, preventing duplicates from increasing drop odds. The first hacking attempt consumes the serial's server-side hacking opportunity; every physical duplicate then reports it as already consumed. Technology implements the intrusion and dirty-funds workflow described in its guide.

Holding a card and running /bank card revoke revokes that server-side serial, so every original or duplicated item with the serial immediately stops working.

Banks

Players submit bank applications and authorized reviewers approve or deny them through /bank review. Each approved bank has:

• one reserve account;

• one owner-controlled business account for capital, interest, and fee profit;

• configurable owner-set checking APR;

• configurable wire percentage and flat fees, capped by government policy;

• a government-set reserve ratio;

• one or more WorldGuard bank regions and registered ATM blocks.

Players may have one checking account per bank and accounts at multiple banks. Balance viewing, account opening, deposits, withdrawals, debit-card issuance, wires, and loan repayment require the appropriate bank region or ATM.

Daily checking snapshots feed weekly average-balance interest. Interest is funded from the bank business account, never minted. Insufficient interest and payroll payments become retryable arrears.

Loans

Bank owners can offer fixed-rate amortized loans with APR, payment frequency, term, missed-payment threshold, and optional collateral reference. Borrowers explicitly accept offers and may repay early without a penalty. Principal returns to reserves; interest enters the bank business account and can be income-taxed. Reserve requirements are checked before disbursement.

CollateralProvider is the stable Property boundary. Collateral validation, locking, release, and seizure activate when Property registers its adapter. No fake property ownership behavior is embedded in Economy.

Taxes and payroll

• Income tax is a configurable flat withholding on /pay, /wire, government/business payroll, and bank loan-interest revenue. Loan principal is not income.

• Balance tax uses marginal brackets across a player's wallet plus checking accounts.

• Property tax uses a flat amount after a configurable tax-free property allowance through PropertyTaxProvider.

• Sales tax is deducted from chest-shop seller proceeds.

• Revenue enters the main government treasury.

• Daily balance/property assessment is partitioned deterministically into 24 hourly groups.

Government assigns each job to the main treasury or a configured department:<key> account. Payroll runs once per real-world day after the configured time. Configurable payroll.minimum-online-time and payroll.eligibility-window default to 15 recorded online minutes in the prior 24 hours. Ineligible players receive nothing; insufficient budgets create arrears that retry after funding.

Chest shops and analytics

Look at a chest containing the exact custom item and use /shop create <sell|buy> <unit-price> [quantity]. Purchases are direct: wallet if no card is held, or only the held card's checking account. Insufficient funds never fall back to another payment method.

Custom identity uses Paper's complete serialized ItemStack with amount normalized to one, covering names, lore, enchantments, attributes, custom model data, and persistent data. /shop inspect prints the identity hash.

ShopDirectoryApi publishes main-thread snapshots of active chest-shop offers for Navigation. Each listing includes the stored price and item template plus availability sampled from a loaded chest. Unloaded chunks are marked unknown, not out of stock; a missing registered chest is unavailable. The API formats prices using Economy's configured currency.

/shop export writes a 30-day aggregate CSV containing day, item identity, material, display snapshot, quantity, gross value, seller proceeds, tax, transaction count, and average unit price.

Company shares and player order books

/economy stock opens the exchange terminal with market listings, holdings and

open orders. Prices come only from matching buy/sell orders. Individuals trade

through their wallets, and business owners can select an owned business account.

Only an active owned business can issue shares. economy.stock.trade and

economy.stock.issue default to players, with ownership enforced for every action.

/economy stock issue <business-account> <symbol> <shares> <dividends:true|false>

/economy stock order <BUY|SELL> <symbol> <type> <GTC|DAY|IOC> <shares> <price-bound> [stop-price] [wallet|business-account]

/economy stock book <symbol>

/economy stock holdings

/economy stock orders

/economy stock cancel <order-id>

/economy stock dividend <symbol> <amount-per-share>

For example, /economy stock order BUY ACME LIMIT GTC 10 25.00 wallet reserves up

to $250. A buy price bound is the maximum paid per share; a sell bound is the minimum

accepted. A market order also requires that protection bound. In the GUI, choose

Place order and enter the same parameters in the private chat prompt, then review

the confirmation. Prompt input expires after two minutes; type cancel to abandon

it. Every issue, order, cancellation and dividend action opens a confirmation.

| Type | Behavior |

|---|---|

| LIMIT | Trades at the requested bound or a better price, with partial fills |

| MARKET | Consumes eligible existing liquidity within the bound, then cancels the remainder |

| STOP_LOSS | Waits for an actual last-trade trigger, then acts as a protected market order |

| STOP_LIMIT | Waits for the trigger, then joins the limit book |

Buy stops trigger when the last trade reaches or exceeds their stop price; sell

stops trigger when it reaches or falls below it. There is no synthetic first price:

stops wait until a real trade exists. Provide the stop price only for stop orders,

before the optional account. Triggered orders receive fresh time priority.

GTC stays open until filled/cancelled. DAY expires at the next UTC midnight.

IOC immediately cancels unfilled shares and cannot be used while a stop is

waiting; stop-loss has immediate cancellation when triggered. Matching uses price

then time priority and the resting order's price. Accounts owned by the same

player cannot trade with each other.

Buy cash is reserved in system:stock-escrow; sell shares are reserved in holdings.

Shares, cash settlement, price-improvement refunds and cancellations commit in one

database transaction, including partial fills. Holdings show available and reserved

shares; orders show remaining shares and cash reservations. Frozen accounts keep

their holds until restored and cannot trade. A business with issued shares, holdings

or live orders cannot close. Each business issues one symbol with a fixed supply;

there is no mint-on-trade, short selling, leverage or server price simulation.

Dividends require the global stocks.yml switch and issuance-time company opt-in.

The issuer chooses a per-share amount, paid from its business cash to all outside

holders, including shares reserved in sell orders. Issuer-held shares do not pay

the issuer itself. The complete distribution rolls back if it cannot be funded.

These payments are recorded as dividends in the ledger. stocks.yml configures

global enablement, maximum supply, maximum order size and open-order limits; its

changes require a restart. The destructive economy reset also clears the exchange.

Technology's existing finance_module enables a stock-terminal button on a placed

computer. It opens this same exchange and enforces the same permissions. The normal

command remains available without a terminal.

Storage

SQLite is the default and enables WAL, foreign keys, busy timeout, startup backups, and exact backup retention. MySQL is an alternative single-server backend using HikariCP. Do not point multiple Minecraft servers at the same database; cross-server transaction coordination is intentionally out of scope.

Set up and use a bank

1. A prospective owner runs /bank apply <name>.
2. A reviewer opens /bank review and approves or denies the application.
3. Capitalize the approved bank's reserve and business accounts before customers withdraw or receive loans.
4. Register one or more WorldGuard regions with /bank region add <bank-id> <region>.
5. Look at a block and register an ATM with /economy atm create <bank-id>. Remove it by targeting it and using the matching remove action.
6. Set the bank's checking APR and wire fees with /bank policy. Government-authorized staff set the reserve ratio separately.
7. Customers enter a bank region or use its ATM, open a checking account, and then deposit wallet money. Deposits increase reserves and the customer's checking liability in one ledger operation.
8. Issue a card only at the bank or ATM. A card is owner-bound and points to one checking account; it carries no stored balance.

Withdrawals and card/wire purchases monitor liquidity. If reserves and the bank business account cannot cover redemption, the operation fails and the bank is marked distressed and frozen for staff resolution. Use /bank resolve only after correcting the underlying funding problem.

Debit cards and wires

Hold the genuine debit card in the main hand when making a card-backed shop purchase or wire. /wire <player> <amount> [memo] requires the sender to be at the card's bank or ATM and the recipient to have at least one checking account. The recipient's first active checking account is used. Bank percentage and flat wire fees are charged according to policy.

If a card is lost, hold another copy of the same serial and use /bank card revoke. Revocation invalidates every duplicated physical copy. Card duplication does not create balances or extra hacking attempts; server-side serial state is authoritative.

Chest shops: complete setup and use

Navigation's /find discovers these shops by exact held-item identity or a typed partial item name, including custom item and gun display names. Economy publishes a ShopDirectoryApi snapshot with price, item template, and availability. An unloaded chest chunk reports unknown stock; the directory does not load it during search. See Navigation for the grouped price list and directions.

1. Place a chest in a protected location and put at least one exact example item inside it. The example determines the complete item identity, including custom model data, persistent data, name, lore, enchantments, attributes, and other components.
2. Look directly at that chest while holding the exact item in the main hand.
3. Run /shop create sell <unit-price> [quantity] to sell chest stock to players, or /shop create buy <unit-price> [quantity] to buy items from players. quantity is the base number transferred per interaction and defaults to the configured value when omitted.
4. Use /shop info while looking at the chest to confirm mode, item, quantity, and price. /shop inspect prints the held item's identity hash when two visually similar custom items need to be compared.
5. Right-click the chest to transact. A normal click uses the configured normal multiplier; sneaking uses the configured sneak multiplier. The final quantity is the shop quantity times that multiplier, capped at 2,304 items.

For a sell shop, the plugin removes stock from the chest before attempting payment. If payment fails, stock is restored. Purchased items go to the buyer's inventory and overflow drops naturally at the buyer. For a buy shop, the chest must have enough capacity and the seller must carry the exact item; failed owner payment restores the seller's items.

Wallet payment is used unless the buyer holds a genuine card in the main hand. Card payment accepts only a valid card owned by that buyer and draws only from its checking account. Sales tax is removed from seller proceeds when enabled. The shop owner receives an online notification or a queued notification on the next login.

Active shop chests cannot be broken, exploded, or moved by pistons. Remove the shop registration first with /shop remove; ownership is checked unless the caller has the administrative removal permission. Removing the registration does not delete the chest or its inventory.

Taxes, payroll, and debt

Income withholding applies only to configured income-producing flows. Balance tax uses marginal brackets across wallet plus checking balances. Property tax requires Property's provider. Sales tax applies to chest-shop seller proceeds. Assessment work is split across the day so all players are not processed in one tick.

Government payroll uses job salary policy and the mapped treasury or department account. A player must meet the configurable active-play requirement (default 15 online minutes in the prior 24 hours). Underfunded payroll and bank interest become arrears rather than minted money and retry after funding.

Guide, account lookup and exchange

/economy guide opens the player guide. /economy analytics presents cash supply, checking liabilities, account categories, obligations and 24-hour ledger activity separately, with explanations that prevent double counting. Administrators use /economy admin lookup <player|business|other> <name> with typed completion; treasury and staff accounts are under other. The administrative account command creates configured institutional accounts; it is not a player balance shortcut.

/economy stock opens the exchange. Businesses issue a fixed share supply and may enable dividends. Individuals and businesses trade with market, limit, stop-loss and stop-limit orders, partial fills and GTC/DAY/IOC policies. Prices come solely from orders and completed trades. Buy cash and sell shares are reserved; no short sales, leverage or trades between the same owner's accounts are allowed. Market orders require a price bound. DAY expires at the next UTC midnight; IOC cancels unfilled quantity immediately and cannot wait for a stop trigger. See Economy's operator guide for exact command syntax and stocks.yml limits.

Business ownership and closure

Use /business create <key> <name> to create an owned account within configured slot limits. The key is 1–32 lowercase letters/digits/underscore/hyphen; display name is remaining text. List your account IDs before using them in Technology or the exchange. Delete first opens a thirty-second confirmation; repeat with confirm only after reviewing. A business with issued shares, holdings or live orders cannot close.

Payment confirmations and recovery

Chest-shop confirmation shows exact item, quantity, total and wallet/card source. Owners sneak-right-click to restock rather than buy their own offers. Confirmation rechecks shop/card/permission/distance. Normal trades archive pre-transfer evidence under shop-trades/completed; interrupted pending trades quarantine their chest/player for staff reconciliation. Do not automatically refund an unresolved pending trade because its cash may already have committed.

Card hacks are implemented through Technology. Duplicate serials share one hack opportunity; revoked cards cannot settle new purchases. Unsecured loan defaults retain collectible principal debt and future garnishment. Provider/database errors are not counted as missed payments.

Parking and impound revenue

Vehicles meters settle plate-validated wallet payments as PARKING transfers to treasury. Impound collection accepts its documented wallet/card source and uses durable operation keys. Keep paired Economy/Vehicle journals and databases together for recovery. Setup and enforcement belong to Vehicles.

Reports and configuration

/economy guide opens player instructions; analytics reports cash supply separately from checking liabilities, account categories, debts, loans, distress and recent ledger movements. Multiple ledger legs count toward volume; volume is not issuance or profit. Typed lookup finds players, businesses or institutional accounts; transactions show immutable per-player records and audit shows administrative events.

Configure policies in module YAML files: bank caps/reserves, starter/reaping/death rules, tax brackets, debt priority/garnishment, payroll time/eligibility, business limits, recipes/messages and stock enablement/limits. Stocks and database changes require restart. Tax rates default to zero. Banks/payroll need funded reserves, owner capital or departmental budgets; interest and wages are not automatically minted.

Debt collection status

Debt collection writes the computed remaining amount and status explicitly, and selects only positive open debts. Startup repairs inconsistent OPEN/PAID flags using the stored balance and records the repair in the audit history. It never resets a balance, repeats a payment or changes existing ledger entries. Fully paid debts no longer trigger Transaction amount must be positive during later scheduled collection. The positive-amount requirement for real transfers remains enforced.

Bus fare integration

Accepted bus fares are recorded as BUS_FARE transactions to government treasury. EconomyApi.chargeBusFare(payer, heldCard, amount, key, route) uses a main-thread signed card snapshot, or null for wallet payment. A card must belong to the payer and remain active; its bank, checking liability and reserve settle atomically. The immutable key binds payer, route, amount and wallet/card source. Repeated accepted requests return the existing receipt; changed requests are rejected. The API creates no zero-amount transfer: free Vehicles routes skip payment. Fares require the rider's Pay confirmation; evasion reports are handled by Vehicles and do not automatically issue fines or debt. Preserve both Economy and Vehicles data during updates. See the Vehicles bus guide for service setup.

Reading command syntax

Configuration defaults: Values shown for operator-configurable settings are the bundled defaults, and can be changed in the module’s configuration or definitions. The server’s active settings take precedence, so costs, speeds, ranges, durations, chances, effects, recipes, limits and enabled features may differ. Command examples illustrate syntax; fixed mechanics and validation bounds are not configuration defaults.

<argument> is required; [argument] is optional. Replace the placeholder, including its brackets, with your value. Choices separated by a vertical bar mean choose one. ... accepts the remaining words. Do not type quotation marks around multiword names unless the command specifically requires them. A bare command has no required arguments. Examples use sample players/IDs: substitute entries from your server and use Tab for configured IDs.

player means a username; operational actions usually require that player online. amount and price are currency values such as 25.00, unless the row specifies items, levels, or units. reason, memo, message, name, and statement accept text where supported. duration uses the module's duration format (for example 10m, 2h, or 7d); it is not a bare number of minutes unless stated. id is the exact identifier displayed by that system, not its friendly name. Permissions and ownership/state/location checks both apply.

Wallet and operator commands

/economy bank ..., /economy business ..., /economy shop ..., /economy balance ..., /economy pay ... and /economy wire ... route to the shortcuts with the same arguments. All bank/shop/business actions require an in-game player; operator reports support console where applicable.

Bank and loan commands

All bank commands pass economy.bank.use, plus their listed role/ownership checks. bank-id comes from the bank list; policy uniquely also accepts full/underscore bank names. Monetary values are currency; percentages are percentage values, e.g. 3 for 3%.

Example: /bank policy First National 3 1 0. Loan IDs come from the offer/menu; reference is provider-owned (Property uses its property reference), not an arbitrary display name.

Business and shop commands

In shop creation SELL means the owner sells stock to buyers; BUY means the owner buys matching items from visitors. Example: /shop create sell 25.00 1 while targeting its chest.

Stock exchange commands

Type is LIMIT, MARKET, STOP_LOSS or STOP_LIMIT. Shares are integer counts. Price bound is maximum buy/minimum sell currency per share, including MARKET. DAY expires at UTC midnight; IOC cancels remainder immediately and cannot await a stop. Example: /economy stock order BUY ACME LIMIT GTC 10 25.00 wallet.

Root commands and aliases

These are the registered command entry points. The subcommand tables above describe their complete operations. Alias names use the same arguments as their root.