PieceReplacer v1.1.9

Quality-of-life replacement modes for Valheim's Hammer.

Single replacement

1. Equip the Hammer.
2. Select the build piece you want to use as the replacement.
3. Aim at an existing compatible build piece.
4. Hold Left Alt and place normally.

The replacement is locked to the old structural slot while rotation stays under normal Valheim player control. Equivalent material prefabs are aligned by their snap-point geometry rather than assuming identical prefab pivots, and the exact visible preview transform is used for the final piece.

Connected surface replacement

v1.1 adds a batch mode for connected planar surfaces such as floors and walls.

1. Select the replacement piece with the Hammer.
2. Aim at one piece of the surface.
3. Hold Left Alt + Left Shift.
4. Review the batch information shown near the bottom of the screen.
5. Left-click to replace the complete connected surface.

A batch only follows pieces that:

• use the same source prefab as the aimed piece,
• lie on the same geometric plane,
• and share an actual snap-point edge with the next piece.

This means a wall around a 90-degree corner is treated as a separate surface and floor tiles that only touch diagonally at one corner are not merged.

The seed preview controls the rotation delta for the complete batch. For example, flipping the preview wall by 180 degrees flips every wall in that selected surface by 180 degrees relative to its previous orientation.

Batch material preview and validation

While Left Alt + Left Shift is held, PieceReplacer displays:

• number of pieces in the connected surface,
• source and replacement piece,
• total material requirement for the complete batch,
• how much of each material is currently available,
• missing amounts when the batch cannot be afforded.

The replacement is blocked unless the player has enough material for the entire batch before it starts. Old pieces are refunded only after the new batch has been placed, so refunds are not used to finance a partially completed replacement.

Removal permissions and required crafting-station range are checked for every piece before committing the batch.

Compatibility

Two pieces can replace each other when they are covered by an explicit safe group or when the automatic structural compatibility check accepts them.

Automatic checks use:

• Piece category,
• Valheim Hammer usage tags,
• functional components,
• local snap-point geometry.

Vanilla beam/pole families additionally have explicit safe compatibility for horizontal 1/2/4 m pieces, 26°/45°/67° angled beams, and vertical 1/2/4 m poles. This avoids false negatives caused by material variants with different local snap layouts.

Safety defaults

AllowBoundsFallback = false by default. Pieces without enough snap points are therefore not automatically matched solely because their visual size happens to be similar.

Connected-surface replacement has a default maximum of 250 pieces. If a surface exceeds that limit the operation is blocked rather than silently replacing only part of it.

Build

.\build.ps1

Build and install:

.\build.ps1 -Install

Config

Generated at:

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

Important settings:

[General]
ModifierKey = LeftAlt
BatchModifierKey = LeftShift

[Compatibility]
AutoCompatibility = true
RequireSameCategory = true
RequireSameUsageTags = true
SnapPointTolerance = 0.035
AllowBoundsFallback = false
BoundsTolerance = 0.075

[Batch Replacement]
Enabled = true
MaxPieces = 250
ConnectionTolerance = 0.08
PlaneTolerance = 0.12
ShowHud = true

For diagnostics, set DebugLogging = true.

v1.1.1 wall compatibility fix

Straight wall size families now have explicit Vanilla compatibility overrides for:

• full 2x2 walls
• half 1x2 walls
• quarter 1x1 walls

This fixes material replacement cases where equivalent wall variants use different prefab-local snap geometry. Full, half and quarter walls remain separate groups so differently sized walls cannot replace each other.

v1.1.2 Vanilla compatibility audit

Direct material equivalents for roofs, roof corners/ridges, triangular gable walls, roof crosses, floors, stairs and additional beam variants now use explicit safe compatibility groups. This avoids false negatives when Vanilla prefabs use different local snap/pivot data while keeping angles and shapes strictly separated.

Replacement transaction safety (v1.1.9)

Repeated single replacements use shortened safety windows (0.10 s + 0.05 s + 0.05 s) so the next beam can be replaced quickly while spawn/support/removal verification and rollback remain active. Single-piece replacement now keeps the original piece until the new piece has survived both a short network stabilization window and a support-isolation check. This is particularly important for vertical beams/poles on dedicated servers, where an overlapping replacement can otherwise exist only optimistically or temporarily inherit support from the piece being replaced.