Taking Questions about Mixintos and Overrides

Modding
9

@voxel_pirate asked on the blog about the namespaces and aliases we use in Stonehearth. Copy-pasting my reply in here:

The first goal of mixintos and overrides is to let people do qb-file swaps, and to manipulate the gross properties of the entities that define them, so that’s what is definitely supported (as per the example with the trees). This is all the team is currently officially ready to assure people is possible. :wink:

However, if you don’t mind playing in unstable territory, you CAN also use mixintos and overrides to do a wide range of things we’re only beginning to fully explore, up to and including replacing whole files of any type. (Given the currently fluid state of the Lua, this is like playing with gunpowder, from a stability POV. It is obviously not sustainable across releases.)

So what’s up with the mod:alias-syntax?

Every file in stonehearth has it’s hard-drive address. From the POV of loading resources referenced from json, this path is rooted in the mods folder. So the berry bush’s model’s full address is:

 "stonehearth/entities/plants/berry_bush/berry_bush.qb"

If you happen to be referring to an entity within your own mod (ie, the mod that the json file is a part of) you can use the file() syntax to automatically add the mod name. If the parent folder of a .json file is the same name as the .json file you want, you can also exclude the last part. So if you look at the manifest.json file for stonehearth, berry_bush.json can be addressed like this:

 "file(entities/plants/berry_bush)"

Usually, models are not aliased, because they are only used in the definition of the entity they belong to, which in this case, is lives in berry_bush.json.

Because we’re always moving files around, it’s very cumbersome to use the full address of a file when referring to it. So the manifest.json of any mod has an “alias” section into which you can just map names to files. stonehearth’s manifest.json describes berry bushes like this:

 "berry_bush" : "file(entities/plants/berry_bush)"

And if you ever need to refer to that berry bush, you can call it by using the name of its mod (stonehearth), plus the alias. So in lua, we do things like this all the time:

--In NewGameCallHandler, places a berry bush beside the camp standard"
self:place_item('stonehearth:berry_bush', camp_x, camp_z+3, 'civ')

So, how does this apply to mixintos? Most entities (things that appear in the game) are aliased, in stonehearth. So that’s why, if you want to mix into a berry bush, with a file you’ve specially prepared, your manifest will look like this:

 "mixintos" : {
      "stonehearth:berry_bush" : [
           "file(/entities/lantern/lit_bushes.json)"
      ]
  }

However, if the file you’re trying to mixinto IS NOT aliased by its mod (like the recipes file), you instead need to use its full path name (and then maybe let us know you’d really like it to be aliased). So if berry bushes weren’t aliased, the same line above would look like this:

  "mixintos" : {
        "stonehearth/entities/plants/berry_bush/berry_bush.json" : [
           "file(/entities/lantern/lit_bushes.json)"
        ]
  },

To figure out if you need to use an alias or the filepath to get to a file in Stonehearth, check the manifest.json file to see if it’s in there. If it’s not, then you’ll want to use the full path, and perhaps let Team Radiant know that there’s a desire for that file in the modding community.

4 Likes