> 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/getting-started/installation.md).

# Installation

## Requirements

* A Paper server (or a Paper fork) matching the Minecraft version declared by `api-version` in `plugin.yml`.
* Java 21.

## Optional soft dependencies

XPlayerCurrencies runs standalone with none of these installed - each one only unlocks an extra integration, and is safely skipped (with a console notice) if missing:

| Plugin                                                                   | Unlocks                                                                                 |
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| [PlaceholderAPI](/home/xplayercurrencies/integrations/placeholderapi.md) | `%xplayercurrencies_*%` placeholders                                                    |
| [Vault](/home/xplayercurrencies/integrations/vault.md)                   | Registering one currency as the server's Vault economy, and `/currencies migrate vault` |
| [WorldGuard](/home/xplayercurrencies/integrations/worldguard.md)         | Region-based currency restrictions                                                      |
| [Citizens](/home/xplayercurrencies/integrations/citizens.md)             | Binding an NPC to a currency's shop                                                     |

## Install

1. Drop the plugin jar into your server's `plugins/` folder.
2. Start the server once so it generates its default files, then stop it (or use `/currencies admin reload` once you're happy with your edits instead of restarting each time).
3. Review `plugins/XPlayerCurrencies/config.yml` - see [Global Configuration](/home/xplayercurrencies/configuration/global-config.md).
4. Review the bundled example currencies under `plugins/XPlayerCurrencies/currencies/` (`coins.yml` and `gems.yml`) - see [Currency Basics](/home/xplayercurrencies/configuration/currency-basics.md).
5. Reload with `/currencies admin reload` (or restart) to apply your changes.

## Choosing a storage backend

Balances are stored through `config.yml`'s `storage.type`, picked once at startup (changing it requires a restart, it is not hot-swappable on reload):

| Type     | Best for                                                                                                                                                           |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `YAML`   | Small servers - one file per player, no extra setup. Leaderboards get slower to build as the player count grows, since every file has to be scanned.               |
| `SQLITE` | The default. A single local database file - fast leaderboards, no extra setup, but still local to one server.                                                      |
| `MYSQL`  | Networks with several servers sharing player data. Required for [real-time cross-server balance sync](/home/xplayercurrencies/integrations/cross-server-redis.md). |

For `MYSQL`, fill in `storage.mysql.{host,port,database,username,password,useSSL,pool-size}` in `config.yml` before starting the server.

{% hint style="warning" %}
The storage type is read once at plugin startup. If you switch it later, existing balances are **not** automatically migrated between backends - use `/currencies export` on the old backend and `/currencies import` after switching, or migrate the database by hand.
{% endhint %}

Next: [Quick Start](/home/xplayercurrencies/getting-started/quick-start.md).


---

# 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/getting-started/installation.md?ask=<question>&goal=<endgoal>
```

`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.