JSON Patching

From Vintage Story Wiki
Jump to: navigation, search

Vintage Story comes with a powerful patching system that lets you perform pinpoint modifications on Assets in JSON format. This significantly improves mod interoperability as you don't have to fully replace these files and overwrite other mod changes in the process. Furthermore you can change multiple files at once.

Below is a basic guide to help you understand how patches are working. A full reference doc is also available however. To make your patching live easier in the long term you can also use the ModMaker 3000™, which is a command line tool that ships with the game itself. If you modify vanilla assets, you can run ModMaker 3000™ to create a mod consisting of a set of patches based on the changes you made to the assets. You can then undo or reinstall the game to get your original files back.

The basics

The first thing you need to do is to setup a generic mod as outlined on the wiki. That information can be found on the mod packaging page. In that example the domain is the name of your mod. Patching is considered a content mod but if you have a .dll or .cs in your mod it is a code mod. Patches go in assets/domain/patches.

Now that the mod files and folders are setup it is time to make the first patch. Start by making a .json and name it however you'd like. Open the file with your favorite text editor and fill it in with the following.

[
	{ file: "", op: "", path: "", value: }
]
  • File is where the file you want to change is located.
  • Op stands for operation and it's what you want to do. Valid operations are add, remove, and replace.
  • Path is where the value you want to change in the file is located.
  • Value is what you want to put in the file.

Now lets give an example. For these examples I'll be modifying the wolf-male.json because it was the first one I modified, I'm very familiar with it, and it provides a good basis for examples. In this first example, we'll modify wolf damage.

For the file put,

file: "game:entities/land/wolf-male"

The game: is the domain. In this case, it's the domain for vanilla VS. You can change the domain to modify other peoples mods as well.

If you look in the vanilla game folders, under assets you'll find the file we are modifying under entities/land/wolf-male. That is why that part comes after the domain.

Next put,

op: "replace"

Since wolves already deal damage we simply want to replace the damage value.

Now for the path,

path: "/server/behaviors/5/aitasks/0/damage"

This is the truly tricky part. In these JSON files, you'll find labels such as server: and behaviors:. You'll know it's a label because it's followed by the colon. Colon  :

Next, we have arrays. These start and end in square brackets. Square brackets [ ]

Within these square brackets, you'll find sections between curly braces. Curly braces { }

These sections don't have a label so they must be referenced by number. To figure out the number you must count starting with 0.

Now to break down the example. We see the value we want to modify on line 52. To get to that we trace it back to the first label which is server. From there the next label is behavoirs. Here we notice the square brackets, so we must count. In this case to 5. Next is the label aitasks, then we hit more square brackets. The count for this is 0 because that's the number you start on. Finally we get to the label damage.

We can now move on to the last part, value

value: 6

Since the value is a number we just put a number. If it were text, the value would be "6".


Advanced patching

We will now move on to a more complex example using the same file. This time we'll add a drop to the male wolf. For this, you can make a new file or put a comma after the first patch and put the new patch on the next line.

[ 
	{ file: "game:entities/land/wolf-male", op: "replace", path: "/server/behaviors/4/aitasks/0/damage", value: 6},
	{ file: "game:entities/land/wolf-male", op: "add", path: "/drops/-", value: { 
		type: "item", 
		code: "stick", 
		quantity: { avg: 2, var: 1 } 
	} } 
]

In this second example, we'll skip straight to the path. You'll notice the label drops and then a dash. Dash -

This dash means append to the end of the array. This is useful because it prevents us from overwriting another drop and we may not know the number of drops if other mods added drops as well.

For the value, there is an entire section showing that the value doesn't just have to be a number or text. In this case, we added the stick to the drops but by specifying a domain in front of stick like we do for the file it could be a stick from any mod!


Disabling Assets

Sometimes you'll want to disable a json entirely. This might be to disable a vanilla recipe for example. For this example I'll be disabling wolves because I don't want to upload another file and hopefully you are quite familiar with the file by this time. All jsons have various labels that the game looks for even if they are not there. In this case the file doesn't have the enabled label so we'll be adding it and setting it to false like so.

[
	{ file: "game:entities/land/wolf-male", op: "add", path: "/enabled", value: "false"}
]

That's all you have to do. If there's already an enabled label in the file then we'd need to switch op from add to replace.


At this point, you have all the tools for modifying assets using the patching system. This is an incredibly powerful tool that only limited by your imagination. Have fun patching!