Valheim Save Tools
This repository contains two projects.
- A command line interface tool that converts Valheim save files to and from JSON and processes them.
- A Java library that can be used in your own Java projects.
The following formats are supported:
- World data files (.db)
- World metadata files (.fwl)
- Character files (.fch)
Running the Command Line Interface tool
There are three ways to get the CLI Tool:
- Download the Latest release,
- Download a snapshot build (click on a commit and find the artifact in the bottom)
- Build the project yourself (see further down)
When you've got your flavour of valheim-save-tools.jar, make sure you have Java 11 installed, and use it as follows:
usage: java -jar valheim-save-tools.jar <infile> [outfile] [--addGlobalKey
<arg>] [--cleanStructures] [--cleanStructuresThreshold <arg>]
[--failOnUnsupportedVersion] [--listGlobalKeys] [--removeGlobalKey
<arg>] [--resetWorld] [--skipResolveNames] [-v]
--addGlobalKey <arg> Adds a global key (.db only)
--cleanStructures Cleans up player built structures
(.db only)
--cleanStructuresThreshold <arg> Minimum amount of structures to
consider as a base (default 25)
--failOnUnsupportedVersion Fail when input archive version is
newer than known supported
--listGlobalKeys List global keys (.db only)
--removeGlobalKey <arg> Remove a global key, specify 'all'
to remove all (.db only)
--resetWorld Regenerates all zones that don't
have player-built structures in
them (experimental, .db only)
--skipResolveNames Do not resolve names of prefabs and
property keys (faster for
processing, .db only)
-v,--verbose Print debug output
<infile>: Input file of type .fch, .db, .fwl or .json
<outfile>: Output file of type .fch, .db, .fwl or .json (optional)
Processors
A handful of built-in processors are included. They are executed in the order they are documented.
Global Keys
Use --listGlobalKeys to list all the global keys in a .db file. With --removeGlobalKey <arg> global keys can be removed. Specify --removeGlobalKey all to clear all global keys. --addGlobalKey <arg> can be used to add a global key.
CleanStructuresProcessor
Usage: --cleanStructures
This will attempt to remove any bases with structures smaller than the threshold. By default this threshold is 25 buildings, but it can be configured with --cleanStructuresThreshold <arg>.
The processor first flags all chunks where:
- The chunk itself contains at least 25 building pieces
- The chunk and all neighbouring chunks contain at least 25 building pieces.
Only buildable pieces count towards this number. Excluded are:
- Dig / Raise actions
- Farms
- Paths and roads
Then it will find and flag any connecting chunks with player built changes in them. This includes farms, paths between bases, etc.
Ships will be left alone.
Any chunks that are not flagged will be cleared of player built structures.
It works great as a preprocessor for ResetWorldProcessor to first remove smaller bases (for example temporary beds / campfires outside a crypt).
ResetWorldProcessor
Usage: --resetWorld
This will attempt to reset the generation state of all chunks and locations, except for:
- Zones with player-built structures
- Zones with boss stones
Flags
--failOnSupportedVersion
The program will exit with code 1 when a version is detected that is higher than the last known supported version. When you automated processing of save files, for example on an auto-updated server, this might come in handy in order to not lose any information / corrupt your save files.
--verbose
Some processors listen to this flag to show more information about the process.
--skipResolveNames
Property keys and prefab names are present in a hashed form in the save file. By default, an attempt is made to look them up in a reverse lookup table of known texts. For processing, this can be disabled in order to improve processing performance and decrease memory usage.
Building
Build the project with gradlew build, a jar build/libs/valheim-save-tools.jar with all dependencies included will be created.
This project uses Lombok (https://projectlombok.org/) to prevent boilerplate code. To fix compilation errors in your IDE (Eclipe, IntelliJ), make sure you have a plugin installed for that.
Using the library in your Java project
From version 1.0.4, the library is published as a Maven package to Github packages. See https://github.com/Kakoen?tab=packages&repo_name=valheim-save-tools
Gradle
Include the following in your build.gradle file to use valheim-save-tools-lib as a dependency.
repositories {
maven {
url = uri("https://maven.pkg.github.com/kakoen/valheim-save-tools")
credentials {
username = System.getenv("GITHUB_ACTOR")
password = System.getenv("GITHUB_PACKAGES_READ_TOKEN")
}
}
}
dependencies {
implementation group: 'net.kakoen.valheim', name: 'valheim-save-tools-lib', version: '1.0.4-SNAPSHOT'
}
This requires two environment variables:
GITHUB_ACTORYour Github usernamePACKAGES_READ_TOKENA Github token with at leastread:packagesaccess. Generate one at https://github.com/settings/tokens
Maven
See https://docs.github.com/en/packages/guides/configuring-apache-maven-for-use-with-github-packages adding the Github repository and setting up authentication for it.
You'll need to add repository url: https://maven.pkg.github.com/kakoen/valheim-save-tools
And then add the following dependency:
<dependency>
<groupId>net.kakoen.valheim</groupId>
<artifactId>valheim-save-tools-lib</artifactId>
<version>1.0.4-SNAPSHOT</version>
</dependency>
3 Apr 28, 2022
11 Oct 9, 2022
4 Feb 7, 2022
385 Dec 30, 2022
4 Oct 21, 2022
7 Oct 15, 2021
7 Dec 15, 2021
16 Jul 27, 2021
206 Dec 17, 2022
13 Apr 13, 2022
26 Nov 16, 2022
243 Jan 4, 2023
7 May 8, 2022
36k Jan 9, 2023
2 Jan 31, 2022
660 Jan 6, 2023
125 Jan 4, 2023
16 Aug 23, 2020