8.1. Fiddle Merging

Note

This page is from before the July 7th 2026 update in which Fields of Mistria migrated game engines. Information here is likely outdated and/or depricated.

Fiddle Merging

When writing fiddle files, these files will be directly merged into the games __fiddle__.json file, with JSON merging strategies. While this page doesn't aim to be a tutorial on how to write or understand JSON, it does aim to explain how JSON Merging Behaviour works

Objects Vs. Arrays

As objects and arrays are merged differently, the first step to understanding the merge behaviour of JSON is to understand the difference between objects and arrays. Objects are items wrapped in { and }, where they have a "key" wrapped in quotes and a "value", which can be anything. You can think of them as a name and a value. Let's take our manifest.json as an example:

{
  "author": "Mod Author Name",
  "name": "Mod Name",
  "version": "1.0.0",
  "minInstallerVersion": "0.1.3",
  "manifestVersion": 1
}

This is an object, where it's got several keys with values on them. The key "author" is for the value "Mod Author Name".

An array, on the other hand, is a list of items. They don't have names, they're have hidden numbers for their "index", starting from 0. An array is a list of values. For example:

["dog", "cat", "chicken"]

This would a small list of strings, in this case a list of animals. Although they don't have numbers clearly written down, they do come with numbers. 0 would refer to "dog", 1 to "cat" and 2 to "chicken". An object can have an array as a value, and an array can have objects in them. As a made-up example:

{
    "dependencies": [
        { "name": "Some Mod", "author": "Some Author" },
        { "name": "Other Mod", "author": "Some Author" }
    ]
}

Here we have an object with a key "dependencies", whose value is a list of objects. Each object in that list has a "name" key and an "author" key.

Object Merging

When JSON merges objects, it will attempt to merge them, not overwrite objects as a whole. That means that you don't need to rewrite an entire object just to replace a single key, you can just specify the key you want to merge. It also means that you can add new keys that didn't previously exist

// __fiddle__.json
{
    "key1": "value1",
    "key2": "value2",
    "key3": "value3" 
}

// Your json
{
    "key2": "my other value",
    "new_key": "my new value"
}

// Final file
{
    "key1": "value1",
    "key2": "my other value",
    "key3": "value3",
    "new_key": "my new value"
}

Since objects can have other objects as values, this merging behaviour will work even for nested objects. Take the following example:

// __fiddle__.json
{
    "parent_key": {
        "key1": "value1",
        "key2": "value2",
        "key3": "value3"
    }
}

// Your file
{
    "parent_key": {
        "key2": "my other value",
    }
}

// Final file
{
    "parent_key": {
        "key1": "value1",
        "key2": "my other value",
        "key3": "value3"
    }
}

Note that parent_key.key and parent_key.key3 don't change or get removed. That's because we're merging objects in here, not replacing them entirely. That means that if you want to remove keys you need to do it over two files: The first file to replace an object with null and a second one to define the new keys. Since MOMI installs mod files in alphabetical order, you'll need to name your files accordingly

// __fiddle__.json
{
    "parent_key": {
        "key1": "value1",
        "key2": "value2",
        "key3": "value3"
    }
}

// my_file1.json
{
    "parent_key": null,
}

// my_file2.json
{
    "parent_key": {
        "key2": "my other value",
    }
}

// Final file
{
    "parent_key": {
        "key2": "my other value",
    }
}

Array Merging

Array merging comes in three distinct behaviours, Merge, Add or Replace. Unless you specify otherwise, the default behaviour will be Merge. You can specify the behaviour per-file, by adding a "__arrayMergeSetting" as a top-level key in your fiddle file with a value of "Merge", "Add" or "Replace".

Merge

The default behaviour for merging arrays in MOMI is to "Merge" them. That means that you're replacing values in the array by their "index", or their position in the list. It's similar to object merging, with the difference being that you don't write out your own key so you're not able to replace items in the middle of the list without affecting the first few items. As an example:

// __fiddle__.json
{
    "pets": ["dog", "cat", "chicken"]
}

// Your fiddle
{
    "pets": ["kitten", "puppy"]
}

// Final file
{
    "pets": ["kitten", "puppy", "chicken"]
}

Because items in an array are given a number starting from 0, the original file has "dog" set to 0 and "cat" set to 1, while your fiddle has "kitten" is set to 0 and "puppy" is set to 1. So it replaces pets[0] with "kitten" and pets[1] with "puppy". Note that there is no way to replace just "chicken" because you can't define the third item in a list without defining the first two. Likewise, in a "Merge" setting, there's no way to add on to the end of an aray without defining all the items that come before it

Add

If you set your fiddle file to "Add", all items will be added onto the end of the array, rather than replacing any values. As an example

// __fiddle__.json
{
    "pets": ["dog", "cat", "chicken"]
}

// Your fiddle file
{
    "__arrayMergeSetting": "Add",
    "pets" ["hamster", "rabbit"]
}

// Final file
{
    "pets": ["dog", "cat", "chicken", "hamster", "rabbit"]
}

Not that your file needs to include "__arrayMergeSetting": "Add" at the top-level of the file and doesn't make it into the final file. This is only needed once per-fiddle file and is only there to tell MOMI how to handle arrays in that particular file. As you can see, with "Add" there's no way to add items to the beginning of the array or replace the entire array

Replace

If you set your fiddle file to "Replace", your file will replace entire arrays at once, removing any of the original arrays in the __fiddle__.json file. This is the only way to make existing arrays smaller/shorter

// __fiddle__.json
{
    "pets": ["dog", "cat", "chicken"]
}

// Your fiddle file
{
    "__arrayMergeSetting": "Replace",
    "pets" ["hamster", "rabbit"]
}

// Final file
{
    "pets": ["hamster", "rabbit"]
}

Not that your file needs to include "__arrayMergeSetting": "Add" at the top-level of the file and doesn't make it into the final file. This is only needed once per-fiddle file and is only there to tell MOMI how to handle arrays in that particular file.

Mixed/Multiple

Because the array merge setting is per-file, you're able to mix and match them by using multiple files in your mod, keeping in mind that MOMI will install them in alphabetical order. As an example:

// __fiddle__.json
{
    "pets": ["dog", "cat", "chicken"]
}

// your_file1.json
{
    "__arrayMergeSetting": "Merge",
    "pets": ["puppy"]
}

// your_file2.json
{
    "__arrayMergeSetting": "Add",
    "pets": ["rabbit"]
}

// Final file
{
    "pets": ["puppy", "cat", "chicken", "rabbit"]
}

Note that your_file1.json has "__arrayMergeSetting": "Merge". Because "Merge" is the default behaviour, this is entirely optional and can be left out, but is added here for clarity. Because it's set to "Merge", "dog" gets replaced with "puppy", and then your_file2.json adds "rabbit" to the end of the array because it's set to "__arrayMergeSetting": "Add"