Grims Chests

Server setup and administration for GrimsChests 0.4.6, using the full 0.4.0 asset pack. For recipes and everyday controls, use the player wiki. The Void Chest and Jack-in-the-Box have their own new chests wiki. Return to the wiki home or project overview.

Contents

• Install or update
• Commands and permissions
• Staff-only moving
• Storage and sorting
• Glass Chest displays
• Configuration
• Filter categories
• Backups and recovery
• Troubleshooting
• Server validation

Install or update

Dependency plugins are not included in the GrimsChests bundle. For touch menus, install the full Client Checker plugin, not its API JAR.

1. Stop the server. Back up the complete GrimsChests data folder and matching world/player data.
2. Put GrimsChests-0.4.8.jar in plugins/, replacing the older GrimsChests JAR. Install the required dependency plugins there too.
3. Install the bundle’s grims_chests content folder in Packforge. Preserve other installed content.
4. Install the following files in the active Geyser instance. For proxy or standalone Geyser, use that instance's folders instead of the Paper server's plugins/Geyser-Spigot/.

| File | Geyser folder | | --- | --- | | GrimsChests-Tiered-Pirate-Chests-0.4.0-Bedrock.mcpack | packs/ | | grims_chests.json (every GrimsChests mapping) | custom_mappings/ |

1. Keep one combined chest Bedrock pack and one mapping file.
2. Delete the 0.3.0 chest .mcpack. The 0.4.0 pack has the same UUID, and Geyser keeps whichever it finds first.
3. Delete the old mapping files grims_chests_wooden.json, grims_chests_tiers.json, grims_chests_emerald.json, grims_chests_sorter.json and grims_chests_tools.json. grims_chests.json contains all of them, so keeping them would register duplicates. Enable Geyser custom content (gameplay.enable-custom-content: true in the supplied setup instructions). These assets require Geyser v2 custom-item mappings.
4. Start the server and run /pf zip to rebuild the Java resource pack. Have Java players accept it. Restart the active Geyser instance after updating its pack/mappings, then reconnect Bedrock players.
5. Check startup logs and test with /gch give <player> double. Issue a wrench, remote or core as needed using the commands below.

Install the full 0.4.0 asset pack, including its single mapping file. It contains every 0.3.0 asset unchanged: eight upgraded storage chest models, Auto Sort, the tools and the Sorting Core. It adds the Void Chest, the Jack-in-the-Box Chest and the Christmas Toy Chest. Vanilla chests keep their ordinary appearances and behavior.

The new chests need the 0.4.0 pack (Bedrock manifest 0.4.8). With only 0.3.0 installed, they show a missing model. Vouchers are plain glinting paper and need no pack changes.

Every chest plays the vanilla chest open and close sounds when a player's menu or sub-chest opens or closes it. The physical inventory keeps the real chest block's own sound, and redstone pops of the holiday chests are silent.

When updating, keep plugins/GrimsChests/chests.db and world/player data. Existing storage and older saved chests remain compatible; no database reset or chest reissue is required. Use a full server stop/start for JAR changes. /gch reload reloads settings, not plugin code or resource packs.

/pf browse creates an asset preview. It does not issue a functional GrimsChests chest, tool or Sorting Core. Use plugin crafting or the commands below.

Commands and permissions

/gch is an alias of /grimschests. These administrator commands require grimschests.admin and also work from console. Recipients must be online and have a free inventory/hotbar slot; issuance never drops overflow.

Accepted tiers are double, copper, iron, gold, emerald, diamond, netherite, glass, void and sorter. Skins are jack (or halloween) and christmas (or xmas). For loot crates, put vouchers in the crate rather than real holiday chests: every copy of one chest item would point at the same chest, while vouchers carry no identity and turn into a new chest each. In game, /gch info uses the chest you are looking at, or its item in your main hand. Console must provide the chest UUID.

Owners, trusted players and administrators may manage a chest. Look at it within six blocks and use /gch trust <online-player> or /gch untrust <online-player>. Trust covers configuration, links, movement and display controls. Ordinary opening uses grimschests.use and installed container/claim protections; ownership is not a private-storage lock. Administrator management access does not automatically bypass protection checks.

The wrench, remote and Sorting Core have no crafting recipes. Their supplied appearances do not grant authority to ordinary or renamed items. Genuine iron-hoe wrenches issued by earlier GrimsChests versions remain valid.

Staff-only moving

To reserve chest moving for staff:

1. Give wrenches only to staff.
2. Set grimschests.move to false for ordinary players in your permissions plugin, and allow it for the staff group. Staff also need grimschests.use.
3. Give staff management access through trust or grimschests.admin when they must move another player's chest. Confirm their claim permissions allow the move.

Holding an authentic wrench in either hand locks all GrimsChests within 15 blocks by default, including access by its holder. Open inventories close, and nearby hopper transfers, sorting and Glass previews pause. This holding lock still applies when the holder lacks movement permission, so keep the tools with staff. Put the wrench away when finished.

To move a chest, leave a free inventory slot, hold the wrench in the main hand, and left-click once. The plugin saves and verifies the portable chest, delivers its item into the player's inventory, and then removes the world chest. Physical contents drop at the old location; sub-chests, contents and settings remain with the carried chest. Placement restores an empty physical inventory. A moved/placed Glass display is off, with its source retained.

Carrying a loaded Iron, Gold, Emerald, Diamond, Netherite or Glass Chest reduces speed to 70% of normal by default. The penalty does not stack. Double, Copper, Auto Sort and empty chests are exempt. Carried chests cannot be stored inside other containers; see the player wiki for handling and recovery controls.

Storage and sorting

Each upgraded storage chest has a separate 27-slot physical inventory, plus 54 slots per sub-chest. Capacities are Double 1, Copper 2, Iron 3, Gold 4, Emerald 5, Diamond 6, Netherite 8 and Glass 9. Hoppers access only the physical inventory. Crouch-interact opens those physical slots; normal interaction opens storage or its selector. The physical slots are also the only part of a Grims Chest that holds shulker boxes — sub-chests never do.

The independent Auto Sort Chest has 27 physical slots and no sub-chests. Its shapeless recipe is one administrator-issued Sorting Core + one actual Crafter block + one ordinary vanilla Chest. Both the personal 2×2 grid and crafting table work. Craft the Crafter first; its raw ingredients are not a substitute. The older iron/hopper/redstone/comparator sorter recipe is removed. Craft through a normal click, one output at a time; shift-click collection and automated Crafter production are disabled.

Each upgraded storage chest has one shared auto-sort filter, covering all its unlocked sub-chests. In Chest settings → Auto-sort filter, choose categories, one exact-item sample, catch-all, or disabled input. Multiple selected categories compose one rule; those modes are otherwise exclusive. Sub-chest settings retain individual names and icons. A Glass Chest's filter covers 486 virtual slots; the separate physical 27 slots are never sorting destinations.

Look at the destination and use /gch filter <category[,category]|none|remaining|exact> to set the same rule directly. For example, /gch filter building,colored configures the entire chest. exact uses the held sample. The legacy /gch filter <sub> <rule> form accepts a valid sub-chest number but changes the whole chest and reports that scope explicitly.

Configure the destination's shared filter, then crouch-interact with the sorter to enter link mode. Select a destination and confirm the link. The player must be able to manage both chests. Links use a centered 64×64×64 area by default: ±32 blocks on each axis, in the same world. Destinations must be placed, loaded, accessible and within the configured range.

Sorting begins when the final viewer closes the sorter's physical input and that player has management access to the sorter and the destinations used. Hopper arrivals alone do not trigger sorting. Exact-item matches take priority, then categories, then an explicitly configured catch-all. Within each matching chest, items fill sub-chests in order from 1 through the unlocked capacity; a partial or full sub-chest passes the remaining quantity to the next, then to another matching linked chest if necessary. The sorter saves and confirms transfers before removing accepted quantities. Unmatched items and overflow stay in its input. New storage chests need a shared filter before they accept automatic transfers; later tier upgrades extend that filter to newly unlocked inventories.

Updating existing filters: saved format-1 and format-2 chests with one distinct configured filter adopt it for the whole chest. Identical filters on several sub-chests count as one; disabled sub-chests do not prevent promotion. A chest with conflicting configured filters pauses automatic input until a manager chooses and saves a shared rule, including an explicit disabled-input choice. Menus identify chests needing review. Contents, names and icons remain intact, and old per-sub-chest filter definitions are retained as migration history. Manual storage access remains available. Do not reset the database to resolve a filter-review notice.

Keep Paper's hopper.disable-move-event set to false in affected worlds so the plugin receives hopper transfer events.

Glass Chest displays

Install PacketEvents 2.14 and leave glass-display.enabled: true. Ordinary storage, hoppers, sorting and chest models work without PacketEvents.

An owner, trusted manager or administrator opens the Glass Chest selector and chooses Choose display source, then one of its nine sub-chests. In standard controls this is the third row, second column. Choosing a source preserves the current on/off state.

Issue /gch giveremote <player>. With the remote in the main hand, left-click or right-interact with the Glass Chest to toggle its display. The player needs grimschests.display, management access and normal chest access. Rapid duplicate clicks are ignored for five ticks. The remote does not move or open chests, or lock nearby storage.

The preview cycles through occupied source slots, skips blanks and shows one item at a time. It cannot be picked up or collected by hoppers, and never changes stored quantities. Moving or placing turns the display off while retaining its source; a normal restart can retain an enabled placed display.

Previews pause under a wrench lock. They are hidden for viewers using native pack fallback or Bedrock's physical/27-slot menu repair, and resume when eligible. Moving, unloading, leaving and shutdown clean them up. Use the settings below to tune preview height; see server validation for the reported test status.

To adjust the item's height and how often the displayed item changes, edit these settings, then run /gch reload:

glass-display:
  enabled: true
  height-offset: 0.10
  interval-seconds: 3.0
  view-distance: 32.0

height-offset is measured in blocks above the chest block's floor; lower values lower the preview. It defaults to 0.10 and accepts -1.0–2.0. interval-seconds is the time before changing to the next occupied source slot, not the client's bobbing/rotation speed. Its default is three seconds; for faster item changes, try 1.0. Reload applies the changed height and interval without reissuing the remote or replacing the chest. These controls were added in 0.3.1 and remain in 0.3.2; tune the visible position for your Java and Bedrock clients.

Configuration

Edit plugins/GrimsChests/config.yml, then use /gch reload. The table lists the shipped defaults.

Blank tool model settings give newly issued tools a plain-paper appearance; they remain functional. Changing a model never turns ordinary paper into a tool. The Sorting Core uses the supplied grims_chests:sorting_core appearance.

visuals.enabled: false selects native chest rendering while preserving storage identities. /gch reload does not rebuild or distribute resource packs, or load a new JAR.

Filter categories

The built-in category IDs are building, colored, natural, functional, redstone, tools, combat, food, ingredients and spawn_eggs.

Add a new category, or override a built-in ID, in config.yml:

categories:
  mining:
    name: Mining
    icon: DIAMOND_ORE
    materials: [COBBLESTONE, IRON_ORE, DIAMOND_ORE]

Use lowercase letters, digits, underscores or hyphens in the category ID, and valid vanilla material names for icons and materials. Run /gch reload after adding, editing or removing definitions. Reload rebuilds the category list from the built-in defaults and current configuration; a restart is unnecessary. Removing an override restores its built-in definition. A removed custom category stops matching, so update any filters that relied on it.

Categories appear in menus and command completion. Each storage chest can select several categories as its one shared rule, applied across every unlocked sub-chest. Custom items with model or plugin identity data do not match ordinary material categories; use exact-item filters for them. Category changes affect future sorting, not items already stored.

When something goes wrong

The plugin protects stored items first: if anything unexpected happens it locks rather than risk losing or duplicating them. It locks as little as it can — a problem with one chest holds that chest, and everything else keeps working. Only a storage-wide failure (the database unreachable, unreadable, or failing its integrity check) locks everything. Stored contents always stay in plugins/GrimsChests/chests.db.

Watch the console. How loud it is tells you how much is broken:

Releasing a held chest

1. /gch held lists each held chest, where it is now, and the command to use.
2. /gch resolve <chest-uuid> finishes it:
3. item: the chest becomes an item its owner can place again. If nobody holds one, a fresh item is issued to the owner (or to you if they're offline).
4. block: the chest goes back in the world where it was, and any item for it stops working.
5. With only one of the two present, the choice is made for you. If the chest exists as both an item and a block, the command refuses and asks you to pick: resolving it blindly is how a duplicate is made. Remove one, or choose explicitly with /gch resolve <chest-uuid> item or ... block.
6. Everything is logged, including who resolved it and which way.

Contents are never touched by any of this. A chest resolved either way keeps all of its stored items.

When a chest keeps locking: /gch reset

If a chest goes straight back to being held after every /gch resolve — its stored data cannot be read, or something about that identity is wrong — destroy it and issue a new one instead of fighting it:

/gch reset <chest-uuid>

It only ever works on an empty chest. Both the stored sub-chests and the physical 27 slots must be empty, and force does not waive that: a reset throws the old chest away, and there is nowhere for anything left inside it to go. Get the contents out with /gch resolve first. The one exception is a chest whose data cannot be read, where emptiness cannot be proved either way — that needs force, and the console records that it was forced.

What you get is a new chest: same tier, same skin, same owner, at the same block, starting at epoch 1. Sub-chest names, icons, filters, trusted players, links and the display setting all start fresh — that is the state you are reaching for this command to be rid of. Then:

• The old ID is retired: it is recorded in the database, never loaded again, and never handed to another chest.
• Its row is kept exactly as it was, so nothing is thrown away. If its data could not be read, those bytes stay

under the retired ID for later inspection.

• Any old chest item for the retired ID stops working.
• Sorters that pointed at the old ID have that dead link removed. The replacement is a new chest and nobody is

linked to it.

• If the chest has no block in the world, the replacement is issued as an item to its owner, or to you if they are

offline or full — whoever receives it can place it.

A chest that is working normally is not reset by accident: the command refuses unless you add force.

Shulker boxes and the holding area

Shulker boxes are kept in the physical inventory, never in sub-chests. The two are different kinds of storage and only one of them is the plugin's:

That split is the whole reason for the rule. A sub-chest is a single database record, so a box full of items there means thousands of nested items in one row. The physical inventory is an ordinary vanilla chest the server saves in world data exactly like any other — the plugin never writes it to chests.db — so a box there costs chest storage nothing. Tell players to crouch-interact and use those 27 slots.

Note that moving a chest drops its physical contents at the old location (see Moving a chest above); sub-chest contents travel with the chest item, physical contents do not. Worth mentioning if players start using the physical slots as a shulker locker.

Sub-chest storage refuses boxes and is not configurable. Arrivals are refused at the window and again where contents are written. A box that is already inside — from an older version, or from any route that ever got past the screen — comes out the next time that sub-chest is opened and closed. Nothing is swept: a chest nobody opens keeps its boxes, and nothing is taken out of a window a player is looking at.

An ejected box goes back to the player's own inventory. If it will not fit, it goes into the holding area — the held_items table in chests.db — and waits there across restarts until they run /gch shulkers. It is never dropped on the floor and never destroyed. /gch shulkers list shows who is owed one.

If the database itself refuses the hand-off, the boxes are written to plugins/GrimsChests/refused/ instead and the console says so; those have to be given back by hand.

Backups and recovery

Back up the whole plugins/GrimsChests/ folder and matching world/player data together while the server is stopped. Sub-chests and settings are in chests.db; physical chest inventories are in world data, and carried chest items are in player data. A live copy of only chests.db may miss pending writes. Restore these components from the same backup point.

For a player whose inventory was full during a saved return, have them free an inventory/hotbar slot and run /gch recover. It returns eligible saved chests without creating another copy of an already-held chest. It does not repair an ambiguous move or override a guarded chest.

If a move or storage operation reports an error:

1. Keep any remaining chest block and carried item. Stop retrying the operation.
2. Record the exact message, player, location and time. Use /gch info while targeting the chest, or /gch info <chest-uuid> using its ID from the logs.
3. Stop the server and preserve the full plugin folder, world/player data and relevant logs. Include any chests.db-wal, chests.db-shm, emergency/ and quarantine/ files that exist.
4. Arrange inspection or restore a matching backup. Do not delete the database, edit chest identity data or replace the affected block to force access.

Imported containers already holding a chest item may be archived under plugins/GrimsChests/quarantine/. These require administrator inspection; there is no automatic archive-restore command. Do not issue a new chest as a substitute for recovering the stored contents.

Troubleshooting

Server validation

The owner reports successful Java and Bedrock testing of 0.3.0. Version 0.3.2's shared-filter menus, overflow across all sub-chests, and legacy-filter review still need live checks. The configurable preview height introduced in 0.3.1 remains available.

The build report records completed automated checks. The owner's gameplay report does not establish that every forced-failure, crash/recovery or third-party compatibility scenario has been tested.

Use the acceptance checklist on your test server. Check Java, touch Bedrock and controller/keyboard Bedrock separately, including physical storage, remote clicks, pack fallback and movement. Include your actual claim, backpack and automation plugins; direct inventory writes by another plugin may bypass ordinary event guards. The current synchronous storage work has not been benchmarked for large sorting networks.

For model/masking details and known client limitations, see Visual integration. For player instructions, return to the player wiki or wiki home.

A failure that keeps happening reports once, in full. After that first banner, repeats of the same error on the same chest are counted and summarised in a single line at most once a minute, ending with Full stack trace: with the first report above — scroll up to that first report for the trace. A different error is never held back by this.