ItemPull

Search, locate, pull and deposit items, and craft or build with resources in nearby chests.

Client-side only: install ItemPull on your own client. The server and other players do not need it. Search results and Locate markers are visible only to you. BepInEx process filters allow the game client and exclude the dedicated-server executable.

Using ItemPull

1. Open your inventory and select ItemPull above the player inventory.
2. Type part of an item's name. Search is case-insensitive and uses the game's translated item names. An empty search lists all available item types.
3. Each result shows its total quantity and the number of matching chests. Quality and appearance variants have separate results. Use Previous/Next for additional pages.
4. Select Locate to close the inventory and show cyan chest outlines with chest names, item quantities and distances. The markers show through walls and expire after 4 seconds by default. Off-screen labels appear at the edge of the screen.
5. Enter a positive Pull amount, or select All, then select the result's Pull button. Items are taken from matching chests nearest first. Full inventories accept only what fits; remaining items stay in storage.

Deposit: with your inventory open, hover an item in your personal inventory and click the scroll wheel (middle mouse). The clicked, unequipped stack moves into accessible chests containing that exact item first, nearest first, then chests containing only items in the same configured group. It can spread across several chests when needed. Other stacks in your inventory remain untouched. The ItemPull panel does not need to be open. If no eligible chest is nearby, nothing happens. Full chests leave the remainder in your inventory. Contents and group settings are checked again after access is granted.

Middle-click also works while a container is open. Your own open, owned chest can receive items without a second access request and stays open afterwards. Chests being used by another player are skipped. Hover your personal inventory, rather than an item inside the container.

Deposit All: select the button beside ItemPull above your inventory. It applies the same exact-first, then group routing to each unlocked stack. Locked, equipped, quest and unmatched items stay in your inventory, along with anything that cannot fit. Empty chests are never seeded. Closing inventory cancels the remaining batch.

Group sorting: enabled by default. For example, Fine Wood can enter a chest containing only Wood and Core Wood even when it has no Fine Wood yet. A chest containing Wood and Stone is mixed, so it accepts exact matches only. An unrecognised item in a chest also prevents inferring its group. Seed an empty chest manually with one item from your intended group. The mod deposits personal stock; it does not rearrange existing chest contents.

Item locks: hover a stack and press Alt + middle-click to lock or unlock it. A gold [L] marker and tooltip identify locked stacks. Locks block both Deposit All and middle-click deposit. They follow the item through saves, moves, splits, merges and upgrades; when locked and unlocked stacks merge, the combined stack is locked. The lock protects against automatic deposits; it does not prevent ordinary manual item movement or resource consumption.

Crafting and building: use the normal crafting, upgrade and build controls. Nearby chest materials count toward the requirements using the same configured radius. Personal resources are consumed first, followed by the exact shortage from nearby accessible chests, nearest first. Ingredients do not need spare inventory slots, but crafted results still need normal inventory space. Recipe discovery, station levels, placement rules, stamina, durability and output amounts follow the native game.

Chest access is checked before completing an action; denied, busy or unavailable chests cannot provide materials. Keep the placement target steady while access is pending. Moving or rotating the target cancels that build; click again at the new target. Closing inventory or pressing Craft Cancel cancels pending crafting. You can disable chest crafting and chest building separately in the config.

Deposit ignores other UI covering an inventory item, typing, item dragging and split dialogs. Exact matches compare item name, quality, appearance variant and world level. Group membership is based on item identity/type; native transfers preserve stack metadata and only merge compatible items. The shortcut supports keyboard keys, mouse buttons and modifiers; rebinding left/right click gives Deposit priority over native drag/equip for that gesture.

Search refreshes after typing and when transfers finish. Refresh updates results after another player changes a chest. Pull and Locate recheck results when selected. Closing the inventory cancels pending transfers; already transferred items remain where they were moved. Closing only the ItemPull panel leaves an authorised transfer running.

Pull follows normal inventory stacking and weight behaviour. It can encumber your character. Item properties are cloned by the game's native transfer method; merging compatible stacks follows the game's normal rules.

Installation

Requires BepInEx 5 for Valheim. The package declares denikson-BepInExPack_Valheim-5.4.2350, the pack used for runtime testing. Jötunn is not required.

Mod manager: install ItemPull in your Valheim profile and launch the game through your mod manager. Its declared BepInEx dependency is installed automatically. To try the upload ZIP before publication, use your manager's local-mod import option with ItemPull-0.4.0-thunderstore.zip.

Manual installation: close Valheim and install BepInEx for Valheim. Extract the upload ZIP's BepInEx folder into your game folder, merging the directories. The resulting DLL path should be BepInEx/plugins/ItemPull/ItemPull.dll. If using the separate ItemPull-0.4.0.zip manual archive, extract its ItemPull folder into BepInEx/plugins/ instead. Replace the previous DLL and keep only one copy in your profile. Your existing config is preserved; the example config is documentation and is not installed as an active config.

Install on your client only. Server installation is unnecessary. The release contains no game assemblies or test plugins.

Configuration

First launch creates BepInEx/config/Dyls123.ItemPull.cfg.

For example, DepositItem = F6 deposits the hovered stack with F6; DepositItem = Mouse2 + LeftControl requires Ctrl and middle click. LockItem = F7 changes the lock toggle to F7. If both shortcuts match, locking takes priority. The same radius applies to search, pull, deposit, crafting and building.

Editing groups

All groups are in the same BepInEx/config/Dyls123.ItemPull.cfg. The included Dyls123.ItemPull.cfg.example contains every default list. Existing configs gain the new sections on first launch; existing settings are preserved.

• 20 standard categories: Wood; Stone and Minerals; Ore and Scrap; Metal Bars; Hides and Leather; Creature Materials; Seeds and Planting; Cooking Ingredients; Mead Bases; Mead and Potions; Prepared Food; Textiles and Fibres; Fuel and Resin; Valuables; Trophies; Tools and Utility; Weapons and Shields; Ammunition; Armour and Clothing; Special Materials.
• Nine optional biome presets: Meadows, Black Forest, Swamp, Mountains, Plains, Mistlands, Ashlands, Deep North and Ocean. These describe item origin/progression, independent of where you put the chest. They are editable starting lists, not an exhaustive classification of every item or mod. Shared items use the first matching preset. Deep North entries use IDs present in the installed game; unavailable IDs on older versions simply never match.
• Five blank custom groups: CustomGroups.01 through CustomGroups.05. Fill in both Name and Items to activate one. Custom groups work with either standard or biome mode and have priority over both.

Each section has an editable Name and comma-separated Items. A blank name or item list disables that group. Keep section headers unchanged. Members use internal prefab IDs, not translated display names: for example, RoundLog is Core Wood and ElderBark is Ancient Bark. Matching ignores case and spaces around entries. Semicolons also separate entries.

Example custom group:

[CustomGroups.01]
Name = My Building Materials
Items = Wood, FineWood, RoundLog, Stone, MyModMaterial*

The * wildcard matches any characters in a prefab ID. type:Trophy, type:Tool and similar native ItemType selectors match whole item types, including modded items of that type. Invalid type selectors are ignored. Standard presets use these selectors for food, equipment and other broad categories; clear or replace them when you want explicit membership only.

An item belongs to one group: custom slots in number order first, followed by the active mode's groups in number order. This lets a custom group override a built-in rule without editing that rule. For example, the custom group above groups Stone with Wood instead of the usual mineral category. Items without any matching rule still deposit into exact-match chests. Renaming a group does not change its priority.

Set UseBiomeGroups = true to choose biome sorting instead of standard categories. Set Enabled = false to disable all group routing, including custom and biome groups. These settings affect deposits only; crafting, building, searching and pulling retain their existing behaviour.

On the first 0.2.0 launch, previous default settings of 30 metres and 20 seconds automatically change to 60 metres and 4 seconds. Other custom values are preserved. This migration happens once; later edits remain unchanged.

The radius is a three-dimensional distance from your character, not the camera. Only loaded, accessible static chests are searched. Increasing the radius does not load distant areas. Private chest permissions and wards are respected. Graves, dropped bags, carts and ship holds are excluded.

Use your mod manager's config editor while the game is closed, or a compatible in-game config editor. Loaded changes apply to the next relevant action; group changes also invalidate the cached membership rules. Editing the file directly while the game is running requires a config reload or restart.

Multiplayer and compatibility

The mod is designed for client installation and uses the game's normal chest-open permission/ownership exchange, so it does not introduce custom server RPCs. Busy, denied, destroyed or out-of-range chests are skipped. Transfers only run after the game grants access and the client owns the chest, with contents refreshed first. Late responses to cancelled requests are consumed without transferring items or unexpectedly opening the inventory.

Other inventory, ward or container mods can change these behaviours. Interactive gameplay and dedicated-server multiplayer must still be tested with the intended profile before treating this preview as a stable release.

Building and testing

Requires the .NET 9 SDK and a local Valheim installation. This preview is built against the installed Valheim 1.0.16 assemblies.

dotnet build ./src/ItemPull/ItemPull.csproj -c Release
./scripts/Test-Unity.ps1
./scripts/Test-Unity.ps1 -CapturePreview
./scripts/Package.ps1
./scripts/Validate-Package.ps1 -Path ./dist/ItemPull-0.4.0-thunderstore.zip

For another installation, pass -p:ValheimDir="path" to dotnet or -ValheimDir "path" to the scripts. The build may report the game's System.Net.Http / System.IO.Compression reference-version conflicts with netstandard; these APIs are not used by ItemPull.

Packaging creates both a manual archive and dist/ItemPull-0.4.0-thunderstore.zip. The upload ZIP has manifest.json, a 256x256 icon.png and this README at its root, with the DLL at BepInEx/plugins/ItemPull/ItemPull.dll. The packaging script checks the exact file list, current source hashes, matching versions, manifest fields, image format/dimensions and documentation encoding before finalising the upload ZIP. Publishing instructions are in docs/THUNDERSTORE.md in the source workspace.

The runtime smoke script launches an isolated headless Valheim process with separate saves and plugins. It needs a BepInEx core in .local/smoke/BepInEx/core/ or the supplied game installation. It exercises real Unity UI prefabs and native inventory transfers, with synthetic chest fixtures. It does not join or edit your existing worlds, and does not replace a real multiplayer or visual gameplay test. See docs/TESTING.md for the gameplay checklist.

Version 0.4.0 passed all 40 isolated runtime checks. These cover client process filters, config migration, quantity conservation, partial capacity, metadata, search filtering, native UI skins/paging, simulated access grants/denials, busy chests, cancellation, deposits, locks, requirement scoping, and resource consumption. Group checks cover exact-first routing, mixed/empty storage, editable/custom precedence, biome replacement, master and shortcut switches, fresh policy checks after permission, range/privacy/capacity and depositing into your own open chest without losing its reservation. Default explicit prefab IDs were checked against installed asset paths and representative categories against actual item prefabs. Native crafting tests include upgrades, one-ingredient recipes, multi-crafting, denied access and a full inventory. The build entry test mocks physical placement and the input loop while exercising the production access/replay hooks and native requirement/consumption methods; it does not validate live-world physics, effects or network concurrency. The pointer test supplies draw depth for its synthetic canvas while exercising native hit geometry and overlay ordering. -CapturePreview renders the search panel and inventory buttons with sample data to .local/smoke/ItemPull-preview.png; it does not capture a live world.

Changelog

0.4.1

• Added support for Valheim Plus.

0.4.0

• Thunderstore upload archive with root manifest, 256x256 icon, BepInEx dependency, documented installation paths and package validation.
• Group sorting for Deposit All and the single-stack deposit shortcut: exact matches first, then nearest chests containing only the same group.
• Master grouping toggle, separate shortcut toggle and optional biome mode (off by default) that replaces standard categories.
• 20 editable standard groups, nine editable biome presets and five blank custom groups in the main config. Custom groups take priority; prefab IDs, wildcards and native item-type selectors are supported.
• Recheck contents and current group rules after permission arrives; empty and mixed chests remain exact-item-only.
• Deposit from personal inventory while a container is open; your own open chest keeps its reservation and uses its existing native access grant.
• Retain client-only installation, lock protection and native inventory persistence.

0.3.0

• Craft, upgrade and build with accessible chest resources using the same search radius.
• Count nearby resources only for requirements; acquire native chest access before completing actions and consume personal stock before chest shortages.
• Deposit All button beside ItemPull, targeting only already-matching chests and skipping locked, equipped and quest items.
• Configurable item-lock shortcut, default Alt + middle-click, with gold [L] indicators and tooltips.
• Locks persist through native serialization, moves, splits, merges and upgrades, and block both deposit methods.
• Keep client-only installation; add separate config switches for chest crafting and building.

0.2.0

• Default radius increased to 60 metres; Locate duration reduced to 4 seconds.
• Previous defaults migrate once while custom settings are preserved.
• Middle-click deposit for the hovered inventory stack, with a configurable shortcut.
• Deposits only enter accessible nearby chests already containing the same item; empty/full/denied storage leaves remaining items in the inventory.
• Native inventory wood panels, button textures, decoration and body fonts replace flat grey styling.
• Client-only installation and vanilla chest access/transfer networking retained.

0.1.0

• Inventory search with translated item names, totals, paging and a configurable radius.
• Locate with temporary cyan chest outlines, quantities and distance labels.
• Pull a chosen quantity or all matching items across nearby chests.
• Native chest access exchange and slot transfers, permission checks, cancellation and partial-inventory handling.