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, plus an optional bird transformation for exploring. 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.

Bird form

Every player can choose Bird form from the native G radial menu. Press Jump to take off, aim to steer, hold Sprint to fly faster, and descend or press Crouch to approach a landing. Flight always moves forward, builds momentum, slows during climbs and speeds up during dives, with a hard speed limit and a compact solid bird collider. Choose Return to Viking to change back.

The Flight energy bar above stamina holds 100 energy: 15 seconds of normal flight, or about 13 seconds while sprinting. It refills from empty in 60 seconds while human or grounded as a bird. Only flight drains it; sprint drains 15% faster. Empty energy automatically restores human form and normal gravity. Energy remains through toggles and character saves.

Other players see the bird with overhead player names and healthbars hidden. See docs/BIRD-FORM.md for full controls and behavior.

The energy bar shows only the remaining percentage and appears only in bird form when energy is below 100. It stays hidden in human form and at full charge while recharge continues normally.

Install

Version: 0.1.14 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.14 loaded; all 24 chest, UI and ownership patch targets verified.

Changes

0.1.14 — recover stalled distributor jobs

• Retry close-triggered requests for up to eight seconds while the native busy flag clears or server settings arrive, instead of silently discarding them after 0.3 seconds. Report unavailable access, queue saturation and requests that expire.
• Have prepared owners retry snapshots and report native revision mismatches. The server republishes the same committed snapshot at a strictly newer revision when a stale owner would otherwise reject it; it does not repeat the transfer or force a client-side inventory write.
• After eight seconds, isolate a committed pair that still awaits acknowledgement and recover it in the background. Unrelated distributors can continue; the two affected chests retain ownership, replication, opening and destruction guards. Recovery is bounded to eight pairs, one pair per tick.
• Clear completed queue/transaction state before notifications. Lost release messages can be retried through authenticated owner probes. Send normal native busy responses to remote open/stack/take-all requests instead of silently swallowing them.
• Prevent a failed inventory-change listener from withholding acknowledgement of contents already installed. Isolate and rate-limit per-chest synchronization errors so they do not starve other jobs.
• Log stalled transactions, owner connectivity, revision repair and recovery at Warning level. Unknown or externally changed contents remain protected; there is no unconditional timeout unlock.
• Includes the 0.1.13 Chest Rules tooltip fix. Live dedicated-server confirmation is still required.

0.1.13 — fix Chest Rules hover errors

• Give item names, acceptance checkboxes, delete buttons, the distributor toggle and the Chest rules opener Valheim's native text-tooltip prefab. Previously, newly created UITooltip components had no prefab, so mouse or controller hover could throw "The Object you want to instantiate is null."
• Use the inventory's crafting tooltip, with the take-all tooltip as a fallback. Disable hints if both native templates are unavailable; the menu and its controls remain usable.
• Extend the UI harness to check every tooltip, hover pooled rows before/after scrolling, exercise the native-template fallback and verify editing works with hints disabled. No global tooltip patches or error suppression are added.

0.1.12 — hide bird players on maps

• Hide transformed players from other players' live map and minimap icons, including their marker names and birds outside the loaded area. Existing markers disappear on the next native map update after receiving bird state.
• Restore normal map sharing when they return to human form. Preserve each player's visibility preference and their own navigation arrow.
• Filter the native map's temporary player list using the existing bird snapshot: no additional RPCs, scene scans or position tracking.

0.1.11 — immediate bird takeoff input

• Close the native radial instantly after an accepted bird activation and clear its native interaction cooldown. Other menu actions retain their normal timing.
• Read the bound keyboard Jump edge independently so Space pressed during the transition can take off on the next eligible physics step, even if vanilla consumed its edge. Retain chat/menu/inventory input-focus guards and flight-energy requirements.
• Require release of a held gamepad confirmation button before it can trigger takeoff, while accepting the next fresh Jump press without a timer.
• Inspect the shipped animation assets: chicken/hen has Walk/Run clips; crow/seagull has a flight clip plus a static perched model. No incompatible chicken clips or custom walking animation are added.

0.1.10 — smaller bird collision capsule

• Use a compact solid bird capsule, at most 0.44 m wide and 0.55 m tall, with its bottom aligned to the original player feet. The ordinary Rigidbody collision sweep uses the smaller capsule.
• Restore the exact original capsule on returning to human form. If there is insufficient room, return the owning player to a remembered human-clear position rather than expand inside a wall or low roof.
• Sample human clearance only on the owning client, at most twice per second while moving, using a reused non-allocating overlap buffer. No additional RPCs, ZDO flags or per-frame clearance scans.

0.1.9 — quieter flight meter

• Show flight energy only while transformed into a bird with less than 100 energy. Hide it immediately in human form and when fully recharged; energy tracking and recharge continue normally.
• Replace the Flight energy text label with just the remaining percentage over the fill.

0.1.8 — bird form for everyone

• Make the native G-menu bird transformation available to every connected player. Keep authenticated connection ownership checks for each player's transformation and share bird appearance with all clients.
• Add a flight-energy meter above stamina: 100 energy, 15 seconds of normal flight, 60 seconds to recharge from empty. Energy drains only during flight; sprinting drains 15% faster. Grounded birds and human players recharge.
• Automatically return to human form when flight energy runs out. Empty grounded birds can recharge before taking off. Retain energy across form toggles, death and character saves; stat tracking and the meter run entirely on the local client.
• Keep sprint, pitch-dependent speed, bounded momentum, collision-aware flight and hidden overhead player labels.

0.1.7 — private build

• Refine native input and movement tuning for the private functionality. Expand regression checks for gradual speed changes, collision limits and sustained movement.

0.1.6 — private build

• Private build for the existing modpack, with additional internal functionality and installed-game contract checks. Chest sorting retains the 0.1.5 behavior.

0.1.5 — discover modded shared storage

• Replace the three-prefab whitelist with a shared component-based eligibility check for public, permanent buildable storage using the standard Container inventory and its own network identity. Quartermaster's resource bins and racks can use the existing HearthSort UI, learning and routing without a Quartermaster dependency.
• Apply the same eligibility check to live chests and server-side prefab validation, including unloaded records. Preserve the explicit Personal Chest exclusion and reject private/group storage, wagons, ships, graves and temporary loot containers.
• Register after normal Container Awake postfixes so other mods can finish configuring storage first. Keep the existing chest-only spatial index and bounded nearby routing; no scene scan is added.
• Cover all 64 combinations of shared-storage eligibility with managed regression checks. Modded furniture still needs manual deposits to learn HearthSort rules; other mods' rules are not imported.

0.1.4 — faster wheel scrolling and shared storage only

• Double physical mousewheel scroll sensitivity from 180 to 360; scrollbar dragging and controller navigation keep their behavior.
• Exclude Personal Chests from the UI, learned rules and both sides of routing, even for their owner or when legacy Hearth Sort rules exist. The server rejects their prefab independently of loaded chest components.
• Restrict supported loaded chests and server access to public storage; preserve normal ward checks.

0.1.3 — allow complementary chest mods

• Remove the blanket Quartermaster incompatibility declaration. Users manage Quartermaster's deposit routing and automatic sorting themselves; Hearth Sort remains an independent sorter with no Quartermaster dependency or settings integration.
• Report locally prepared chests as busy through the standard Container.IsInUse query, so other inventory consumers that honor it yield during transfers. Refresh the chest before publishing that signal.
• Move Chest rules beside the chest header to leave the shared footer available to other inventory tools. F8 still opens the panel.

0.1.2 — native UI polish

• Give the title, chest mode and item list clearer spacing, subtle gold dividers and a warmer inset palette while keeping the native wood panel, fonts, controls and lighting material.
• Add a distributor description that updates with the toggle, larger item icons, alternating rows and quieter paused states.
• Space the acceptance and forget controls under distinct headers, add hover explanations and widen the scroll thumb.

0.1.1 — chest UI registration fix

• Correct Harmony class registration so chest-open UI, chest discovery and ownership guards actually attach.
• Verify every required hook at startup; fail with an explicit log error if registration is incomplete.
• Anchor the native Chest rules button below the chest panel so it never covers an inventory slot.
• Add a regression check for Harmony discovery of every method's declaring class.
• Check APIs against the newly installed Valheim 1.0.17 build as well as the original 1.0.16 target.
• Remove standalone Mono checks and block Mono launches in the check runner after native crash dialogs bypassed suppression.

0.1.0 — initial beta

• Distributor sorting on chest close; no idle base-wide sorting scans.
• Persistent learned acceptance rules with independent enabled/paused states and complete deletion.
• Native Valheim settings panel with item icons, wrapped names, adjacent checkbox/X controls and an inset virtualized scroll list.
• Server-coordinated transfers across different player owners; validated handoffs and synchronization before release.
• Exact serialized metadata preservation, bounded transfers, partial capacity and leftover feedback.
• Automated rule, quantity, metadata and ownership-protocol checks; installed-game API and codec checks.
• Contained Windows test processes with log output and crash-dialog suppression.

Live dedicated-server and in-game visual checks remain outstanding; this release is a beta.