Storage Groups

Work in progress. Use at your own risk. This mod is not fully tested yet, especially in multiplayer and with wards. Back up your world before using it.

A Valheim mod. Put your chests in groups, and items move to the right chest by themselves.

Licensed under Apache 2.0. See LICENSE and NOTICE for terms and project credit.

How it works

Open any chest. The Storage Groups controls sit next to the chest window, and they change with the chest.

A chest without a group

• Group: (none): click to open the group menu and pick a group for this chest. Hover to see the group chests nearby (closest first, marked if full or behind a ward edge) and which groups are Strict.
• New Group From Contents: makes a group from what's in the chest. The name is filled in for you from the item there is most of (for example "Wood"); press Enter, or type your own. The chest joins the new group and all its item types are added. If an item belonged to another group, it moves to this one and the game tells you.
• Pause sorting: while ticked, nothing moves in or out of this chest. Handy when you want to collect items first, for example ones that already belong to another group, before making a group from them. Turns off when you close the chest.

A chest with a group

• Group: Stone: hover to see the group's items and the group chests nearby; click to open the group menu.
• Add Contents: adds this chest's item types to its group. The group keeps the items it already had. If an item belonged to another group, it moves to this one and the game tells you.
• Edit Items...: the group's item list. Remove single items, or use Clear all (click it twice) to start over.
• Pause sorting: same as above.
• Priority: this chest fills first. The group's other chests nearby also move their items into it whenever it has room (for example right after you take something out), so your stock gathers in one place. Tick it on the chest you use most. With several Priority chests in a group, items already in one of them stay there.

A Locked chest

Put a chest in the built-in Locked group to keep it to yourself: nothing moves into or out of it automatically. You can still put items in and take them out by hand. Good for personal gear, boss loadouts, or materials saved for a build. A Locked chest only shows the Group button (blue, with a padlock); pick another group to unlock it.

The group menu

• Locked is always at the top. It's built in: it can't be renamed, deleted or given items. If your world already had a group called "Locked", it's now called "Locked (old)", with its chests and items unchanged.

• Every group, with how many item types it has. The one with the border is this chest's group; click it again to take the chest out of the group. + at the bottom of the list makes a new, empty group.

• Strict (per group, optional): a strict group's chests only keep the group's own items. Anything else goes to a chest of its own group nearby. If none has room, it goes to a nearby ungrouped chest, or failing that to a chest of a group that isn't Strict (never to a Locked chest). Without Strict, other items stay where they are.

• Rename, and X to delete a group. Deleting a group never deletes items; its chests just become ungrouped.

• Show routing messages (just for you): shows a short message every time an item is routed near you, like "Evicted 3 Stone to an ungrouped chest (7 m)". Handy to see what the mod is doing. Off by default.

  

Where items go

When an item lands in any chest, and a chest of that item's group is within 10 meters with room, the item moves there. Priority chests first, then the closest chest.

• If its group's chests are all full or too far away, the item stays put, unless the chest it landed in is Strict (see above). Nothing is lost.
• Items with no group stay where you put them, unless the chest is Strict.
• Locked chests are skipped completely: nothing leaves them, nothing is sent to them.
• Changing a chest's group re-checks everything in it.
• Hover over a chest to see its group, whether it's Strict, and whether it is inside a ward.

Where does an item go?

                  An item lands in a chest
                            |
                            v
        +-------------------------------------+
        | Is this chest Locked?               |--- yes ---> STAYS
        +-------------------------------------+
                            | no
                            v
        +-------------------------------------+
        | Is this chest in the item's group?  |--- yes ---> STAYS (it is home),
        +-------------------------------------+             unless a Priority chest
                            | no                            of the group nearby has
                            v                               room: then it MOVES there
        +-------------------------------------+
        | Is a chest of the item's group      |--- yes ---> MOVES there
        | within 10 m, with room, and in the  |             (Priority chests first,
        | same ward (or both outside wards)?  |              then closest)
        +-------------------------------------+
                            | no
                            v
        +-------------------------------------+
        | Is this chest's group Strict?       |--- no ----> STAYS
        |                                     |             (waits for room)
        +-------------------------------------+
                            | yes
                            v
        +-------------------------------------+
        | Is an ungrouped chest nearby        |--- yes ---> MOVES there
        | with room (same ward rule)?         |
        +-------------------------------------+
                            | no
                            v
        +-------------------------------------+
        | Is a grouped chest that is NOT      |--- yes ---> MOVES there
        | Strict (or Locked) nearby with room?|
        +-------------------------------------+
                            | no
                            v
                  STAYS (nowhere to send it)

Locked chests never take part. An item moves at most three times, and never back and forth. A group chest works like a sink: it keeps pulling in its group's items from nearby chests until it is full.

Everything is checked again when:

• an inventory changes (this chest and nearby chests are rechecked),
• a chest's group is set, changed or cleared, or its Priority is turned on or off,
• any group setting or item list changes, including Strict turning off,
• Pause sorting is turned off,
• a group is deleted,
• a chest is built nearby, or loads in as you come near (a new place for items with nowhere to go).

Install

You need BepInExPack for Valheim installed first.

Install with a mod manager such as Gale or r2modman. That's all.

The mod is exactly two files: StorageGroups.dll and StorageGroups.Core.dll. Everything else it uses already comes with Valheim or BepInExPack.

With Gale (manual profile install):

1. Open your profile folder. In Gale: the profile menu, then "Open profile folder".
2. Go to BepInEx/plugins.
3. Make a folder called StorageGroups and put both DLLs in it.
4. Start the game through the mod manager.

Manual install:

1. Go to your Valheim folder (Steam: right-click Valheim, Manage, Browse local files).
2. Go to BepInEx/plugins.
3. Make a folder called StorageGroups and put both DLLs in it.

Updating: a mod manager replaces the files for you. If you ever installed by hand, make sure no loose StorageGroups.dll or StorageGroups.Core.dll sits directly in BepInEx/plugins: an old leftover copy can be loaded instead of the new one. If that happens, the mod turns itself off and the log (BepInEx/LogOutput.log) names the file to delete.

Uninstall: delete the StorageGroups folder. Your chests keep their items.

Multiplayer

• Install on the server and on every player, and keep everyone on the same version (0.2.x).
• Mixed versions still work, with warnings that only appear when an older version is certain: such a player gets a message asking them to update, and everyone else is told who's outdated. Older versions don't know Locked, so while such a player is around, Locked chests they handle aren't fully protected.
• Groups are shared by everyone on the server. Anyone can create, rename or delete a group, and change its settings, except the built-in Locked group, which nobody can change.
• All chests work together, no matter who built them or who has them open.
• Renaming a group keeps every chest in it, for everyone.

Wards

• Items never cross the edge of a ward. Chests inside a ward only send items to chests inside the same ward, and chests outside wards only to chests outside wards.
• A chest standing where two wards overlap only routes with chests covered by the same wards.
• Private chests are never touched.

Works with

• AzuAutoStore: AzuAutoStore puts the item in a chest first, then this mod moves it to the right group chest. Tip: turn on Strict for your groups, because AzuAutoStore stores into any chest that already has that item.
• Other mods don't know about Locked. AzuAutoStore can still put items into a Locked chest (this mod then leaves them there), and mods that craft from nearby chests, such as AzuCraftyBoxes, can still take from one.

Does NOT work with

• Smart Containers / Smarter Containers, and other mods that move items between chests on their own. Two sorting mods fight over the same items. This mod will not load if Smart Containers is installed. Remove it first.

Settings

After the first launch, the config file BepInEx/config/com.jonasd.valheim.storagegroups.cfg appears. With a mod manager, open it from the manager's config editor.

• Routing.RangeMeters (default 10): how far, in meters, an item can travel to reach another chest. Everyone on a server should use the same value.
• UI.ShowRoutingMessages (default off): same as the checkbox in the group menu.

Disclaimer

• This is a work in progress and not fully tested. Use at your own risk.
• Multiplayer and ward support are the least tested parts. Back up your world before using it on a server, and report anything odd.
• Items are only moved, never created or deleted on purpose. Still, if something goes wrong, the backup is your safety net.

Changelog

0.2.3: Safe with players who don't have the mod

Update the server and every player. Players on 0.2.2 or older are asked to update.

Fixes

• With a player online who didn't have Storage Groups, a Strict chest could send the same items back and forth every few seconds, and items piled up on the ground next to it. The game lets the nearest player's game look after nearby chests, and a game without the mod never answered. Now items are only sent to chests looked after by a game that runs Storage Groups 0.2.3 or newer; other chests simply don't get items until that changes. A chest that didn't answer or said no isn't tried again until something changes (who looks after it, who is online, the groups, or the chest itself). Nothing repeats on a timer.
• A Strict chest can no longer fill up with items that don't belong to its group. The game looking after a chest now checks every item it is handed against its own group list, and a group it doesn't know counts as Strict.
• A chest's group is only removed when its group was really deleted. Before, a game with an empty or unreadable group list could remove it, turning a Strict chest into a place where other chests dumped their leftovers.
• An item that can't go back into its chest goes into another suitable chest nearby (never across a ward edge) before it is dropped on the ground.

Multiplayer

• When a player joins without Storage Groups (or with a version older than 0.2), everyone with the mod gets a message, including players who join later, and that player is asked to install it. Turn the message off with UI.WarnAboutPlayersWithoutMod.
• Changing a chest that a player without the mod looks after now says so, instead of silently doing nothing.
• The log now shows items a chest refused, items received from another player, items put into a Strict chest by hand or by another mod, and whose chests are skipped because their game doesn't run 0.2.3 or newer.
• If items ever keep coming back to a chest, keep dropping on the ground at it, or keep moving back and forth between two chests, the log says "Possible loop" (at most once every two minutes per chest and item). Please include that part of the log if you report a problem.

0.2.2: New characters can join again

Update the server and every player. The server part fixes joining for everyone, even players who haven't updated yet.

Fixes

• A brand-new character (or anyone without a bed) could get stuck on the loading screen forever when joining a world with Storage Groups. The mod keeps its group data on a hidden object at the centre of the world, right next to the start temple, and the game waited for that object to appear before letting the player spawn. The server now moves the group data far outside the world, and the game no longer waits for it. Your groups and chests are not affected.
• "Name isn't on Storage Groups 0.2" no longer appears when that player is on 0.2: your game only believes a list of outdated players from a server that counts proof alone (0.2.2 or newer). A 0.2.0 server could flag a player who was just slow to load.

0.2.1: No more false "please update" message

Fixes

• Players already on 0.2 could get "This server uses Storage Groups 0.2 ... please update" when they joined. The server gave each player 20 seconds to report their version, but a game only reported once the player had spawned, and loading the world can take longer than that. Now your game reports its version as soon as it connects.
• Version warnings now only appear when a different version is certain: a player's game reported another version, or it edited a group the way only 0.1.x does. Being slow to load never counts.
• The "server runs an older Storage Groups" warning is gone, because an older server can't be recognised for certain.

Works together with 0.2.0 players and servers. Update the server too, so it uses the stricter rule.

0.2.0: Locked chests, Priority and a new look

Update the server and every player to 0.2. Mixed versions still work, but Locked chests are only fully protected when everyone is on 0.2 (see Multiplayer below).

Thanks to @datacain for reporting the issues and ideas behind this release: Locked chests (#1), the popup size on large screens (#2) and Priority (#3).

New

• Locked group, built in and always at the top of the group menu. Nothing moves into or out of a Locked chest automatically; you can still put items in and take them out by hand. Good for personal gear, boss loadouts, or materials saved for a build. It can't be renamed, deleted or given items.
• Priority toggle on grouped chests. Priority chests fill first, and the group's other chests nearby move their items into a Priority chest whenever it has room, so your stock gathers in one place.

Look and feel

• The Storage Groups and Edit Items popups now use the chest window's own wood background, and its colour changes with the time of day just like the chest window's. They used to be solid dark panels.
• The popups now scale with the rest of the game's UI. They were about half size on large screens, such as 2160p.
• Locked shows a padlock and a blue tint, in the group menu and on a Locked chest's Group button. A Locked chest's sidebar shows only the Group button; its hover explains that nothing moves.
• Priority is a new row below Pause sorting, shown on grouped chests.
• The chest sidebar always stays on screen, even when it has to move aside for the weight badge on a narrow screen.

Fixes

• Placing a new chest didn't make nearby chests send it anything until something else changed. Now, for example, a Strict chest's leftover items move into a new ungrouped chest right away.

Multiplayer and updating

• Version check, warnings only (nobody is kicked): players on an older version get an on-screen message asking them to update, and 0.2 players are told when someone outdated is online.
• Players on 0.1.x don't know Locked: while their game is handling a Locked chest, it can still move items out of it, or (rarely) drop overflow into it. Their edits to the Locked group are refused, with a message telling them why.
• If your world already has a group called "Locked", it's renamed to "Locked (old)". Its chests and items stay as they were.
• Saved groups use the same format as before, so 0.1.x players and servers can still read them. Priority is saved separately, and 0.1.x ignores and keeps it.
• If you ever installed the mod by hand, delete any loose StorageGroups.dll / StorageGroups.Core.dll directly in BepInEx/plugins and keep only the mod's own folder. 0.2 now detects an old leftover copy, turns itself off and names the file to delete in the log, instead of filling the log with errors.

0.1.7: UI/UX overhaul

• The chest sidebar now changes with the chest. A chest without a group shows New Group From Contents; a chest with a group shows Add Contents and Edit Items.... Both have Pause sorting.
• New Group From Contents: one click (plus Enter) makes a group from the chest's items, named after the item there is most of, and puts the chest in it.
• Edit Items...: a list of the group's items with icons, a Remove button for each, and Clear all.
• The Group button's hover now also shows the group chests nearby, so the separate Routes (?) button is gone.
• Clearer names: Evict Mismatching is now Strict, Hold routing is now Pause sorting, Extend From Contents is now Add Contents, and Edit in the group menu is now Rename. Set From Contents is gone: use Clear all, then Add Contents.
• Popups have a solid dark background, so nothing shows through them.
• Hover boxes update while you hover, for example right after Add Contents.
• No gameplay or save changes. Groups, settings and multiplayer messages are the same as before, so older players and servers still work together with 0.1.7.

0.1.6

• New Extend From Contents button in the chest sidebar: adds this chest's items to its group without removing the group's other items. An item still belongs to one group only; if it was in another group, it moves over and the game tells you.
• New icon: three chests, each with its own group.
• The mod page now has screenshots.

0.1.5

• Group changes on a server now show up almost immediately (they could take up to about 5 seconds). This covers creating, renaming and deleting groups, Evict Mismatching, and Set From Contents.
• For the full effect, update both the server and all players. Players on 0.1.5 already see their own changes quickly, even on a server that's still on an older version.
• The group menu picks up changes faster and does less work while it's open.
• No gameplay changes. Saved groups and multiplayer messages use the same format as before, so 0.1.2 to 0.1.4 players and servers still work together with 0.1.5.

0.1.4

• The mod is now just two DLLs (StorageGroups.dll, StorageGroups.Core.dll). It no longer bundles any .NET libraries, including copies of ones Valheim already ships.
• Fixed a flood of "LiberationSans SDF Font Asset was not found" warnings in the log when opening a chest.
• No gameplay changes. Saved groups and multiplayer messages use exactly the same format as before, so existing worlds keep their groups and players on 0.1.2 or 0.1.3 can still play together with 0.1.4 players.
• If you installed an earlier version by hand, delete the old StorageGroups folder first so the extra DLLs are gone. Mod managers do this for you.

0.1.3

• No longer bundles System.Memory and System.Runtime.CompilerServices.Unsafe. Valheim already ships both, and a second copy could conflict with the game's own.

0.1.2

• Pressing the Use key while typing a group name no longer closes the name editor.

0.1.1

• Works with the standard BepInExPack for Valheim, with no extra MonoMod libraries needed.
• Nearby chests are rechecked when a group's settings change (including turning Evict Mismatching off) and when a nearby chest's contents change.

0.1.0

• First release. Put chests in groups and items move to the right chest by themselves.