Animations

The animation effects are stored in some of the subdirectories of stonehearth/data/rigs.

The effect file

Example of an animation track from an effect JSON file:

  "animation": {
     "type": "animation_effect",
     "start_time": 0,
     "animation": "chop.json",
     "loop": true
  }

These are the fields that we can find in an animation track:

Hide bone and attach item tracks

Together with the animation tracks, we sometimes see these other types of track: "hide_bone" and "attach_item_effect".

Example of a hide bone track:

  "hide_carrying" : {
     "type": "hide_bone",
     "start_time": 0,
     "end_time": 0,
     "bone": "carry"
  }

We have these properties:

Example of attach item tracks:

  "grab_axe" : {
     "type": "attach_item_effect",
     "start_time": 0,
     "end_time": 0,
     "item": "stonehearth:worker_axe",
     "bone": "mainHand"
  },

  "grab_tool" : {
     "type": "attach_item_effect",
     "start_time": 0,
     "end_time": 0,
     "item_in_slot": "mainhand",
     "bone": "mainHand"
  }

We have these properties:

The animation files

Let's now discuss the different files involved in making animations.

In the stonehearth mod, they're organized in subfolders from stonehearth/data/rigs. For example, for hearthlings they're in stonehearth/data/rigs/entities/humans. We normally have 2 folders (effects and animations) and then one JSON file for the skeleton and one for the postures.

For the case of hearthlings, we made a skeletons folder to contain the male and female skeleton files, and also have several JSON files besides postures.json to store data concerning conversations and happiness (moods).

The skeleton

The skeleton or rig is a JSON file defining the bones that will move every part of the entity.

Example of a small rig file:

  {
     "type" : "rig",
     "skeleton": {
        "ATTOVERCOG": [15.0,-15.8389449183,50.7871090782],
        "door": [7.0,15.0,19.0],
        "frame": [15.5,15.0,0.0],
        "head": [15.0,-14.9748535817,23.3160510152],
        "root": [15.0,15.0,0.0]
     },
     "animation_root" : "file(animations)",
     "effects_root": "file(effects)"
  }

We can see these properties:

You might see a "weighted_effects" field in some rigs. It's not used anymore, instead we have a "stonehearth:idle_effects" field inside the entity_data to randomize idle effects based on weights.

You might also see a "collision_shape" : {} field in some of the rigs. It's also not used, we define the collision type in the mob component of the entity.

iconImportant! To associate a skeleton to an entity, we need to define the animation table in the render_info component of the entity's JSON file. For instance:

  "components": {
     "render_info": {
        "animation_table": "stonehearth:skeletons:humanoid:male"
     }
  }

The "animation_table" property must point to the skeleton JSON file.

Postures

Postures are a way of defining different animations for certain situations. They are managed via the posture component.

A shortened example from the human postures.json

  {
     "stonehearth:carrying" : {
        "idle_breathe" : "carry_idle",
        "run" : "carry_walk"
     },
     "stonehearth:sitting" : {
        "idle_breathe" : "sitting_idle",
        "idle_sway" : "sitting_idle",
        "idle_look_around" : "sitting_idle"
     },
     "stonehearth:sitting_on_chair" : {
        "eat" : "sitting_on_chair_eat"
     },
     "stonehearth:patrol" : {
        "run" : "patrol_walk"
     },
     "stonehearth:have_shield" : {
        "combat_1h_idle" : "combat_1h_idle"
     },
     "stonehearth:swimming" : {
        "idle_breathe" : "idle_swim",
        "idle_sway" : "idle_swim",
        "idle_look_around" : "idle_swim",
        "run" : "run_swim"
     }
  }

In this file we define postures, and map animations to other animations inside them. In Lua code we call radiant.entities.set_posture(entity, posture) (or use the 'stonehearth:set_posture' AI action) to change the posture to one of the keys defined here.

Then when we play any of the animations defined for that posture while the entity is in that posture, the animation that will actually play is the one assigned in the map.

For example, when a hearthling is swimming they get a buff that changes their posture to "stonehearth:swimming". If then we tell them to play the "idle_breathe" animation, they'll play the "idle_swim" animation instead.

Animations

Finally, let's describe the animation files. Like everything else, they're just JSON files. We place them all inside the animations folder of the corresponding rig, so that the folder can be referenced in the skeleton (there's no index to mixinto animations to). Usually they have the same name than the effect file that references them, even if the effect file has additional tracks (like sounds, particle effects, etc).

Each animation file contains 3 fields:

How to create animations

In order to create an animation for an entity in Stonehearth, we need a 3D modeling/animation program that can export to the JSON format that the game uses. To do that, people have created plugins or add-ons that can be used with known programs. You can create your own too.

Here you can find the original animation video tutorials by community member voxel_pirate.

Here you can find a more recent animation video tutorial made by community member Moonsight.

Below we'll explain how to animate with the Blender add-on based on those tutorials.

These are general steps that should work to produce animations for Stonehearth. Feel free to adjust your workflow if you're more proficient with Qubicle / Blender. You can also use other 3D applications as long as they can import / export to the formats that Stonehearth uses for the rigs and animations.

Tools for animating

There are several plugins available for creating animations in the Stonehearth format. If you want more functionality, you can make your own plugin for the animation program of your choice. The format of the JSON files that need to be imported / exported is easy to understand.

Preparing the model

First of all, regardless of the tool you've chosen, the QB model should be prepared and exported to a format that your animation program can read.

Normally models meant to be animated will not be centered over (0, 0, 0) in Qubicle / your modeling program (at least the ones for mobs). When in doubt, load up their QB model and see if it's centered.

  1. As mentioned before, each movable part of the model should be split into a separate matrix/layer in the .qb file.

    We usually leave all the layers with the same size until we're done iterating with the model, and then optimize them at the end. We might need to separate more parts to different layers if when animating they look strange, and in Qubicle they move to the origin when we paste them, so keeping the same size will ensure they're correctly aligned to each other while we work on the model.

  2. Name each layer like the bone you're going to use in your skeleton (e.g. head, body, leftArm, etc). We normally use lowercase names without underscores, although we use numbers sometimes. Check this page to see how the hearthling body parts were named.

    If you're going to reuse an existing skeleton (such as the hearthling's rig) make sure that the bone names match with those in the skeleton file (without counting the helper bones). Qubicle might have appended extra _0 text in their names which will give us some trouble later.

    In Qubicle, you can rename a matrix by selecting it and pressing F2:

    renaming_matrix

    For hearthlings, the body, head, eyes (and eyebrows for the male) are in separate files, so you'll want to merge them together before exporting to .obj (or export them separately then import all of them in Blender).

  3. Once all the parts are split and correctly named, it's time to export them. Select them all (or none) so that the whole model is taken into account, and export it as .obj (or another format that your animation program supports, such as .dae for example). Make sure that in the export options the layers are kept as separate objects.

    For Qubicle 1, the .obj export settings are:

    • Export As : One Object Per Matrix
    • Material : SimpleTex

    Settings for SimpleTex:

    • Colormap : Use colors of selected matrices
    • Pixels per color : 1 pixel
    • Faces per color : 1
    • Padding : unchecked
    • Draw outlines to texture : unchecked
    • Outline color and outline opacity : (indifferent as we didn't check the setting above)
    • Don't overwrite existing texture map : unchecked

    General settings:

    • Scale factor : 1.00
    • Remove lamina faces : checked
    • Remove completely surrounded cubes : checked
    • Move center to world origin : unchecked

    obj_export_settings

Lastly, once you've finished iterating with the model/rig, you can optimize the matrices/layers and reexport the model as a .qb, to save in size in your mod. In Qubicle 1 this is done by selecting the matrices and clicking on the 'Modify > Optimize Size' menu. All empty space around the voxels will shrink while maintaining a cubical layer as boundary.

iconThe workflow to export the prepared model might be completely different in other tools. For example, Voxelshop can't export to .obj, but can export to .dae (which Blender can read). However, the model parts might move, flip or scale themselves during import/export or other issues can arise since it's a different format, so you'll need to adjust your animation workflow.

Blender add-on setup

We'll explain how to setup the environment for animating with the open source program Blender.

The Blender add-on was developed by community member voxel_pirate. It supports import of existing rigs, use of meta files (which are custom files created by the add-on to reflect bone hierarchy, not used in the game), export of skeletons and animations, and offseting animations so that we don't have to make the same animation from scratch for the male and female skeletons. It can import existing animations too, but since the JSON files describe each frame of the animation, it's hard to work with them.

Instructions for installing the add-on:

  1. Open Blender, and go to File-> User Preferences... and make sure "Add-ons" is selected at the top and "Import-Export" is selected at the left menu: blender_user_prefs

  2. Click on the "Install Add-on from File..." button at the bottom of the window.

  3. Select the zip folder of the add-on, there's no need to uncompress it (or if you've already uncompressed it, select the init.py file instead). Click on "Install from File..." at the top right.

  4. Search for 'Import-Export: Stonehearth Add-On' (the list should have refreshed to only show that), and check it in order to enable it.

  5. Click on "Save User Settings" at the bottom so that the add-on keeps being enabled any time you open Blender, and close the window.

  6. Verify that the add-on was loaded. Go to 'File->Import...' and 'File->Export...' and check that a new type called "Stonehearth (.json)" is listed there.

    icon If installing the add-on this way didn't work (due to permissions or other reasons), try uncompressing it and pasting the folder inside the Blender Foundation/Blender/<version_number>/scripts/addons directory (might be hidden).

    If you are updating the Add-On then you might want to un-check it from the add-ons list and delete it from your hard disk, to prevent any confusion.

Preparing the scene in Blender

Instructions to prepare the scene for animating:

  1. Open Blender.

  2. Go to the Scene menu. In a default installation of Blender, it will appear in the menu at the right. Click on the third icon (a light, sphere and cylinder) and if you scroll down, you should see a section called "Stonehearth UI", expand it if it's closed:

    blender_scene_menu

  3. With the mouse cursor over the default 3D scene, press "A" twice to select everything.

  4. Press "Delete" and click on the small button that appears next to your mouse to confirm the deletion.

    blender_cleaning_start_scene The starting scene must be empty. You may save the current scene as a Blender file (.blend) for the future, to start your new animations with a clean environment.

  5. If you import now the .obj model, you might think the model wasn't imported correctly. But if you zoom out, you'll see something like the following picture:

    blender_small_grid which feels strange an uncomfortable.

  6. To change the grid this Press "N" to open the hidden menu at the right side of the scene.

  7. Expand the "Display" section, click on "Lines" and type 22, then press enter. Click on "Scale" and change it to 10.

  8. Now the view grid will fit the model better:

    blender_big_grid You can save this setup by going to File->User Preferences and saving. Press N again to hide the menu if you want.