> 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/xstash/readme.md).

# Introduction

XStash is a Paper plugin that gives every player their own set of **virtual chests** plus a Hypixel SkyBlock-style **sacks** system — automatic resource collectors with upgradeable capacity tiers. Both modules are independent (either can be disabled without touching the other), fully permission-driven, and configurable down to individual menu items through YAML.

## What's in here

* [**Chests Module**](https://docs.xandtech.fr/home/xstash/chests-module/chests.md) — up to 30 virtual chests per player, unlocked by rank permission and/or individual purchase, with a utility bar (sort, auto-smelt, compact, sell-all), per-chest customization, search, and a travel backpack shortcut.
* [**Sacks Module**](https://docs.xandtech.fr/home/xstash/sacks-module/sacks.md) — a configurable catalog of sacks, each a single physical item whose storage capacity is upgraded in place through tiers, with auto-collect and a "Sack of Sacks" menu to carry every sack at once.
* **Admin tools for both** — `/xstash view <player>` and `/sacks view <player>` open a live-editable management view of any player's chests/sacks, including offline players. Both sides (the admin's view and the player's own, if open at the same time) refresh automatically within about a second of any change, in either direction. `/xstash export` dumps the chest transaction log to CSV/YAML/JSON.
* **Economy** — Vault (money) and PlayerPoints (points) for every purchase and sale, an optional PlaceholderAPI-driven condition (not a spend) as a third chest-purchase option, an optional fallback to an installed shop plugin's own prices, and a permission-driven sell price boost.
* **Integrations** — PlaceholderAPI, ExecutableItems, and a public Java API (`XStashAPI`) for other plugins to read/modify a player's chests and Sack of Sacks slots.

## Requirements

* Paper (or a Paper fork) `1.21.x` or newer — API version `26.2`.
* Java 21+.

Everything else is optional:

| Plugin                                                                                  | Needed for                                                                                                                       |
| --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| [Vault](https://www.spigotmc.org/resources/vault.34315/) + any Vault-compatible economy | Money-based chest purchases, sells, and sack upgrade costs                                                                       |
| [PlayerPoints](https://www.spigotmc.org/resources/playerpoints.80745/)                  | Points-based purchases/sells                                                                                                     |
| [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/)               | The `%xstash_*%` placeholders, plus `currency: placeholder` condition-based chest purchases                                      |
| [ExecutableItems](https://www.spigotmc.org/resources/executableitems.100480/)           | Custom `ei:<id>` items in sack contents/crafting                                                                                 |
| EssentialsX, ShopGUIPlus, EconomyShopGUI, GUIShop, or RoyaleEconomy                     | Shop-plugin sell price fallback (see [Economy & Selling](https://docs.xandtech.fr/home/xstash/reference/economy-and-selling.md)) |

None of these are required to run XStash — each integration only activates if the corresponding plugin is actually installed.

## Where to start

New to XStash? Read [Installation & Setup](https://docs.xandtech.fr/home/xstash/getting-started/getting-started.md) first, then jump into whichever module you're setting up: [Chests](https://docs.xandtech.fr/home/xstash/chests-module/chests.md) or [Sacks](https://docs.xandtech.fr/home/xstash/sacks-module/sacks.md). Server admins managing existing players should also check [Admin Tools](https://docs.xandtech.fr/home/xstash/chests-module/admin-tools.md) and the [Permissions](https://docs.xandtech.fr/home/xstash/reference/permissions.md) reference.
