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. Press Organize and the whole base tidies itself. Press Gather at a crafting station and the missing ingredients come to you.

Features

Sorter chests Toggle any chest into a dump chest with one button, or build the craftable Sorter Chest, which is one out of the box. 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 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, while you carry nothing. Homes persist: chests keep their assigned role between runs, so a tidy base stays tidy and a second press right after the first has little or nothing left to do. Weapons, armor and tools get homes of their own, and small odds and ends share a misc chest instead of each claiming their own.

Gather at the crafting station (new in 2.0) A Gather button under Craft pulls the selected recipe's missing ingredients from chests in range, scaled to your craft multiplier. Green (N) counts show what storage holds. Craft, then dump what's left into a Sorter chest and it flows back to where it belongs. Greyed out means there is nothing to fetch: you already carry what the recipe needs, or storage has none of what is missing.

Sign control, now with areas (area-off new in 2.0) A sign next to a chest labels it: sort: wood claims a group, sort: off opts the chest out entirely. New in 2.0: add a number on its own line and the off covers every chest within that radius. One sign protects a whole room.

Processor-aware routing (changed in 2.0) During Organize, a chest next to a smelter or blast furnace attracts ores and fuel, and one next to a fermenter attracts meads. Crafting stations (forge, workbench, cauldron and so on) no longer attract chests by default. With Gather you fetch what a recipe needs instead of storing materials beside the bench. Any station can be re-added in config.

Pin filters & Pull to restock Put sample items in a chest and press Pin. That chest now claims those item types even when empty. Pull fetches one stack of each saved item from surrounding storage.

Safe in multiplayer Every transfer (sorting, Pull, Gather and Organize) runs through MultiUserChest's networking, so only the actual owner of a chest modifies it, and the completion message counts only transfers the network confirmed. No duped stacks, no vanishing items.

Before your first Organize: protect curated chests

Organize thinks in item types. A hand-curated chest that mixes types, like a "meals for the trip" chest or an adventure kit, is a player concept it cannot see, and it will be reorganized like everything else. Before your first press, protect what you've curated:

Quick Start

1. Open a chest near your storage and click Sorter: OFF so it reads Sorter: ON, or build a Sorter Chest (Furniture tab, near the end).
2. Dump your inventory into it and close the chest. Items fly to whichever chests already hold those types.
3. Protect any curated chests (see above), then press Organize in the sorter chest. It previews ("move 340 items across 12 chests"), the button turns into Confirm?, and a second press runs it.
4. At a crafting station, select a recipe and press Gather to pull the missing ingredients from storage.
5. For a dedicated chest (carrots and onions near the cauldron): put samples in, press Pin. Press Pull any time to restock it from storage.

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? 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.

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. 2.0 and 1.1.x cannot mix; anyone mismatched gets a clear message at connect telling them what to fix. 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 in the chest UI:

And in the crafting panel:

Signs

Place a sign next to a chest (the sign binds to its nearest chest). Lines starting with sort: are read; everything else is your label text.

sort: wood, hides       <- this chest claims the wood and hides groups
sort: p2                <- priority 2 (higher wins ties)
sort: off               <- opt this chest out: never read, never filled
sort: off
10                      <- area mode: every chest within 10 m is opted out (max 32)

Group names and item names (wildcards allowed) both work as tokens. A number line only means something together with off.

How a target chest is picked

For each item, in order: a chest that pins the item wins first, then a chest whose sign or group covers it, then a chest next to a mapped processor, then (during Organize) an established home from a previous run, then any chest that already contains some. Ties go to higher sign priority, then for live sorting to the chest holding the most of that item, then to the nearest one; Organize breaks its ties by anchor strength and distance instead, so an organized base does not churn.

Organize: one-press base cleanup

Each item type gets exactly one winning home, chests are claimed by volume, and the assignment is remembered on the chests. The next Organize keeps established homes in place instead of reshuffling. A category can still move if it no longer fits its chest.

Default station map (editable in config under [Stations]), feed-in processors only since 2.0:

Good to know:

• A chest counts as "next to" a station within 8 m (StationRange). The nearest mapped station wins.
• Crafting stations (forge, workbench, cauldron and the rest) attract nothing by default since 2.0. To restore any of them: CustomStations = $piece_forge=metals,ores; $piece_cauldron=cooking,meat,seeds.
• Weapons, armor and tools are organized into their own homes since 2.0. Set [Organize] IncludeGear = false for the old leave-my-gear-alone behavior.
• Carts and ships are transport, not storage: everything ignores their inventories (VehiclesAreStorage to opt in). The Obliterator is never a target.
• Sorter chests are sources only. Organize empties them but never fills them.
• The completion message counts confirmed transfers only; anything that could not move says so ("N could not move") and is picked up by the next press.

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 for everything that changes the outcome (radius, groups, stations, Organize behavior). The keys marked client-side below only change speed or UI on your own screen, so each player controls their own.

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).

The [Stations] section maps processors to the groups they attract during Organize. For anything else, crafting stations you want back or modded stations, use CustomStations with the format token=group1,group2; token2=group3. The token is the station piece's name id: $piece_forge, $piece_workbench, $piece_cauldron and $piece_artisanstation are the common vanilla ones, and a modded station's token is in that mod's documentation or config.

Upgrading from 1.1.x: stored [Stations] lines for the removed crafting-station defaults become inert automatically, and the old [Organize] MovesPerTick key is ignored (replaced by MovesPerSecond). No manual migration needed.

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.
• Controller: ChestButler's buttons are reachable on gamepad since 2.0.

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 chest, and confirmed back. Since 2.0 the completion message counts only those confirmations. If a transfer cannot complete, the items stay where they were.

I pressed Organize and it rearranged a chest I had set up by hand. Working as designed, unfortunately. Organize can't tell a curated mixed chest from clutter, so protect it first (see Before your first Organize above). Established single-type chests are safe, since homes persist between runs.

Gather is greyed out. Greyed means there is nothing to fetch. Either you already carry everything the selected recipe needs at the current multiplier, or the chests in range hold none of what is missing. It re-arms by itself as crafting consumes your materials.

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. "Nothing to organize" means every item is already in its home. Organize never moves an item to a random chest.

Where is the Sorter Chest in the build menu? Hammer, Furniture tab, near the end. (It gets a proper spot next to the vanilla chests, and its own icon, in 2.1.)

Can I remove the mod (or roll back) mid-playthrough? Mostly yes: sorter flags, pins and homes are stored on the chests and are simply ignored without the mod. The one exception is the Sorter Chest piece. It is a custom prefab, and the game deletes placed ones (with contents) on load if the mod is missing. Empty them first.

My chest next to the smelter does not attract anything. The chest must be within 8 m of the station (StationRange). If the station is not one of the three mapped processors, it needs a CustomStations entry (see Configuration above). Windmills cannot be detected at all (the game gives them no station identity), so pin a chest for barley and flour instead.

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

2.0.0

The base-management release. Organize is now a whole-base allocator with persistent homes, a Gather button pulls recipe ingredients to you at the crafting station, a craftable Sorter Chest joins the build menu, and signs can protect whole areas. Server and all clients must update together. A 2.0 server refuses 1.1.x clients (and the other way around) with a clear message at connect.

Organize v2: whole-base, volume-aware

• Every item type is classified into a bucket (groups, pinned types, gear, misc) and buckets claim chest space by volume, anchored by pins, signs, adjacent processors, and the homes of previous runs. 1.1.x just sent things wherever most of them already sat.
• Homes persist on the chests themselves. A second press moves little or nothing, and established chests keep their role between runs. A category can still relocate when it no longer fits its chest.
• Weapons, armor and tools are organized into their own homes by default now. Set [Organize] IncludeGear = false to restore the 1.1.x leave-gear-alone behavior.
• Small leftovers fold into a shared misc home instead of claiming a whole chest per item type (MiscPromoteSlots).
• The completion message counts only transfers the network actually confirmed, never what was merely attempted.
• Dedicated-server correctness: chests that no peer owns are claimed before moving items out of them (those moves previously did nothing, silently, which is why Organize could take 3-4 presses), declined or failed transfers are retried or reported by name in the log, and a big base converges in two presses. Verified on a 5,838-item base: press 2 swept 15 items, press 3 found nothing to do.
• A chest another player is currently holding (by networked ownership) is skipped and retried instead of being taken over mid-browse. This closes the known issue from the 1.1.2 notes.

Gather (new)

• A Gather button under Craft pulls the selected recipe's missing ingredients from chests in range, scaled to the craft multiplier.
• Green (N) counts show what storage holds. Greyed out means there is nothing to fetch, because you already carry what the recipe needs or because storage has none of what is missing; it re-arms as crafting consumes materials.

Sorter Chest (new)

• A craftable chest that is a Sorter out of the box. It sits at the end of the Furniture tab for now (grouping and a distinct icon come in 2.1).
• Rollback caveat: it is a custom prefab, so removing the mod (or rolling back to 1.1.x) deletes placed Sorter Chests from the world. Toggled vanilla chests are unaffected.

Signs: area-off and priorities

• sort: <groups or item names> on a sign binds the nearest chest, pN sets its priority, and sort: off excludes it, same as before.
• New: add a number on its own line (or after off) and the off applies to every chest within that many meters of the sign, up to 32. One sign protects a whole room.
• sort: off chests are now also safe from other chests' Pull buttons. Previously a neighbour's Pull could drain a chest that was marked off.

Breaking / behavior changes

• Station adjacency is now feed-in processors only. Smelter, blast furnace and fermenter attract their materials; forge, workbench, cauldron and the other crafting stations no longer do. With Gather, materials no longer need to live beside the bench: you fetch exactly what a recipe needs and return leftovers via a Sorter chest. Any station can be re-added in config, for example CustomStations = $piece_forge=metals,ores. Upgrading servers lose crafting-station attraction automatically (the stored [Stations] lines for removed defaults become inert).
• Curated chests need protection before your first Organize. A hand-picked mixed chest (a meals chest, an adventure kit) is reorganized like everything else unless a sort: off sign protects it. See the README's "Before your first Organize" section.
• Carts and ships are transport, not storage. The sorter, Organize, Gather and Pull all ignore vehicle inventories (VehiclesAreStorage restores the old behavior). The Obliterator is no longer a valid target for anything.
• [Organize] MovesPerTick (per-frame) is replaced by MovesPerSecond (default 25) and MaxMovesPerRun (default 500). An old stored key is ignored.
• The speed and UI knobs are each player's own now: TransferInterval, StacksPerTick, MovesPerSecond, MaxMovesPerRun and the [Gather] toggles are no longer admin-locked or server-synced. They only change how fast or what you see, never the outcome. A server's stored values for them no longer apply to clients.
• Controller users: ChestButler's buttons are now reachable on gamepad.

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