Hearth Logistics

Client-side inventory, smart storage and base logistics for Valheim — version 0.4.0.

Spend less time moving items and more time building, crafting and exploring. Create personal inventory profiles, organize your storage, and run Deposit, Restock, Rebalance or Service Base when you need them.

Client-only use remains supported. An optional server installation adds unloaded portal-container transfers; it is disabled by default. Requires BepInEx 5; Jotunn is not required.

What's new since 0.2.12

• Download nearby resources: browse nearby storage by item, category or search, then transfer a chosen quantity to your inventory or an open chest/cart. Includes item icons, Max quantity, a scrollbar and an optional Ignore weight limit setting.
• Build from nearby storage: use eligible nearby materials for hammer construction as well as supported crafting.
• Multiple Overflow containers: designate several chests or carts as Overflow, with Priority controlling which destinations are used first.
• Optional fallback storage: Treat Unconfigured Chests As Overflow lets ordinary unconfigured containers provide extra storage capacity.
• Expanded base servicing: use unlocked carried supplies first, then nearby storage; configure global material permissions and station policies. Service Structures During Deposit is also available as an optional preference.
• Mead fermenters: supply valid mead bases and collect finished batches through your normal storage routes.
• Overflow highlighting: locate explicitly designated Overflow chests and carts with small cyan markers.
• Container contents visuals: see item icons on chest faces, plus a compact hover summary, without opening the container.

Inventory Profiles

Select an Inventory Profile beside the normal inventory statistics. Choose Edit to create, rename, duplicate or delete profiles and set item Min/Max quantities.

• Min 10 / Max 10: Restock and Deposit aim to keep 10.
• Min 5 / Max 10: Restock when below 5, up to 10; Deposit anything above 10.
• A blank Min means no refill requirement. A blank Max means no upper inventory limit. A Min-only rule restocks to Min.

Lock physical inventory slots while editing by hovering a slot and pressing F4. Locked slots protect their items from depositing and other logistics transfers. Building may consume their materials by default; disable Preferences → Building can consume materials in locked slots to protect them during nearby-storage building too. Explicit item locks, equipped items and quest items remain protected. Switching profiles changes the active rules without moving items automatically. Profiles and preferences are saved locally per character.

Smart storage

Open a chest or cart to adjust priority, overflow, contents faces/layout and icon background/colour in the main panel. Debug dump and panel refresh controls also remain there when diagnostics are enabled. Select Contents & filters to open the adjacent panel for filters, stock rules and templates:

Both panels share the same height. The filter panel keeps its actions at the bottom and gives the remaining space to a scrollable item area with a draggable scrollbar.

• Item or category filters for individual slots, rows or the entire container.
• Filter ghost icons and Create filters from current contents.
• Stock Min / Max, Fill Available Space, Priority and Overflow.
• Layout copy/paste and named templates.

Configured destinations are preferred, followed by explicitly marked Overflow containers and then optional unconfigured fallback storage. Higher Priority wins within a destination tier. Transfers can continue across multiple containers when one fills up.

Min protects stored supplies from withdrawal. Placement filters control where items may be deposited; they do not prevent taking existing items out. Max and Fill Available Space control destination capacity rather than reserving existing stock.

Carts support the same storage rules. Their configuration follows the cart as it moves.

Logistics actions

Base servicing and fermenters

Supported structures include smelters, blast furnaces, charcoal kilns, windmills, spinning wheels, fermenters, finite-fuel fires, hearths and ground/wall torches.

Servicing uses unlocked carried resources first, then eligible nearby storage. Chest Min and personal storage reserves remain protected. Configure station enablement, refill thresholds and global material permissions under Servicing.

Fermenter recipes come from the game's component data. If several valid bases are available, selection follows a stable prefab-name order. Active fermentation is left alone. Finished barrels are tapped only when existing storage routes have room for the whole batch. A tapped barrel can be refilled on the next servicing action.

Remote-owned machines use vanilla's debit-then-owner-RPC path, with local capacity reservations to limit repeated sends against stale counts. Vanilla supplies no acceptance reply: network failures and concurrent clients can still cause resource loss or overfill. Hearth Logistics never infers a refund or retry from delayed replication. Fermenter tapping still requires local ownership for output tracking; remaining products stay as drops if storage becomes unavailable. Output collection recognizes supported production observed during the current session.

Download nearby resources

With the build menu open, hover a building piece and press F5 to download the materials you are missing for one copy into your inventory. Repeated presses top up shortages without fetching another full set. This does not place the piece. Change Download hovered building materials under Settings → Controls → Hearth Logistics if desired.

This shortcut works independently of Craft / build from nearby storage. It follows Download's chest Min, access, range, inventory-lock and weight rules, including your Ignore weight limit preference. Unavailable materials produce a partial-result message. Repair/remove icons and free-build mode do not request materials.

Open your inventory or a chest/cart and click the small down-arrow button just outside the inventory window's top-left corner. The browser identifies the destination and excludes it from source storage.

Browse localized item names and icons, filter by category, search, choose a quantity or use Max, then transfer items directly. The list supports mouse-wheel scrolling and a draggable scrollbar.

• Download requests additional items: carrying 20 Coal and downloading 30 aims for 50.
• Player profile Min/Max does not limit this manual action; locked slots remain protected.
• Source chest Min remains protected. Personal storage reserves apply to Restock, crafting and servicing, but not Download.
• Chest/cart destinations respect placement filters, stock Max and available space.
• Player downloads respect carry weight by default. Ignore weight limit is an optional local preference; normal encumbrance can still occur.
• Partial transfers report the amount moved and the limiting condition. Use Refresh to update availability explicitly.

Craft and build from nearby storage

Enable Craft / build from nearby storage to use eligible nearby supplies for ordinary new-item crafting, normal crafting-station item upgrades and hammer construction. Crafting and upgrades use player ingredients first, then nearby supplies. Source Min and personal storage reserves remain protected. Normal station, placement, DLC and other vanilla requirements still apply.

Hammer construction does not require spare player inventory slots. Storage ingredients are consumed only after successful placement. Explicitly upgrading equipment is allowed even when its slot or item rule is locked; those locks continue to protect it from depositing. Ingredient locks still apply. Upgrades share the crafting transaction: a failed resource commit restores ingredients and the original item, including its equipped state. Special probabilistic upgrader stations, one-of-ingredient recipes and no-cost crafting modes remain outside the nearby-resource integration.

Find and preview containers

Under Mod Settings → Hearth Logistics → Preferences:

• Highlight Overflow Containers — off by default. Shows small cyan markers on nearby accessible chests/carts explicitly configured as Overflow. Unconfigured fallback storage is not marked.
• Show Chest Contents Icons / Hover Text — on by default. Displays item icons directly on nearby accessible chest faces. Also adds the existing text summary when hovering, totaling stacks by item type (up to eight types, ordered by quantity then name).

All chests default to Sides, 4 icons (2 × 2). Open a chest's Hearth Logistics panel to change Contents faces between Sides and Front / back, and Contents layout between 1 icon and a grid. Side grids hold up to 4 icons; front/back grids hold up to 6 icons (3 × 2). The first unique items are selected in inventory-slot order, left to right and top to bottom. Duplicate stacks occupy one icon; empty slots in the display stay blank. Icons are attached to both faces of the selected pair: narrow faces for Sides, wide faces for Front / back. They follow rotated/moving containers and are occluded by world geometry.

Layout choices are saved per container alongside its shared rules and included in copied layouts/templates. The small Icon background circle toggle adds one combined panel behind the grid; it defaults to Off. Open Colour beside the toggle to use a colour wheel, brightness/opacity sliders or a #RRGGBB / #RRGGBBAA hex value. The picker opens beside the chest panel. Save colour at the top saves the colour to that chest and to your personal palette; Cancel discards the draft. Select a saved swatch and press Save colour to reuse it on another chest. Up to 128 unique swatches are saved per character. Colours travel with shared chest settings, copied layouts and templates. As chest settings refresh automatically or through Refresh Nearby / Resync Known Containers, colours from currently accessible chests within storage range are merged into your swatches. Your existing swatches remain; a private unused palette is not broadcast. Old chest settings retain the dark background. Changing only the visual layout does not change routing. The global visibility toggle is a local preference. Icons remain visible on nearby chest surfaces without needing to aim at each chest individually; hover text is hidden while inventory/menu screens are open. Both previews respect access restrictions and never open inventories or request ownership. An Overflow label identifies explicitly designated containers.

Portal containers

For personal storage, open any chest, cart or boat container and enable Ignore this container at the top of its Hearth Logistics panel. This shared, persistent setting excludes it from depositing, restocking, rebalancing, servicing, Download/F5, nearby crafting/building, contents previews and client/server portal transfers. Normal manual use still works. Turn Ignore off to rejoin; inventory, rules and paid portal installations are preserved. The preference is not copied with layouts/templates. Update all participating modded clients and the optional server module to honor the setting; this is a logistics opt-out, not a replacement for vanilla access permissions.

Chests, carts and boat storage can contain a portal. Open the container panel: Build buttons and recipe costs appear only for standard wood and stone portals your character has unlocked. Carry the listed materials and build one portal inside each endpoint. Internal/world portal recipes are excluded.

Destroying a portal container drops the installed portal's recipe materials beside it, in addition to the normal container drops. This also applies to ignored containers. The owning client (or server, for server-owned containers) must have the mod installed to issue the refund. Unloading an area does not refund anything.

Set the source to Outgoing, the destination to Incoming, and give them the same Link ID. Close both inventories to start automatic transfers. The outgoing portal type and server teleport rules govern which items can move. Full or unavailable destinations leave items at the source; source minimums and destination filters/maximums apply. Duplicate loaded incoming IDs pause transfers. Portal installations cannot be copied through layouts or templates.

Client-only limit: both endpoints must be loaded and owned by this client. They may be beyond the normal storage range, but unloaded or other-client-owned endpoints wait. The optional server worker handles unloaded, unowned/server-owned pairs. Install/claim both endpoints with the same character; IDs are scoped to that character. See server setup and portal details.

Controls and settings

Preferences → Container Icon Calibration provides a local preview of real loaded container models, with sample icons, a cyan logical bounding box and a yellow centre marker. Choose the prefab using Previous/Next type. Only nearby player-built containers you can access within Storage range are listed, with shared accessible chests included and world-generated loot chests excluded. Each type appears once; the list refreshes while the page is open. Adjust Origin X/Y/Z (offsets from the automatic centre), Size X/Y/Z (absolute dimensions), and Rotation X/Y/Z (degrees) with numeric inputs or +/- buttons. Changes update the preview and world displays immediately. Auto Rotate can be paused; Previous/Next view turns the camera by 90°. Preview controls can show sides or front/back, one icon or a grid, and the combined background.

Calibration is local per prefab and saved with your personal Hearth Logistics settings when leaving settings; it applies to every matching chest/cart. Reset This Container removes only that prefab's calibration. No calibration data is written to chest rules or shared with other players. Automatic defaults use closed fixed-body geometry; preview and world icons use the same calibrated placement function. The preview is rebuilt from render-only meshes and never spawns a gameplay container. See the feature-pass handoff for implementation and validation details.

Change all ten bindings in Settings → Controls → Hearth Logistics. Existing bindings are preserved. Select a binding and press a keyboard/mouse button; Escape cancels capture and Delete clears it. OK saves; Back discards changes. Use the section reset button to restore mod defaults, or the native binding reset to restore all defaults. Action hotkeys operate outside inventory/settings menus and are suppressed during text entry. Alt + right-click an inventory item opens the profile editor.

Open Mod Settings → Hearth Logistics from the main menu or pause menu, or press F10:

• Inventory profiles: personal rules, profile management and Storage reserves.
• Servicing: global material permissions and station policies.
• Preferences: visual options, notifications, crafting, logistics options, diagnostics and ranges.

Storage range and Service range default to 20 m, adjustable from 2–50 m. Treat Unconfigured Chests As Overflow and Service Structures During Deposit both default off.

Personal data is stored in BepInEx/config/HearthLogistics/<character-ID>.json; main-menu defaults use menu.json. Container configuration is stored with the container's network data.

Installation

Install with a compatible mod manager, or install manually:

1. Install BepInEx 5 for your Valheim client and close the game.
2. Extract the package's BepInEx folder into your Valheim directory.
3. Confirm the plugin is at BepInEx/plugins/HearthLogistics/HearthLogistics.dll.
4. Start the game and look for Hearth Logistics 0.4.0 loaded in BepInEx/LogOutput.log.

When updating, replace the existing DLL rather than keeping multiple copies. For optional portal server mode, install the same DLL on the server and follow server setup. To uninstall, close the game and remove the HearthLogistics plugin folder.

Built against BepInEx 5.4.23.5 and Valheim 1.0.15. Harmony comes from BepInEx; Unity and Newtonsoft.Json come from the game. Dependencies are not bundled.

Multiplayer and practical limits

Transfers use nearby, loaded, accessible storage. Selected remote-owned chests/carts request ownership through vanilla's owner-arbitrated open request, reload the inventory after a grant, then validate and transfer. Busy or inaccessible containers and tombstones are skipped. Discovery never claims containers. Other players do not need the mod; clients using Hearth Logistics can read shared container rules. Personal profiles and preferences remain local.

Restock, Download, crafting and servicing share inventory source hints, separate from the persistent configuration cache. A missing source can trigger one nearby inventory-index refresh per preparation, without a world scan. Hammer placement requiring remote storage refreshes access first and asks you to place again, avoiding delayed placement at a changed position. See the multiplayer access handoff for all 27 requested findings and remaining limitations.

Portal containers transfer automatically while both endpoints are loaded, locally owned and accessible. With the optional server worker enabled, unloaded unowned/server-owned portal pairs can transfer while the server runs, including with no players online. Other logistics actions are user-triggered. Shared-rule persistence and cross-client behavior should be checked on your server. Nearby caches limit repeated inventory work; the optional server worker separately discovers portal records in bounded batches.

Container rules are cached locally, separately for each world, and refreshed automatically when another player's updates arrive. The chest or cart remains the source of truth; cached files never restore rules into shared storage. Moving carts use their current position. Cache files live under BepInEx/config/HearthLogistics/ContainerCache/ and can be deleted while the game is closed to rebuild them.

Under Hearth Logistics → Preferences, Refresh Nearby reloads rules for accessible loaded containers within Storage range. Resync Known Containers reloads all currently loaded containers known to this client, including those outside that range. Neither action loads distant areas or scans every chest in the world. Use these controls if rules appear out of date. No server plugin is required.

Restock and Download fill compatible unlocked partial stacks before using empty slots, including equipped ammunition. Equipped stacks keep their position and equipped state; explicit slot and item locks still apply.

Version 0.4.0 has passed compilation and code-level/static checks. Gameplay, visual layout and multiplayer behavior have not been verified as part of this build.

Feedback and diagnostics

Bugs, suggestions and feedback: Discord racidon.

Under Preferences → Debug Logging, select Off (default), Normal or Verbose. Logs are written to BepInEx/logs/HearthLogistics.log. With logging enabled, the chest panel also offers Dump Chest Debug and Refresh Logistics Panel.

For a report, include your mod, Valheim and BepInEx versions, what happened, and the relevant log excerpt.

License

Hearth Logistics is released under the MIT License. Third-party dependencies retain their own licenses.