HearthSort

HearthSort

Simple chest sorting for shared storage.

Teach your storage chests what belongs in them, drop your loot into a distributor chest, and close it. HearthSort moves matching items into nearby storage.

HearthSort provides a small native chest UI and a clear sorting workflow. Keep using your preferred mods for crafting, building, and the rest of your base.

How it works

1. Teach a storage chest. Put an example item into an ordinary chest. That chest remembers the item type, even after you empty it.
2. Choose your drop-off chest. Open a supported chest, click Chest rules beside its header, and enable Use as distributor. F8 also opens the settings while the chest is open.
3. Drop off your loot and close the chest. Matching items move to the closest eligible nearby storage. Items without a destination, or without available space, stay in the distributor.

To teach already-filled storage, take an example stack out and put it back. Native manual quick-stack also teaches receiving chests. Other mods' acceptance lists are not imported.

A small, readable rules list

The inset list uses Valheim's native fonts, controls, panel material, and real item icons. Scroll with your mousewheel or the scrollbar; controller navigation is also supported.

• Checkbox: enable or pause acceptance. A paused entry stays saved, and depositing another example does not turn it back on.
• X: forget the item and remove its row completely. Items already stored in the chest stay there. A new manual deposit can teach it again.
• Esc / controller Back: close the panel.

Shared chests only

HearthSort supports public wooden, reinforced, and black metal chests, plus modded storage furniture built with Valheim's standard networked Container and Piece components. This includes Quartermaster's resource bins and racks; no Quartermaster dependency or per-mod chest list is needed. Newly supported furniture learns HearthSort rules from manual deposits, just like ordinary chests. Existing rules from other mods are not imported.

Personal Chests are excluded for everyone, including their owners. They cannot distribute or receive items, learn HearthSort rules, or show its settings. Rules saved by an older version are ignored.

Normal ward access still applies. Wagons, graves, ship holds, private or group-restricted storage, and temporary loot containers are excluded. Supported furniture must have its own network identity and ordinary serialized inventory. Mods using a separate inventory system, custom access rules or additional item restrictions may require explicit integration; component-based discovery does not reproduce those rules.

Focused sorting

Sorting is requested when you close a distributor. Supported chests register as they load, and nearby destinations are found through a chest-only spatial index. There is no recurring scene-wide entity search or idle base inventory scan. Ward permission checks also inspect nearby world records; ward sizes are cached from prefab definitions.

Transfers use bounded batches. Full, busy, or unavailable chests leave leftovers in the distributor; closing it again requests another attempt. The server coordinates ownership and synchronization, and serialized item metadata is preserved during movement. Items with different metadata stay separate.

Close requests briefly retry while the native chest-busy flag clears. If a committed batch takes more than eight seconds to synchronize, its two chests remain protected and retry in the background while unrelated distributors can continue. The server can republish the committed contents above a stale owner's revision without repeating the item movement. Up to eight pairs can recover at once; additional sorting waits when that limit is reached. A pair still cannot unlock until its connected owners synchronize, or disconnect. Unresponsive owners and unexpected inventory changes are logged rather than resolved by discarding a lock or overwriting uncertain contents.

This design aims to keep sorting work focused. Live performance gains have not been benchmarked.

Install

Version: 0.1.17 beta. Built against Valheim 1.0.20.

Supports current format 110 inventories and existing format 109 chests. Sorting writes the current format while preserving item metadata, including the game's updated interpretation of legacy item flags. Unknown future formats are refused with contents retained.

Stack-size mods are supported through the prepared chest owner's current item limits, including Quartermaster's 5,000-item stacks. Existing stacks and new slots use the destination limit. Configure your stack-size mod consistently on the server and clients; HearthSort does not change its settings. Queries cover only the incoming item types during a sorting transaction, with no idle item-database or scene scan.

Install with Thunderstore Mod Manager or r2modman. The package declares these required dependencies:

• BepInExPack Valheim 5.4.2351
• Jotunn 2.30.2

Install the same HearthSort version on the server and every client. Jotunn enforces matching patch versions. Use matching item mods too; unknown items stop a transfer with contents retained.

For manual installation, close the game and copy the ZIP's BepInEx folder into your game or selected profile folder. The DLL should land at BepInEx/plugins/HearthSort/HearthSort.dll. For a dedicated server, use its folder containing BepInEx.

When switching from a local/manual build to a mod-manager package, remove the old HearthSort DLL first so only one copy is installed. Removing the DLL leaves ordinary chests and their contents usable; unused HearthSort rule data remains in the world.

Moving from the combined mod