[Tutorial] How to add additional looks for your settlers

Actually I am struggling a bit to provide interesting modding-tutorials without touching Lua (which I do not want to for the time being - at least until the new API is implemented). However, here is another one which shows how it will work later on to add all kind of variety into the game (at least how I think it will work also for other elements).

This time we will add some additional options to Stonehearth regarding the random look of our settlers (the example adds some hair-colors, but can be adjusted to change also the skin-color, etc.):

Get prepared:

  • Unzip the “stonehearth.smod”-file
  • Create custom .qb-files which we will use to replace head_1.qb, head_2.qb and head_3.qb

Creating the .qb-files will again require a Stonehearth-Edition of QC (Home and Master will work, too :wink:).

Relevant References (where to change / add something):

  • Stonehearth >> Mods >> stonehearth >> entities >> humans :one:
  • Stonehearth >> Mods >> stonehearth >> services >> population >> data :two:
  • Stonehearth >> Mods >> stonehearth :three:

Step by Step:

:one: - Just take an existing folder (e.g. “female_1”) and use it as a template. You have to rename the folder into e.g. “female_4” and replace the existing heads with your designs. So go ahead and overwrite the existing files called “head_1.qb”, “head_2.qb” and “head_3.qb” with the new looks you have exported from Qubicle. You will also have to rename the .json-file into “female_4.json” but you do not have to change the content in the file itself.

:two: - Open the file called “ascendancy.json” which is the only kingdom which is loaded into the game at the moment (later on this will allow to use different names and looks for each kingdom). In the file look for the code which looks like:

   "female_entities" : [

and add an entry for “female_4”:

   "female_entities" : [

:three: - Open the file “manifest.json” and look for an existing entry for the females (e.g. “female_1”). Just underneath it add another line where you introduce the new design:

     "female_4" : "file(entities/humans/female_4)",

Once you have done all the steps, you are done. You do not have to zip the folder again and rename it into stonehearth.smod if you ensure that there is only the unzipped folder in the directory (otherwise your changes might not be taken into account because the Alpha might use the .smod-file instead of loading your changes in the folder which is named the same way).

A short (7 Min.) tutorial can be found here:

P.S. The optional heads will be added and do not overwrite the existing looks. So at the end you will end-up with a wider variety.


Thats not how it will work as I understood. The whole good thing about the upcoming mod tools is that you dont need to add to the existing manifest directly.
Or change files like female entities.

You create a separate file that contains the data and write mixinto and overrides.

i believe so, yes… and in this case, i think it would be a mixinto, as we would be introducing a new female model, as opposed to replacing an existing one…

still, i always enjoy @voxel_pirate’s tutorials!! :smile:

Sure, it will not be exactly the way how it works… what I mean is that this approach is not editing the female looks and does not overwrite any other settings, but simply adds another option. Once we have the new release you will just have to add your own manifest.json and add an entry to the ascendancy.json (via mixinto).

I also enjoy the tutorials.
I was just surprised you did it this way because it becomes outdated very soon. :blush:

Yeah, I know. But on the other hand, everything will get outdated quite often in the next months :wink:… so why not now. In addition I think it will be pretty easy to adjust it, so I can just provide a small update covering both “tutorials” next :smile:.

1 Like

Yet there’s absolutely no reason one should mess around with the original game files, especially when there is (soon) a proper API in place.

@RepeatPan that might be very true for people like you, who already have been digging into the depths of Stonehearth. However, I am not targeting at already existing modders with my videos / posts but am trying to reduce the barriers for others to join us and start modding. For this purpose I think the key point here is not that this or that will change or that there will be an API in place, but that it is pretty easy to understand a bit of what is going on behind the scenes and it does not take much to change something by yourself… even without deep coding knowledge. If something changes… well, it’s an Alpha and you know best that doing something you should maybe not do (in terms of modifying code, etc.) at least provides you with insights and a better understanding :wink:.


well said… and further compounds my own personal shame in not having begun my code explorations…

i place the blame for that squarely on the shoulders of my PC though… which, unfortunately, brings that other shameful fact to light… :stuck_out_tongue:

Yes, where is this new computer, eh Steve? We keep hearing that you plan on getting one, but all it seems is a way of excusing yourself from not having got going with the modding! :wink:


i know, i know! trust me, my personal shame is getting the best of me… although, i just found out i get $750 back from my credit card (earned “points” for purchases), so that will ease the cost of purchasing said new PC… :smile: