palworld-save-tools

Tools for converting Palworld .sav files to JSON and back.

This tool currently supports additional parsing of the following data in the Level.sav not handled by uesave or other non-Palworld aware Unreal save editors, emcompassing almost all known data structures as of Palworld v0.1.4.0:

1. GroupSaveDataMap
   • Groups such as in-game organizations and guilds
2. CharacterSaveParameterMap
   • Characters such as players and pals
3. MapObjectSaveData
4. ItemContainerSaveData
5. CharacterContainerSaveData
6. DynamicItemSaveData
7. FoliageGridSaveDataMap
8. BaseCampSaveData
9. WorkSaveData

Instructions

[!IMPORTANT] Converting Level.sav files to JSON will result in very large files, and may require significant amounts of RAM to process. Use a modern text editor such as Visual Studio Code or a Jetbrains IDE to open these files.

Prerequisites

1. Python 3.9 or newer.
   • Windows users: You can install Python 3.12 from the Microsoft Store or from python.org

Windows GUI steps

1. Download the latest release from [https://github.com/cheahjs/palworld-save-tools/releases/latest].
2. Unzip the file into a folder.
3. Drag and drop your .sav file (for Steam on Windows, these are located at %LOCALAPPDATA%\Pal\Saved\SaveGames\<SteamID>\<SaveID>) onto convert.cmd to convert the file into JSON.
4. To convert the .sav.json file back into a .sav file, drag and drop your .sav.json file onto convert.cmd.

[!NOTE] In the event that the convert.cmd fails to function correctly, try to disable Python's app execution aliases ("Manage app execution aliases"), or failing that, please use the Terminal instructions below

Terminal

1. Download the latest release from [https://github.com/cheahjs/palworld-save-tools/releases/latest].
2. Unzip the file into a folder.
3. Open a terminal in the folder you just unzipped.
4. Depending on how Python is installed, the next steps should use either python, python3, or py.
5. Run python convert.py <path to .sav file> to convert the .sav file to a .sav.json file.
6. Run python convert.py <path to .json file> to convert the .sav.json file to a .sav file.

[!NOTE] On Windows, you can drag and drop the convert.py file and the .sav/.sav.json file to avoid typing out the path.

Additional command line arguments:

1. --to-json: Force SAV to JSON conversion regardless of file extension
2. --from-json: Force JSON to SAV conversion regardless of file extension
3. --output: Override the default output path
4. --minify-json: Minify output JSON to help speed up processing by other tools consuming JSON
5. --force: Overwrite output files if they exist without prompting
6. --custom-properties: Comma-separated list of paths from paltypes.py to decode. This can be used to ignore processing of types that are not of interest. For example --custom-properties .worldSaveData.GroupSaveDataMap,.worldSaveData.CharacterSaveParameterMap.Value.RawData will only parse guild data and character data.

Developers

This library is available on PyPi, and can be installed with

pip install palworld-save-tools

[!NOTE] Due to ongoing rapid development and the potential for breaking changes, the recommendation is to pin to a specific version, and take updates as necessary.

Roadmap

• [ ] Parse all known blobs of data
• [ ] Optimize CPU and memory usage

Development philosophy

• No additional dependencies. Scripts should run with a default install of Python. Distributing binary builds of Python is laden with AV false positives.
  • Optional dependencies are allowed, for example switching out the stdlib's JSON library for something more performant.
• Correctness of the conversion process is more important than performance. SAV > JSON > SAV should yield bit-for-bit identical files (pre-compression).

Projects that make use of palworld-save-tools

[!NOTE] This does not serve as an endorsement of any of these projects, use at your own risk.

• xNul/palworld-host-save-fix - Migrating save data between player IDs (eg, converting coop saves to dedicated server saves)
• PalEdit - GUI for editing Pals
• palworld-server-tool - Managing dedicated servers via RCON and SAV file parsing
• palworld-server-toolkit - Assorted set of SAV file manipulations