Stonehearth Add-On for Blender (Animation)

As mentioned in the thread “Modding Stonehearth’s Graphics Test Program”, I have been working on an Stonehearth Add-On for Blender. The idea is to support modders who want to including their own animations into Stonehearth.

Disclaimer: This Add-On is still work in progress and might get broken or change its functionality over time.

Latest Version:Stonehearth Add-On for Blender v0.9.1

A manual can be found on the official homepage of the Add-On.

Available meta-files:

You can download an example of an .obj-file here, just in case you cannot export yet from your Qubicle version (will require Home or Master Edition) and you still want to try the Add-On out.

I have also uploaded a short series to explain the functionality and am planning to add further videos to it:

Here a custom made idle animation (starting around 0:20):

Some testing makes me believe that the Add-On is working, i.e. it can export skeleton- and animation-files in the .json-format which is supported by Stonehearth. For sure this format might change, but adjusting some lines in the export-code is pretty easy, so this should be fine.

Now I would like to share the Add-On, invite you all to play around with it and to give me feedback (of course this includes reporting bugs).

For all Maya and 3ds Max users… bad choice :stuck_out_tongue_winking_eye:.

Let’s start with a short and high-level overview of core-features:

  1. Export skeleton-file (.json, readable by Stonehearth)
  2. Export animation-file (.json, readable by Stonehearth)
  3. Support custom skeleton- and animation-files
  4. Support “templates” (meta-files) for known skeletons / animations
  5. Support export of custom “templates” (meta-files)
  6. Import of existing animations (.json) :new:
  7. Support export of multi-gender animations (create one, export both). :new:

Workflow with existing model:

From my point of view the process to create an additional animation for an existing model can be split into the following steps. Some of them are very basic, so don’t panic and let me explain :wink::

  1. Load .qb-file into Qubicle, export it as .obj-file and load it into Blender
  2. Import an existing skeleton-file to read pivots / origins
  3. Import “meta-file” to read hierarchy and information about helper bones (if available)
  4. Adjust pivots / origins, add helper bones and hierarchy and prepare model for animation
  5. Animate and export

Step one is pretty basic. We need something to animate and the .qb-format which is used in the Graphics Test is a proprietary format of Qubicle so we need something readable by Blender.

Step two makes our lives a bit easier. The skeleton-file we see in Stonehearth includes pivot-values for each “bone” (in Blender pivots are called “origins” and “bones” can be split in either “Armatures” or “Meshes”). By importing the file it can be matched with the loaded .obj-file and the pivots / origins can be adjusted automatically.

Step three is my approach to make the process a bit more user-friendly. After having the pivots / origins adjusted adding some hierarchy between the single “bones” is required and adding some “helper bones” makes the animation process easier (plus the animation-files of Stonehearth require them as it seems). I think it is a good idea to define a format and write this information into a separate file per “type” (e.g. one file for standard settlers, one for rabbits, etc.). This way the code of the Add-On will stay slim and users can add additional info-files for their own models or other models which I will not provide from day one (is a bit of work to do them all).

If you have a meta-file, step four is something like the click on one button or two. All required data was gathered in step two and three. Now this information has to be applied to the model. There is also some preparation required so the the outcome of an animation will be readable for Stonehearth (mostly rotation and location data has to be adjusted). As mentioned, the idea is that the Add-On will take care of this and the user has only to press a button.

Step 5 will be the most time-consuming because here your model is ready to be animated and you need to move the body-parts, add keyframes and to all the animation-magic.

Workflow for custom model:

I plan to also support custom models and animations. The first time you start working on a custom model you will have to define the pivots / origins, helper-bones and hierarchy by yourself. However, once you have this data defined you can export a skeleton file and write a custom “meat-file”. So the second time you start working on your model, the process is similar as for existing models.

I plan to upload also short videos describing the workflow mentioned above for custom models and sharing some background information on the “meta-files”.

Future (possible) features:

  • Add shortcut keys to access options for import / export.
  • Support of animations with object-interaction.
  • Add a written instruction of how to use the Add-On.
  • Improve tutorial videos (English and German).
  • Add a FAQ with common mistakes.
  • Improve usability of UI.
  • Improve error handling.

If you have any comments, questions or if you want to share an animation you have been able to create… be my guest! Looking forward to hear about your thoughts!

New link to download the latest build…


I don’t know if you are aware of this little useful blender addon but i guess perhaps u allready heard of it.

Rigify Blender Addon
Blendercookie rigify tutorial

Its a very powerful Addon which lets you rig human like characters very easy. First you setup a template rig which the addon then translates in a more advanced powerful animation rig. I think taking a look at “rigify” could help you with your developement. SH Characters do not have the complexity like human rigs so a “lite” version of rigify would do the trick for SH characters i guess.


Thanks @Pandaroc. Yes, saw the Add-On and played a bit around with it some time ago. In the meanwhile I haved stopped to rig my models. I have just the feeling that “small” animations like for Stonehearth are done faster / easier without adding an armature first (even with Rigify).

Very nice, Voxel_Pirate! Thank you for making this. I look forward to seeing how it keeps developing!

Cool, this sounds like a great project. I believe I followed most of it :slight_smile: my brain is a little slow today. I look forward to trying it out - I followed your animation tutorials and they were awesome. However when I tried to animate my guy, things blew up and fingers were found miles away. I haven’t yet re-attempted animation, I consider it my weakest area.

So this would be a huge benefit if I can work with it, I will be sure to help use and test if I am able to figure it out.

I can see a player-created “animations” file with like, 100s of animations for the people. So cool :grin:

Happy to share some progress… I was able to close the last “big” open item (for the time being). I have now included the option to import some kind of an info-file which includes data on “parenting / relationships” and “helper bones” for the model you are working on. This is not a mandatory file but makes life much easier. I wanted to locate this kind of data outside of the code for some reasons (one or the other was mentioned already):

  • Keep the code cleaner
  • Remove requirement to update the code “just” to add this kind of support for new models
  • Allow everyone to contribute to the Add-On (by adding support for new models)

Might sound a bit cryptic so far, but I plan do create a video which should explain all that stuff. For the moment the supported info-file looks like the following (just for your information):

		"type": "meta", 
		"archetype": "rabbit",
		"helperBone": ["root", 1, 2, 3, -4],
		"hierarchy": ["leftBackPaw", "leftLeg"],
		"hierarchy": ["rightBackPaw", "rightLeg"],
		"hierarchy": ["rightEar", "leftEar", "head"],
		"hierarchy": ["rightLeg", "leftLeg", "tail", "head", "rightPaw", "leftPaw", "torso"],
		"hierarchy": ["torso", "root"]

Again, this is not a file which will be found in Stonehearth. It has to be created specifically for the Add-On… but is fully optional.

Next is to clean up the UI, add some debugging info and this kind of things. Hope to be able to share the Add-On soon.

Here a very brief preview on how fast you can start animating supported by the add-on if you are prepared, i.e. under 30 seconds :wink::


Very impressive, sir! Thanks again for making this.

Anatomy of an animation… so far we know two files (both of the type .json) which are of importance to implement an animation in Stonehearth.

“skeleton (rig)” - This file includes mostly location data for each part of the object / model and its helper bones. It also includes information for where to find related animations, effects, postures and data on the “hit box”. E.g.:

   "type" : "rig",
   "skeleton" : {
		"root": [15.5,15.5,0],
		"bodyPosition": [15.5,15,7.5],
		"pelvis": [15.5,15,7.5],
		"torso": [15.5,15.5,10],
		"head": [15.5,15,18],
		"leftShoulder": [21,15.5,15.5],
		"leftArm": [23,15,11],
		"leftHand": [23,15,10],
		"leftThumb1": [22,12,9],
		"leftThumb2": [22,11,7],
		"leftFinger11": [25,13,8],
		"leftFinger12": [25,13,6],
		"leftFinger21": [25,15,8],
		"leftFinger22": [25,15,6],
		"leftFinger31": [25,17,8],
		"leftFinger32": [25,17,6],
		"offHand": [23,15,7],
	"animation_root" : "file(../animations/male)",
   "effects_root" : "file(../effects)",
   "postures" : "file(../postures.json)",
   "collision_shape" : {
      "type" : "cylinder_collision_shape",
      "radius" : 5,
      "height" : 35

Object-/Model-parts are associated with a location in the format “x, y, z” on the coordiante-system. It seems like file defines the base-position for an object / model which will be animated.

“animation” - Each animation is described in a single file which looks like this:

	"type": "animation",
	"frames": [
				"root": {
					"pos": [0,0,0],
					"rot": [1.0,0.0,0.0,0.0]
				"bodyPosition": {
					"pos": [0,0,7.5],
					"rot": [1.0,0.0,0.0,0.0]
				"pelvis": {
					"pos": [0,0,7.5],
					"rot": [1.0,0.0,0.0,0.0]
				"torso": {
					"pos": [0,0,10],
					"rot": [1.0,0.0,0.0,0.0]
				"head": {
					"pos": [0,-1.02572,16.9696],
					"rot": [1.0,0.0,0.0,0.0]
				"root": {
					"pos": [0,0,0],
					"rot": [1.0,0.0,0.0,0.0]
				"bodyPosition": {
					"pos": [0,0,7.5],
					"rot": [1.0,0.0,0.0,0.0]
				"pelvis": {
					"pos": [0,0,7.5],
					"rot": [1.0,0.000136616,0.0,0.0]
				"torso": {
					"pos": [0,-0.00068308,10],
					"rot": [1.0,-5.60977e-005,0.0,0.0]
				"head": {
					"pos": [0,-1.02562,16.9697],
					"rot": [1.0,-7.87468e-005,0.0,0.0]

The animation-file includes only two kind of informations related to the parts belonging to this object / model (including helper bones). One information is the position (again the used format is “x, y, z”). The other information is the rotation of the “part”. Rotations are highlighted as “quaternions”, i.e. consists of 4 float numbers. All this data is saved for each frame of the animation (not only keyframes).

In the example above we see abstracts of the files for a basic worker. Apart from the parts of his body (e.g. torso or head), there are “helper bones” visible. The most important bone is probably called “root” which is centered in the coordiante-system for an animation (not centered in the skeleton-file). In animations this helpers can support animations, as you can parent all parts to a helper bone and once you move the bone, the whole model will move. In Stonehearth it looks like they are also used as placeholders (e.g. mainHand, offHand) and to calculate the animation.

So if we want to adjust an existing animation, we can take the relevant skeleton-file as a basis, move the model to the center, animate it and export the animation. In case we want to create our own model and animate it, we will have to create also a skeleton-file, which defines the base-line, prior working on the related animation files.

Just as some insights which might help to understand the format.


you continue to outdo yourself my good man… well done!

i am curious though, as to how much time you will spend playing the preview release, before you dive in and start meticulously tearing it apart … :smile:

1 Like

After examining the animation files, do you have any insight on whether multiple animations at once will be possible? For example, if I have a “Walking” animation and a “Waving” animation, do you think there will be a way to combine them, so that the body and legs keep walking, while the hand waves? I figure if anything there will be some sort of hierarchy, where some animations have priority over certain limbs, but who knows.
Everything looks great, man! Keep making life easy for the rest of us! :smiley:

I know this might not be the right place to put this question, but it’s better then pulling an ownerpure,
What is recommended for making a more animated figure? Blender or Qubicle?

Well, building the model itself is really easy in Qubicle, but that’s all Qubicle does. I’ve only been using Blender for a couple months, but I suppose you could make a model in Blender, but getting the look right and having it fit with SH might be pretty difficult.
Blender is best for animating the model that you’ve previously made in Qubicle. If you haven’t yet, watch Voxel_Pirate’s videos about using Qubicle and Blender to make and animate models. They’re very good. Here’s the first one: Part 1 - From Picture to Animation - Dwarf Speed Replication
When Voxel_Pirate finishes the add-on he’s describing in this topic, it should be very easy to animate in Blender, then export that directly to a json file which you can then use in your mod. Hope this helps!

1 Like

Thank you, will do, this was very helpful information

Me too, but I guess I will play the first day :wink:.

At the moment I am not sure. As far as I understand it from the code seen so far “events” are calling single animation-files which are including data for the full model. Technically what you say is for sure possible. You could either ignore some of the data for single body-parts or allow animation-files which are only including a sub-set of data. However, if the engine will allow this… no idea and we have only 2 models (bunny and human) and very few examples for animations available to judge.

Thanks! I thought there probably wasn’t enough information to be able to tell one way or another, but I thought I’d ask.

As @Salletan mentions… you want to use both tools. Modelling for Stonehearth in Blender will take you significantly more time than in Qubicle. On the other hand, Qubicle will not allow you to animate models (at least at the moment). So if you really plan to create some custom animations (and maybe even own models), you will probably use both.

What you can ask yourself is if you want to go with Blender or 3ds Max or Maya. This might be a question of your personal situation (if you are not a Student 3ds Max and Maya are probably too expensive) and preferences. Obviously I am in “Team Blender” :wink:.

1 Like


It is possible i think they are doing it with some sort of master and slave animation. Lets say an event starts a walking animation which is the slave. Then another event starts an animation which use some bodyparts of the slave animation so it is going to overwrite the parts of the slave animation which uses these bones. And there you have it multiple animations at the same time. But you really don’t need to do this because for example when you have a jump forward animation you don’t need at the same time a walk forward animation and that this is applyable to every action. Hope it is understandable what i am trying to say :slight_smile:

1 Like

@Alesfatalis you’ve found some evidence in the Lua-code? Would be an interesting piece of information. As mentioned, technically it is for sure possible but if the engine supports it we cannot see from the .json-files.

Btw. as it looks at the moment, the Add-On will only partially support animations done via a rigged body (i.e. with armatures linked to the body-parts). The issue is that all of this bones will be handled as “helper bones” and exported into the akeleton and animation files. Depending on how Stonehearth is handling this, that might cause some issues in the future… or not. The work-around around would be to manually adjust the exported files prior including them in Stonehearth.

P.S. … chances are high that I will release the first version of the Add-on this week. Of course it will be a first, modable release and no Beta :stuck_out_tongue_closed_eyes:. Just need to run a final test and create some videos to explain it.

P.S. … the first version is now available for download! See above :arrow_double_up:.

P.P.S. I have started to work now on the option to export custom created hierarchies and information on helper-bones into a meta-file. This will remove the need to create the meta-file manually for custom models.

1 Like

congratulations on all your hard work! i am sure this will be immensely helpful to the modding community… :+1: