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 is designed to be simple, modular, and straightforward. It stays focused on chest sorting, with a small native UI and a clear 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.

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

Install

Version: 0.1.5 beta. Built against Valheim 1.0.17.

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.

Other mods, including Quartermaster

Quartermaster may stay installed and enabled. Turn off its deposit/distributor routing and automatic chest sorting for chests managed by HearthSort, using Quartermaster's own controls.

HearthSort does not depend on Quartermaster, read or change its settings, or include its other features. Prepared chests report the standard busy signal so inventory consumers that honor it can yield during a transfer. Mods that directly mutate a busy inventory can still conflict. Combined Quartermaster multiplayer gameplay has not yet been verified.

Configuration

BepInEx/config/cheyenne.hearthsort.cfg

The server controls the range. Restart after changing it.

Beta status

The native UI has been confirmed in-game. Automated checks cover rule persistence, transfer conservation, metadata handling, ownership protocol transitions, and installed-game contracts. A live two-client dedicated-server session and the latest integration changes still need verification. Try the beta on a copy of your world before relying on it for shared storage.

Detailed validation and build notes are included in the ZIP's docs folder. To confirm startup, check BepInEx/LogOutput.log for:

Hearth Sort 0.1.5 loaded; all 24 chest, UI and ownership patch targets verified.