BuildPiecesCustomized

BuildPiecesCustomized

Customize individual Valheim build pieces, apply common properties globally, and adjust structural material properties.

Features

• Customize individual piece properties, including enabled state, name, description, requirements, placement rules, durability, targeting, and Hammer usage tags.
• Apply common properties globally through prefab lists.
• Change material support properties to build higher or farther.
• Load JSON, YAML, and YML piece configuration files from the plugin directory or BepInEx/config/shudnal.BuildPiecesCustomized.
• Synchronize server-controlled configuration and reapply changes when configuration files change.

Hammer usage tags

Valheim 1.0 uses Piece.UsageTagFlags for the main Hammer build menu filters. BuildPiecesCustomized does not reassign legacy PieceCategory values.

Individual piece files can define usageTags:

usageTags:
  - Building
  - Doors

usageTags is a full replacement:

• If usageTags is omitted, the piece keeps its original usage tags.
• If usageTags is present, the listed built-in tags replace the current tag set.
• usageTags: [] clears all usage tags.
• Tag names are case-insensitive when loading.
• Only built-in Valheim Piece.UsageTagFlags names are supported. Numeric masks and custom runtime tags added by other mods are not supported.
• Unsupported custom tags remain untouched while usageTags is omitted. Setting usageTags replaces the mask with built-in tags only.

The generated Pieces and properties.md file contains the currently supported tag names, their localized in-game names, and the current tags of every discovered piece.

Bulk usage tag configuration

For centralized overrides, create Piece usage tags.yaml, Piece usage tags.yml, or Piece usage tags.json.

A single file can configure tags in both directions:

pieces:
  wood_door:
    - Building
    - Doors
  custom_piece: []

tags:
  Defense:
    - h_drawbridge01
    - hayzestake_01

The two sections have different semantics:

• pieces: prefab -> tags. The list fully replaces the piece's usage tags.
• tags: tag -> prefabs. The tag is added to every listed piece without removing its other tags.

The bulk usage-tag file has higher priority than individual piece files. Processing order is:

1. Individual piece usageTags.
2. Bulk pieces replacements.
3. Bulk tags additions.

This allows a piece to receive a complete tag set in pieces and then receive additional shared tags from tags in the same file.

If more than one fixed-name bulk file is found, the last file in configuration search priority is used. The config directory is processed after the plugin directory.

The old Piece categories.json / YAML format is no longer supported.

Setting global values

There are several global lists set in the main config:

• Clip everything
• Allow in dungeons
• Can be removed
• Ash and lava immunity
• Heavy snow immunity
• Water and rain damage immunity
• Structural integrity
• Is roof
• Is leaky (non-roof)
• Disabled pieces

All lists are comma-separated prefab names. If a prefab is present in a global list, that value overrides the corresponding individual setting.

Use AllPieces to apply a supported global rule to every piece. Disabled pieces does not use AllPieces.

Material properties

Material groups provide multipliers for:

• Max support multiplier - support provided when grounded.
• Min support multiplier - minimum support before the piece breaks.
• Vertical stability multiplier - increases or decreases vertical building stability.
• Horizontal stability multiplier - increases or decreases horizontal building stability.

A value of 1.0 keeps the vanilla material behavior.

Automatically generated documentation

When the main menu or a world initializes, Pieces and properties.md is generated in BepInEx/config/shudnal.BuildPiecesCustomized.

It contains:

• Supported usageTags and their localized Hammer category names.
• The bulk usage-tag file format and precedence rules.
• Supported enum identifiers for other configurable properties.
• All discovered build-piece prefab names.
• Current usage tags for every listed piece.

Regenerate it at any time with:

bpcdocs

Setting individual values

Generate a template for one piece:

bpcsave [prefab name]

Generate templates for multiple pieces using a partial name or wildcard:

bpcsaveall [prefab partial name or wildcard *]

Files are created in BepInEx/config/shudnal.BuildPiecesCustomized using JSON by default or YAML when Save piece data as YAML is enabled.

You can remove every property you do not want to override. Missing properties preserve the default value captured from the piece prefab.

Configuration files can be placed in subdirectories under either the plugin directory or BepInEx/config/shudnal.BuildPiecesCustomized. Files placed on the server are synchronized to clients according to ConditionalConfigSync policy.

Live configuration reload and build-menu compatibility

Only piece JSON, YAML, and YML files trigger a live reload. Documentation, logs, package manifests, and obsolete Piece categories files are ignored. Changes arriving close together are combined into one reload after a short quiet period. Rewriting identical configuration does not reapply pieces or publish another identical local configuration snapshot.

An unreadable or malformed file keeps the previous complete configuration active. The loader retries transient read failures three times and then logs the failure; fixing the file triggers another attempt. Delete a configuration file, or use an empty object, to remove its overrides. An empty file is not treated as a valid replacement.