STABLE v1.1

Why NXVAULT?

Most player-vault plugins follow the same model: several distinct vaults—commonly accessed with commands like /pv 1, /pv 2, /pv 3—that behave like separate double-chests or ender chests. That approach is simple, but it exposes a recurring UX problem: when a player stores many shulker boxes it becomes time-consuming to find a specific item that might be deep inside a shulker. Players must open each container and search manually.

NXVAULT was created to fix that exact workflow. Instead of treating each numbered vault as an isolated silo, NXVAULT models pages as *views into a single logical vault*. Pages are primarily a navigation convenience, not separate storages. When a player searches, NXVAULT searches across every page and every nested container (including shulker content) so the result set is comprehensive. Searching recognizes item names and enchantments — so a player can find a single protected item by querying for the enchantment name.

Permissions control how many pages a player may have and who may use administrative commands. Starting with v1.1 (stable), NXVAULT's backup system has been updated and in-game restore and rollback commands are available to server operators. Administrative staff with the proper permission can also view other players' vaults using the new admin command.

The rest of this document contains exact command usage, configuration examples, and practical installation guidance.

Installation

NXVAULT is designed to integrate cleanly into existing Paper-based servers. Installation follows the same workflow as most modern plugins and does not require special migration steps for first-time use.

Requirements

Paper server (recommended for performance and inventory handling)
A Minecraft version supported by the current NXVAULT release
Basic permission management plugin (e.g., LuckPerms)

Installation steps

Download the plugin: Place the NXVAULT .jar file into your server’s /plugins directory.
Start the server: On first launch, NXVAULT will automatically generate its data folder and default config.yml. No manual setup is required at this stage.
Review configuration (optional): The default configuration is safe for immediate use. Server owners may optionally adjust page size, sounds, or save behavior to better match their server scale.
Set permissions: Grant nxvault.use to players and assign page limits using nxvault.pages.X. Administrative permissions should be restricted to staff.
Restart or reload: Restart the server (recommended) or use /vault reload to apply configuration changes.

After installation

Once installed, players can immediately access their vault using the /vault command. Vault pages function as a single unified storage system, and search is available across all pages and nested containers.

Note for larger servers: NXVAULT performs inventory saves during normal player interactions (page switches, close events, searches). For high-population servers, keeping the default page size ensures consistent performance.

Commands

Command	Description
`/vault`	Open your personal vault (first page by default).
`/vault <page>`	Open a specific vault page (pages are views of the same vault).
`/vault search`	Start the in-chat search prompt to find items across all pages and nested containers.
`/vault help`	Show all available NXVAULT commands.
`/vault info`	Show plugin version and basic diagnostics.
`/vault reload`	Reload configuration files (requires `nxvault.admin`).
`/vault restoreall <time>`	Restore all vaults to a previous backup snapshot. Accepts `1d`, `5d`, `7d`. Example: `/vault restoreall 1d`.
`/vault rollback <player> <time>`	Rollback a specific player's vault to a previous backup snapshot. Accepts `1d`, `5d`, `7d`. Example: `/vault rollback Steve 5d`.
`/vaultadmin <player>`	Open and inspect another player's vault (requires `nxvault.admin`).

Example: /vault 4 opens page 4 for the caller if they have that page allowed by permissions. Restore time values accepted: 1d, 5d, 7d.

Permissions

Permission	Effect
`nxvault.use`	Allow a player to open and use their vault.
`nxvault.admin`	Allow administrative commands such as `/vault reload`, `/vault restoreall`, `/vault rollback`, and `/vaultadmin` (view other players' vaults).
`nxvault.pages.X`	Grant a player permission to hold up to X pages (replace `X` with number).

Keep admin nodes limited. NXVAULT's admin permission is powerful and should be restricted to trusted staff only.

Configuration

Full reference (copyable)

gui:
  # Inventory size (must be multiple of 9, usually 54)
  size: 54

  # Items per page (slots 0–44)
  page-size: 45

  titles:
    vault: "&0My Vault &8(Page %page%)"
    search: "&0Search: &8&n&o%query%"

  filler:
    enabled: true
    material: LIGHT_GRAY_STAINED_GLASS_PANE
    name: " "

  buttons:
    previous:
      slot: 45
      material: ARROW
      name: "&aʙᴀᴄᴋ"
      lore:
        - "&7Go to the previous page"

    search:
      slot: 49
      material: OAK_SIGN
      name: "&eѕᴇᴀʀᴄʜ &7(ᴄʟɪᴄᴋ)"
      lore:
        - "&7Search items in your vault"

    next:
      slot: 53
      material: ARROW
      name: "&aɴᴇxᴛ"
      lore:
        - "&7Go to the next page"

search:
  enabled: true

  # Message sent when clicking search
  prompt-message: "&eType your search query in chat. Type &c&l&ncancel&e to abort."

  cancel-word: "cancel"

  no-results-message: "&cNo results for: &e%query%"

  # Max items shown in search results (prevents huge GUIs)
  max-results: 45

vault:
  # Block vault usage in creative mode
  block-creative: true
  creative-block-message: "&b&lNxVault &7» &fVaults are not usable in Creative mode."

  # Save behavior
  save-on-close: true
  save-on-page-switch: true

sounds:
  open:
    sound: BLOCK_BARREL_OPEN
    volume: 0.8
    pitch: 1.1

  close:
    sound: BLOCK_BARREL_CLOSE
    volume: 0.8
    pitch: 1.0

  page:
    sound: UI_BUTTON_CLICK
    volume: 0.7
    pitch: 1.2

  pickup:
    sound: ENTITY_ITEM_PICKUP
    volume: 0.7
    pitch: 1.2

messages:
  inventory-full: "&b&lNxVault &7» &fYour inventory is full!"
  search-cancelled: "&cSearch cancelled."
  only-players: "&b&lNxVault &7» &fOnly players can use this command."
  no-more-pages: "&b&lNxVault &7» &fYou have reached the maximum number of vault pages."

Config notes: Keep size as a multiple of 9. The page-size should match how many content slots you want per page (45 leaves room for 9 navigation/filler slots in a 54 slot GUI). search.max-results controls the number of items rendered for a search result to avoid client-side rendering issues.

Backups (v1.1 system)

NXVAULT ships with an updated backup subsystem in v1.1 (stable). Backups are produced automatically and in-game restore/rollback tools are now available for operators.

How backups work (accurate)

Hourly backups are created/updated every hour.
At the end of each day, hourly files are consolidated/saved as that day's daily snapshot.
The system retains the last 30 backups (combined view of hourly/daily retention — configured retention may vary later).
Each backup file contains only the data for vaults that were updated during that interval (i.e., they are per-vault delta files, not full global dumps).
Storage format change: Backups are stored as plain/open folders (no zip archives) inside the plugin's root /backup directory. This makes manual inspection and extraction simpler for operators.

Restore & rollback (in-game)

/vault restoreall <time> — Restore all vaults to the selected snapshot (accepted time values: 1d, 5d, 7d).
/vault rollback <player> <time> — Rollback a single player's vault to the selected snapshot.
/vaultadmin <player> — Open and inspect another player's vault (admin-only).

Important: Automatic single-click full restores are now available via the in-game commands above, but because backup files are incremental, some manual assembly or verification may still be required for complex recovery cases. Operators are still recommended to keep periodic full server backups in addition to NXVAULT backups.

Backup files are written under the plugin folder in a /backup directory. To make off-server archival easier, periodically copy the backup folder to external storage and test restores on a staging server.

FAQ

Can players open other players' vaults?

Not by default. Administrators with the nxvault.admin permission can inspect other players' vaults using /vaultadmin <player>.

Does search look inside shulker boxes and enchantments?

Yes. Search indexes shulker contents and recognizes enchantment names so queries for an enchantment will return matching items even if they're nested.

Is automatic restore available?

Yes — starting in v1.1, NXVAULT supports in-game restore and rollback commands (/vault restoreall, /vault rollback) to recover vault data from the backup snapshots stored in the plugin's /backup folder.