Skip to content

JSON Merging

Jump to bottom
Mike edited this page Feb 7, 2023 · 3 revisions

JSON Merging

JSON file merging is fundamental to how NKHook5 works. Each mod contains only the JSON data it requires, which saves space and helps make mods more portable. Unlike regular BTD5 mods, NKHook5 mods can be uploaded to Discord!

Stripping

The first step to JSON merging is to strip down the mod JSON data and keep only the changes between the mod file and the vanilla file. Here is an example of what stripping might look like:

Example Mod File

{
    "PropertyA": "I am the same!",
    "PropertyB": "We are different!",
    "PropertyC": "I don't exist!"
}

Example Vanilla File

{
    "PropertyA": "I am the same!",
    "PropertyB": "I am different!",
}

Result

{
    "PropertyB": "We are different!",
    "PropertyC": "I don't exist!"
}

As you can see, when the mod file is stripped, only the changed properties remain. Also, note that added properties will remain in the final result.

Merging

The behavior of JSON merging is SUBSTITUTIVE by default. However, you can specify which behavior you want with the universal MERGEMODE property. This property can be applied to any JSON files.

SUBSTITUTIVE Behavior

When the stripped JSON files are loaded by NKH5, they then need to be merged again with the original vanilla file. This happens when the game tries to load the file. This is done automatically by NKH5. Here is a simple example of how merging works:

Example Mod File:

{
    "PropertyA": "I am a string!",
    "PropertyC": "I conflict!"
}

Example Vanilla File:

{
    "PropertyB": "Here I am!",
    "PropertyC": "Goodbye!"
}

Result:

{
    "PropertyA": "I am a string!",
    "PropertyB": "Here I am!",
    "PropertyC": "I conflict!"
}

As you can see, conflicting properties will be replaced by whatever the mod's json specifies should be there. Additional properties will be added, and existing properties that do not exist in the mod JSON will be available in the final merged document.

INSERTIVE Behavior

The main difference between INSERTIVE and SUBSTITUTIVE behavior is that lists will have items appended (meaning added or inserted) at the end. This is useful for the tower selection menu JSON files since this can specify you want your custom tower entries to be appended rather than taking the place of an existing entry.

Testing

As of version 0.7.0, DevKit.exe now has a RunMerge feature. This will strip and merge the file you specify and display the results in the terminal window output. If you wanted to try merging your modded DartMonkey.tower, for example, you would run DevKit.exe -r JSON/TowerDefinitions/DartMonkey.tower.

Merge Ignore

Sometimes merging files can cause issues for your mod, and you may find it necessary to fully replace the file for whatever given reason. This is strongly discouraged and will almost certainly cause your mod to be incompatible with other mods!!! Only do this if you ABSOLUTELY need to!!! To do this, create a MergeIgnore.json file inside of the Mod/JSON/ folder. Inside, specify a list of paths to files you wish to not have merged or stripped by NKH5.

Example MergeIgnore.json file:

[
    //This will cause the 
    //file Mod/JSON/TowerDefinitions/DartMonkey.tower 
    //to fully replace the vanilla tower file
    "Assets/JSON/TowerDefinitions/DartMonkey.tower"
]
Clone this wiki locally