Animation files#

A .anim file is a clip, written as JSON. Most clips are made in the animation editor or imported from Blockbench, and you only read this page to write one by hand or to know what a field does. To play a clip, see Animations.

There are two layouts:

• Curves per joint, versions 2 and 3. Each joint has its own curves for rotation, position and scale. The Blockbench importer and the animation editor write this layout.
• Poses at keyframes, version 1, the older layout. It lists whole poses at keyframes.

Version 3 is version 2 with more in it: key types, easings, handle types, curve modifiers, track settings, ping-pong loops, autoplay, a speed, and sound and clip tracks. Every version 2 file is a valid version 3 file and reads the same.

A clip of curves#

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

{
  "version": 2,
  "length": 1,
  "loop": "loop",
  "priority": "movement",
  "euler": "yxz",
  "joints": {
    "rightLeg": {
      "rotation": [
        [0,   [30, 0, 0], "catmullrom"],
        [0.5, [-30, 0, 0], "catmullrom"],
        [1,   [30, 0, 0]]
      ]
    },
    "torso": {
      "position": [
        [0,    [0, 0, 0], "bezier", { "out": [0.1, [0, 0.05, 0]] }],
        [0.25, [0, 0.06, 0], "bezier", { "in": [-0.1, 0], "out": [0.1, 0] }],
        [0.5,  [0, 0, 0], "step"]
      ],
      "weight": 0.8
    }
  },
  "mask": ["rightLeg", "leftLeg", "torso"],
  "blend": "normal",
  "markers": [{ "time": 0.25, "name": "step", "value": "right" }],
  "events": [{ "time": 0.75, "name": "sound", "payload": { "effect": "step", "volume": 0.6 } }]
}

This swings the right leg back and forth once a second and bobs the torso up and down at 0.8 of its weight. Only joints is required.

Clip fields#

Playback:

Joints:

Things that happen at a time:

For the editor only:

Joints#

A joint has up to three channels, a weight, and the settings of its track:

Channels a joint does not have are left alone. A clip with only rotations turns the joints and does not pull their positions back to the rest.

Keys#

A channel is a list of keys, and a key is [time, value, interpolation, extra]. The last two are optional.

1
2
3
4
5
6
7
8
9

"rightArm": {
  "rotation": [
    [0,   [24, 0, 0], "bezier", { "type": "extreme", "left": "autoClamped", "right": "autoClamped", "out": [0.1, [-4, 0, 0]] }],
    [0.3, [0, 0, 0],  "back",   { "type": "breakdown", "ease": "out" }],
    [0.6, [-24, 0, 0]]
  ],
  "interpolation": "bezier",
  "modifiers": { "rotation": [{ "type": "cycles", "before": "repeat", "after": "offset" }] }
}

Interpolation#

The interpolation says how the value travels from this key to the next one:

Angles are interpolated one axis at a time, as Blockbench does, so a key can spin a joint more than half a turn. Quaternion keys slerp, and treat catmullrom and bezier as linear.

Two keys at the same time make a jump: the value arrives at the first and leaves from the second.

The extra#

The extra is an object, and every field of it is optional:

The editor works out autoClamped, auto and vector handles from the keys around them and writes the result in in and out. The engine only ever reads the handles.

Bezier handles#

Handles are { "in": [dt, dv], "out": [dt, dv] }:

• dt is the handle's time from its key, in seconds, negative for in.
• dv is how far the handle is from the key's value: one number for all three axes, or [dx, dy, dz].

The two handles of a segment share one time line, so the three axes ease in step, and a handle only moves its own axis's value. A missing handle is flat and a third of the segment long, which gives an ease in and out.

Curve modifiers#

A curve modifier changes a whole channel without touching its keys. Modifiers run in the order they are listed, the ones that move time first. They work on angle and offset channels, not on quaternion keys.

Each has two optional fields:

• axis: 0, 1 or 2 for x, y or z. Every axis when left out.
• enabled: true when left out.

Version 1: poses at keyframes#

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "length": 1,
  "looped": true,
  "priority": 1,
  "keyframes": [
    { "time": 0,   "poses": { "rightLeg": { "angles": [30, 0, 0], "easing": "sine" },
                              "leftLeg":  { "angles": [-30, 0, 0], "easing": "sine" } } },
    { "time": 0.5, "poses": { "rightLeg": { "angles": [-30, 0, 0], "easing": "sine" },
                              "leftLeg":  { "angles": [30, 0, 0], "easing": "sine" } } },
    { "time": 1,   "poses": { "rightLeg": { "angles": [30, 0, 0] },
                              "leftLeg":  { "angles": [-30, 0, 0] } } }
  ],
  "markers": [
    { "time": 0.25, "name": "step", "value": "right" },
    { "time": 0.75, "name": "step", "value": "left" }
  ]
}

A pose:

Everything a pose leaves out is the rest: no offset and no turn. Markers have their own times and do not belong to a keyframe, so you can put a marker between two keyframes.

The animation editor opens a version 1 clip as it is, and writes it as version 3 when you save it.

The .retarget file#

A .retarget file maps the joints of a clip onto a rig that names or rests its bones differently. A track uses it through retargetId, see Playing a clip on another rig.

1
2
3
4
5
6
7
8
9
10
11

{
  "version": 1,
  "source": "res://models/knight.bbmodel",
  "target": "res://models/goblin.bbmodel",
  "scale": 0.8,
  "joints": {
    "Body": "spine",
    "LeftArm": { "to": "arm_l", "source": [0, 0, 0], "target": [0, 0, -90] },
    "Cape": ""
  }
}

A joint the file does not name plays on the rig joint of the same name, if there is one. Masks take either name. The animation editor writes these files, see Retargeting.