Grims Backpacks

This guide covers Grims Backpacks 0.1.3 for Paper 26.3. Version 0.1.1 added two scary Halloween styles (Soul Coffin and Cursed Spellbook) and backpack vouchers for crates and vote rewards; 0.1.2 and 0.1.3 fix their Bedrock presentation (Soul Coffin lid direction; both styles now sit at the Java height). Complete the included test checklist before player release.

Requirements

• Paper 26.3
• Java 25
• GrimsClientChecker 0.3.0
• Floodgate
• Geyser-Spigot for Bedrock players

Install the normal GrimsClientChecker-0.3.0.jar. Its -api and -sources JARs are development files and do not belong on the server.

Installation

1. Stop the server.
2. Put GrimsBackpacks-0.1.3.jar, GrimsClientChecker-0.3.0.jar, and Floodgate in plugins. Remove any older GrimsBackpacks-*.jar.
3. Install GrimsBackpacks-Java-0.1.3.zip as the Java server resource pack. If pack merges Java resources, regenerate and publish the merged pack instead.
4. Put GrimsBackpacks-Bedrock-0.1.3.mcpack in plugins/Geyser-Spigot/packs and delete the older GrimsBackpacks-Bedrock-*.mcpack. Both share one pack UUID, and Geyser loads only the first file it finds.
5. Extract grimsbp_items.json from GrimsBackpacks-Geyser-Mappings-0.1.3.zip into plugins/Geyser-Spigot/custom_mappings, replacing the old grimsbp_items.json. It is still the plugin's only mapping file.
6. Set gameplay.enable-custom-content: true in Geyser's config.yml.
7. Restart the server. Fully disconnect and reconnect both Java and Bedrock test clients.
8. Confirm the Grims Backpacks startup banner appears without dependency, SQLite, pack, or mapping errors.

Geyser accepts multiple separately named files in custom_mappings; this plugin's file does not replace other mappings. See Geyser's custom-item and resource-pack documentation for the current directory rules.

The plugin creates its own local files:

plugins/GrimsBackpacks/config.yml
plugins/GrimsBackpacks/backpacks.db

No MySQL server or account is required.

Commands and permissions

/backpack may be shortened to /bp.

Permission defaults:

The command target must be online. When an in-game administrator omits the target of give or giveupgrade, the command applies to the sender.

Examples:

/bp give Steve basic
/bp give Steve halloween
/bp give Steve christmas
/bp give Steve coffin
/bp give Steve spellbook
/bp givevoucher Steve coffin 3
/bp giveupgrade Steve 6

The Halloween, Christmas, Soul Coffin (coffin), and Cursed Spellbook (spellbook) backpacks are command-only. They have no crafting or creative-menu entry. The classic fox-and-lantern Halloween backpack stays as the neutral option; Soul Coffin and Cursed Spellbook are the scary ones.

Vouchers for crates and vote rewards

Don't put a real backpack in a crate or vote reward. Crate plugins copy the item they hand out, and every copy of a backpack points at the same stored inventory. Use a voucher instead.

• /bp givevoucher <player> <style> [1-36] gives vouchers for any style: basic, halloween, christmas, coffin, or spellbook. The player must be online.
• A voucher is glinting paper named "Voucher: <style> Backpack". It carries no backpack ID, so a crate can copy it freely.
• Players redeem it by right-clicking in the air or on a block. The voucher turns into a brand-new tier-0 backpack of that style in the same slot, with its own ID and empty storage, so a full inventory never matters. The click never uses the block.
• Vouchers don't stack: each one takes its own slot. givevoucher is all or nothing. If the player lacks enough free slots, nothing is given or dropped.
• Vouchers can't be used in any recipe, crafter, anvil, or other workstation.
• Redeeming needs grimsbackpacks.redeem, which everyone has by default. Remove it to stop a group from redeeming.

To add a voucher to a crate, give yourself one (/bp givevoucher <you> coffin) and add that item to the crate the way your crate plugin normally takes items. Every copy it hands out redeems into a separate backpack.

Recipes

The Basic Leather Backpack uses grimsbackpacks:basic_backpack:

String       Leather   String
Leather      Leather   Leather
Iron Nugget  Leather   Iron Nugget

Every material upgrade uses the previous backpack in the center:

String    Leather   String
Leather   Backpack Leather
Material            Material

The armor recipe grimsbackpacks:backpack_absorb_chestplate is shapeless: one standalone backpack plus one supported chestplate.

The recipe book advertises grimsbackpacks:basic_backpack only. The six material upgrades, both admin-paper bypasses, and the armor recipe are undiscovered when a player joins and their discovery is cancelled, so a player searching "backpack" gets one entry instead of ten. Every hidden recipe stays registered and crafts normally from a hand-laid grid, including for operators - the admin papers are no longer advertised to ordinary players either.

Minecraft's recipe system can only advertise a vanilla Bundle for recipes requiring an existing backpack. The recipe book may therefore show an ordinary Bundle, but server validation accepts only one genuine standalone Grims Backpack. Shift-click crafting and vanilla Crafters are blocked so each crafted item receives one valid storage identity.

Admin upgrade paper

The marked paper from /bp giveupgrade is an uncraftable material bypass:

• One paper upgrades tiers 0 through 4 by one tier.
• Two marked papers in separate crafting slots upgrade Diamond to Netherite.
• Ordinary paper does nothing.
• Papers from the archived 0.0.1 format are unsupported; issue current items.

Interaction and crossplay routing

• Dragging a backpack into the chest armor slot equips it.
• Main-hand sneak-use-air or double-crouch equips or swaps a backpack.
• Sneak-use-air, double-crouch, or /bp opens a worn backpack.
• A placeable main-hand block takes priority over sneak-use opening. Double-crouch still works.
• A main-hand fishing rod receives the complete sneak-use gesture; double-crouch and /bp remain available.
• /bp settings doublecrouch on|off is stored per player in backpacks.db and defaults on.
• /bp dt toggles that same setting. Java, Bedrock, and touch players keep their own manual choice across reconnects and restarts.

GrimsClientChecker selects the compartment interface:

Use /gcc check when verifying a player's detected platform and input mode.

Capacity and progression

Menu-tier compartments reserve their final GUI slot for Back to Compartments. Existing data in a newly reserved slot is moved to the next free storage slot; if completely full, it remains persisted until space is available.

A tier-6 backpack plus Netherite helmet, leggings, and boots blocks fire-tagged damage. The bonus follows tier, so upgraded Halloween, Christmas, Soul Coffin, and Cursed Spellbook backpacks also qualify.

Absorbed armor

Every standalone tier and seasonal style accepts Leather, Copper, Chainmail, Iron, Golden, Diamond, or Netherite Chestplates.

• The result stays a UUID-backed Bundle-form backpack and retains its tier, style, contents, and visual.
• Exact snapshots preserve both source items for safe detachment.
• Armor attributes, durability, enchantments, unbreakable state, repair data, and supported gameplay components are copied to the worn backpack.
• Condensed lore identifies the armor and lists localized enchantment names.
• /bp detach validates both snapshots, restores the original backpack, and equips the chestplate with its current wear and gameplay data.
• Armor-infused backpacks cannot be upgraded, reinfused, or used in workstations. Detach first.
• When the armor breaks, the same backpack UUID is recovered; the broken chestplate is not returned.
• Curse of Binding blocks plugin-driven detach and replacement outside Creative mode.
• With keep-inventory off, Curse of Vanishing destroys the chestplate and drops exactly one clean backpack. With keep-inventory on, the combined item remains.

The physical item remains a Bundle, so plugins that require a chestplate Material, ArmorMeta, or proprietary marker may not recognize it as armor. Test every combat, equipment, gravestone, soulbinding, and set-bonus plugin used by the server.

Legacy migration

The short-lived 0.0.3 Iron Chestplate carrier converts to the Bundle-first format when it reaches an online player's inventory, offhand, or chest slot. Its backpack UUID, contents, and current Iron Chestplate metadata are retained. Items in chests or barrels convert after retrieval.

Startup removes obsolete entities marked grimsbackpacks:bedrock_armor_carrier; version 0.1.0 creates no replacement armor stand.

Storage and database policy

Backpacks are accepted by player inventories, chests, trapped chests, double chests, and barrels. They are rejected by shulker boxes, ender chests, hoppers, bundles, other backpacks, and other container blocks. They cannot be placed.

Each backpack's UUID points to its row in plugins/GrimsBackpacks/backpacks.db.

• Back up the complete plugins/GrimsBackpacks directory.
• Stop the server before taking the cleanest database backup.
• Never delete backpacks.db while physical backpacks still exist.
• Do not manually edit item metadata or database rows.
• Preserve both the database and physical backpack items during restoration.

The plugin saves open storage periodically, when menus close, when players disconnect, and during an orderly shutdown.

Configuration

autosave-seconds: 30

wearables:
  java:
    enabled: true
    fit-version: 3
    back-offset: 0.18
    height-factor: 0.64
    scale: 0.50

• autosave-seconds controls periodic copies of open contents to SQLite.
• wearables.java.enabled controls the Java ItemDisplay wearable.
• back-offset, height-factor, and scale tune Java positioning and size.
• fit-version is an internal migration marker and should remain unchanged.

Java display scale and back offset follow the player's live minecraft:scale attribute. Bedrock uses the attachable supplied by its pack. /bp reload rereads the file, but restart before judging autosave timing or wearable-position changes.

Resource-pack facts

• Java and Bedrock resources affect only plugin-marked backpacks; ordinary bundles are unchanged.
• The Bedrock manifest uses internal revision 0.1.11, minimum engine 1.21.130, and capabilities: ["pbr"] for Vibrant Visuals. The revision rises with each pack release (0.0.8 in 0.1.1, 0.0.9 in 0.1.2, 0.0.10 in 0.1.3 through 0.1.9, then matched to the plugin version from 0.1.10) so Bedrock clients download the new pack instead of using a cached copy.
• Pack UUIDs are unchanged from the prior prototype.
• The Geyser file contains 264 unique definitions: 33 unarmored and 231 armor-specific (11 visual families).
• The Bedrock pack contains 88 worn attachables: 11 standalone and 77 armor-specific.
• The Soul Coffin's soul-fire crack, lantern and crow eyes, and the Cursed Spellbook's eye, runes and candle flames glow in the dark on Java (light_emission). The spellbook's eye watches, looks left and right, and blinks on Java through texture animation. Bedrock shows both styles without glow, and the spellbook's eye stays open (a static first frame, like the Christmas backpack).
• Vouchers are plain paper with no pack assets.
• Do not add these items to Geyser creative categories; recipes and commands must create the UUID-backed item.

After changing the Java pack, update its configured SHA-1 and regenerate any pack merge. After changing the Bedrock pack or mappings, replace both files, restart Geyser, and fully reconnect test clients.

Validation before release

The packaged build completed 168 automated checks with zero failures or errors and one MockBukkit-only skip. Automated checks do not prove live Paper combat, Java rendering, Bedrock rendering, Geyser translation, touch/controller input, or third-party plugin compatibility.

Complete TESTING.md before player release. At minimum, verify:

• Unique inventories, upgrades, compartment navigation, restart persistence, and backup restoration
• Every allowed and forbidden storage transfer method
• Java and Bedrock wearing, opening, swapping, and armor detachment
• All seven chestplate materials, enchantments, Thorns, durability, breaking, Binding, and Vanishing
• Java/Bedrock self-view and mixed-client rendering at normal and altered player scales
• Bedrock touch forms plus controller and keyboard/mouse inventory menus
• Netherite fire protection and both seasonal styles
• Compatibility with combat, armor, death-inventory, gravestone, and soulbinding plugins

Troubleshooting

Plugin does not enable

Confirm the normal GrimsClientChecker JAR and Floodgate are installed. Review startup for missing dependency, service, or SQLite messages.

Java model is missing or outdated

Confirm the client accepted the current Java pack. Change the configured resource-pack SHA-1 and rebuild any combined pack before reconnecting.

Bedrock model or wearable is wrong

Confirm the current .mcpack and grimsbp_items.json are installed, enable-custom-content is true, and the client fully disconnected before retesting.

Touch player receives the inventory menu

Run /gcc check. Only Bedrock players currently reporting touch input receive the form.

Backpack does not open

Confirm it is in the chest slot. Test /bp, then double-crouch. Placeable blocks and fishing rods intentionally reserve sneak-use for their normal action.

Infused armor differs from the source chestplate

Retest on a clean Paper server. If it works there, inspect plugins that require a chestplate material or manage combat, equipment, enchantments, sets, or death inventories.

Legacy item does not migrate

Move the 0.0.3 carrier into an online player's inventory, offhand, or chest slot and wait one tick. Preserve the item and review logs if it remains unchanged.

Data does not survive restart

Check shutdown logs for SQLite errors and verify write access to plugins/GrimsBackpacks. Restore only from a backup made with the server stopped.