# Economy

CoreEngine comes with a complete server economy: accounts, transfers, admin management and a leaderboard. [Chest shops](shop.html) and [jobs](jobs.html) book directly through these accounts. Every transaction is persisted immediately and protected against concurrent bookings.

## Commands

| Command | Syntax | Permission | Default | Description |
|---|---|---|---|---|
| `/balance` | `/balance [player]` (alias `/bal`, `/money`) | `economy.balance` | `true` | Show balance; other players: `economy.balance.others` (true, offline too) |
| `/pay` | `/pay <player> <amount>` | `economy.pay` | `true` | Transfers money to an online player |
| `/baltop` | `/baltop [page]` (alias `/balancetop`, `/moneytop`) | `economy.baltop` | `true` | Leaderboard of the richest players |
| `/eco give` | `/eco give <player> <amount>` | `economy.admin` | `false` | Credits money (offline too) |
| `/eco take` | `/eco take <player> <amount>` | `economy.admin` | `false` | Withdraws money |
| `/eco set` | `/eco set <player> <amount>` | `economy.admin` | `false` | Sets the balance exactly |
| `/eco reset` | `/eco reset <player>` | `economy.admin` | `false` | Resets to the starting balance |
| `/eco reload` | `/eco reload` | `economy.admin` | `false` | Reloads config and balances |

> **Tip:** Amounts accept comma and dot as decimal separator plus the suffixes `k` and `M`: `1.5k` = 1500. Invalid values (negative, NaN, infinite) are rejected everywhere.

> **Note:** The leaderboard is cached for up to 30 seconds, so a record freshly set via `/eco set` does not appear in `/baltop` immediately. Ranks 1 to 3 are highlighted with 🥇/🥈/🥉.

## Vault: your own or a foreign economy

CoreEngine works with [Vault](https://www.spigotmc.org/resources/vault.34315/) in both directions. The switch is `economy.internal` in `config.yml`:

- **`internal: true` (default):** CoreEngine uses its own economy and registers it as the Vault economy. Other plugins (shops, quests, job rewards) then operate on the same accounts.
- **`internal: false`:** CoreEngine uses the economy of another plugin through Vault (for example EssentialsX). All money features then run through it. Without a found economy plugin the internal economy stays active as a fallback (warning in the log). `/baltop` is technically not available in that mode.

Changing `economy.internal` requires a restart. On Folia the official Vault currently does not load, so the internal economy automatically stays active there.

## Accounts and rounding

Every player automatically gets an account with the starting balance on first join. Queries for players without an account show the starting balance without creating one. All balances are rounded to two decimal places so floating point errors never accumulate; the [shop system](shop.html) uses the same rounding.

## Configuration (config.yml)

```yaml
economy:
  # true = own economy (and Vault provider). false = use a foreign economy
  # through Vault. Changing requires a restart.
  internal: true
  # Starting balance of every new account.
  start-balance: 1000.0
  # Currency name (singular at exactly 1.0), plural and symbol.
  currency-name: "Coin"
  currency-name-plural: "Coins"
  currency-symbol: "⛃"
  # Upper bound per account and smallest allowed /pay amount.
  max-balance: 1000000000.0
  min-transfer: 0.01
  # Entries per /baltop page.
  baltop-entries-per-page: 10

cooldown:
  commands:
    # Seconds between two /pay commands (prevents spam).
    pay: 1
```

## Complete example config

```yaml
economy:
  internal: true
  start-balance: 500.0
  currency-name: "Coin"
  currency-name-plural: "Coins"
  currency-symbol: "$"
  max-balance: 10000000.0
  min-transfer: 1.0
  baltop-entries-per-page: 15

cooldown:
  commands:
    pay: 3
```