-
Notifications
You must be signed in to change notification settings - Fork 0
Home
- Overview
- Installation
- Backpack Types
- The Six Tiers
- Crafting Recipes
- Commands
- Permissions
- Configuration - config.yml
- Configuration - backpacks.yml
- Loot Integration
- Admin Guide
- Anti-Dupe System
- Data Storage
- Frequently Asked Questions
DynamicBackpacks adds a fully progression-based backpack system to your server. Players can craft backpacks that range from a single row of storage all the way up to a full double chest, and every item backpack is a real physical item with a unique identifier tracked in a SQLite database, so contents are never lost, even if the item itself is destroyed.
There are two backpack modes available. Item backpacks are physical player head items that players can craft, trade, and carry in their inventory. Command backpacks are personal storage slots tied to a player's account and opened with a simple slash command, no item required. Both modes can run simultaneously, or either one can be disabled entirely depending on your server's needs.
The plugin is designed to work identically on both Spigot and Paper for all versions from 1.21 through 1.21.11, using only the standard Bukkit API throughout.
Drop the DynamicBackpacks-<version>.jar file into your server's plugins/ folder and restart. On first start the plugin will create a plugins/DynamicBackpacks/ directory containing config.yml, backpacks.yml, and a backpacks.db SQLite database file. No additional setup is required.
If you are running Paper, make sure you are using the shadowJar build of the plugin (the release jar already includes the bundled SQLite driver). Spigot does not ship with SQLite, so the bundled driver in the plugin jar handles that automatically.
An item backpack is a craftable player head item. Right-clicking the item anywhere, in your hand, in your hotbar, or inside any inventory slot, opens a chest GUI sized to the tier. The item carries a hidden unique identifier stored in its persistent data, which is how the plugin associates it with a saved inventory in the database. Stack size is permanently forced to 1.
Item backpacks can be passed between players, placed in chests, and traded. If an item backpack is destroyed (thrown into lava, blown up by a creeper, etc.), the data is not deleted, an admin can restore it to any player using the /dbp restore command as long as they know the backpack's UUID.
Command backpacks are account-bound storage slots opened with /bp <slot>. There are up to 10 slots per player and each slot has a configurable tier set in config.yml. These are not items, they cannot be dropped, traded, or destroyed. Think of them as permanent bank slots attached to the player's account.
The slot number a player can access is controlled individually by permission, so you can grant players access to only the slots you want. Each slot independently stores its own set of items in the database.
Tiers control how much storage a backpack provides. Lower tiers are cheap to craft and carry only a handful of slots, while the top tiers require significant material investment and offer full double-chest storage.
| Tier | Color Code | Storage | Craft Material |
|---|---|---|---|
| Tier 1 |
&6 Gold |
9 slots (1 row) | Leather + Chest |
| Tier 2 |
&7 Grey |
18 slots (2 rows) | Iron Ingots + T1 Backpack |
| Tier 3 |
&e Yellow |
27 slots (3 rows) | Gold Ingots + T2 Backpack |
| Tier 4 |
&b Aqua |
36 slots (4 rows) | Diamonds + Leather + T3 Backpack |
| Tier 5 |
&a Green |
45 slots (5 rows) | Emeralds + Iron + T4 Backpack |
| Tier 6 |
&8 Dark Grey |
54 slots (6 rows) | Netherite + Gold + T5 Backpack |
Each tier has its own unique player head texture so players can immediately identify the tier at a glance. The texture and display name for each tier are fully configurable in backpacks.yml. Individual tiers can be disabled entirely by setting enabled: false on that tier, which removes the tier from recipes and prevents any new backpacks of that tier from being given or opened.
All recipes use a standard 3×3 crafting table layout. The upgrade system means every recipe (except Tier 1) requires the previous tier's backpack in the center slot. When you craft an upgrade, the contents of the old backpack are automatically transferred into the new one, nothing is lost.
Tier 1 - 8x Leather surrounding a Chest
L L L
L C L
L L L
L = Leather, C = Chest
Tier 2 - 8x Iron Ingots surrounding a Tier 1 Backpack
I I I
I B I
I I I
I = Iron Ingot, B = Tier 1 Backpack
Tier 3 - 8x Gold Ingots surrounding a Tier 2 Backpack
G G G
G B G
G G G
G = Gold Ingot, B = Tier 2 Backpack
Tier 4 - Diamonds at corners, Leather on edges, Tier 3 Backpack in center
D L D
L B L
D L D
D = Diamond, L = Leather, B = Tier 3 Backpack
Tier 5 - Emeralds at corners, Iron Ingots on edges, Tier 4 Backpack in center
E I E
I B I
E I E
E = Emerald, I = Iron Ingot, B = Tier 4 Backpack
Tier 6 - Netherite Ingots at corners, Gold Ingots on edges, Tier 5 Backpack in center
N G N
G B G
N G N
N = Netherite Ingot, G = Gold Ingot, B = Tier 5 Backpack
Crafting a tier requires both the dynamicbackpacks.craft.tier.<N> permission for the tier being crafted and possession of a valid backpack item for the previous tier in the center slot. Individual recipe tiers can be toggled off in backpacks.yml under crafting.enabled.
The player-facing command for opening command backpacks.
/bp <1-10>
Opens your personal command backpack at slot number. You must have the dynamicbackpacks.command.bp.use permission as well as the per-slot permission dynamicbackpacks.command.bp.<N>.
/bp view <player> <1-10>
Admin subcommand. Opens a full read/write GUI of the target player's command backpack slot. Requires the dynamicbackpacks.admin.view permission. The target player receives a chat message while their backpack is being viewed by an admin.
Tab completion is supported for all arguments. Slot numbers will only appear for slots the running player has permission to access. The view subcommand will only appear if the player has the view permission.
The admin management command. Alias: /dynamicbackpacks.
/dbp reload
Reloads both config.yml and backpacks.yml, re-registers all crafting recipes, and closes any currently open backpack inventories before applying changes. Requires dynamicbackpacks.admin.reload.
/dbp give <player> <tier>
Creates a new item backpack of the specified tier and places it into the target player's inventory. The backpack is saved to the database immediately. Requires dynamicbackpacks.admin.give.
/dbp restore <uuid> <player>
Re-issues an orphaned item backpack (one whose physical item was destroyed) to the target player. The UUID printed to console when any item backpack is created can be used here. The restored backpack retains all of its original contents. Requires dynamicbackpacks.admin.restore.
Tab completion for /dbp suggests subcommands on the first argument, player names on the second argument for give and the third argument for restore. The UUID argument for restore has no auto-complete since UUIDs are long strings you'll want to copy from console or logs.
All permissions default to op status.
These permissions gate whether a player can open item backpacks at the given tier. A player without the relevant tier permission will see an error when they try to open a backpack of that tier.
| Permission | Description |
|---|---|
dynamicbackpacks.use.item.tier.1 |
Open Tier 1 item backpacks |
dynamicbackpacks.use.item.tier.2 |
Open Tier 2 item backpacks |
dynamicbackpacks.use.item.tier.3 |
Open Tier 3 item backpacks |
dynamicbackpacks.use.item.tier.4 |
Open Tier 4 item backpacks |
dynamicbackpacks.use.item.tier.5 |
Open Tier 5 item backpacks |
dynamicbackpacks.use.item.tier.6 |
Open Tier 6 item backpacks |
These permissions are checked when a player completes a crafting recipe that outputs a backpack. A player who lacks the crafting permission for the tier they are crafting will see the result item removed from the crafting output.
| Permission | Description |
|---|---|
dynamicbackpacks.craft.tier.1 |
Craft Tier 1 backpacks |
dynamicbackpacks.craft.tier.2 |
Craft Tier 2 backpacks |
dynamicbackpacks.craft.tier.3 |
Craft Tier 3 backpacks |
dynamicbackpacks.craft.tier.4 |
Craft Tier 4 backpacks |
dynamicbackpacks.craft.tier.5 |
Craft Tier 5 backpacks |
dynamicbackpacks.craft.tier.6 |
Craft Tier 6 backpacks |
| Permission | Description |
|---|---|
dynamicbackpacks.command.bp.use |
Required base permission to use /bp at all |
dynamicbackpacks.command.bp.1 |
Access command backpack slot 1 |
dynamicbackpacks.command.bp.2 |
Access command backpack slot 2 |
dynamicbackpacks.command.bp.3 |
Access command backpack slot 3 |
dynamicbackpacks.command.bp.4 |
Access command backpack slot 4 |
dynamicbackpacks.command.bp.5 |
Access command backpack slot 5 |
dynamicbackpacks.command.bp.6 |
Access command backpack slot 6 |
dynamicbackpacks.command.bp.7 |
Access command backpack slot 7 |
dynamicbackpacks.command.bp.8 |
Access command backpack slot 8 |
dynamicbackpacks.command.bp.9 |
Access command backpack slot 9 |
dynamicbackpacks.command.bp.10 |
Access command backpack slot 10 |
The dynamicbackpacks.admin node is a parent that automatically grants all four child permissions below it.
| Permission | Description |
|---|---|
dynamicbackpacks.admin |
Parent, grants all admin sub-permissions |
dynamicbackpacks.admin.view |
Use /bp view <player> <slot>
|
dynamicbackpacks.admin.give |
Use /dbp give <player> <tier>
|
dynamicbackpacks.admin.restore |
Use /dbp restore <uuid> <player>
|
dynamicbackpacks.admin.reload |
Use /dbp reload
|
Located at plugins/DynamicBackpacks/config.yml.
config-version: 2
# Plugin mode controls which backpack systems are active.
# both - item backpacks and command backpacks are both enabled
# item - only physical item backpacks
# command - only command backpacks (/bp)
# off - all backpack functionality disabled
mode: both
database:
# Name of the SQLite database file inside the plugin data folder.
file: backpacks.db
command-backpacks:
# Tier assigned to every command backpack slot (1-6).
# All slots share the same tier by default.
default-tier: 6
loot:
# Master switch for structure loot chest injection.
# Per-structure chances are configured in backpacks.yml per tier.
enabled: false
inventory:
# If false (default), players cannot place shulker boxes inside backpacks.
# Set to true to allow nested shulker box storage.
allow-shulker-boxes: falsemode is the most important option. Setting it to item disables the /bp command entirely. Setting it to command disables all item backpack functionality including crafting. Setting it to off shuts everything down without unloading the plugin.
command-backpacks.default-tier applies to all command backpack slots unless you override it programmatically. Since command backpacks are account-bound and not craft-limited, most servers set this to 6 so players get a full double chest.
loot.enabled is a master switch. Even if individual tier entries in backpacks.yml have their loot chances set, nothing will spawn unless this top-level toggle is true.
Located at plugins/DynamicBackpacks/backpacks.yml. This file controls all per-tier settings including storage size, display name, textures, crafting recipes, and loot table injection.
Each tier block lives under tiers.<number>: and supports the following fields:
enabled (boolean, default true) - Set to false to completely disable a tier. Disabled tiers are excluded from the recipe registry, cannot be given via /dbp give, and cannot be opened. This is a clean on/off for individual tiers without having to delete the configuration block.
rows (integer, 1–6) - Number of inventory rows. Each row is 9 slots. Tier 1 defaults to 1 row (9 slots) and Tier 6 defaults to 6 rows (54 slots).
display-name (string) - The item display name shown when hovering over the backpack. Supports legacy & color codes (e.g., &6Tier 1 Backpack for gold text).
texture (string) - A Base64-encoded Minecraft skin value used to texture the player head. You can grab these from sites like minecraft-heads.com - copy the value from the "Value" field under "Minecraft-URL". The six default textures are distinct leather-to-netherite themed backpack heads.
Under crafting: for each tier:
enabled (boolean) - Toggle whether this tier's recipe is registered. Disabling it removes the recipe from the server's recipe book.
shape (list of 3 strings) - Standard 3×3 crafting grid. Each string is exactly 3 characters wide.
ingredients (map) - Maps each character in the shape to a material name. Use standard Bukkit material names (e.g., LEATHER, DIAMOND, GOLD_INGOT). To reference another backpack tier as an ingredient, use the special key TIER_N_BACKPACK where N is the tier number (e.g., TIER_1_BACKPACK).
Under loot: for each tier, there is one entry for every supported structure type. Each entry takes:
enabled (boolean) - Whether this tier can appear in this structure's loot chest.
chance (integer, 0–100) - Percentage chance per chest generation event.
Both fields must be set for a location to be active. If enabled is false, the entry is ignored regardless of the chance value.
The following structure keys are recognized:
Overworld structures: dungeon, mineshaft, desert_temple, jungle_temple, stronghold_corridor, stronghold_library, stronghold_crossing, woodland_mansion, igloo, pillager_outpost, shipwreck_map, shipwreck_supply, shipwreck_treasure, ocean_ruin_big, ocean_ruin_small, buried_treasure, ruined_portal, ancient_city, ancient_city_ice_box
Villages: village_armorer, village_butcher, village_cartographer, village_desert_house, village_fisher, village_fletcher, village_mason, village_plains_house, village_savanna_house, village_shepherd, village_snowy_house, village_taiga_house, village_tannery, village_temple, village_toolsmith, village_weaponsmith
Nether structures: nether_fortress, bastion_bridge, bastion_hoglin_stable, bastion_other, bastion_treasure
End structures: end_city
Trial Chambers: trial_chambers_supply, trial_chambers_corridor, trial_chambers_entrance, trial_chambers_intersection, trial_chambers_reward, trial_chambers_reward_rare
By default, loot injection is disabled. To enable it, set loot.enabled: true in config.yml. Once enabled, the plugin hooks into the LootGenerateEvent and injects backpack items into matching structure chests according to the per-tier, per-location configuration in backpacks.yml.
The default chance values are intentionally conservative. Higher-tier backpacks are set to spawn only in the most challenging late-game locations and at very low probability. The default distribution by tier is roughly:
Tier 1 and Tier 2 are configured to appear in common overworld structures (dungeons, mineshafts, desert temples, villages) at moderate chances. These are early-game finds.
Tier 3 starts appearing in mid-tier structures like nether fortresses, ancient city, and later overworld dungeons, dropping out of village loot entirely.
Tier 4 only appears in high-effort structures, woodland mansions, ancient city, bastion treasure, end city, and select trial chambers.
Tier 5 is restricted to the most dangerous or remote locations: ancient city, end city, bastion treasure, trial reward chests.
Tier 6 has a hard cap of 1% and only spawns in woodland mansion, ancient city, bastion treasure, end city, and trial reward chests. Finding one naturally is rare by design.
All of these values are fully configurable and can be raised, lowered, or zeroed out per location. To disable loot from a specific location entirely, set enabled: false on that entry.
/dbp give <player> <tier>
The tier must be a number from 1 to 6 (or whatever range you have enabled). The item will be placed directly in the player's inventory. If their inventory is full the command will fail with a message. The backpack is registered in the database the moment it is created, so its UUID is immediately tracked.
If a player loses their item backpack (dropped it in lava, fell into the void, a griefer blew it up), the contents and UUID remain intact in the database. To find the UUID, search the server console logs for Created item backpack for that player, the UUID is logged at creation time. You can also query the item_backpacks table directly if you have SQLite access.
Once you have the UUID:
/dbp restore <uuid> <player>
This creates a new item with the same UUID and contents and places it in the player's inventory. The old orphaned database record is reused, not duplicated.
/bp view <player> <slot>
This opens the player's command backpack in a full editable GUI for the admin who ran the command. The target player will receive a notification message. Any changes the admin makes are saved when the admin closes the GUI, following the same save-on-close logic as regular backpack usage.
/dbp reload
A full reload does the following in sequence: it closes any currently open backpack inventories (triggering a save for each), then reloads config.yml and backpacks.yml, and finally unregisters all crafting recipes and re-registers them from the newly loaded configuration. Recipe changes take effect immediately in the server's recipe book. Mode changes (item, command, both, off) also take effect without a restart.
DynamicBackpacks uses several layers of protection to prevent item duplication.
Every item backpack has a UUID embedded in its PersistentDataContainer. This UUID is the primary key in the database and is present on every legitimate backpack item regardless of how it was obtained. Stack size is permanently forced to 1.
When a backpack is opened, the plugin registers the backpack's UUID and the opening player's UUID in a session map. Any attempt to open the same backpack while it is already registered in the session is denied. This prevents clients from opening the same inventory in two windows simultaneously.
While an admin is viewing a player's command backpack, the owner of that slot receives a notification and cannot open it themselves until the admin closes the GUI.
Any inventory interaction that would move a backpack item into an open backpack GUI is cancelled. This covers shift-clicking, dragging, and hotbar swapping, backpacks cannot be placed inside other backpacks.
Backpack items cannot be placed in the helmet armor slot. The plugin catches both direct armor slot clicks and shift-click auto-equip attempts that would land a backpack in the helmet position.
When the server shuts down, any backpacks still open have their contents saved before the inventory is closed. This means a sudden server restart does not risk losing unsaved changes.
All backpack data is stored in a SQLite database at plugins/DynamicBackpacks/backpacks.db. The database has two tables:
item_backpacks stores every physical backpack item. The primary key is the backpack's UUID. Contents are serialized using Bukkit's built-in ItemStack serialization, encoded as Base64. Timestamps for creation and last modification are recorded in epoch milliseconds.
command_backpacks stores command backpack slots keyed by player UUID and slot number. The structure mirrors item_backpacks but uses a composite primary key of (player_uuid, slot) instead of a single UUID.
The database file can be opened with any SQLite viewer (like DB Browser for SQLite) for manual inspection, backup, or migration. Deleting the database file will permanently erase all backpack contents, always back up the file before performing manual edits.
Why does the recipe preview in the crafting book show a Steve head instead of a backpack texture for the upgrade ingredient? This is a known limitation of the Spigot/Paper recipe API in 1.21. The recipe ingredient for the "previous tier backpack" is matched by material type (PLAYER_HEAD) rather than by skin texture, since matching on exact item data would require each player to have the specific exact backpack item referenced, which is impossible at recipe registration time. The crafting still works correctly, any item backpack of the correct tier will match in the center slot.
Can players put shulker boxes inside backpacks?
By default, no. You can allow it by setting inventory.allow-shulker-boxes: true in config.yml.
What happens if the server crashes while a backpack is open?
Any unsaved changes since the last close event will be lost. The onDisable save loop covers normal shutdowns and /stop. A hard crash (kill -9, power cut) may skip the save. For this reason, consider backing up backpacks.db regularly.
Can players wear backpacks as helmets? No. The plugin blocks both direct clicks into the helmet slot and shift-click auto-equip that would place a backpack in the helmet position.
How do I completely disable a tier without removing it from the config?
Set enabled: false on that tier in backpacks.yml and run /dbp reload. The tier will be removed from the recipe registry immediately and no new backpacks of that tier can be opened or given.
Where can I find a backpack's UUID for restoration purposes?
The UUID is logged to console at item creation time. You can also open the backpacks.db file with a SQLite viewer and query the item_backpacks table, filtering by owner_uuid to find a specific player's backpacks.
Does this work on BungeeCord or Velocity networks?
The plugin stores data in a local SQLite file per server. If players switch between servers in a network, their data will not follow them since each server has its own database. For cross-server support you would need to replace the SQLite backend with a shared database (MySQL/MariaDB), this is not currently built in but the DatabaseManager interface is designed to make that swap straightforward.