ChestButler

Sorts your storage for you. Mark a chest as a Sorter, dump everything into it, close the lid, and the items get moved to the right chests around your base. Or press Organize and tidy the whole base in one go.

Features

Sorter chests Toggle any chest into a dump chest with one button. Anything inside gets distributed to nearby chests the moment you close it. Items that no chest wants stay in the sorter, so nothing is ever lost or dropped.

Organize your whole base (new in 1.1.0) Sorter chests get an Organize button. One press scans every chest in range and previews what would move; press again and every item type consolidates into its best home, in place — you carry nothing. Perfect for adopting the mod on an established, messy base.

Station-aware routing (new in 1.1.0) During Organize, a chest sitting next to a crafting station attracts that station's materials: metals and ores pool by the forge, cooking ingredients by the cauldron, wood by the workbench, ore and coal by the smelter, meads by the fermenter. The map is editable in config, and modded stations can be added without a rebuild.

Works with zero setup Chests attract items they already hold, fullest chest first. Dump ore after a mining trip and it lands wherever your ore already lives.

Pin filters Put sample items in a chest and press Pin. That chest now claims those item types even when it is empty. An Auto/Manual toggle controls whether the sorter fills it automatically or leaves it alone.

Pull to restock Chests with filters get a Pull button that fetches one stack of each saved item from surrounding storage. Useful for a cooking chest next to the cauldron: press Pull, start cooking.

Safe in multiplayer Every transfer — sorting, Pull, and Organize — runs through MultiUserChest's networking, so only the actual owner of a chest modifies it. No duped stacks, no vanishing items, even with several people using the same storage room.

Quick Start

1. Open a chest near your storage area and click Sorter: OFF so it reads Sorter: ON.
2. Dump your whole inventory into it and close the chest.
3. Watch the items fly to whichever chests already hold that item type.
4. For a dedicated chest (for example carrots and onions near the cauldron): put samples in, press Pin, and from then on the sorter routes those items there. Press Pull any time to grab a stack of each back from storage.
5. Messy base already? Press Organize in the sorter chest. It previews how much would move ("move 340 items across 12 chests"), the button turns into Confirm?, and a second press runs it — every item type consolidates into its best chest, station materials pool next to their stations.

Installing

With a mod manager (recommended)

Install ChestButler with the Install button on this page or through r2modman / Thunderstore App. The dependencies (BepInEx, Jötunn, MultiUserChest) install automatically. Launch the game with Start modded.

With a profile code (server groups)

Playing on a server that runs ChestButler? The whole mod setup can be shared as one profile code. In r2modman or the Thunderstore App go to Import / Update, pick Import new profile, choose From code and paste the code your server admin gave you. That installs every mod the server runs, at the exact versions.

The code for the EK_Solutions server is:

019f56be-5a3d-1f95-1b1e-9c8aa52a8a6b

Manual

Extract ChestButler.dll into BepInEx/plugins/. You also need BepInExPack Valheim, Jötunn and MultiUserChest installed the same way.

BepInEx/
    plugins/
        ChestButler.dll
        Jotunn.dll
        MultiUserChest.dll

Multiplayer and dedicated servers

The mod must be installed on the server and on every client, at the same version. Anyone missing it or on a different version gets a clear message at connect telling them what to fix, so a half-modded lobby cannot corrupt anything. Crossplay must be disabled; modded servers are Steam only.

On a managed host (for example CubeCoders AMP): enable the BepInEx option in the instance configuration, then upload ChestButler.dll, Jotunn.dll and MultiUserChest.dll to BepInEx/plugins/ via the file manager.

Usage

Buttons appear at the bottom of the chest UI:

How a target chest is picked

For each item, in order: a chest that pins the item wins first, then a chest whose group covers it, then any chest that already contains some. Ties go to higher sign priority, then to the chest holding the most of that item, then to the nearest one. If the best chest only has room for part of a stack, it gets topped off and the rest re-routes to the next candidate.

Organize: one-press base cleanup

Organize uses the same ranking with one extra tier: after pins and groups, a chest sitting next to a crafting station claims that station's materials, and only then does the most-held rule apply. Each item type gets exactly one winning chest, so nothing ping-pongs.

Default station map (editable in config under [Stations]):

Good to know:

• A chest counts as "next to" a station within 8 m (StationRange setting). The nearest mapped station wins.
• Tools, armor and other non-stackables stay where they are unless a chest pins them — same rule as the sorter.
• The preview capacity check is exact at plan time; anything that can no longer move when you confirm (a chest filled up meanwhile, or another player is using it) simply stays put. Nothing is ever dropped or lost.
• Sorter chests are sources only — Organize empties them but never fills them.
• Kilns, eitr refineries and cooking stations are detected but unmapped by default; windmills cannot be detected at all (the game gives them no station identity) — pin a chest for those instead.
• Modded stations: press Organize once, copy the station token from BepInEx/LogOutput.log (chest near station '$piece_...'), and add it to the CustomStations setting.

Configuration

The config file is BepInEx/config/eksolutions.chestbutler.cfg, generated on first launch. On a server, the server's values are authoritative and sync to all clients.

The [ItemGroups] section defines the item groups: stone, wood, ores, metals, cooking, meat, seeds, trophies, valuables, meads, ammo, hides, fuel. Every group is a comma separated list of item name tokens (wildcards allowed), so you can edit them or add entries for modded items.

The [Stations] section maps station names to the groups they attract during Organize (for example $piece_forge = metals, ores). To cover a modded station, use the CustomStations entry with the format token=group1,group2; token2=group3 — the exact token is printed to BepInEx/LogOutput.log whenever a chest's nearest station has no mapping.

Compatibility

• Requires and works together with MultiUserChest, which also lets several players open the same chest at once.
• Quick Stack Store Sort Trash Restock works alongside it and covers player-inventory quick stacking.
• Mods that MultiUserChest lists as incompatible (QuickStore, QuickStack, SimpleSort) will not run with this stack either.
• Chest-size mods work fine. Item mods work in routing and can be added to the config groups by name.

FAQ

Can items get duplicated or lost? No. An item never exists in two places: each move is packed into a request, executed by the one client that owns the target chest, and confirmed back. If a transfer cannot complete, the items stay where they were. Anything the sorter cannot place simply waits in the sorter chest.

Does sorting happen while nobody is near the base? No. Valheim only simulates loaded areas, so sorting runs while someone is around, which in practice is exactly when you are dumping loot.

Do tools, armor and other non-stackable items get moved? Only if a chest explicitly claims them via Pin. The contains rule ignores non-stackables on purpose, so your spare gear does not wander around. Organize follows the same rule.

I pressed Organize and nothing moved. The first press is a preview — the button turns into Confirm? and a second press within 5 seconds runs it. If it says "Nothing to organize" instead, every item is already in its best spot, or the scattered items have no home yet: no chest pins them, no mapped station is near a chest, and no other chest already holds that type. Organize never moves an item to a random chest.

My chest next to the smelter (or forge) does not attract anything. The chest must be within 8 m of the station (StationRange). After pressing Organize, BepInEx/LogOutput.log shows one line per chest: the nearest station that matched, or the nearest unmapped one if none did. A "has NO [Stations] mapping" line means that station has no default mapping — a modded station, or a kiln / eitr refinery / cooking station: copy the token from that line into the CustomStations setting. A mapped station closer to the chest wins and can hide an unmapped station's token, so read the log from a chest that sits nearest to the unmapped one. Windmills cannot be detected (the game gives them no station identity); pin a chest for barley and flour instead.

Can I add or remove the mod mid-playthrough? Yes. Sorter flags and pinned filters are stored on the chests themselves and survive restarts; without the mod they are simply ignored.

My item will not route into a group chest. Group lists match item names. Some items have internal names that differ from the display name; pin a sample of the item once and the pinned name shown in the message is the exact token to use in the config groups.

Links

• GitHub repository (source, issues, feature requests)
• Report a bug
• Changelog: see the Changelog tab on this page

Credits

Item transfer networking is built on MultiUserChest by MSchmoecker.

Changelog

1.1.2

Maintenance release: correctness and performance fixes found by a full source audit. No new features, no config migration needed. Cross-compatible with 1.1.x, so it deploys as a normal patch.

Fixes that can affect your items

• Organize could run twice at once (pressing it on a second sorter while the first run was still going). The two runs could not see each other's in-flight moves and could both issue a transfer for the same stack. Only one Organize run at a time now.
• Organize could over-fill a destination chest: it re-checked free space per move but never counted what it had already promised that chest in the same run, and in-flight transfers are not reflected locally. It now tracks its own promises.
• Organize never checked that a source chest still existed. A chest destroyed or unloaded mid-run left a window where a transfer was issued against a dying chest. Both endpoints are validated now.
• Organize now reports what it could NOT move ("N could not move") instead of silently dropping those moves and reporting success.

Performance

• A sorter chest holding items with no home did a full base-wide scan for every one of them, every tick, forever — the most expensive path in the mod on a large base. Unroutable item types are now remembered for 10 s before being retried.
• The sorter tick no longer runs at all on a dedicated server, where it could never do anything (routing needs a local player for the access and ward checks) but still paid for the scan.
• Filter/sign lookups were cached for only 3 seconds and re-resolved by scanning every sign and every chest. The cache is now invalidated on the events that actually change it (editing a sign, changing pins, unloading a chest) and lives longer.
• Item-name matching is ordinal instead of culture-sensitive, wildcard tokens are parsed once instead of per comparison, and normalized names are memoized.
• Organize's per-frame move budget is now also capped in real time, so a high-refresh-rate client no longer sends proportionally more traffic to the server than a 60 fps one.
• Station tracking no longer rescans everything on each registration, and the per-chest station log moved to Debug (it was one synchronous log write per chest per Organize); the "unmapped station" hint is now logged once per station type instead of once per chest.
• The chest spec cache is dropped when a chest unloads, instead of accumulating an entry per chest per zone reload for the whole session.

Consistency

• Chests at exactly the same distance are now ranked by a stable id, so a symmetric storage hall routes the same way every session. Same for a chest sitting equidistant between two crafting stations.
• Group precedence is now explicit and documented in code. Some items match two groups in the default config (FlametalOre matches both ores and metals), which was previously resolved by dictionary order.
• A [Stations] mapping that points at a group name which does not exist in [ItemGroups] (a typo, or a renamed group) now logs a warning instead of silently attracting nothing.
• TransferInterval's minimum is now 1 s (was 0.2 s). The default was already 1 s; only settings that were never safe on a large base are removed.

Known, not fixed here — see docs/known-issues-1.1.x.md: a chest opened by another player is invisible to us (m_inUse is a local field), so Organize can still take ownership from someone browsing a chest; and the sorter radius default of 128 m may exceed the distance at which chests are actually loaded. Both need changes that are out of scope for a patch.

1.1.1

• Dependency pin updated to Jotunn 2.29.2 to match the server (no gameplay changes)
• Default sorter/Organize radius raised to 128 m (max raised to 128). Existing config files keep their saved Radius; on a server the admin value is authoritative and syncs to clients, so set the server's Radius to 128 to apply it for everyone

1.1.0

• New Organize button on Sorter chests: one press sweeps every accessible chest within the sorter radius (32 m by default) and consolidates each item type into its best home, in place — you carry nothing
• Previews first ("Organize: move N items across M chests — press again to confirm") and only runs on a second press within 5 seconds; closing the chest, opening another, or the timeout cancels it
• Routing priority per item type: a chest that pins/filters it, then a chest whose adjacent crafting station attracts its group (forge → metals/ores, workbench → wood/hides, stonecutter → stone, cauldron → cooking/meat/seeds, black forge → metals/valuables, galdr table → valuables/meads), then the chest already holding the most of it; otherwise it stays put
• Tools and armor (non-stackables) stay where they are unless a chest explicitly pins them
• Station adjacency also covers processing pieces: smelters and blast furnaces attract ores + fuel (new fuel item group with coal), fermenters attract meads; kilns, eitr refineries and cooking stations are detected too (add mappings in config if wanted)
• New server-synced [Stations] config section maps station names to item groups (editable; add modded stations via the CustomStations entry — the log prints every detected station token); new [Organize] MovesPerTick and StationRange settings
• CAVEAT: windmills are not detectable (no station identity in game code) — pin a chest for barley/flour instead
• Default sorter/Organize radius raised from 20 m to 32 m (existing config files keep their saved value — edit Radius in the cfg to adopt the new default)
• Fixed the ores group never matching metal scraps (the in-game tokens are singular: ironscrap, bronzescrap, copperscrap) and wrongly claiming leather scraps via the old *scraps wildcard — existing config files keep their saved pattern; delete the ores line under [ItemGroups] (or paste the new default) to adopt the fix
• This is a minor release: server and all clients must update together (a 1.1.0 client is refused by a 1.0.x server, and vice-versa)

1.0.2

• Rewrote the Thunderstore page: quick start, clearer install/multiplayer instructions, config table, compatibility notes, FAQ
• Chest UI buttons now match the vanilla Take all / Place stacks style and anchor to the panel's bottom-left corner
• Docs no longer mention sign labels (that path stays in the code but is undocumented for now)

1.0.1

• Mod ID changed to eksolutions.chestbutler (config file is now BepInEx/config/eksolutions.chestbutler.cfg; settings reset to defaults once)
• Server and all players must update together, older versions are refused at connect

1.0.0

• First public release
• Sorter chest toggle with tiered routing: pinned filters, then groups, then chests that already hold the item
• Consolidation (fullest chest wins ties) and partial fills
• Pin / Auto / Manual / Clear / Pull buttons in the chest UI
• Sign labels (sort: ...) with groups, wildcards, priority and off
• Server-synced config including editable item groups
• Same-version check for server and clients at connect