ChunkedSaveFix

ChunkedSaveFix

Server-side BepInEx plugin for Valheim public-test chunked-save worlds.

This plugin was created to mitigate a Valheim public-test 0.221.13 chunked-save issue where stale chunk mappings could remain in the.chunks manifest and cause duplicated world objects after reloads.

Status

Public beta.

Use it carefully and keep backups. The repair tools were tested against the public-test 0.221.13 chunked-save format.

What it does

Preventive fix

By default, the plugin removes stale chunk mappings marked as sizeChanged before the.chunks manifest is written.

This is controlled by:

[Fixes]

RemoveSizeChangedChunks = true

Repair tools

The plugin can also scan and repair exact duplicate ZDO save clones.

Repair is disabled by default for public safety.

[Repair]

RepairMode = Disabled

ForceFullRepairSave = false

Supported repair modes:

• Disabled: no duplicate scan or repair.
• ScanOnly: logs duplicate save clones but does not remove anything.
• FilterSaveExact: removes exact duplicate ZDO save clones from the save output before chunk files are written.

Important safety notes

Back up the full world folder before enabling repair modes.

Do not enable ForceFullRepairSave permanently. It is a one-shot repair tool. Turn it off after the repaired world has loaded correctly.

This plugin is server-side. Clients do not need to install it.

Recommended safe default

[General]

Enabled = true

[Fixes]

RemoveSizeChangedChunks = true

[Repair]

RepairMode = Disabled

ForceFullRepairSave = false

PruneManifestToFullRepairChunks = true

RepairIncludePortals = false

PositionPrecision = 100

RotationPrecision = 10000

MaxRemovalsPerSave = 0

TopGroupsToLog = 10

[Diagnostics]

Verbose = false

TopChunksToLog = 0

LogManifestOverlaps = false

One-shot full repair flow

Use this only if your world already has duplicated objects.

• Stop the server.
• Back up the world folder.
• Start the server with the plugin once so the config file is generated.
• Stop the server again.
• Edit the config:

[Repair]

RepairMode = FilterSaveExact

ForceFullRepairSave = true

PruneManifestToFullRepairChunks = true

RepairIncludePortals = false

MaxRemovalsPerSave = 0

• Start the server and let it save once.
• Restart the server.
• Verify the world visually and check the logs.
• Turn off the full repair flag:

[Repair]

ForceFullRepairSave = false

You may keep this afterward as a preventive belt-and-suspenders mode:

[Repair]

RepairMode = FilterSaveExact

ForceFullRepairSave = false

Or disable duplicate filtering completely:

[Repair]

RepairMode = Disabled

ForceFullRepairSave = false

Logs to look for

During a full repair you should see messages like:

[FullRepair] ForceFullRepairSave active

[DedupeSave] Mode=FilterSaveExact

[DedupeSave] Removed X duplicate ZDO save clone(s)

[FullRepair] Pruned X stale manifest chunk(s)

After the world is repaired and ForceFullRepairSave=false, healthy saves should show no large duplicate removal.

Install

Copy the plugin DLL into your server BepInEx plugins folder:

BepInEx/plugins/FixSave.dll

Restart the server.

Build from source

This project is intended to be built with Docker. You do not need to install.NET locally.

• Build the Valheim mod builder image

From the repository root:

docker buildx bake --no-cache --load \

--set default.args.VALHEIM_BRANCH=public-test \

--set default.args.VALHEIM_BETA_PASSWORD=yesimadebackups

This prepares the local valheim-mod-builder:dev image with the public-test Valheim assemblies and BepInEx dependencies required by the Cake build.

• Build the plugin

From the repository root:

docker run --rm -it \

-v "$PWD:/work" \

-w /work \

valheim-mod-builder:dev \./build.sh --configuration=Release

The compiled DLL is written to:

output/FixSave.dll

• What build.sh does

build.sh runs inside the valheim-mod-builder:dev container. It should not start another Docker container.

Expected content:!/usr/bin/env bash

set -euo pipefail

cd "$(dirname "${BASH_SOURCE[0]}")"

export DOTNET_SKIP_