Latest revision as of 23:40, 16 December 2020

In Staxel, *.patch files are used to patch existing files in the game. This doesn't work for everything but will work for most things. Note that you can only patch one file using a *.patch file. You will need to make another file if you use to patch something else.

Creating a Patch

While not as necessary for patches, make sure to follow Modding#Getting Started with Staxel Modding first. Once this is done, create a file with an ending of .patch, and place the following into it.

{
    "file": "staxel/item/Broom.item", //Case sensitive
    "patchIfFilesExists": [
        "staxel/item/ore/Ore1.item",
        "staxel/item/ore/Ore2.item",
        "staxel/item/ore/Ore23.item" //This should fail and avoid the patch being made as there is no Ore23
    ],
    "patchIfFilesDontExist": [ //This should succeed as there is no Ore 23 or Ore 33
        "staxel/item/ore/Ore23.item",
        "staxel/item/ore/Ore33.item"
    ],
    "priority": 5, //Higher priority leads to this patch being applied later than others.
    "mergeLists": false, //Causes the patch to override arrays/lists rather than merge them.
    "patch" : {
        "pricing": {
            "buyable": true,
            "sellPrice": 10,
            "value": 343434
        },
        "categories": [
            "test",
            "patch",
            "5"
        ]
    }
}

This is a fairly straight forward patch. It is used to change the pricing component and categories of a Broom. Feel free to edit these values however you want.

Caveats, Warnings and Troubleshooting

Not every file can be patched.

Some files can only be partially patched (Meaning that certain keys can't be edited by patching while others can. Changing the .QB file for a TileObject for instance can't be done, but you can change that object's sell value. You can't change the "code" entry at all.)

Some keys can't be merged and you'll simply have to replace the entire contents of that key (Auto Tiles aren't partially patchable.)

Generally you should avoid using the patch system to try to remove something entirely. You can't remove a key that has already been set, and removing something from a list will require re-writing the list entirely while merging is off. If you ARE trying to remove something please give your patch a low priority so other people's patches can be set higher to override it if they need to.

Two patches set to the same level WILL conflict so try to give your patch priority numbers some buffer room that other modders can work around.

If your patch doesn't seem to be working make sure you set the file path correctly, use content builder (not mod manager) to build your content for more detailed information about the build process, and check your staxel log files in Staxel/bin/crashlogs/ one of the files might tell you something about why a patch is tossing up problems.

Config Options

"file"

Valid options (String ): A string containing the path to a file.

Default Value: No default value is specified. Always need to provide your own.

The file to use for the patch. This includes the file path as well as the filename extension. The game will not notify you if you have entered an incorrect filepath so ensure that you have entered it correctly.

"priority"

Valid options (Integer): A positive integer number.

Default Value: If not specified, will default to 0.

This is the order in which to apply the patch. The patch with higher priority will display over the top of the patch with lower priority.

"patchIfFilesExists"

Valid options (List of String): A list of valid strings.

Default Value: If not specified, will not have any list entries and will be ignored.

This is a list of strings containing a path to files. If all the strings lead to valid files than the patch will succeed. Otherwise it will be ignored.

"patchIfFilesDontExist"

Valid options (List of String): A list of valid strings.

Default Value: If not specified, will not have any list entries and will be ignored.

This is a list of strings containing a path to files. If any the strings lead to valid files than the patch will be ignored. Otherwise it will succeed.

"mergeLists"

Valid options (Bool): True or False.

Default Value: If not specified, will default to True.

This value specifies whether or not to mergeLists included in "patch". True will add properties inside of your list to the list of the existing file while false will override the existing list with the list you have provided.

"fileCheck"

Valid options (Bool): True or False.

Default Value: If not specified, will default to True.

This value specifies whether or not to check if the "file" exists. Currently this doesn't seem to work and can be omitted.

"patch"

Valid options (Blobs): JSON objects or properties.

Default Value: No default value is specified. Always need to provide your own.

This is the main part of the .patch file. This blob contains all the components, lists and properties you wish to patch.