Modding:JSON Patching

From Vintage Story Wiki
This page contains changes which are not marked for translation.
Other languages:

This page was last verified for Vintage Story version 1.19.4-rc.1.

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 set up 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 set up, 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, addeach, remove, replace, move and copy.
  • 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 let's give a few examples, using the wolf-male.json file. Note that specific line numbers etc. below might not match your own wolf-male.json file if you're using a different version of the game. 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. Note that this is not the same thing as the mod folder; all three of the vanilla folders (survival, game, and creative) all use the domain "game".

You can change the domain to modify other people's 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, we have sections. These start and end in 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 (damage) on line 119. Trace it back to the first label, which is server. From there the next label is behaviors. Here we notice the square brackets, so we must count -- in this case to 9.

  • { code: "repulseagents"... is section 0
  • { code: "controlledphysics"... is section 1
  • { code: "despawn"... is section 2
  • { code: "health"... is section 3
  • { code: "deaddecay"... is section 4
  • { code: "floatupwhenstuck"... is section 5
  • { code: "harvestable"... is section 6
  • { code: "breathe"... is section 7
  • { code: "emotionstates"... is section 8
  • { code: "taskai"... is section 9

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/9/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.

Targeting server or client assets

If you know that a target JSON file is only applied on the server or client, you can use the attribute "side" with the appropriate value to avoid unnecessary processing and the accompanying warnings in log files such as "Hint: This asset is usually only loaded Server side". For example, a cooking recipe will only be loaded by the server and you could therefore add the attribute :

"side": "server"

so the client doesn't try to patch anything.

File Path and Name Considerations

By default, when you generate a mod using ModMaker 3000™, the folder structure will use game as the domain, and use the same file name as the vanilla JSON file. This can lead to mod conflicts.

Let's use the wolf examples from above. If you run ModMaker after making these changes to wolf-male.json, the resulting ZIP will contain the file assets\game\patches\survival-entities-land-wolf-male.json. This seems to suggest two conventions that VS expects; that you should put JSON patches under the game folder, and that you should match the source file name using a folder-hyphen notation. Neither are true, however.

Say you split up the two different wolf changes into two different mods. The first is WolvesAreWimps and the second is WolvesDropSticks. ModMaker would generate identical folder structures and files for these two different mods; that is, both would contain the file assets\game\patches\survival-entities-land-wolf-male.json. These two mods will not work together because they have a filename conflict. (The one that is alphabetically last will take precedence: WolvesDropSticks.)

To avoid the possibility of mod conflicts, do not use the game folder. Instead, use a folder with the same name as your modid; that is, your mod's domain. So in this example, should instead have the folders assets\wolvesarewimps\patches and should instead have the folders assets\wolvesdropsticks\patches. File names are also arbitrary, you do not need to use survival-entities-land-wolf-male.json and can name the file anything you want, since its contents direct the game on what and how to patch, not the file's name.

Overwriting issue

Patches that are creating e.g. behaviors or attributes (for example, if item does not have it), will be overwritten by patches from other mods that are doing same, but with another value.

For example, this patch will be overwritten with patch from example below, even if add operation is used:

    "op": "add",
    "path": "/behaviors",
    "value": [{ "name": "SealPlacedCrock" }],
    "file": "game:itemtypes/resource/fat.json"
    "op": "add",
    "path": "/behaviors",
    "value": [{ "name": "Placeable" }],
    "file": "game:itemtypes/resource/fat.json"

Note : see the Compatibility page for possible ways to handle conflicts and dependencies between mods.

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

Green Items require C# coding

Getting Started | Basic Examples | Theme Pack

Asset System | Textures | Items | Recipes | Blocks | Entities | Model Creator | Animation Basics | VTML & Icons | Packaging & Release | Modinfo | Debugging


JSON Patching | Advanced JSON Item | The Remapper | Server-Client Considerations | Compatibility with other mods

Setting up your Development Environment

Advanced Blocks | Advanced Items | Block and Item Interactions | Block Behavior | Block Entity | Particle Effects | World Access | Inventory Handling | Commands | GUIs | Network API | Monkey patching (Harmony)

Data Management

Savegame Data Storage | ModConfig File | Chunk Data Storage | TreeAttribute


WorldGen Concepts | Terrain | Ores | Trees | WorldGen API | NatFloat | EvolvingNatFloat | Json Random Generator


Shaders and Renderers

Property Overview

Item | Entity | Block | Block Behaviors | Block Classes | Block Entities | Block Entity Behaviors | World properties

Workflows & Infrastructure

Modding Efficiency Tips | Mod-engine compatibility | Mod Extensibility | VS Engine

Additional Resources

List of server commands | List of client commands | Client startup parameters | Server startup parameters | Creative Starter Guide | ServerBlockTicking | Bot System | WorldEdit | Cinematic Camera | Adjustable FPS Video Recording

Example Mods | API Docs | GitHub Repository