Paver 2.0.14 - Save Editor and Reporting Tool  

Paver: A Palworld Save Editor
A comprehensive and extensible save editor and reporting tool for Palworld, intended to work with any version of Palworld v0.1.2.0 and above. Point it to your save directory (where your Level.sav is) and go!

One of the main goals with this project was for end-users to be able to generate reports of their world & players state and make any changes they want, without needing to touch the SAV or JSON or find the correct nested keys. One wrong type or value can break your save or server, so I wanted to try to remove some of the complexity. Further, Paver operates with a "safety-first" mindset, and only makes changes to the SAV files when it's sure there are no errors.

As of v2.0.14, this project is now considered "stable" in that it has accomplished its desired safety-first goals and provides a safe mechanism through which to update save files, and in an easier manner than manually doing so yourself (yes, the config.json is annoying sometimes but its still better than searching 200K+ lines in a SAV file to change a value you need). That said, nothing in life or programming is perfect, so I'll always recommend making a backup of your save before using this tool.

Questions? Bugs? Ideas? Join the Paver Discord

========================

Key Features:

• Save Editing, ofc: Add a config file with a path to your save directory and the changes you want (to the world, or to players), and Paver will make it happen! The config abstracts away a lot of the manual work for you  - for example, when you adjust a player's level, it auto-calculates and adjusts their exp values, too. Many common changes/usecases are already supported, and more are planned and on the way (they just didn't make it into the first release).
• Modify Player Appearance: That's right - you can't change your appearance ingame, but you can with Paver! Change your player's body type, hair, head, name, & more (color changes coming in next feature release).
• Built-In, Modular Reporting: Paver can optionally run read-only (or not) and generate reports on your save, players, and more to be added. Reporting inclusions are modular and can be added to or removed from the config file as you see fit. Paver can also detect and report when players in your world save are missing matching Player save files or other important data. There are plans to further add reporting for VAC bans, usage of too many perf-degrading resources/items/Pals, etc.
• Incremental Changelog: Reports of Paver include changelogs, so you know exactly what was changed, when, and where down to the line.
• Highly Customizable: The bare minimum requires only a single line in a config file (pointing to your save directory), but there are a dozens of options to tailor Paver to your needs (and more planned).
• Automatic SAV<>JSON conversion (optional): Paver uses @cheahjs/palworld-save-tools to convert your save to JSON, and back again. Paver provides the option to retain both the SAV and the JSON, making it easy for you to verify changes, run other mods, etc. Conversion is optional: as long as you already have your SAV converted to JSON, Paver can work with that too!

• Run as an executable (Windows), or a Node app: Most users likely want Paver as an executable, but for advanced usage and more control, Paver was built in and is available to be run as a NodeJS app. See the Github for details.

Prerequisites:
You do not need to know Python, etc to use Paver. The requirements below are *dependencies* - like an engine is to a car, they're necessary for Paver to run. Just like you don't need to be a mechanic to drive a car from point A to B, you don't need to know how these work or how to code in order to use Paver - they're "under the hood".

• @cheahjs/palworld-save-tools and Paver both require Python 3.9 or newer.
  
  • Windows users: You can install Python 3.12 from the Microsoft Store or from python.org
  • See the palworld-save-tools README for updates and more information; CheahJs' tools are used for converting save files to and from JSON.
  • Paver uses Python in a couple of places when aggregating your changes back into a cohesive save file.
• Paver uses "ijson", a Python module, during the save conversion process. Paver will attempt to install this for you, but a couple of notes:
  
  • This is not needed if your save files are already in JSON format.
  • If you see errors about "ijson", or see an error related to "helpers/updatePlayersInLevelSav.py", you can workaround this by install "ijson" yourself. Just open command prompt, type "pip install ijson", and hit enter. Then restart Paver and you should be good!

Getting Started: Run Paver!

• Install any necessary prerequisites (see above).
• Download the latest release. For most users, you'll want to grab the zip file, which includes an exe and some helper files. Once downloaded, extract the zip file to a location of your choice.
• Create a config file, or run Paver once to create one for you. The config file is a JSON file (usually "config.json" in the same directory as Paver) that tells Paver what to do, what you want to change, etc. Later, we'll likely have a nice UI that does the config file stuff for you so you don't have to, but for now, this is what we have (and it's still way simpler and efficient than making the changes yourself) The contents of the file should look something like this:
  { "gameSaveDirectoryPath": "C:\\path\\to\\your\\save\\directory" }

  Only this first field, "gameSaveDirectoryPath", is required. All other fields are optional. This field can be a relative path (like "./my-save") or an absolute path, like "C:\\my\\path", but note that you'll need to escape your backslashes - so "C:\my\path" must be written as "C:\\my\path".

Advanced: Need to change the config file location?
Add the config flag to the command to specify a different config file location or name. For example, `paver.exe config=./my-config.json`. Alternatively, if you want to run Paver from source (e.g. in Node/Python), you can! Check out the Paver Github to learn more.

Now just run Paver (the exe)! 

• • It will pick up the config file you created and start working based on what you've added. Check out the 

Examples

•  below to see some common use cases.

Config Examples

Making basic changes to a single player:

Let's give player "Lent" 42 Technology Points and add 10 Stat Points to his HP. Also, make sure his friend, G goes to leg day - set his leg size to 0.8 and change his hair type.
{
  "gameSaveDirectoryPath": "C:\\path\\to\\your\\save\\directory",
  "changesToMake": {
    "enableGuardrails": true,
    "players": [
      {
        "handle": "Lent",
        "techPoints": 42,
        "statusPoints": {
          "health": 10
       },
       {
         "handle": "Ghostpixel",
         "appearance": {
           "legSize": 0.8,
           "hairType": "type12"
         }
       }
     ]
  }
}

Note the "enableGuardrails" option. This is enabled by default, and it will help make sure you don't set something wrong (for example, make sure you don't set legsize to "fdjsklfajs"). If you're confident in your changes, or you want to play with values that go beyond the game defaults (level 100, anyone?), just set this to false.

All of the above values we're changing include references to deeply nested keys in the save files, and often depend on multiple values - Paver handles all of this for you. You don't ever have to touch the SAV or JSON files or worry about the exact nested keyname of the field you want to change.

Generating reports

By default, Paver automatically generates reports for you in a ./reports directory that include a summary of your world data, analysis on your players, and a list of any changes you've attempted (including whether they're successful, failed, and what they attempted to modify).

You don't *have* to make changes - you can opt to just have Paver just generate reports. Here's an example with some specific things toggled on/off:

{
  "gameSaveDirectoryPath": "C:\\path\\to\\your\\save\\directory",
  "reporting": {
    "export": true,
    "exportPath": "./reports",
    "showSummary": true,
    "showPlayerData": true,
    "showCapturedPals": true,
    "showPlayerUnlockedRecipes": false,
  }
}

In the above case, we're showing some things but specifically saying we don't want to include each player's unlocked recipes list in our export. The above will not attempt to make any changes to your save, since only reporting options are specified.

Changing levels and names

There's a little more nuance here, but it's still easy! Let's start with level. Note that "level" is mostly just a number in Palworld. Your total experience also needs to change, or you'll receive future XP as if you're a different level. For example, if we set a level 1 player to level 40, they'll be 40 but only gain XP as if they're level 1 - meaning going from 40 to 41 will take the same amount of XP as going from 1 to 40!

This is probably not what we usually want, right? No problem - Paver calculates the exp for you! If you set the level field and do not specify an explicit exp value, Paver will determine how much XP that level should have and adjust that for you.

In the example below, we are changing Lent's name to Seraph, and setting his level to 40:

{
  "gameSaveDirectoryPath": "C:\\path\\to\\your\\save\\directory",
  "changesToMake": {
    "enableGuardrails": true,
    "players": [
      {
        "guid": "e1337m8e-0000-0000-0000-000000000000",
        "handle": "Seraph",
        "level": 40
       }
     ]
  }
}

Notice something else above? We also specified the player's unique "guid". In order to change a player's name, a GUID must be specified - this is to ensure we can properly track the player's other changes even after the name has changed.

A Player's GUID is not required for most changes, but you'll need it for name changes or for cases where more than one player in your save/server has the same name. If you don't provide a GUID and Paver finds multiple players with the same name, it will avoid making changes to any of them so it doesn't risk breaking anything.

Don't know a player's guid? Just run Paver atleast once - the report it generates will include players' GUID's!

Config Options

Below is a list of all currently available options for the config.json file. All fields other than "gameSaveDirectoryPath" are optional; the values you see below are the defaults (by Palword or Paver). Generally, you probably don't need to use any of these options unless you want them to be different than the defaults below.

Here's an example config.json with all possible options specified; again, note that almost everything is optional.

Writing good docs takes time, and I work during the day :) A full table/rundown of each option is coming asap!

{
  "gameSaveDirectoryPath": "C:\\path\\to\\your\\save\\directory",
  "savToJsonConversion": {
    "enable": true,
    "repoUrl": "https://github.com/cheahjs/palworld-save-tools.git",
    "relativeInstallPath": "./palworld-save-tools-cheahjs",
    "convertFreshEveryRun": true,
    "cleanUpJsonAfterConversion": true,
  },
  "reporting": {
    "export": true,
    "exportPath": "./reports",
    "showSummary": true,
    "showPlayerData": true,
    "showCapturedPals": true,
    "showPlayerUnlockedRecipes": true,
    "showPlayerAppearance": true,
    "showChangesMade": true
  },
  "changesToMake": {
    "enableGuardrails": true,
    "world": { "soon": "Changes to bases, inventory, Pals, & planned to come soon!" },
    "players": [
      {
        "guid": "e1337m8e-0000-0000-0000-000000000000",
        "handle": "Lent",
        "level": 42, // Level of the player. Omit "exp" to auto-calculate XP for you.
        "exp": 123456789, // Manually specify how much XP a player has, or omit.
        "techPoints": 250,
        "ancientTechPoints": 100,
        "unlockedRecipes": [
          "Workbench",
          "Product_Axe_Grade_01",
          "Product_Pickaxe_Grade_01",
          "HandTorch",
        ],
        "unlockedFastTravels": [
          "soon - fast travels will be added here soon"
        ],
        "countEffigiesFound": 0, // This is number of Effigy points you have!
        "currentHp": 50000, // Current HP (base before modifiers)
        "maxHealth": 50000, // Max HP (base before modifiers)
        "maxStamina": 50000, // Max stamina (base before modifiers)
        "hunger": 100, // Current hunger level. 0 is hungry, 100 is full
        "sanityValue": 100, // Current *player* sanity value. Unsure if this is used.
        "isPlayer": true, // Are this a player? The save file has this partially because Pals are stored in the same spot.
        "workSpeed": 100, // Your base work speed (before modifiers)
        "support": 100, // No idea what this does yet
        "unusedStatusPoint": 50000, // Unused status points you can assign to stats
        "statusPoints": {
          "health": 0, // Current # of points that add to your max HP stat. Each point is +100 HP.
          "stamina": 0, // Current # of points that add to your maxStamina stat. Each point is +10 Stamina.
          "attack": 0, // Current points in attack. Each point is +2 attack
          "weight": 0, // Current points in weight stat. Each point is +50 weight.
          "catptureRate": 0, // This is player's base capture rate! The devs set it up as a Status Point (which is why it's listed here)
          "workSpeed": 0, // Current points in work/craft speed. Each point is +50 work speed.
        },
        "appearance": { // Color support coming in next update!
          "bodyType": "TypeA", // Body type, TypeA or TypeB
          "torsoSize": 0.5, // Smol or big, 0 to 1.
          "armSize": 0.5, // Smol or big, 0 to 1.
          "legize": 0.5, // Smol or big, 0 to 1.
          "headType": "type1", // head/face type, from 1-21
          "hairType": "type1", // hair type, from 1-27
          "eyeMaterialName": "Type001", // eye type, from 1-6
        },
        "voiceId": 1, // Voice to use. 1-3 are more traditionally feminine, 4-6 are more trad'lly masculine
       }
     ]
  }
}

Deeper rundown coming ASAP - it's late and I'm sleepy.

Planned Improvements & Features

I'll be adding to this list soon, but there are quite a lot of things I'd expect to add to this project if people find it useful. Here's a few things I'm thinking аbout:

• Full appearance options
• Inventory & base editing
• In reports, scan world & players for potential issues (chars in name that could break things), VAC/global ban lists, evidence of cheating, etc.
• Better abstraction and clean up the code - it's fresh out of hackathon mode, and it shows.
• More guardrails and safety checks, more options with saving.
• Potential automated/rolled-up RCON + backup + save edit + restart server functionality.
• Incremental and/or Git-style rollbacks of changes.
• Way better documentation
• Features requested on by users/community.