Mods / Patch Wars: Enhanced JSON Patching

Category: #Library #QoL
Author: JapanHasRice
Side: Both
Created: Apr 9th 2023 at 2:31 AM
Last modified: Jan 22nd at 7:30 PM
Downloads: 683
Follow Unfollow 8

Latest file for v1.19.1:
PatchWars_v0.1.3.zip 1-click install


Features

Prepatches

Patches found inside the prepatches folder of a mod's assets will run before any regular patches are processed, guaranteeing the ability to patch standard patches before they have run.

Postpatches

Patches found inside the postpatches folder of a mod's assets will run after all prepatches and patches are processed.

JPath Queries

Adds the ability to use Newtonsoft's JPath queries to define more expressive and dynamic patches. This feature is available for use in patches found in patches, prepatches, and postpatches.

Use

To utilize JPath queries, place your query inside the path field of your patch.

If you expect and want your patch to apply to multiple elements in the target file, be sure to add "patchMultiple": true to your patch.

When performing an add or addeach patch operation using JPath queries, because the element being added does not exist yet and would cause the query to fail, it must be left out of the path definition. Instead, add the new element name (or index) to pathAppend. The string found in pathAppend will be added to the end of the pointers found by your JPath query before patching the target file. pathAppend does not support JPath and must be in vanilla's standard JsonPointer notation.

Examples

You'd like to mod the panning loot table so that temporal gears are far more common from both sand/gravel and bony soil. (Excerpt from pan.json as of Vintage Story v1.18.0)

{
  "code": "pan",
  "attributes": {
    "panningDrops": {
      "@(bonysoil|bonysoil-.*)": [
        // ... 17 other items not shown
        { "type": "item", "code": "gear-temporal",  "chance": { "avg": 0.001, "var": 0 }  },
        // ...
      ],
      "@(sand|gravel)-.*": [
        // ... 19 other items not shown
        { "type": "item", "code": "gear-temporal",  "chance": { "avg": 0.0005, "var": 0 }  },
        // ...
      ]
    }
  }
}

If you were to write a patch file for this in the vanilla patching system (or use modmaker.exe), your patch file would look like this:

[
  {
    "op": "replace",
    "path": "/attributes/panningDrops/@(bonysoil|bonysoil-.*)/17/chance/avg",
    "value": 20,
    "file": "game:blocktypes/wood/pan.json",
    "side": "Server"
  },
  {
    "op": "replace",
    "path": "/attributes/panningDrops/@(sand|gravel)-.*/19/chance/avg",
    "value": 20,
    "file": "game:blocktypes/wood/pan.json",
    "side": "Server"
  }
]

These patches are brittle to any changes to the drop tables in vanilla as well as from other mods due to the array indexes shifting from additions and deletions. Also, you and anyone reading your patch have no idea which item in the drop table is being changed without referencing pan.json.

Using a JPath query instead, your patch might look like this:

[
  {
    "op": "replace",
    "path": "$.attributes.panningDrops.*..[?(@..code == 'gear-temporal')].chance.avg",
    "value": 20,
    "patchMultiple": true,
    "file": "game:blocktypes/wood/pan.json",
    "side": "Server"
  }
]

Now the patch is expressive and resilient to vanilla and third party mod adjustments. The leading $ signifies the root element. A . followed by a key finds the appropriately named child element. .* selects all of the current element's children. In this example, this is both the @(bonysoil|bonysoil-.*) and @(sand|gravel)-.* elements, but also includes any potential additions and changes to panningDrops. A .. indicates any descendant element from the current point in the tree. [?()] is a JPath filter expression. @ inside the expression represents the current element. In this example, [?(@..code == 'gear-temporal')] finds any element which has any descendant element key named code with a value of gear-temporal. The remaining portion of the query, .chance.avg, continues traversing the tree to the element where the changes need to be made.

This patch file now has the flexibility to handle many potential changes from vanilla and third party mods.

As a final example, the below patch would raise the chance for cabbage seed drops to 1 for all crop stages where the current chance is less than 1.

[
  {
    "op": "replace",
    "path": "$.dropsByType.*..[?(@.code == 'seeds-cabbage' && @..avg < 1)]..avg",
    "value": 1,
    "patchMultiple": true,
    "file": "game:blocktypes/plant/crop/cabbage.json",
    "side": "Server"
  }
]

Debugging

Log messages have been expanded to help with troubleshooting. Along with standard errors and summaries that appear in server-main and client-main, there are additional messages located in server-debug and client-debug to further explain both failed and successful patches.

[VerboseDebug] Patch 0 in patchwars:prepatches/jpathtest1.json: Found 2 paths using supplied JPath ($.attributes.panningDrops.*..[?(@..code == 'gear-temporal')].chance.avg): /attributes/panningDrops/@(bonysoil|bonysoil-.*)/17/chance/avg, /attributes/panningDrops/@(sand|gravel)-.*/19/chance/avg

Version For Game version Downloads Release date Changelog Download 1-click mod install*
v0.1.3 135 Jan 22nd at 7:30 PM Show PatchWars_v0.1.3.zip Install now
v0.1.2 232 Apr 13th 2023 at 1:42 PM Show PatchWars_v0.1.2.zip Install now
v0.1.1 176 Apr 11th 2023 at 11:09 AM Show PatchWars_v0.1.1.zip Install now
v0.1.0 140 Apr 9th 2023 at 4:27 AM Show PatchWars_v0.1.0.zip Install now

6 Comments (oldest first | newest first)

💬 Pamela, Jan 23rd at 3:37 PM

So happy to see you back!!!

💬 Pamela, Aug 30th 2023 at 1:26 PM

Will this work in 1.18.8 (.net 7)??

💬 NiclAss, Apr 11th 2023 at 4:44 PM

Looks interesting... Need to def take a look at it!

💬 Buggi, Apr 10th 2023 at 8:00 PM

Functionality should be merged into the base game IMHO. A very elegant solution, well done!

💬 JapanHasRiceAuthor, Apr 9th 2023 at 3:57 PM

Craluminum

Agreed, that has been my preferred method to do those things. Part of the reason I've avoided using JSON patching in the past is because of how specific the patches can get and that they're likely to break as the game and other mods expand. Modifying behaviors and drops in code is much easier than it is in JSON. The first mod I ever posted here does exactly that. I hope that having this tool available gives more of that same flexibility back to modders who choose not to write code for their mods, keeping them content-only.

There are aspects of the game that are more difficult to code for changes compared to behaviors and drops. An example that comes to mind and was the inspiration for creating this is worldgen. Everything is moddable in code, especially considering Harmony of course, this mod itself uses Harmony to override the vanilla JSON patcher, but worldgen is more closed off in its current state, requiring anyone who wishes to tweak other mods' settings like spawn chances to use Harmony. In a situation where a server has multiple mods augmenting worldgen, patching via JSON the vanilla way is effectively impossible. You can't write a patch to target a patch because you can't guarantee that the other patch won't run first, blanking yours, nor can you write a patch that writes to the same elements because 1), yours might run first and get overwritten by the other mod, and 2) as soon as another mod is introduced that writes to the same file, your patch can break.

I'm certain there are people who don't want to jump straight into Harmony to make what should be essentially configuration changes to their server and make multiple mods play nice with each other, and this tool is for them.

💬 DanaCraluminum, Apr 9th 2023 at 7:34 AM

I use C# to patch attributes, behaviors, drops etc. without using any JSON patches

(edit comment delete)