Commands
AstralEconomy registers three commands: the admin edit command /eco (alias /economy), the player-to-player transfer /pay, and the self-service /balance (alias /bal). Admin edits made through /eco ignore each currency's transferable flag — only /pay enforces it, since that's a player moving money rather than an operator directly writing a balance. Every mutation runs through the same guarded database transaction described in Overview, so an overdraft is structurally impossible regardless of which command triggers it.
/eco (/economy)
Base permission: economy.command, set at the class level — every subcommand below requires it in addition to its own permission.
Subcommand | Syntax | Permission | Description |
|---|---|---|---|
|
|
| Set a balance to an exact value. |
|
|
| Deposit into a balance. |
|
|
| Withdraw from a balance. |
|
|
| Check another player's balance. |
|
|
| Reload |
<player> tab-completes against @offlinePlayers. <currency> tab-completes against every registered currency id (@currencies, backed by CurrencyCompletionHandler) and is resolved by CurrencyContextResolver — an unknown id fails the command immediately with Currency with id '...' not found. before the subcommand handler runs.
set
Sets the account's balance to exactly <amount>. <amount> must be finite and >= 0; a negative or non-finite value is rejected with amount-negative before touching the database. The accepted value is then normalized to the money column's scale (4 decimal places) by rounding down, never up, so a set can never mint fractional money. A set has no meaningful before/after delta, so unlike add/take it never triggers the action-bar balance notification (see Overview).
The write fails as ACCOUNT_NOT_FOUND if the target has no account row for that currency yet — the ledger never provisions one. On success: set-success; on failure: set-failure with %reason%.
add/give
Deposits <amount> into the account. <amount> must be finite and strictly > 0; zero, negative, or non-finite is rejected with amount-not-positive. The amount is then rounded down to the money column's scale — if that rounds it to zero (a sub-tick amount), the command fails as INVALID_AMOUNT rather than silently succeeding as a no-op. A missing account row fails as ACCOUNT_NOT_FOUND. On success: deposit-success; on failure: deposit-failure with %reason%.
take
Withdraws <amount> from the account, with the same > 0, rounding, and account-existence rules as add. An overdrawn withdrawal fails at the database's guarded-update floor as INSUFFICIENT_FUNDS — the balance can never go negative. On success: withdraw-success; on failure: withdraw-failure with %reason%.
balance
Reports <player>'s balance for <currency> to the sender (balance-other), reading through the authoritative asynchronous path — it loads from the database on a cache miss rather than trusting a possibly-stale cached figure. On a read failure the sender gets balance-error and the error is logged.
reload
Calls AstralEconomy.loadConfiguration(), which re-reads config.yml, currencies.yml, and messages.yml in that order and replaces the in-memory configuration objects. Sends reloading immediately, then either reload-success or reload-failure (with a stack trace logged to console on failure). See Configuration for what reload does and does not pick up (database.properties is excluded — the connection pool is only rebuilt on a full restart).
/pay
Player-only. Transfers <amount> of the default currency (the entry with default: true in currencies.yml) from the sender to <player>. No permission node is required. <player> tab-completes against @offlinePlayers.
Validated in order:
<amount>must be finite and> 0— otherwiseamount-not-positive.Sender and target must differ — paying yourself is rejected with
pay-self.A default currency must be configured — otherwise
pay-no-default-currency.The default currency must be
transferable— otherwisepay-untransferable. This is the one check/ecoskips: an admin edit bypassestransferable, but/payrespects it because a player, not an operator, is the one moving the money.
On success the transfer runs through the same guarded transaction as every other mutation: the sender receives pay-success-sender and the recipient is sent pay-received through ChatService, delivered network-wide regardless of which server the recipient is on. On failure: pay-insufficient-funds (INSUFFICIENT_FUNDS), pay-account-not-found (ACCOUNT_NOT_FOUND — the recipient has no account row for that currency yet), or pay-failed with %reason% for anything else (e.g. INVALID_AMOUNT, a sub-tick amount that rounds to zero at the column scale).
/balance (/bal)
Player-facing self and other-player balance check.
Invocation | Sender | Permission | Description |
|---|---|---|---|
| player | none | Report the sender's balance in the default currency. If none is configured, |
| player | none | Report the sender's balance in |
| any |
| Report |
/balance and /balance <currency> both read through the authoritative asynchronous path — loading from the database on a cache miss — so the figure is always current even for an account this server has never cached. On a self-read failure: balance-self-error. others mirrors /eco balance: success sends balance-others, failure balance-others-error, and unlike the two self-service forms it accepts any CommandSender, not just a player.
Permission summary
Node | Grants |
|---|---|
| Base node for |
|
|
|
|
|
|
|
|
|
|
|
|
/pay, /balance, and /balance <currency> require no permission node.