[Tutorial] Adding Custom Animations

This tutorial will require more creative than coding skills :wink:. We are going to add an additional animation to the male worker model. This animation will not overwrite an existing one but will add to the list of random animations which will be trigged in case your workers are bored. Why male only? Because it would require 2 animation-files to be politically correct and I am lazy :disappointed:.

We have to separate the required work into two steps this time:

  1. Creating the animation, e.g. in Blender.
  2. Modding the animation into Stonehearth.

:a: ** Let’s start with a few words on the first step (creating an animation)…**

To create an animation for Stonehearth you have to generate an .obj-file out of the .qb-files which you can find in Stonehearth. In our case you will find the male human model e.g. in the following folder:

  • “…\Stonehearth\mods\stonehearth\entities\humans\male_1”.

You can use Qubicle Constructor to create an .obj-file. However, this will require you to have the Home or Master edition. It seems like QC2 will allow the export also in the “play editions” (of which I guess the “Stonehearth Edition” is one of).

Once you have the exported .obj-file, start Blender and load the Stonehearth Add-On for Blender:

This way you should be able to start working on your animations rather fast and it is not really complicated. For the second step let’s assume that you have succeeded. If not just download the animation I have prepared (as you can see it in the video below).

:b: ** Second we need to work our way through the different files in the Stonehearth folders…**

This time we have 5 items to work on:

:one: ** “Save the Animation”**

Save your animation in the folder “…\Stonehearth\mods\stonehearth\data\rigs\humans\animations\male” and give it a name which you will remember, e.g. “idle_hand.json”.

:two: ** “Adding the Effect”**

Go to the folder “…\Stonehearth\mods\stonehearth\data\rigs\humans\effects” and copy and paste an existing file, e.g. “idle_sway.json”. Rename the file to reflect the name of your animation (e.g. “idle_hand.json”) and change the sixth line in the code to:

 "animation": "idle_hand.json",

:three: ** “Adding the Action 1”**

Open the file: “…\Stonehearth\mods\stonehearth\mixins\base_human\base_human.json” and add a line in between the existing entries under “actions”:


:four: ** “Adding the Action 2 (Lua)”**

Unfortunately we will have to edit again a Lua-file. Go to the following folder and copy and paste an existing file, e.g. “idle_sway_action.lua”. Rename it to reflect the name of your animation (e.g. “idle_hand_action.lua”):


In this file you want to change all references from “sway” to “hand”. Just pay attention that you do not miss one.

:five: ** “Adjust the Manifest”**

As “usual” we need to introduce our animation to Stonehearth using the manifest, which you can find here:


The easiest way might be again to look for something we know. Search for the word “sway” and add the following line just below the entry you will find:

 "actions:idle:hand" : "file(ai/actions/idle_hand_action.lua)",

If everything went well, you can now restart the game and wait until one of your male workers will get bored. Randomly the added animation should be triggered now.

In case you prefer to see the related tutorial-video (12 Min.):

Enjoy animating!

P.S. In case you cannot edit the Lua-files, head over to @Xavion’s thread and see if this helps.


More fantastic work not done much in blender for a while but that will probably change now. I was wondering have you tried anything yet with animation that involves interaction with other entities like chairs or beds?

Not yet. That might be a bit tricky and I have not thought through it yet. With the Add-On you can import animations now so you can see which additional “objects” are involved from the point of view of Stonehearth. You will have to take this into account… but as mentioned, I did not take a look into this yet. Probalby I will take a look into male / female animations next… but it is on the list.

i never enjoyed animating, back when i was going through my 3D modeling phase… but you, being the energetic Helping Hand that you are, make the process look like “fun” again… :smile:

you need to stop being such a positive influence… you’re starting to make @Geoffers747 look bad worse…


To be honest… it is quite some fun, once you have spent a few minutes to understand how Blender and the Add-On works. I guess the biggest obstacle is to lose the respect from the tool. With the Add-On it is really easy in most of the cases to get everything prepared for your animations. Need to congratulate myself for that one… even if this sounds like self-adulation :wink:.

P.S. Once QC2 hits the ground and the Stonehearth Edition offers the option to export as an .obj-file (crossing fingers), I hope another obstacle will be removed.

1 Like

Hey voxel, have you considered doing a tutorial on coloring? I’m having issues picking good color palettes, I was wondering is there are some secrets for this?

Now that we can load Stonehearth’s .qb-files you can simply use the colors from original models… that might be the easiest way.