> For the complete documentation index, see [llms.txt](https://docs.xandtech.fr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xandtech.fr/home/xplayercurrencies/configuration/currency-basics.md). # Currency Basics (currencies/\.yml) Every currency is one file under `currencies/`. The **filename** (without `.yml`) is its permanent internal id, used in commands (`/currencies give coins Steve 100`) and PlaceholderAPI placeholders (`%xplayercurrencies_coins_balance%`) - keep ids lowercase, no spaces (use `_` instead). To create a new currency, duplicate `coins.yml` (or `gems.yml`) under a new name and adjust the values - there's no limit on how many currency files you can have. This page covers the base fields every currency has; each feature section (shop, bank, boosters, etc.) is documented on its own page under **Features**. ## Identity & display | Key | Default | Description | | --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | `true` | Master toggle. A disabled currency is completely ignored: its commands reply as if it didn't exist and its placeholders return an empty string, but any balance already stored stays on disk untouched. | | `name-display` | the id | Display name shown in messages and placeholders. | | `name-display-plural` | `name-display` | Plural form. | | `icon-display` | `""` | Shown wherever a message references `{icon}` - an emoji, a color tag, anything cosmetic, not tied to an in-game item. | | `symbol` | `name-display` | Glued to a formatted balance. | | `symbol-position` | `AFTER` | `AFTER` (`1,000 Coins`) or `BEFORE` (`$1,000`). | | `decimals` | `0` | Decimal places kept for balances. | | `thousands-separator` | `true` | Adds a `,` every 3 digits (`1000` -> `1,000`). Cosmetic only. | | `priority` | `0` | Sort order (lower first) in `/currencies list` and a player's own balance overview. Ties fall back to alphabetical order. | | `gui-material` | `GOLD_NUGGET` | Icon material used in the `/currencies admin gui` menus only. | ## Balance limits | Key | Default | Description | | ----------------- | ------- | ---------------------------------------------------------------------------- | | `default-balance` | `0` | Balance a player starts with the first time they're seen with this currency. | | `min-balance` | `0` | Lower bound enforced on every give/take/set. | | `max-balance` | `-1` | Upper bound - `-1` means unlimited. | These bounds are enforced on **every** mutation path: admin commands, the GUI, PlaceholderAPI, Vault, and the [API](/home/xplayercurrencies/developer/api.md). ## Commands | Key | Default | Description | | ----------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `command` | `""` (none) | Gives this currency its own dedicated command on top of `/currencies ... ...`, e.g. `coins` registers `/coins` - `/coins` alone shows your balance; `/coins give ` (also take/set/reset/balance/pay) work exactly like their `/currencies ... coins ...` equivalent. | | `allow-pay` | `true` | Whether players can send this currency to each other with `/currencies pay` (or the scoped command). Set `false` for a currency that should only ever be granted by an admin/another plugin (e.g. a premium currency), to prevent player-to-player trading. | Takes effect on `/currencies admin reload` - already-connected players may need to reconnect for a new/renamed command to show up in tab-completion (the command itself works right away either way). ## Leaderboard & menu appearance See [Leaderboard](/home/xplayercurrencies/features/leaderboard.md) for `leaderboard-enabled`/`leaderboard-size`, and `menu-size`/`menu-border-material` (which also apply to the transaction logs menu). ## Restrictions ```yaml restrictions: mode: NONE # NONE, WHITELIST or BLACKLIST worlds: [] regions: [] ``` Gates this currency to (or blocks it from) specific worlds and/or WorldGuard regions - checked **only** on self-service actions (pay/cheque/exchange, the currency's own custom command), never on admin give/take/set/reset, since those are explicit overrides that should work anywhere. | Key | Description | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `mode` | `NONE` (default, usable everywhere), `WHITELIST` (only usable in the listed worlds/regions) or `BLACKLIST` (usable everywhere except them). | | `worlds` | Exact world names - always works, no dependency needed. | | `regions` | WorldGuard region ids - only enforced if [WorldGuard](/home/xplayercurrencies/integrations/worldguard.md) is installed; silently ignored otherwise. | ## Plugin integration ```yaml plugin-integration: NONE # NONE, VAULT, or PLAYERPOINTS (reserved) ``` Lets this one currency also back an external economy plugin, on top of its own commands/ GUI/PAPI, which keep working normally either way. See [Vault](/home/xplayercurrencies/integrations/vault.md) for the `VAULT` option. If several currency files request the same integration, only the first (by `priority` then id) gets it - the rest are skipped with a console warning. ## Cheques & Exchange See [Cheques & Exchange](/home/xplayercurrencies/features/cheques-and-exchange.md) for the full `cheque` and `exchange` sections. See [Default currency: coins.yml](/home/xplayercurrencies/configuration/default-configuration-files/default-currency-coins.md) and [Default currency: gems.yml](/home/xplayercurrencies/configuration/default-configuration-files/default-currency-gems.md) for the exact files as shipped, in full. Next: [Languages](/home/xplayercurrencies/configuration/languages.md), or jump into a [feature](/home/xplayercurrencies/readme.md#features). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.xandtech.fr/home/xplayercurrencies/configuration/currency-basics.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.