> 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/xplayerexp/features/bottles.md).

# XP Bottles

The core of the plugin: a physical item that stores a player's experience, tradeable and consumable like any other item in their inventory.

## Creating a bottle

`/bottlexp create <amount>` (player only) takes `<amount>` worth of the player's own experience — in whichever unit [`calculation-mode`](/home/xplayerexp/getting-started/getting-started.md#calculation-mode) is set to — and hands them back a bottle holding it.

Before anything is taken, the plugin checks, in order:

1. **Restrictions** — is bottle creation blocked in this world/region right now? See [Cooldowns & Restrictions](/home/xplayerexp/features/cooldowns-and-restrictions.md).
2. **Cooldown** — has this player created a bottle too recently? Same page.
3. **Minimum/maximum amount** — does `<amount>` fall within this player's permission-based tier? See below.
4. **Enough XP** — does the player actually have `<amount>` available?

If every check passes, any configured **tax** is deducted from the stored amount (the player still loses the full `<amount>` from their own XP), the bottle is created, and a sound plays ([`sounds.bottle-create`](/home/xplayerexp/reference/configuration-files.md#config-yml)).

## Consuming a bottle

Right-click while holding a bottle to drink it — the stored amount is added straight back to the player's XP (in the same unit it was stored in), the bottle stack shrinks by one, and [`sounds.bottle-use`](/home/xplayerexp/reference/configuration-files.md#config-yml) plays.

{% hint style="info" %}
Only the **main hand** is checked, so a bottle in the off-hand while another item is used in the main hand won't accidentally get consumed by the same click.
{% endhint %}

## Minimum, maximum & tax

`config.yml`, under `bottle-settings`:

```yaml
min-exp-requirement:
  enabled: true
  permissions:
    - "xplayerexp.bottle.min.1": 5
    - "xplayerexp.bottle.min.2": 10

max-exp-requirement:
  enabled: true
  permissions:
    - "xplayerexp.bottle.max.1": 40
    - "xplayerexp.bottle.max.2": 50

tax:
  enabled: true
  permissions:
    - "xplayerexp.bottle.taxe.1": 10
    - "xplayerexp.bottle.taxe.2": 15
```

All three follow the same tiered-permission logic:

* A player holding **none** of the listed permissions isn't restricted/taxed at all by that section.
* A player holding **multiple** of them gets the **highest** value among the ones they hold — so tiers should be additive permissions (e.g. a higher rank inherits the lower rank's node too), not exclusive ones.

Tax is a percentage taken off the amount *stored in the bottle* — the player still spends the full requested amount from their own XP either way.

## The item itself

```yaml
item:
  material: "EXPERIENCE_BOTTLE"
  display-name: "&d&lExperience Bottle &7(Right-Click)"
  lore:
    - ""
    - "&7Contains: &a%amount% %unit%"
    - "&7Created by: &f%player%"
    - ""
    - "&e▶ Right-click to consume"
```

Any `Material` works, not just `EXPERIENCE_BOTTLE`. `display-name` and every `lore` line support `%amount%`, `%unit%` (from [`bottle-settings.units`](/home/xplayerexp/reference/configuration-files.md#config-yml), and `%player%` — plus legacy and hex color codes.

## Giving vouchers

`/bottlexp give <player> <amount>` (console or in-game, needs `xplayerexp.admin.give`) hands a bottle straight to `<player>`'s inventory for the exact `<amount>` given — no XP is taken from anyone, and none of the checks above (min/max, tax, cooldown, restrictions) apply. It's a pure admin/console grant, not a shortcut for `create`. See [Commands](/home/xplayerexp/reference/commands.md) for the full syntax.


---

# 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/xplayerexp/features/bottles.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.