Nexal Backpacks

A configurable backpack system for Minecraft servers. Define any number of backpack types with their own item, size, item restrictions, auto-pickup and crafting recipe. Backpack contents are stored on the server and linked to the item by a unique ID, so the item itself carries nothing to duplicate.

Features

Unlimited Backpack Types - Define backpack types in config with their own material, name, lore, optional custom model data and size
Variable Sizes - Any capacity from 1 to 540 slots; larger backpacks are paginated at 45 slots per page, and unused slots are locked
Item Restrictions - Whitelist and/or blacklist items per type (a mining backpack only accepts ores); enforced for clicks, drags, shift-clicks and hotbar swaps. Backpacks, and shulker boxes or bundles holding one, never go inside a backpack
Auto-Pickup - Backpacks with auto-pickup collect matching items straight from the ground, with actionbar notifications
Batch Notifications - Pickups in a short burst are combined into one actionbar message; each player can turn this off
Backpack Menu - Sort, Quick Deposit (storage slots only, armor and offhand stay put) and an auto-pickup toggle
Backpack Overview - /backpack list shows every backpack you carry, how full it is, and opens it
Soulbound Option - Configure types to stay in the inventory on death
Crafting Recipes - Shaped or shapeless recipes per type; each crafted backpack, crafter output included, gets its own storage
Server-Side Contents - Contents live on the server, one open menu per backpack at a time, every change in an open menu is saved right away, and open menus are saved when the server stops
Lost Backpack Recovery - Backpacks destroyed by lava, fire, cactus, explosions, the void or despawning are listed in an admin GUI for preview and recovery
Admin GUI - /backpack admin opens a hub: configuration, backpack types (give, slots, soulbound, auto-pickup, recipe), lost backpacks, reload, export and import
PlaceholderAPI Support - Placeholders for backpack counts, items and capacity
Dual Storage - JSON or MySQL/MariaDB, with export and import to move between them
Customizable Messages - Every message, and the text of the player menus, is in messages.yml, with sounds
Hot-Reload Config - Changes to config.yml and messages.yml apply without a restart

Technologies

Paper API 1.20.1+ - Minecraft server API, Spigot compatible
Utilizer 0.21.2 - Configuration, messages, GUIs, tasks
ACF - Command framework
nexal-core - JSON/SQL persistence (shaded into the jar)
PlaceholderAPI - Placeholder integration (optional)

Commands

Aliases: /backpack, /backpacks, /bp.

Player Commands

Command	Description	Permission
`/backpack` or `/backpack help [page]`	Show the help menu	None
`/backpack list`	Overview GUI of the backpacks in your inventory	`nexalbackpacks.list`
`/backpack autopickup`	Toggle auto-pickup on the held backpack	`nexalbackpacks.autopickup`
`/backpack notifications`	Toggle your auto-pickup notifications	`nexalbackpacks.notifications`
`/backpack notifications batch`	Toggle combining a burst of pickups into one notification	`nexalbackpacks.notifications`

Right-click a backpack to open it.

Admin Commands

Command	Description	Permission
`/backpack admin`	Open the admin GUI (console: list the admin commands)	`nexalbackpacks.admin`
`/backpack admin help [page]`	List the admin commands	`nexalbackpacks.admin`
`/backpack admin give \<player> \<type>`	Give a new backpack to a player	`nexalbackpacks.admin`
`/backpack admin lost`	View, preview and recover lost backpacks (GUI)	`nexalbackpacks.admin`
`/backpack admin types`	List the registered backpack types	`nexalbackpacks.admin`
`/backpack admin cleanup`	Permanently delete every lost backpack (console only)	`nexalbackpacks.admin`
`/backpack admin export`	Export all backpacks and player preferences to `export.json`	`nexalbackpacks.admin`
`/backpack admin import`	Import `export.json`; existing records are kept as they are	`nexalbackpacks.admin`
`/backpack admin reload`	Reload the configuration	`nexalbackpacks.admin`

Permissions

Permission	Description	Default
`nexalbackpacks.list`	Use `/backpack list`	true
`nexalbackpacks.autopickup`	Use `/backpack autopickup`	true
`nexalbackpacks.notifications`	Use `/backpack notifications` and `/backpack notifications batch`	true
`nexalbackpacks.admin`	All admin commands and the admin GUI	op

Placeholders

Requires PlaceholderAPI.

Placeholder	Description
`%backpacks_count%`	Total backpacks in inventory
`%backpacks_total_items%`	Total items across all backpacks
`%backpacks_total_capacity%`	Total slots across all backpacks
`%backpacks_fill_percentage%`	Percentage of slots used across all carried backpacks
`%backpacks_count_\<type>%`	Count of a specific type (e.g., `%backpacks_count_mining%`)
`%backpacks_items_\<type>%`	Items in backpacks of a type
`%backpacks_capacity_\<type>%`	Capacity of backpacks of a type

Admin GUI

/backpack admin opens a hub with:

Configuration - toggle batch pickup notifications and set the batch delay
Backpack Types - every type in config.yml. Left-click gives you one; right-click opens the type's settings: slots, soulbound, auto-pickup by default and whether its recipe is enabled
Lost Backpacks - every backpack marked as lost, with its reason and time. Left-click recovers it into your inventory (you need a free slot), right-click previews its contents
Reload, Export and Import - the same as the /backpack admin commands

Changes are saved to config.yml and apply at once. A type's name, material, lore, item filters and recipe shape are edited in config.yml.

Configuration

config.yml

# Storage settings
storage:
  type: json  # json (plugins/NexalBackpacks/data.json) or sql (MySQL/MariaDB)
  sql:
    host: localhost
    port: 3306
    database: minecraft
    username: root
    password: ""

# Auto-pickup settings
auto-pickup:
  # Combine multiple pickup notifications into one
  batch-notifications: true
  # Delay in ticks before sending batch notification (1 second = 20 ticks)
  batch-delay-ticks: 10

# Backpack types
types:
  small:
    display-name: "\<green>Small Backpack\</green>"
    material: LEATHER
    custom-model-data: 0   # optional, for a resource pack model
    lore:
      - "\<gray>Capacity:\</gray> \<white>%slots% slots\</white>"
    slots: 9
    soulbound: false
    auto-pickup-default: false
    whitelist: []  # Empty = all items allowed
    blacklist:
      - BEDROCK
    recipe:
      enabled: true
      type: shaped   # or shapeless
      shape:
        - "LLL"
        - "LCL"
        - "LLL"
      ingredients:
        L: LEATHER
        C: CHEST

  mining:
    display-name: "\<red>\<bold>Mining Backpack\</bold>\</red>"
    material: DIAMOND_PICKAXE
    slots: 36
    auto-pickup-default: true
    whitelist:
      - COAL_ORE
      - IRON_ORE
      - DIAMOND_ORE
      # ... more ores

The default config.yml ships seven types: small (9), medium (27), large (45), ender (54, soulbound), mining (36, ores), farming (36, crops) and huge (90, two pages).

messages.yml

Every chat message, actionbar and sound, and the text of the backpack, list and lost-backpack menus, is in messages.yml, in MiniMessage format. A color reference at the top lists the gradients used, for find-and-replace. Keys added in an update fall back to the bundled defaults when an older messages.yml does not have them.

prefix: "<gradient:#9B59B6:#AF7AC5>Backpacks\</gradient> \<gray>|\</gray> "

auto-pickup-notification:
  actionbar: "\<gray>Picked up\</gray> <gradient:#C39BD3:#D7BDE2>%item%\</gradient> \<gray>x\</gray>\<white>%amount%\</white> \<gray>into backpack\</gray>"

gui-sort-button:
  display-name: "<gradient:#9B59B6:#AF7AC5>\<bold>Sort Items\</bold>\</gradient>"
  lore:
    - ""
    - "<gradient:#2ECC71:#52D68A>▶ Left Click\</gradient> \<gray>to sort\</gray>"

Storage

JSON

Everything is stored in plugins/NexalBackpacks/data.json, in two collections: backpacks and backpacks_users. Writes happen off the main thread; auto-pickup changes are saved every few seconds rather than per item.

SQL

When storage.type is sql, the plugin creates these tables:

`backpacks`

Column	Type	Key	Description
`id`	VARCHAR(255)	PK	Backpack UUID, also stored on the item
`type_id`	VARCHAR(255)		Backpack type from `config.yml`
`contents_base64`	MEDIUMTEXT		Serialized contents
`auto_pickup`	BOOLEAN		Auto-pickup enabled
`lost`	BOOLEAN		Marked as lost
`lost_reason`	VARCHAR(255)		lava, fire, cactus, explosion, void or despawn
`lost_at`	BIGINT		When it was lost
`created_at`	BIGINT		Creation timestamp
`last_accessed`	BIGINT		Last opened

`backpacks_users`

Column	Type	Key	Description
`id`	VARCHAR(36)	PK	Player UUID
`notifications_enabled`	BOOLEAN		Auto-pickup notifications on
`batch_notifications`	BOOLEAN		Batched notifications on

Moving between JSON and SQL

/backpack admin export
Change storage.type in config.yml
Restart the server
/backpack admin import

Upgrading from 1.0.2 or earlier

Contents stored by 1.0.2 and earlier are rewritten in the new format on the first start. With JSON storage, data.json is first copied to data.json.pre-1.0.3.bak. With SQL storage, the contents_base64 column is widened from VARCHAR(255) to MEDIUMTEXT.

Installation

Copy NexalBackpacks-\<version>.jar to your server's plugins/ folder
Start the server
Edit plugins/NexalBackpacks/config.yml to configure backpack types
Changes apply automatically; /backpack admin reload reloads on demand

How It Works

Item Identification: Each backpack item has a unique UUID in its PersistentDataContainer
Server Storage: Contents are stored on the server, not in the item, and only one player can have a backpack open at a time
Auto-Pickup: Picked-up items that a carried backpack accepts go into it; a backpack that is open is skipped
Lost Detection: A dropped backpack is marked as lost only once its item is actually destroyed or despawns
Recovery: Admins recover a lost backpack as a new item linked to the existing contents

Features​

Technologies​

Commands​

Player Commands​

Admin Commands​

Permissions​

Placeholders​

Admin GUI​

Configuration​

config.yml​

messages.yml​

Storage​

JSON​

SQL​

backpacks​

backpacks_users​

Moving between JSON and SQL​

Upgrading from 1.0.2 or earlier​

Installation​

How It Works​