Using Mixintos and Overrides, you'll be able to modify content in the Stonehearth mod (or in any mod, actually) without tampering with the mod's internal files. Both mixintos and overrides are specified in your mod's manifest.

Remember to add commas only when needed, or the game won't be able to read your manifest and it won't be able to load your mod. See these other tips for debugging.

• The mixinto
• Modifying content using mixintos
• The override
• Injecting content using overrides
• Mod compatibility

The mixinto

A "mixinto" allows for pushing content into existing files from a different mod. An outside mod (like your mod!) specifies what content to push into a destination data file. Mixintos only work for JSON files, we can't add to nor modify Lua/HTML/Javascript/other types of files with them.

Let's take a look at the manifest from the rayyas_children mod, which uses mixintos to inject content into the stonehearth mod. This is the "mixintos" node from its manifest (located at the same level than "info"):

  "mixintos": {
     "stonehearth:playable_kingdom_index": "file(data/rc_playable_kingdom_index.json)",
     "stonehearth:data:gm_index": "rayyas_children:data:gm_index",
     "stonehearth:farmer:initial_crops": "file(data/rc_initial_crops.json)",
     "stonehearth:building_templates:index": "file(data/saved_objects/building_templates_index.json)",
     "stonehearth:data:sound_constants": "rayyas_children:data:sound_constants",
     "stonehearth:gm:campaigns:arcs:ambient_threats": "file(data/mixintos/encounters/rc_ambient_threats_arc.json)"
  }

As you can see, the keys on the left are references to assets from the stonehearth mod, while the values on the right refer to files in the rayyas_children mod that contain the data that we want to mix into those assets. In the "mixintos" node we can use either aliases or paths, for both keys and values.

For mixintos, we ALWAYS need to prefix the keys on the left with the namespace of the other mod plus a colon, in this case "stonehearth:". If it's a path, it should be in the form "/<other_mod_namespace>/..." (in the example above, instead of the alias "stonehearth:data:gm_index" we could have used the path "/stonehearth/data/gm/gm_index.json").

This way the game knows exactly which file from which mod do we want to alter, since it's easy to have files with the same name in different mods.

If you use aliases for the values (on the right) inside the "mixintos" node, make sure they are always prefixed by the namespace of your mod, too. If you use paths, they can be either relative or "absolute".

Our mixintos shouldn't be an exact copy of the original file from the other mod, they should contain just the part that we want to add or modify. For example, this is what the rc_playable_kingdom_index.json mixinto looks like:

  {
     "kingdoms": {
        "rayyas_children" : "rayyas_children:kingdoms:rayyas_children"
     }
  }

And this is the original playable_kingdom_index.json from the stonehearth mod:

  {
     "type": "index",
     "kingdoms": {
        "the_ascendancy": "stonehearth:kingdoms:ascendancy"
     }
  }

In the mixinto, we need to specify the parent nodes (in this case, "kingdoms") so that the game will know exactly at which level of the JSON nodes inject our content. After applying the mixinto from rayyas_children, the playable_kingdom_index from stonehearth will be read by the game as the following, effectively adding a new kingdom to the list of available choices:

  {
     "type": "index",
     "kingdoms": {
        "the_ascendancy": "stonehearth:kingdoms:ascendancy",
        "rayyas_children" : "rayyas_children:kingdoms:rayyas_children"
     }
  }

For most of the cases, we will create aliases for our new entities, then inject them via mixinto into the corresponding files from the stonehearth mod. Examples would be adding new crafting recipes, new factions, new biomes, new traits, new commands, etc.

Modifying content using mixintos

We can change existing content with mixintos, if the value we want to change is not an object nor an array. For example, we can change the scale of an existing entity using a mixinto like this one:

  {
     "components": {
        "render_info": {
           "scale": 0.8
        }
     }
  }

In this case, the final value after the files have been merged will be the one from our mixinto.

The override

Mixintos are used to modify or enhance the content in a mod. An override will completely overwrite that asset. Here's the syntax for adding an override in the manifest (the "overrides" node is located at the same level than "info"):

  "overrides": {
     "/stonehearth/entities/critters/poyo/poyo.qb": "file(sandy_poyo/sandy_poyo_tan.qb)"
  }

Just like with mixintos, we specify an alias (preceded by the namespace of the mod we want to modify plus a colon) or an "absolute" path (if for example the specific asset doesn't have an alias for it) and then we tell which file of our mod do we want to override it with, either with an alias (preceded by our mod's namespace plus a colon), or with a path (either relative or "absolute").

While mixintos allow for many mods to add content to the same files, overrides completely replace that file. This means that if two mods override the same file, only one of them will win, which can cause compatibility problems. Thus, overriding is not recommended for code files, but it can be useful for things like swapping models or images in some cases.

For example, the override above (which pertains to a deferred manifest) is applied when we choose to play in the desert biome, and changes the .qb model of poyos to be more fitting with the desert theme.

Injecting content using overrides

We can add certain type of content using overrides, too. This is useful when we need to add animations to hearthlings, for example, since the list of effects for those is not an index, just a path to a folder inside the stonehearth mod, so there's no file that we can mixinto to.

In order to do this, we can specify a path that doesn't exist in the stonehearth mod, pointing to the file in our mod. Animations are specified in effect files, so we would have an effect file that references an animation in our mod's folder. This is how it would look in our manifest, in the overrides node:

  "overrides" : {
     "stonehearth/data/rigs/entities/humans/effects/my_effect.json" : "/my_mod_namespace/my_effect.json",
     "stonehearth/data/rigs/entities/humans/animations/female/my_anim.json": "/my_mod_namespace/animations/female/my_anim.json",
     "stonehearth/data/rigs/entities/humans/animations/male/my_anim.json": "/my_mod_namespace/animations/male/my_anim.json"
  }

Of course you can have the same path in your mod so that your files are organized in the same way than in the stonehearth mod, if you want.

In this case, "my_effect.json" does not exist in the stonehearth mod, only in our mod, but by specifying it like this in the manifest, the game will think that it really has that non-existent file and will override it with our content. When will this effect/animation be played is another issue.

Notice that the paths in these overrides (the paths to files that don't exist inside the stonehearth mod) don't start by a forward slash. For this type of overrides they must be declared this way, otherwise they won't work.
Other full paths in the manifest and the rest of files must start by a forward slash unless specified otherwise. Some of them will work fine either with or without the slash but for consistency we'll be using the same syntax throughout our examples.

Mod compatibility

As you can guess, when several mods mixinto the same file all the new content will be read. If the mixintos change specific values, it will happen the same than with overrides, only one mod will win, so be aware of your changes to notify users of possible incompatibilities with mods that touch the same files as yours.