PieceReplacer

PieceReplacer is a quality-of-life building mod for Valheim that lets you replace compatible building pieces directly in place.

Instead of destroying a piece and manually rebuilding it, select the replacement piece with the Hammer, aim at the existing piece, hold Left Alt, adjust the rotation if needed, and place it.

Features

• Replace compatible building pieces directly in place
• Preserves the exact target position
• Keeps rotation under player control
• Uses the visible placement preview for the final result
• Uses normal Valheim building costs
• Refunds the replaced piece through Valheim's normal removal flow
• Supports floors, walls, beams, poles, roofs, stairs, and other compatible structure pieces
• Automatic compatibility detection for structurally matching pieces
• Explicit replacement groups can be configured as overrides
• Designed for multiplayer-safe Valheim placement/removal behavior
• No Jötunn dependency required

Usage

1. Equip the Hammer.
2. Select the building piece you want to build.
3. Aim at a compatible existing building piece.
4. Hold Left Alt.
5. Rotate the preview normally if required.
6. Left-click to replace the old piece.

The replacement is placed at the target position using the rotation currently shown by the placement preview.

Example

Replace a wooden floor with an Ashwood floor without manually realigning it:

• Select the Ashwood floor
• Aim at the existing wooden floor
• Hold Left Alt
• Left-click

The same workflow applies to other compatible structural pieces.

Installation

Thunderstore / r2modman

Install PieceReplacer through your preferred Thunderstore-compatible mod manager.

Manual installation

1. Install BepInEx for Valheim.

2. Copy PieceReplacer.dll into:

   Valheim/BepInEx/plugins/PieceReplacer/

3. Start Valheim.

Configuration

After the first launch, the configuration file is created in:

Valheim/BepInEx/config/uk.ainzworth.valheim.piecereplacer.cfg

Configuration options include replacement behavior, explicit compatibility groups, and debug logging.

Compatibility

PieceReplacer primarily targets structural Hammer pieces.

Automatic replacement compatibility checks are intentionally conservative to avoid invalid replacements such as:

• walls -> doors
• floors -> roofs
• short beams -> long beams
• walls -> poles

Pieces that share compatible structural geometry can be replaced even when they use different materials.

Troubleshooting

If a compatible-looking piece cannot be replaced, enable debug logging in the PieceReplacer configuration file and inspect:

Valheim/BepInEx/LogOutput.log

This can be used to identify why a particular pair was rejected by the compatibility check.

Requirements

• Valheim
• BepInExPack for Valheim

License

All rights reserved unless otherwise stated by the package author.

1.1.12

• Exclude diagonal-only batch contacts by default, including thick slabs sharing a vertical corner edge.
• Add [Batch Replacement] IncludeDiagonalConnections (default false) to opt into corner contacts.
• Retain side connections and linear beam endpoints. Snap envelopes are compared in piece-local coordinates.
• 19 stand-in checks passed; game-reference build has 0 warnings/errors. In-game verification pending.

1.1.11

• Allow connected batches for beams and other compatible non-planar pieces, using shared snap points. Planar groups retain their plane/edge restrictions; batches still select one source prefab.
• MaxPieces remains 250 by default; 0 disables the configurable performance guard.
• Revalidate on click and show all removal/station blockers with local red outlines for four seconds. No piece materials or network state are changed by these markers.
• Release build passed with 0 warnings/errors. In-game connectivity and visual validation pending.

1.1.10

• Batch material checks use the patched Hammer requirement path with full batch quantities, allowing AzuCraftyBoxes container supplies and restrictions to participate.
• The batch HUD distinguishes container-backed availability from inventory counts.
• Surface recognition uses planar snap geometry, reads canonical prefab geometry, and accepts thick slabs with a 1:2 thickness ratio.
• Verification: 13 stand-in regression checks and game-reference Release build, 0 warnings/errors. Live game validation remains pending.

Changelog

1.1.9

• Reduced the single-replacement transaction lock from roughly 1.0 s of fixed safety windows to roughly 0.2 s.
• Placement stabilization is now 0.10 s instead of 0.50 s.
• Support-isolation and post-removal verification are now 0.05 s each instead of 0.25 s.
• All spawn, support, removal and rollback checks remain enabled; only the deliberately conservative waiting windows were shortened.
• This makes rapid beam-by-beam replacement responsive again now that v1.1.8 fixed the actual pivot/snap alignment cause of the missing vertical replacements.

1.1.8

• Fixed replacement positioning for equivalent prefabs that use different local root pivots.
• Single replacement previews are now aligned by structural snap-point centroid instead of blindly copying the old prefab root position.
• Fixes rotated/vertical beam replacements where the new piece could be successfully spawned at an offset, causing the old beam to be removed while the replacement appeared to be missing.
• Applied the same pivot-aware alignment to connected batch replacements.
• Added debug diagnostics that report the applied pivot correction in metres.

1.1.7

• Added a 0.5 s replacement stabilization window before the original piece may be removed.
• Added a support-isolation preflight: the original piece colliders are temporarily disabled and the replacement must survive before the original is deleted.
• Forces WearNTear.UpdateSupport through reflection during the isolation/post-removal checks.
• Added a post-removal survival check and clearer failure logging for multiplayer/network races.
• Specifically hardens vertical beam/pole replacement against the case where the old piece disappeared but the new piece did not persist.

1.1.6

• Fixed a critical replace-only safety issue where holding the replacement modifier could fall back to normal Valheim placement when no compatible target was resolved.
• Improved targeting for thin beams/supports mounted directly on walls by searching compatible overlapping hits near the frontmost aimed piece.
• Updated Valheim 1.0 usage-tag access from Piece.m_usageTags to Piece.m_usage with a legacy fallback.
• Added post-removal verification and rollback so a failed removal cannot permanently leave the new and old piece occupying the same slot.

1.1.5

• Replaced deprecated UnityEngine.Object.FindObjectsOfType<Piece>() calls with FindObjectsByType<Piece>(FindObjectsSortMode.None).
• Removes the two Unity CS0618 build warnings from placement verification.
• Uses unsorted object lookup because PieceReplacer does not rely on InstanceID ordering, avoiding unnecessary sorting overhead.
• No gameplay or compatibility behavior changed from 1.1.4.

1.1.4

• Made single-piece replacement commit safe: the original piece is no longer removed merely because TryPlacePiece returned success.
• Added post-placement verification of the requested replacement prefab, captured position and rotation before the original piece is removed.
• Verification ignores the placement ghost and any matching instance that already existed before the placement attempt.
• Verification retries for several frames and requires the new piece to survive an additional frame before removal of the original target.
• If placement cannot be verified, the original piece remains intact and the BepInEx log records the failed verification.
• Added detailed debug logging for target/replacement prefab, captured transform, vanilla placement result and verified spawned instance.
• Regression target: horizontal 2 m Wood Beam -> horizontal 2 m Ashwood Beam.

1.1.3

• Fixed Valheim 1.0 build references for the connected-surface HUD.
• Added assembly_guiutils.dll, which now contains Valheim's Localization implementation.
• Added UnityEngine.TextRenderingModule.dll, required by IMGUI TextAnchor.
• No gameplay or compatibility behavior changed from 1.1.2.

1.1.2

• Audited Vanilla direct-equivalent build-piece families for the same snap/pivot false-negative seen on beams and half walls.
• Added explicit compatibility for Thatch <-> Darkwood roof panels, inner corners, outer corners and ridges at 26°, 45° and 67°.
• Added explicit compatibility for Wood/Ashwood/Scalewood triangular roof-wall pieces at 26°, 45° and 67°, with inverted variants kept separate.
• Added explicit compatibility for Wood/Ashwood/Timber roof crosses at 26°, 45° and 67°.
• Added guaranteed Wood <-> Ashwood floor 1x1/2x2 and standard stair compatibility independent of user config.
• Added Ashwood alternate angled-beam prefabs and decorated Timber beam/pole variants to their matching structural groups.
• Kept all angle, size, corner type and inverted/non-inverted families isolated to prevent unsafe cross-shape replacements.

1.1.1

• Fixed half-wall replacement between Vanilla material families.
• Added explicit compatibility groups for full 2x2, half 1x2 and quarter 1x1 straight walls.
• Kept wall sizes strictly separated to prevent invalid cross-size replacements.

1.1.0

• Added connected planar-surface replacement with Left Alt + Left Shift.
• Added connected floor/wall detection using plane alignment and shared snap-point edges.
• Added total batch material calculation and inventory availability checks.
• Added bottom-screen batch HUD with piece count, total costs and missing materials.
• Batch replacement is blocked unless the complete material cost is available before starting.
• Added per-piece removal permission and crafting-station validation before a batch commit.
• Added configurable maximum batch size, connection tolerance, plane tolerance and HUD toggle.
• Batch rotation uses the visible seed preview as a delta applied to the complete surface.

1.0.1

• Added explicit safe compatibility for horizontal, 26°, 45°, 67° and vertical Vanilla beam/pole families.

1.0.0

• Initial public release.