Player Vaults

Player Vaults Addon

The Player Vaults addon is an optional premium add-on for X-Prison that gives every player their own personal storage, opened with /pv. How many vaults somebody has comes from their permissions, so vaults slot straight into an existing rank ladder or store.

Each vault can be renamed and given its own icon, so a player's menu ends up looking like their own filing cabinet rather than a row of identical chests. Both are separate switches with their own permission, so either can be sold as a perk — or turned off entirely.

The part that matters most is the part you cannot see in a screenshot. A vault plugin's real job is to never lose or duplicate an item, and this one is built around the four moments where that goes wrong: two people opening one vault, a row that will not decode, the server dying with a window open, and the vault size being lowered. Those are covered in Item Safety below.

---

Requirements

Requirement	Notes
X-Prison	2026.3.7.0 or newer
Java 17+	Required
Paper / Spigot / Folia	1.16 – latest
PlaceholderAPI	Optional — only needed for the placeholders below

Storage: vaults are saved in your existing X-Prison database, following your database_type setting. H2, SQLite and MySQL all work with no extra configuration and no second connection pool.

No module dependency — Player Vaults does not need Currencies, Mines or anything else enabled.

---

Installation

1. Download X-Prison-PlayerVaults-*.jar from your purchase platform.
2. Place the JAR inside plugins/X-Prison/addons/.
3. Restart the server (do not use /reload).
4. Three default files are created in plugins/X-Prison/addons/PlayerVaults/:
   • vaults.yml — settings
   • vaults-gui.yml — the menus and the icon catalogue
   • vaults-messages.yml — every player-facing line
5. Edit to taste, then run /pv reload to apply all three without restarting.

To regenerate the defaults, delete the PlayerVaults folder before starting. Files are only written when they are missing.

---

How It Works

1. A player runs /pv and sees one pane per vault they have unlocked.
2. Left-click a pane to open that vault — a normal inventory window they can put things into and take things out of.
3. Right-click a pane to open Customize Vault, where they can rename it or change its icon.
4. Closing the vault writes it to the database. There is no save command and nothing for the player to remember.
5. /pv 3 skips the menu and opens vault 3 directly.

Contents are read when a vault opens and dropped when it closes, so a busy server holds one inventory per open window rather than one per vault every online player owns.

---

Vault Access

How many vaults a player gets is the highest xprison.vaults.amount.<n> node they hold, on top of the default-vaults baseline.

xprison.vaults.amount.3           →  3 vaults
xprison.vaults.amount.12          →  12 vaults
xprison.vaults.amount.unlimited   →  as many as max-vaults allows

A rank ladder is just amount.3, amount.6, amount.12. There is no need to grant every step — only the largest node counts, and a player carrying both a rank node and a donor node gets the larger of the two whichever order your permission plugin lists them in.

vaults:
  default-vaults: 1      # what somebody with no node at all gets. 0 = permission-only
  max-vaults: 100        # nothing can grant more than this
  rows: 6                # size of every vault, 1-6
  permission-prefix: 'xprison.vaults.amount.'
  admin-unlimited: true  # whether holding the admin permission also grants max-vaults

Vault size is one value for the whole server. Vault count is per-permission; vault size is not.

rows is safe to change later in either direction. Lowering it does not delete anything — see Item Safety.

---

Renaming and Icons

customization:
  enabled: true
  rename:
    enabled: true
    permission: ''      # empty = everybody
  icon:
    enabled: true
    permission: ''
  reset:
    enabled: true

A control a player may not use is not drawn at all, so you never advertise a button that can only refuse.

Renaming

The player clicks the rename button, the menu closes, and they type the new name in chat. The menu reopens around the result.

naming:
  default-title: '<white>Vault %number%'
  max-length: 32
  colour-permission: 'xprison.vaults.rename.color'
  timeout-seconds: 30
  cancel-word: 'cancel'
  blocked-words: []

• max-length is measured on the rendered text, so colour tags never eat a player's allowance.
• Without colour-permission, MiniMessage a player types is escaped and shown as the literal characters — it cannot colour your menu.
• blocked-words is matched anywhere in the name, case-insensitively.

Icons

Icons come from a curated picker you control, so a vault can never turn up in the menu as a command block or a spawn egg. The shipped catalogue has 70 entries; any item id works, including ItemsAdder, Nexo and Oraxen ids such as nexo:my_block.

icon:
  default: CHEST
  defaults:              # a themed set out of the box
    1: CHEST
    2: DIAMOND
  require-permission: false
  permission-prefix: 'xprison.vaults.icon.'
  hide-locked: false

With require-permission: true, each icon asks for its own node. The node is the icon id lowercased with everything but letters and digits folded to an underscore:

Icon	Node
DRAGON_EGG	xprison.vaults.icon.dragon_egg
nexo:my_block	xprison.vaults.icon.nexo_my_block

A locked icon is drawn with the locked-icon template from vaults-gui.yml — which is what advertises it — unless hide-locked takes it out of the menu entirely.

The catalogue itself lives in vaults-gui.yml under gui.icon-picker.materials.

---

Advertising Locked Vaults

Set locked-shown in vaults-gui.yml and the list draws greyed-out panes past what the player has unlocked, using your own wording:

gui:
  list:
    locked-shown: 3      # 0 shows only their own vaults

It never goes past max-vaults, and it is not applied when staff view somebody else — an upsell aimed at the wrong person is just noise.

---

Item Filter

Decides what may be put into a vault.

item-filter:
  mode: 'OFF'            # OFF | BLACKLIST | WHITELIST
  bypass-permission: 'xprison.vaults.filter.bypass'
  materials:
    - BEDROCK
    - SPAWNER

Mode	Behaviour
OFF	Anything goes
BLACKLIST	Everything except the listed materials
WHITELIST	Only the listed materials

WHITELIST is for an ore-only bank or a token-and-key vault — something a blacklist cannot express without listing every item in the game and updating it on every Minecraft release.

The filter covers every route an item can take into a container: placing, swapping under the cursor, shift-clicking from below, the number-row swap, the off-hand swap and dragging.

The filter only ever applies to items going in. Anything already stored when you change it stays where it is and can still be taken out — confiscating what a player banked under the old rules is a support ticket you do not want.

Quote 'OFF'. YAML reads a bare OFF as a boolean. The addon accepts it either way, but the quoted form is what the file actually says.

---

Worlds

disabled-worlds:
  - pvp_arena

/pv does nothing in a listed world, and a vault carried into one is closed — because the arena is the one place somebody will try to bank their inventory mid-fight.

---

Staff Tools

/pv <player> opens somebody's vault list and /pv <player> <n> jumps straight to one of their vaults. Both work on offline players.

Every staff open and every staff deletion is written to console:

command:
  log-admin-access: true

A vault holds whatever a player values most, so who looked inside is the first thing you will be asked after an accusation. Deleting a vault while somebody has it open is refused rather than silently undone by their close.

An offline player's permissions cannot be read, so the menu shows the vaults that actually have data. Anything beyond that is still reachable as /pv <player> <n>.

---

Item Safety

Everything here exists because of something that goes wrong in vault plugins.

One window per vault, locked until the write lands. A vault is locked from the moment somebody asks for it, through the database read, until the row has actually reached the database — not until the window closes. That gap is the classic duplication bug: close a vault, reopen it fast enough, and you read the row as it was before your last visit, then save that back over what you just stored. An admin and the owner cannot both have vault 3 on screen; the second is told to try again in a moment.

A vault that cannot be read refuses to open. If the stored contents fail to decode, the addon will not open an empty window — an empty window gets closed, and closing writes, and items that were merely unreadable would then be genuinely gone. The player is told to fetch an admin, the console says what went wrong, and the row is left alone.

Lowering rows never deletes anything. Items past the new end are kept out of sight and written back out on the far side of whatever the player does. Put the rows back up and everything reappears.

Three save points. Closing the window (which covers quitting and being kicked), a timer while a vault is open, and a synchronous save when the server stops.

storage:
  autosave-seconds: 300   # 0 switches it off
  return-to-list: false   # whether closing a vault reopens the list

---

Menus, Messages and Sounds

Everything a player sees is a template.

• vaults-gui.yml — three menus (list, customise, icon picker), each with its own title, rows, filler, slot positions, materials, custom_model_data, custom head textures, lore, page arrows and optional decorations block.
• vaults-messages.yml — 33 messages. Empty a line to silence it; a line you delete falls back to the copy inside the jar.
• sounds in vaults.yml — six cues (menu-open, click, denied, vault-open, vault-close, customised), each with volume and pitch, each silenceable with enabled: false or sound: none.

All raw MiniMessage. Nothing renders italic — every item these menus draw, fillers and page arrows included, has Minecraft's default italics turned off.

To remove a button, set its slot: -1 rather than deleting it. Deleting falls back to the bundled copy.

At startup the console names any menu mistake that would otherwise be silent — two items sharing a slot, a button past the end of its menu, or an icon picker with nothing in it.

---

Configuration Reference

Key	Default	Meaning
enabled	true	Master switch
command.name	pv	Command label; aliases under command.aliases
command.permission	(empty)	Gate the command entirely. Empty = everybody
command.admin-permission	xprison.vaults.admin	Staff commands and other players' vaults
command.log-admin-access	true	Log staff opens and deletions to console
vaults.default-vaults	1	Vaults with no permission node
vaults.max-vaults	100	Hard ceiling
vaults.rows	6	Size of every vault
vaults.admin-unlimited	true	Admin permission also grants max-vaults
storage.autosave-seconds	300	Write open vaults on a timer. 0 = off
storage.return-to-list	false	Reopen the list when a vault is closed
customization.*	on	Rename / icon / reset switches and permissions
naming.max-length	32	Longest name, measured on visible text
icon.default	CHEST	Icon before anybody picks one
icon.require-permission	false	Gate individual icons
item-filter.mode	'OFF'	OFF / BLACKLIST / WHITELIST
disabled-worlds	(empty)	Worlds where vaults do not work
placeholders	true	Register the PlaceholderAPI expansion

---

Commands & Permissions

Command	Permission	Description
/pv	command.permission (open by default)	Opens your vault list
/pv <number>	same as /pv	Opens that vault directly
/pv <player>	xprison.vaults.admin or xprison.menu.other	Opens another player's list. Works offline
/pv <player> <number>	as above	Opens one of their vaults directly
/pv info <player>	xprison.vaults.admin	Vault count, how many are in use, items stored
/pv delete <player> <number>	xprison.vaults.admin	Deletes one vault. Refused while it is open
/pv clear <player>	xprison.vaults.admin	Deletes every vault a player owns
/pv reload	xprison.vaults.admin	Reloads all three config files

Aliases /vault, /vaults, /playervault and /playervaults are configurable under command.aliases.

Permission nodes

Node	Grants
xprison.vaults.amount.<n>	That many vaults. Highest held node wins
xprison.vaults.amount.unlimited	As many as max-vaults allows
xprison.vaults.rename.color	MiniMessage in a vault name
xprison.vaults.icon.<id>	One specific icon, when require-permission is on
xprison.vaults.filter.bypass	Ignores the item filter
xprison.vaults.admin	Staff commands and other players' vaults

Rank ladder example:

lp group vip permission set xprison.vaults.amount.3 true
lp group mvp permission set xprison.vaults.amount.6 true
lp group elite permission set xprison.vaults.amount.12 true

---

Placeholders

All placeholders use the xprisonvaults identifier and require PlaceholderAPI.

Placeholder	Returns
%xprisonvaults_unlocked%	Vaults this player may open
%xprisonvaults_max%	The configured ceiling
%xprisonvaults_used%	How many of their vaults hold anything
%xprisonvaults_items%	Items stored across all their vaults
%xprisonvaults_rows%	Vault size in rows
%xprisonvaults_size%	Vault size in slots
%xprisonvaults_items_<n>%	Items in that one vault
%xprisonvaults_name_<n>%	What they called that vault
%xprisonvaults_icon_<n>%	That vault's icon

---

Frequently Asked Questions

Can two players open the same vault at once? No. The vault is locked from the moment it is asked for until its write reaches the database, so an admin and the owner cannot both have it on screen. The second one is told to try again in a moment.

Is that safe across a network of servers? Not by itself. The lock lives in the server's memory, so if you run several servers against one shared MySQL X-Prison database, a player logged into two of them could open the same vault twice. On a single server, or with a database per server, it is airtight.

What happens if I lower vaults.rows? Nothing is lost. Items past the new end are held out of sight and written back out when the vault is saved; raise the rows again and they reappear. No "empty your vaults before the update" announcement needed.

Can players buy vaults with in-game currency? Not built in. Vaults are granted by permission — hand them out with your rank ladder, a store package, or a command reward.

Can different ranks have different vault sizes? No. Vault count is per-permission; vault size is one value for the whole server.

Does the item filter understand item names or NBT? No, it matches materials. It cannot single out one specially-named item from others of the same type.

Does an item already in a vault get removed if I add it to the blacklist? No. The filter only stops items going in. Anything already stored can still be taken out.

Do vaults survive a restart? Yes. They are saved when the window closes, on a timer while open, and synchronously when the server stops.

A vault says it could not be opened. Did I lose the items? No — that message means the stored contents could not be decoded, and the addon deliberately refused to open an empty window over them. Nothing was overwritten. The console line printed alongside it says what went wrong.

Can I rename the command? Yes. command.name and command.aliases are configurable and re-register on /pv reload.