ChestSorter

Tag your chests with categories ("Wood", "Ores & Metals", "Food: Meals (Health)"...). After that, one click empties a messy chest into the right chests around your base.

Client-side only. The server and other players don't need the mod.

Installation

With a mod manager (recommended): install ChestSorter with r2modman or the Thunderstore Mod Manager. BepInEx is installed automatically.

Manually: install BepInExPack for Valheim, then copy ChestSorter.dll into <Valheim folder>\BepInEx\plugins\.

Client-side only. The server and other players don't need the mod.

Quick start

1. Open a chest and click Categories. Pick what belongs in it, e.g. Wood. The chest now shows a glowing WOOD label on all four sides.
2. Tag your other storage chests the same way.
3. Dump your loot into any chest, then click Push (or press Shift+P). Each item goes to a nearby chest tagged for its category.
4. Click Sort (Shift+S) to tidy the open chest.

Buttons

When a container is open, a column of buttons appears to the right of the container panel:

Button	Hotkey	What it does
Push	Shift+P	Sends items that don't belong in this chest to chests that are tagged for them.
Sort	Shift+S	Merges stacks and lays the chest out alphabetically. For a chest group, it sorts the whole group.
Categories		Opens the category picker for this chest.
Only these items		Tags the chest with exactly the items that are in it right now.
Join below / Leave group		Joins this chest to the chest directly underneath it, or takes it out of its group.
Undo		Undoes the last Push.

Features

Categories

The Categories panel lists every category from the rules file. Click a row to turn it on or off. Selected categories are highlighted and saved immediately.

• The top of the panel shows what's in the chest right now, grouped by category.
• From contents tags the chest with the categories of the items that are currently in it.
• Clear removes all tags.

A chest can have any number of categories. Tags are stored on the chest itself in the world save, so they:

• survive restarts,
• are shared with every player who has the mod,
• keep working when the category rules change.

Parent categories: Some categories have a parent. For example, all Food: ... categories belong to Food (all kinds). A chest tagged Food accepts every kind of food, but Push fills chests with the exact category first and uses Food chests only as overflow.

"Only these items" chests

Put, for example, honey into a chest and click Only these items. That chest is now a honey chest: its label reads HONEY, and it replaces whatever categories the chest had before.

Item-specific chests take priority over category chests. If a general Food chest contains honey and a honey chest exists nearby, the next Push from the Food chest moves the honey to the honey chest. In the Categories panel, these tags appear as Item: <name>, and you can untick them like any other tag.

Push

The chest you open acts as the source. Only the source loses items. Every other chest only receives items.

For each kind of item in the source:

1. The item fits the source by its exact item tag: it stays.
2. The item fits the source by category: it stays, unless an "only these items" chest for that exact item is nearby. In that case it moves there.
3. The item doesn't fit the source: it moves to the best-matching chest nearby.

Destinations are chosen in this order:

1. Chests tagged with that exact item.
2. Chests tagged with the item's category.
3. Chests tagged with a parent category, such as Food.

At each of those levels, chests (or groups) that already contain the item come first, to top up existing stacks. After that, the nearest chest wins. Inside a group, chests fill from the bottom up.

A chest can receive items only if it is:

• within SearchRadius of you (150 m by default) and loaded,
• a stationary chest built by a player (not a cart, a ship, a gravestone or a dungeon chest),
• public (private chests are skipped, even your own),
• not currently open by another player.

Before anything moves, the mod checks that the destination has room. If an item doesn't fit anywhere, it stays in the source. No items are ever dropped or deleted.

After a Push, a message in the center of the screen tells you how many items moved. The top-left corner lists anything that stayed behind, and why ("no room in Wood chests", "no chest with a matching category for...").

An untagged chest keeps nothing, so a Push from it tries to move every item out. That's handy for emptying a drop-off chest next to your portal.

Sort

Sort does the following:

• Merges partial stacks into full stacks.
• Orders items alphabetically by their in-game name. Different quality levels of the same item are kept apart and ordered by level.
• Fills the chest from the top-left.

For a chest group, Sort treats the group as one big chest. It fills the bottom chest first, then moves up. Every item stays within the group, and merging stacks never needs more room than before.

If another player has any chest of the group open, Sort refuses to run.

Chest groups

For tall stacks of chests, open the upper chest and click Join below. It joins the chest directly underneath (up to 4 m below and no more than about 0.6 m to the side). Repeat this upward to build a column of any height.

• All members share the same categories. Changing categories on one member changes them for the whole group.
• When you join a chest to a group, the group keeps its categories. If the group had none yet, it takes the joining chest's categories.
• Push treats a group as a single destination and fills it from the bottom.
• Sort treats a group as one big chest.
• Leave group takes the chest out of its group. The chest keeps its categories.

Undo

Undo reverts the last Push. It puts back the number of each item that every involved chest had before the Push. It doesn't restore the exact slot positions.

If some of the items have been taken in the meantime, or a chest is no longer available, Undo restores what it can and tells you what it couldn't. Undo is cleared after you sort a chest group, because sorting moves items between the chests in the group.

Labels

Every tagged, stationary chest shows its categories in glowing orange capitals on all four sides. The labels use the game's Norse font, just like signs. Item tags are listed first, then categories in rules-file order.

Labels also update when another player changes a chest's tags. You can turn them off with ShowLabels.

Mismatch highlight

When you open a tagged chest, every item that Push would send away gets a yellow frame. In other words, it frames items that don't match the chest's tags, and items that have their own "only these items" chest nearby. Untagged chests are never framed. You can turn this off with HighlightMismatches.

Settings

File: BepInEx\config\local.chestsorter.cfg

Section	Setting	Default	Description
General	SearchRadius	150	How far from you (in meters) Push looks for destination chests.
General	PushHotkey	LeftShift + P	Same as clicking Push. Works only while a container is open.
General	SortHotkey	LeftShift + S	Same as clicking Sort. Works only while a container is open.
General	ShowLabels	true	Shows the glowing category labels on tagged chests.
General	HighlightMismatches	true	Shows the yellow frames around items that don't belong.
Debug	VerboseLog	false	Logs every changed item kind per chest, not just the summary.
Debug	LogSlowFramesMs	60	Logs frames slower than this (in ms), with what the mod did in them. 0 turns it off.

Category rules

File: BepInEx\config\ChestSorter.categories.txt

The mod creates this file on first launch, with rules that cover the whole vanilla item list. The file explains its own format. You can edit it while the game is running: the mod reloads it the next time you click Push.

The file has one rule per line, with fields separated by |. Anything after # is ignored.

Examples from the default file:

category | HidesAndFur | Hides & Fur                  # id | name shown in the game
override | Consumable | Honey | Produce               # one exact item
prefix   | Consumable | Mead | Potions                # internal name starts with "Mead"
contains | Material | Uncooked | CookingIngredients   # internal name contains "Uncooked"
suffix   | Material | Pelt | HidesAndFur              # last word of the name is "Pelt"
foodcolor | Health | MealsHealth                      # food by its icon color
itemtype | Consumable | Food                          # fallback by item type
parent   | Produce | Food                             # Food chests also accept Produce
alias    | Currency | Valuables                       # old id "Currency" now means "Valuables"

The scope field (Consumable, Material, ...) limits a rule to one item type. Use * for a rule that applies to every item type.

• Matching order: override, then prefix, endswith, contains, suffix, foodcolor, and finally itemtype. The first rule that matches decides the category. If nothing matches, materials fall into Misc, and other items use their item type name.
• Rule matching uses the internal prefab names (e.g. TrophyDeer, CopperOre), not the translated names you see in the game. As a result, the rules work in every game language.
• Category ids are stored on the chests. Never rename an id. To rename a category, change its display name, or add an alias line from the old id to the new one.
• Food colors match the colored icons in the game: Health (red), Stamina (yellow), Eitr (blue) and Balanced (white).
• Parse errors are written to ChestSorter.log.

When a mod update ships newer default rules, the mod replaces your file. It keeps your old copy as ChestSorter.categories.txt.v<N>.bak, so you can merge your changes back.

Multiplayer notes

• Tags and groups are saved on the chests in the world, so every player who has the mod sees them.
• Before the mod changes a chest, it takes network ownership of that chest, the same way the game does when you open a chest.
• The mod never touches chests that another player has open.
• Players without the mod see no labels or buttons. Their game isn't affected in any other way.

Safety

Every move checks for free space before it takes anything from the source. If a stack only partly fits, the remainder goes back where it came from.

After each Push, Sort and Undo, the mod counts every item in every chest involved and compares the counts with the totals from before. If the counts don't match, it writes a loud error to ChestSorter.log. If a Sort ever couldn't fit an item back in, the item goes to your inventory, or at worst is dropped at your feet. It is never lost.