- PlayerVaultZ: Modern, paginated player vaults with sorting, instant search, blacklist enforcement, and a working PlayerVaultsX importer. Built for Paper/Spigot 1.21, Java 21.

Key Features

- Pagination: Clean multi-page GUI with bottom navigation bar.
- Sorting: Alphabetical, by type, quantity, rarity, or custom name.
- Search: Anvil-based search UI with clickable results to jump to items.
- Import: Working importer for PlayerVaultsX .yml vault files.
- Blacklist: Block items by material, custom name, lore, or NBT tag, with admin bypass.
- Backup/Restore: Automatic backups (scheduled, on vault close, optional on player join), compressed storage, retention, and interactive restore GUI.
- Permissions: Rank-based vault limits (playervaultz.vaults.N), unlimited option, access others, delete, import, info.
- Performance: SQLite + HikariCP, async I/O, caching, session timeouts, and auto-save.
- Customization: Fully configurable GUI (items, titles, sounds, styles) and messages.

Compatibility

- Server: Paper/Spigot 1.21+
- Java: 21
- Softdepend: Vault (for broader ecosystem; not required)

Quick Start

- Drop the jar into plugins/.
- Start the server to generate configs.
- Grant permissions with your permission plugin.
- Use /pv to open your vault. Use the nav bar to switch pages.
- Optional: Import PlayerVaultsX vaults (see Import section).

Commands

- /pv: Opens your vault 1.
- /pv <#>: Opens your vault number.
- /pv <player> <#>: Opens another player’s vault (requires permission).
- /pv list [player]: Lists vaults you (or a target) have.
- /pv search <term>: Searches your vaults (fallback to Anvil search).
- /pv info: Shows vault system info (permission required).
- /pvadmin: Admin suite
- reload: Reloads plugin + GUI + blacklist config.
- info: Shows plugin info and runtime stats.
- refresh: Refreshes all open GUIs to reflect permission/config changes.
- clearcache: Clears permission caches (compatibility no-op + GUI refresh).
- debug [on|off]: Toggles debug logging.
- backup|backupall|restore|restoreall|listbackups|restoregui: Backup/restore helpers (see Backups section for practical usage).
- /pvimport pvx: Imports PlayerVaultsX vault files (see Import section).

Permissions

- playervaultz.use: Use vaults (default: true)
- playervaultz.vaults.N: Access up to N vaults (1–100; only 1 default true)
- playervaultz.unlimited.vaults: Unlimited vault access
- playervaultz.other: Open other players’ vaults
- playervaultz.delete.own / playervaultz.delete.other / playervaultz.delete.all: Deletion controls
- playervaultz.sort: Sort own vaults
- playervaultz.sort.others: Sort others’ vaults
- playervaultz.import: Use /pvimport
- playervaultz.info: Use /pv info
- playervaultz.bypass.cooldown: Reserved for cooldowns
- playervaultz.blacklist.bypass: Bypass item blacklist
- playervaultz.admin: Grants admin suite
- Tip: Give players exactly one playervaultz.vaults.N node (or unlimited). Admins can also be given playervaultz.admin.

PlayerVaultsX Import

- Location: Place .yml files in plugins/PlayerVaultZ/import/playervaultsx
- If the folder does not exist, run /pvimport pvx once to auto-create it.
- Steps:
- Stop the server and back up your data.
- Copy PlayerVaultsX vault .yml files into the import folder.
- Start the server, run /pvimport pvx.
- Progress and totals appear in chat, with successes/failures logged.
- Notes:
- Importer handles Base64 format and common newline issues.
- The importer processes vault files named by player UUID.

Search & Sorting

- Search:
- Click the “Search” button in the vault navigation bar to open the anvil UI, type a term, and view results.
- Click a result to jump directly to the vault/page/slot where it exists.
- Fallback: /pv search <item name> shows a textual list.
- Sorting:
- Click the “Sort” button in the nav bar.
- Left-click: Sort now. Right-click: Cycle modes.
- Modes: Alphabetical, By Type, By Quantity, By Rarity, By Custom Name.

Blacklist

- What it blocks:
- By material: e.g., COMMAND_BLOCK, SPAWNER, etc.
- By custom name: exact match with color codes.
- By lore: substring match; color codes supported.
- By NBT tag: persistent data keys on items.
- Where it applies:
- Shift-click from player inventory into vault.
- Cursor placement into vault slots.
- Inventory drags into vault area.
- Admin bypass:
- Grant playervaultz.blacklist.bypass to allow storage anyway.
- Configure in plugins/PlayerVaultZ/config.yml:
- blacklist.enabled: true/false
- blacklist.materials: list of blocked materials
- blacklist.custom-names: list of blocked display names (supports & color codes)
- blacklist.lore-contains: list of blocked lore substrings
- blacklist.nbt-tags: list of blocked NBT keys (supports namespaced keys)
- blacklist.message: deny message
- blacklist.admin-bypass: allow bypass with permission

Backups & Restore

- Automatic triggers (configurable):
- Scheduled: Periodic backups of active vaults.
- Vault Close: Creates a backup when a vault GUI closes.
- Player Join: Optional; back up first few vaults for that player.
- Loss Detection: Emergency backup when item loss is detected.
- Storage:
- Files saved in plugins/PlayerVaultZ/backups/
- Compressed .yml.gz format (configurable).
- Retention: Keep up to max-backups per vault; older files purged.
- Restore:
- Use /pvadmin restoregui <player> <vault> to browse backups and selectively restore items or pages.
- Or, restore by file name: /pvadmin restore <player> <vault> <backup-file>
- Safety:
- Optional pre-restore backup, confirmation prompts for bulk operations, operation logging.
- Notes:
- Admin suite covers backup/restore operations.
- For reliability, always back up the server before bulk restores/imports.

Configuration (config.yml)

- vaults.cache.cache-expire-time: Minutes before unused vaults are evicted from cache.
- vaults.cache.max-cached-vaults: Cache size cap.
- performance.auto-save-interval: Minutes; use -1 to disable periodic auto-save.
- performance.session-timeout: Minutes before inactive sessions are cleaned up.
- updates.check-for-updates: Enable/disable update checks (informational).
- blacklist.*: See Blacklist section.
- backup.*: Enable automatic backups, triggers, retention, compression, restore GUI behavior.
- debug.enabled: Enables detailed debug logging.

GUI Customization (gui.yml)

- Titles:
- vault.title: Inventory title; placeholders {vault_number}, {owner}, {player}.
- search-results.title: Title when viewing search results; {search_term} placeholder.
- Navigation items (slots 45–53):
- previous-vault, next-vault, vault-info, search, sort, close, filler.
- Each item supports:
- `material`: Vanilla item fallback.
- `display-name`, `lore`, `custom-model-data`, `glow`.
- Conditional visibility: `permission`, `show-only-if-accessible`, `show-only-for-owner`.
- Disabled state via `disabled-item`.
- Custom item plugins:
- Use one of: nexo-id, itemsadder-id, or oraxen-id. If not present, falls back to material.
- Sounds:
- sounds.enabled: Global toggle.
- Per-action sound with sound, volume, pitch (e.g., vault-open, navigation-click, blacklist-deny).
- Sort method descriptions:
- Customize descriptions shown for sort modes.

Storage & Data

- Database: plugins/PlayerVaultZ/vaults.db (SQLite).
- Schema managed automatically; no setup required.
- Backups: plugins/PlayerVaultZ/backups/ (compressed by default).
- Import folder: plugins/PlayerVaultZ/import/playervaultsx.

Performance Tips

- Reduce auto-save frequency if you have heavy write load.
- Tune cache size to match your active player count.
- Keep debug logging off in production (debug.enabled: false).

FAQ / Troubleshooting

- “Search button does nothing”
- Ensure AnvilGUI is shaded (it is) and you’re on Paper/Spigot 1.21 with Java 21.
- Fallback: /pv search <term>.
- “Players can’t see vault 2+”
- Grant playervaultz.vaults.N (e.g., playervaultz.vaults.5) or playervaultz.unlimited.vaults.
- “Can’t open other players’ vaults”
- Grant playervaultz.other.
- “Blacklist not working”
- Confirm blacklist.enabled: true and that the item matches material/name/lore/NBT rules.
- Admins with playervaultz.blacklist.bypass will skip checks.
- “Importer says no files found”
- Place .yml files under plugins/PlayerVaultZ/import/playervaultsx and run /pvimport pvx again.
- “Backups too large or too frequent”
- Lower backup.triggers.scheduled.interval and set reasonable backup.retention.max-backups.
- Compression is on by default; keep it enabled for smaller files.

Best Practices

- Always take a full server backup before import or bulk restore.
- Start small: test import with one or two players first.
- Use /pvadmin refresh after changing GUI/permissions so open vaults update immediately.