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.

1. Stop the server.
2. Back up the world folder.
3. Start the server with the plugin once so the config file is generated.
4. Stop the server again.
5. Edit the config:

[Repair]
RepairMode = FilterSaveExact
ForceFullRepairSave = true
PruneManifestToFullRepairChunks = true
RepairIncludePortals = false
MaxRemovalsPerSave = 0

1. Start the server and let it save once.
2. Restart the server.
3. Verify the world visually and check the logs.
4. 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.

1. 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.

2. 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

3. 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_FIRST_TIME_EXPERIENCE=1
export DOTNET_CLI_TELEMETRY_OPTOUT=1
export DOTNET_NOLOGO=1

dotnet tool restore
dotnet cake "$@"

4. Cake build behavior

The Cake build:

• reads the plugin version from FixSave/BalguitoFixSave.csproj;
• generates FixSave/PluginInfo.g.cs;
• updates manifest.json version_number;
• publicizes Valheim assemblies when needed;
• builds the plugin into output/.

FixSave/PluginInfo.g.cs is generated and should not be committed.

Recommended .gitignore entry:

FixSave/PluginInfo.g.cs

5. Rebuild

To force a clean rebuild:

docker run --rm -it \
  -v "$PWD:/work" \
  -w /work \
  valheim-mod-builder:dev \
  ./build.sh --target=Rebuild --configuration=Release

Compatibility

• Valheim public-test 0.221.13 chunked saves: tested.
• Other Valheim versions: not guaranteed.
• Client install: not required.

License

GPL-2.0-only.