Confirmedusers
7
edits
Modding:JSON Patching: Difference between revisions
From Vintage Story Wiki
m
Changing all "json" syntax highlighting to "yaml"
m (→AddEach operation: Fixing incorrect markup syntax) |
m (Changing all "json" syntax highlighting to "yaml") |
||
| Line 21: | Line 21: | ||
<!--T:7--> | <!--T:7--> | ||
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. | 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. | ||
<syntaxhighlight lang=" | <syntaxhighlight lang="yaml"> | ||
[ | [ | ||
{ file: "", op: "", path: "", value: } | { file: "", op: "", path: "", value: } | ||
| Line 38: | Line 38: | ||
<!--T:10--> | <!--T:10--> | ||
For the file put, | For the file put, | ||
<syntaxhighlight lang=" | <syntaxhighlight lang="yaml"> | ||
file: "game:entities/land/wolf-male" | file: "game:entities/land/wolf-male" | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| Line 51: | Line 51: | ||
<!--T:13--> | <!--T:13--> | ||
Next put, | Next put, | ||
<syntaxhighlight lang=" | <syntaxhighlight lang="yaml"> | ||
op: "replace" | op: "replace" | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| Line 58: | Line 58: | ||
<!--T:14--> | <!--T:14--> | ||
Now for the path, | Now for the path, | ||
<syntaxhighlight lang=" | <syntaxhighlight lang="yaml"> | ||
path: "/server/behaviors/5/aitasks/0/damage" | path: "/server/behaviors/5/aitasks/0/damage" | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| Line 89: | Line 89: | ||
<!--T:19--> | <!--T:19--> | ||
We can now move on to the last part, value | We can now move on to the last part, value | ||
<syntaxhighlight lang=" | <syntaxhighlight lang="yaml"> | ||
value: 6 | value: 6 | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| Line 98: | Line 98: | ||
<!--T:21--> | <!--T:21--> | ||
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. | 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. | ||
<syntaxhighlight lang=" | <syntaxhighlight lang="yaml"> | ||
[ | [ | ||
{ file: "game:entities/land/wolf-male", op: "replace", path: "/server/behaviors/9/aitasks/0/damage", value: 6}, | { file: "game:entities/land/wolf-male", op: "replace", path: "/server/behaviors/9/aitasks/0/damage", value: 6}, | ||
| Line 120: | Line 120: | ||
<!--T:25--> | <!--T:25--> | ||
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. | 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. | ||
<syntaxhighlight lang=" | <syntaxhighlight lang="yaml"> | ||
[ | [ | ||
{ file: "game:entities/land/wolf-male", op: "add", path: "/enabled", value: "false"} | { file: "game:entities/land/wolf-male", op: "add", path: "/enabled", value: "false"} | ||
| Line 129: | Line 129: | ||
=== Targeting server or client assets === | === 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 : | 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 : | ||
<syntaxhighlight lang=" | <syntaxhighlight lang="yaml"> | ||
"side": "server" | "side": "server" | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| Line 158: | Line 158: | ||
For example, prior to version 1.19.4, the fat item did not have a behaviors array. Let's say a mod added the behaviors through a patch (notice the path does not end in '''dash -'''): | For example, prior to version 1.19.4, the fat item did not have a behaviors array. Let's say a mod added the behaviors through a patch (notice the path does not end in '''dash -'''): | ||
<syntaxhighlight lang=" | <syntaxhighlight lang="yaml"> | ||
# Bad patch example | |||
[ | [ | ||
{ | { | ||
| Line 171: | Line 171: | ||
However, in version 1.19.4 the vanilla fat object was changed to include a behaviors array. | However, in version 1.19.4 the vanilla fat object was changed to include a behaviors array. | ||
<syntaxhighlight lang=" | <syntaxhighlight lang="yaml"> | ||
# Section of fat.json from 1.19.4 | |||
behaviors: [ | behaviors: [ | ||
{ name: "GroundStorable", properties: { layout: 'Quadrants', collisionBox: { x1: 0, y1: 0, z1: 0, x2: 1, y2: 0.125, z2: 1 }, scale: 0.3 } } | { name: "GroundStorable", properties: { layout: 'Quadrants', collisionBox: { x1: 0, y1: 0, z1: 0, x2: 1, y2: 0.125, z2: 1 }, scale: 0.3 } } | ||
| Line 179: | Line 179: | ||
So if the old patch was applied on the new game version, then it would replace the vanilla behavior instead of adding a new behavior. | So if the old patch was applied on the new game version, then it would replace the vanilla behavior instead of adding a new behavior. | ||
<syntaxhighlight lang=" | <syntaxhighlight lang="yaml"> | ||
# Result of bad patch on 1.19.4 | |||
behaviors: [{ "name": "SealPlacedCrock" }], | behaviors: [{ "name": "SealPlacedCrock" }], | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Whereas, instead the patch could use the "addmerge" operation (putting aside that the "addmerge" operation didn't exist in 1.19.3). | Whereas, instead the patch could use the "addmerge" operation (putting aside that the "addmerge" operation didn't exist in 1.19.3). | ||
<syntaxhighlight lang=" | <syntaxhighlight lang="yaml"> | ||
# Good patch example | |||
[ | [ | ||
{ | { | ||
| Line 198: | Line 198: | ||
If the target array exists (which it does in this example), then addmerge will append the patch array to the target array instead of replacing it. | If the target array exists (which it does in this example), then addmerge will append the patch array to the target array instead of replacing it. | ||
<syntaxhighlight lang=" | <syntaxhighlight lang="yaml"> | ||
# Result of good patch on 1.19.4 | |||
behaviors: [ | behaviors: [ | ||
{ name: "GroundStorable", properties: { layout: 'Quadrants', collisionBox: { x1: 0, y1: 0, z1: 0, x2: 1, y2: 0.125, z2: 1 }, scale: 0.3 } } | { name: "GroundStorable", properties: { layout: 'Quadrants', collisionBox: { x1: 0, y1: 0, z1: 0, x2: 1, y2: 0.125, z2: 1 }, scale: 0.3 } } | ||
| Line 214: | Line 214: | ||
"addeach" is used to insert multiple entries at some index in an array. As example, let's say a mod wanted to insert two new behaviors before the AnimationAuthoritative behavior in the hammer tool. This is the initial value before the patch: | "addeach" is used to insert multiple entries at some index in an array. As example, let's say a mod wanted to insert two new behaviors before the AnimationAuthoritative behavior in the hammer tool. This is the initial value before the patch: | ||
<syntaxhighlight lang=" | <syntaxhighlight lang="yaml"> | ||
# Section of hammer.json | |||
behaviors: [{ | behaviors: [{ | ||
name: "GroundStorable", | name: "GroundStorable", | ||
| Line 229: | Line 229: | ||
The two new behaviors could be inserted using two "add" or "addmerge" patches. | The two new behaviors could be inserted using two "add" or "addmerge" patches. | ||
<syntaxhighlight lang=" | <syntaxhighlight lang="yaml"> | ||
# Example patch using "add" | |||
[ | [ | ||
# Insert new behaviors in the hammer item before the existing AnimationAuthoritative behavior. | |||
{ | { | ||
side: "server", | side: "server", | ||
| Line 251: | Line 251: | ||
Or to be more concise, "addeach" could be used to insert both entries in the array with one operation. Note that when using "addeach", the entries to insert are in standard (non-reversed) order. | Or to be more concise, "addeach" could be used to insert both entries in the array with one operation. Note that when using "addeach", the entries to insert are in standard (non-reversed) order. | ||
<syntaxhighlight lang=" | <syntaxhighlight lang="yaml"> | ||
# Example patch using "add" | |||
[ | [ | ||
# Insert new behaviors in the hammer item before the existing AnimationAuthoritative behavior. | |||
{ | { | ||
side: "server", | side: "server", | ||
