You are viewing a potentially older version of this package. View all versions.
KydlDev-ChestSnapping-2.1.1 icon

ChestSnapping

Lets chests use Valheim's built-in snap system. Press Q/E while placing to pick one of 14 snap points. Works with modded chests, and the snap points can be adjusted in-game.

By KydlDev
Date uploaded 3 days ago
Version 2.1.1
Download link KydlDev-ChestSnapping-2.1.1.zip
Downloads 265
Dependency string KydlDev-ChestSnapping-2.1.1

This mod requires the following mods to function

ValheimModding-Jotunn-2.30.2 icon
ValheimModding-Jotunn

Jötunn (/ˈjɔːtʊn/, 'giant'), the Valheim Library was created with the goal of making the lives of mod developers easier. It enables you to create mods for Valheim using an abstracted API so you can focus on the actual content creation.

Preferred version: 2.30.2
denikson-BepInExPack_Valheim-5.4.2351 icon
denikson-BepInExPack_Valheim

BepInEx pack for Valheim. Preconfigured with the correct entry point for mods and preferred defaults for the community.

Preferred version: 5.4.2351
KydlDev-KydlCore-1.1.1 icon
KydlDev-KydlCore

Shared runtime for all KydlDev mods: one UI root and theme, the KY hub window (F6; the one menu of every KydlDev mod) and the KY-Items category and registry.

Preferred version: 1.1.1

README

Chest Snapping

Lets chests and other containers use Valheim's built-in snap system, the same way walls and floors do.

While placing a chest, press Q / E to cycle through its snap points. The normal message in the middle of the screen shows which one is active (for example Snapping: Bottom Front Left). Nothing about input or messages is re-implemented: vanilla already does the cycling and the message for any piece that has snap points. This mod just gives chests snap points.

Client-side only. Other players and servers do not need it (if they do have it, the versions must match).

Install

Requires BepInEx (BepInExPack_Valheim), Jötunn and KydlCore. A mod manager such as Gale installs them for you.

Install with a mod manager, or put ChestSnapping.dll in BepInEx/plugins (Jötunn and KydlCore need to be installed as well).

Snap points (cycle order)

# Name
1-4 Bottom Front Left, Bottom Front Right, Bottom Back Left, Bottom Back Right
5-8 Top Front Left, Top Front Right, Top Back Left, Top Back Right
9-14 Bottom Center, Top Center, Back Center, Front Center, Left Center, Right Center

Points are placed on the chest's real collider bounds, so chests snap flush against each other. Front is the chest's local +Z and Right is +X, from the chest's own point of view. Names are localizable (English is provided, other languages fall back to English).

How to use it: pick a point on the chest you are holding (for example Bottom Back Right), aim near a snap point on another piece (another chest's corner or face center, or a wall/floor corner), and it locks on within vanilla's snap range (0.5 m). Rotation still matters: match the other chest's rotation with the normal rotate controls so the faces line up.

Stacking chests without planks

Vanilla only lets you put a chest on top of another chest when a plank or floor sits between them (a chest does not count as a building support). With [Stacking] Enable (on by default) a chest you aim at another chest is accepted, so you can stack chests directly, with or without a snap point selected. A chest under another chest counts as its support (otherwise the game destroys the top chest after about 30 seconds); a chest still supports nothing else, so floors, walls and the like cannot be built on it. Turn it off in the KY hub (F6) or the config to get vanilla behaviour back.

For mod authors

To let your own storage chest snap and stack, call ChestSnappingApi.RegisterChest("YourPrefabName") (public static class in the ChestSnapping assembly, namespace ChestSnapping; UnregisterChest, IsChest(GameObject), IsStackingOn() and ApiVersion are there too). No reference is needed: Type.GetType("ChestSnapping.ChestSnappingApi, ChestSnapping")?.GetMethod("RegisterChest")?.Invoke(null, new object[] { "YourPrefabName" }). Registering before ChestSnapping loads works. The player's ExcludedPrefabs and the [Prefabs] / [Stacking] switches still decide.

Built-in chests: piece_chest_wood, piece_chest, piece_chest_private, piece_chest_blackmetal, piece_chest_grausten, the wardrobe (piece_chest_warderobe), the barrel (piece_chest_barrel) and the three pots (piece_pot1, piece_pot2, piece_pot3, with their cracked and red variants).

Modded chests (or future vanilla chests)

No recompile needed. Use either way:

Console (F5)

The console commands below exist only while the developer's KydlTools mod is loaded in that world. Without it, use the config file (next section).

Command What it does
chestsnap_list [filter] Lists every buildable container prefab and whether it has snap points.
chestsnap_add <prefab> Adds a prefab. Saved to the config, existing chests update immediately.
chestsnap_remove <prefab> Takes a prefab you added back off the list.

Config file BepInEx/config/com.kydldev.ChestSnapping.cfg

  • ExtraPrefabs: comma-separated prefab names.
  • ExcludedPrefabs: prefabs that should not get snap points (also works for the built-in ones).
  • AutoDetectContainers (default off): every buildable piece with a Container on its root (ships and carts excluded) gets snap points automatically. Good for big modpacks, use ExcludedPrefabs for anything it catches that you do not want.

Prefab names are not case-sensitive.

Adjusting the snap points

Some modded chests have an oversized invisible collider or an off-center model, which puts the snap points in the wrong place. Each chest can be tuned separately. All distances are in meters along the chest's own axes (+X right, +Y up, +Z front). Both 0.05 and 0,05 are accepted in the console.

The console commands below exist only while the developer's KydlTools mod is loaded in that world. Without it, use the config file (next section).

Command What it does
chestsnap_show [on|off] Draws a sphere on every snap point (yellow = corners, cyan = face centers). Session only.
chestsnap_info <prefab> Prints the measured box, the current adjustments and where each of the 14 points ends up.
chestsnap_shift <prefab> x y z Moves all points together.
chestsnap_grow <prefab> x y z Adds to the box's half-size per axis. 0.05 makes the box 10 cm bigger on that axis, negative values shrink it.
chestsnap_point <prefab> <point> x y z Offsets a single point. <point> is 1-14 (the Q/E order) or a name such as top_front_left.
chestsnap_reset <prefab> [point] Clears the adjustments of a chest, or of just one point.

Setting a value to 0 0 0 clears it. Changes apply to chests that are already standing, and are saved in the config.

Example for a chest whose collider is 10 cm too wide and deep:

chestsnap_list crate
chestsnap_add MyMod_Crate
chestsnap_show on
chestsnap_grow MyMod_Crate -0.05 0 -0.05
chestsnap_point MyMod_Crate top_center 0 0.02 0
chestsnap_show off

The adjustments are stored in the PrefabAdjustments config entry and can be edited by hand. Entries are separated by ;:

MyMod_Crate: shift=0,0.05,0 grow=-0.05,0,-0.05 p9=0,0.02,0; OtherChest: grow=0.1,0,0

Numbers always use . as the decimal separator in the config file, whatever language your system uses.

Configuration

BepInEx/config/com.kydldev.ChestSnapping.cfg, or the Settings tab of ChestSnapping in the KY hub (F6, KydlCore). Changes apply right away to chests that are already built.

Section Setting Default What it does
General Enable Mod true Switches the whole mod on / off while playing
General Enable Prefabs true Chests get snap points (off removes them)
Prefabs ExtraPrefabs (empty) Extra chest prefab names that get snap points
Prefabs ExcludedPrefabs (empty) Prefab names that never get snap points
Prefabs AutoDetectContainers false Every buildable container gets snap points
General Enable Offsets true Apply the saved adjustments below
Offsets PrefabAdjustments (empty) Per-prefab shift / grow / point offsets (the console commands write it)
DebugLog Enable false Detailed lines in the BepInEx log for bug reports

Multiplayer

Nothing is synced: snap points are a local help while you place a piece, and the placed chest is a normal vanilla piece. Other players and servers do not need the mod. If both sides have it, the version has to match exactly.

Bug reports

Turn on [DebugLog] Enable, reproduce the problem, and attach BepInEx/LogOutput.log.

How it works

Vanilla snapping (Player.FindClosestSnapPoints / Piece.GetSnapPoints) looks for direct children of a Piece tagged snappoint. A Harmony postfix on Piece.Awake adds 14 such children to matching chests, for placed chests and for the placement ghost. Q/E (m_manualSnapPoint) and the $msg_snapping message are vanilla code and untouched.

Known limitations

  • Prefab bounds come from non-trigger colliders (mesh bounds as a fallback). A chest with an oversized invisible collider gets oversized snap points. Use chestsnap_grow to fix that.
  • Vanilla only snaps the ghost's points to other pieces' snap points, not to terrain.
  • Debug spheres from chestsnap_show are depth-tested, so parts of them can be hidden inside the chest model.

KydlDev

Get help and stay in touch

Questions, bug reports, ideas or mod requests? Come say hi in the KydlDev Discord: https://discord.gg/tX2CcTNC4W Everyone is welcome, and it is the quickest way to reach me. Source code and issues: https://github.com/kydlDev

CHANGELOG

Changelog

2.1.1

  • Changed: needs KydlCore 1.1.1 or newer (the KY hub shows every settings category of the mod as its own tab).
  • Changed: all the Enable switches are now together in [General] and have new names: Enable Mod (was EnableAll) and Enable Prefabs, Enable Offsets, Enable Stacking (each was Enable in its own section). The values you had set are taken over; the old entries are removed from your config file.
  • Changed: Enable Mod is now the first setting of [General], in the F1 menu and in the F6 hub (your value is taken over).
  • Changed: the console commands exist only when the developer's own KydlTools mod is loaded in that world; players do not get any console command from this mod (use the config file).

Testing

  • Unit tests: 40 passed. Integration tests: 38 passed.
  • Property-based tests (FsCheck, included in the unit tests above): 8 property checks with generated inputs.
  • Coverage of the testable code: 100%. Mutation testing (Stryker): 100% of the mutants are caught by the tests.
  • Performance benchmarks (BenchmarkDotNet): 7.
  • Static analysis (SonarQube): no Medium or High issues.
  • In game with DrakesTestLab: the full suite of 21 tests per run, run 3 times in a row on the release build, all green (the release requirement).

2.1.0

  • New: chests can be placed on top of (or against) other chests without planks or floors. Vanilla refuses it because a chest does not count as a building support; the new [Stacking] Enable switch (also needs [General] EnableAll) lets a chest aimed at a chest pass that one check. Chests never become real supports, so building stability is unchanged. Checked with the TestLab suite (the game's own placement test says Valid for a chest on a chest, Invalid with the switch off).
  • Fix: a chest placed on a chest was destroyed by the game about 30 seconds later (vanilla gives no building support from a chest). A chest under another chest now counts as support in the game's support check; chests still support nothing else.
  • New [Prefabs] SnapRange (default 1 m, vanilla 0.5): how close a snap point of the chest you hold has to be to another snap point before it locks on, so chests find their snap point sooner.
  • Fix: the side of a chest was refused as a "tilted surface" when you aimed at it, so a chest next to another chest (side by side, front to back) showed a red ghost. Aiming at a chest side is now accepted when you hold a chest.
  • Fix: chests that only touch along an edge or a corner showed a red ghost because the ghost was a few degrees off the placed chest. The chest you hold now takes the rotation of the chest it snaps to (the nearest quarter turn, so a turn you chose yourself is kept). New [Prefabs] AlignRotation (default on) switches it off.
  • Fix: the Grausten (ashlands) chest has a collider much smaller than the chest you see (the lid is not in it), so chests snapped into each other, stacked ones sank into the one below and a chest on top was destroyed. The snap box now also covers the closed, visible meshes (not the open lid), and a chest whose collider is smaller than its body gets one extra collider for the visible body. New [Prefabs] VisibleBounds (default on) switches this off.
  • New: the Grausten chest, the wardrobe, the barrel and the three pots (with their cracked and red variants) are built-in: they get snap points and stack like the other chests.
  • Fix: pots snapped about 0.2 m too high (staggered, floating, diagonal rows) because the game only looks for snap points on pieces whose colliders are on its piece layers, and pots keep theirs on the default layer. Pots now get the extra body collider on the piece layer, so their snap points are found like any chest.
  • New API for other mods: ChestSnappingApi.RegisterChest(prefab) makes their storage chests known (snap points and stacking). See the README.
  • Tested in game with the TestLab suite: for every chest type a stack of 3, 3 side by side, a row of 3 front to back and front to front, placed for real on wood floors on cleared ground (the game's support check runs; nothing is destroyed).

2.0.0

  • Tested in game with the full TestLab suite (6 tests): 3 green runs in a row on 2026-11-05, plus the ecosystem run with all 12 KydlDev mods loaded together.
  • Breaking: ChestSnapping now needs the KydlCore mod (hard dependency). Install KydlCore as well.
  • Ported to the KydlDev layout (feature switches, KY hub settings tab, TestLab suites). The snap points and console commands work as before. Checked in game on 2026-11-04 (clean start and quit with all mods loaded, no errors from this mod).
  • New config switches: [General] EnableAll, [Prefabs] Enable (snap points on chests) and [Offsets] Enable (apply the saved PrefabAdjustments). Switching them changes the chests that are already built, no restart needed.
  • The settings are a tab in the KY hub window of KydlCore (F6).
  • [DebugLog] Enable writes detailed lines to the BepInEx log.
  • Still client-side: the network check is VersionCheckOnly with exact version match when both sides have the mod (a player without it can still join).

1.0.0

First release.

  • Chests get 14 snap points that work with Valheim's built-in snap system: 4 bottom corners, 4 top corners and 6 face centers. Press Q / E while placing to cycle through them; the vanilla "Snapping: ..." message shows the active one.
  • Built-in support for the wood chest, reinforced chest, private chest and blackmetal chest.
  • Snap points are placed on the chest's real collider bounds, so chests snap flush against each other.
  • Modded chests: add any prefab name with the ExtraPrefabs config entry or the chestsnap_add console command (chestsnap_remove takes it out again, chestsnap_list shows candidates). ExcludedPrefabs opts prefabs out, and AutoDetectContainers can give every buildable container snap points automatically.
  • Adjustable snap points: per-prefab shift, grow and single-point offsets, saved in the PrefabAdjustments config entry. Console commands: chestsnap_shift, chestsnap_grow, chestsnap_point, chestsnap_reset, chestsnap_info.
  • chestsnap_show draws a sphere on every snap point so you can see what an adjustment does.
  • Changes to the config or the console commands apply to chests that are already built right away, no restart needed.
  • Client-side only: other players and servers do not need the mod.
  • Config file: BepInEx/config/com.kydldev.ChestSnapping.cfg.