Merging Files

The primary goal of System Template is to enable users to group related files together into directories, making it easier to reuse them in other projects and maintaining organized code. However, in Minecraft, it’s common for a system to need modifications to common files shared by multiple systems. For example, you can’t add new sounds to the game without modifying the sound_definitions.json file, and introducing new abilities to the player often involves adjustments to the player’s behavior (in the default setup of System Template, this corresponds to the player.behavior.json file).

To solve this problem, System Template offers various methods for merging files based on their types. You can enable file merging in your Mapping Rules by using the on_conflict property. You also have the option to overwrite or ignore conflicting files or throw an error if you don’t expect any conflicts.

Merging files depends on their type. The following sections describe what merging options are available for each file type. If you need to treat a file as a different type, you can override its type using the file_type property.

Merging Policies

There are following merging policies (explained in detail in sections below):

append_start
append_end
merge
stop
skip
overwrite

Merging Text Files

Non-JSON text files like .mcfunction or .lang provide 3 ways of merging, which can be enabled by setting the on_conflict property to "append_start" or "append_end". The behavior is self-explanatory: "append_start" adds the content of the new file at the beginning of the existing file and "append_end" adds the content of the new file at the end of the existing file.

Merging JSON Files

JSON files (.json or .material) support a single method of merging, which can be enabled by setting the on_conflict property to "merge". The "merge" option tries to keep as much information from both files as possible, with the following merging rules:

If the JSON path from the new file leads to a primitive value (string, number, boolean, null), the same value in the same JSON path is added to the merged file.
If the JSON path from both files leads to an array, the value in the merged file is the concatenation of both arrays, with the values from the new file added at the end.
If the JSON path from both files leads to an object, the value in the merged file results from the recursive merging of both objects.

Here are some examples illustrating how merging works:

Original File:

{
    "A": [
        1,
        {"x": 1, "y": 2, "z": 3}
    ],
    "B": true,
    "C": {
        "x": 1,
        "y": 2,
        "z": 3
    },
    "D": "Hello World!"
}

Added File:

{
    "A": [
        11,
        {"x": 11, "y": 22, "z": 33}
    ],
    "B": false,
    "C": {
        "x": 11,
        "y": 22,
        "z": 33
    }
}

Merged File (with comments indicating their origin):

{
    "A": [                          // Values are concatenated
        1,                          // Original File
        {"x": 1, "y": 2, "z": 3},   // Original File
        11,                         // Added File
        {"x": 11, "y": 22, "z": 33} // Added File
    ],
    "B": false,                     // Added File (overwrites)
    "C": {
        "x": 11,                    // Added File (overwrites recursively)
        "y": 22,                    // Added File (overwrites recursively)
        "z": 33                     // Added File (overwrites recursively)
    },
    "D": "Hello World!"             // Original File (unchanged)
}

This merging approach is well-suited for most cases in Minecraft, as it does not allow overwriting values inside arrays, which is typically desirable.

Warning

This method of merging does not preserve the order of values in objects. While the order of values in objects does not matter in JSON, it may make reading the merged files more challenging.

Other Merging Options

The on_conflict property includes additional options ("stop", "skip" and "overwrite") that do not merge the files but handle conflicts in alternative ways. Further details can be found in the on_conflict section of the documentation page about Mapping Rules.

The `export_once` flag

If you’re using one of the merging policies, that can modify an existing file (append_start, append_end, merge), you can set the export_once flag to True to ensure that the file is only exported once to its final location (in case of multiple system exporting the same source file to the same target location). This can be useful if multiple systems use the same shared resource which needs to modify some common target file. For example when multiple systems reuse the same sound that needs to be added to the sound_definitions.json file.

Warning

The export once option is triggered whenever the same source file is used multiple times during export to modify the same target. It does not take into account that the source file may have been used with a different scope, and thus have different contents during export. Export onece doesn’t check the contents of the evaluated source file.