ANIMATIONS DOCUMENTATION
Version: 1.21.40.3

Index

Animation Controllers

State Blending
State Transitions
States
Channels (Rotation, Position, Scale)
Entity Animation Format Examples
Getting Started
Adding Animations
Animation Hierarchy
Upgrade from v1.10 to v1.17.30
Upgrade from v1.17.30 to v1.18.10
Upgrade from v1.18.10 to v1.18.20
Upgrade from v1.7 Beta to v1.8
Upgrade from v1.8 Beta to v1.10
Key Frames
Interpolation
Names
Overview
Render Controllers
Examples
Getting Started
Transforms

Animation Controllers

Animation controllers decide which animations to play when. Each controller contains a list of states that play one or more animations, each of which can be blended by a Molang expression if so desired. Controller files are stored as JSON in the animation_controllers folder

Animation Controller Format:

{
  "format_version": "1.17.30",
  "animation_controllers": {
    "controller.animation.sheep.move": {
      "states": {
        "default": {
          "animations": [
            { "walk": "query.modified_move_speed" }
          ],
          "transitions": [
            { "grazing": "query.is_grazing" }
          ]
        },
        "grazing": {
          "animations": [ "grazing" ],
          "transitions": [
            { "default": "query.all_animations_finished" }
          ]
        }
      }
    }
  }
}

State Blending

If you would like there to be a cross-fade between states when transitioning, simply set "blend_transition" to the time you would like the system to take in blending between the two states. This is done as a simple lerp between the two states over the time specified.

For example:

"controller.animation.tiger.move": {
  "states": {
    "default": {
      "animations": [ "base_pose", "walk" ],
      "transitions": [
        { "angry": "query.is_angry" } // transition to angry state if query.is_angry returns true
      ],
      "blend_transition": 0.2          // when transitioning away from this state, cross-fade over 0.2 seconds
    },
    "angry": {
      "animations": [ "roar", "extend_claws" ],
      "transitions": [
        { "default": "query.any_animation_finished" } // transition back to default state when either the roar animation or extend_claws animation finishes
      ]
    }
  }
}

State Transitions

A state can specify any number of transition scripts, listed in order. Each transition has a target state to switch to, and a script for whether it should switch or not. For each transition in order, evaluate the script, and if it returns non-zero, switch to the specified state immediately. NOTE: Only one transition will be processed per frame.

"<controller_name>": {
  "states": {
    "<state_name>": {
      ...
      "transitions": [
        // Evaluate the below expressions in order.
        // The first to return non-zero is the state to transition to.
        // If all are zero, then don't transition.
        { "<target_state_name_A>", "<expression>" },
        { "<target_state_name_B>", "<expression>" },
        ...
      ]
    }
  },
  ...
}

For example:

"controller.animation.tiger.move": {
  "states": {
    "default": {
      "animations": [ "base_pose", "walk" ],
      "transitions": [
        { "angry": "query.is_angry" }, // transition to angry state if query.is_angry returns true
        { "tired": "variable.is_tired" } // transition to tired state if variable.is_tired returns true
      ]
    },
    "angry": {
      "animations": [ "roar", "extend_claws" ],
      "transitions": [
        { "default": "query.any_animation_finished" } // transition back to default state when either the roar animation or extend_claws animation finishes
      ]
    },
    "tired": {
      "animations": [ "yawn", "stretch" ],
      "transitions": [
        { "default": "query.all_animations_finished" } // transition back to default state when the yawn and stretch animations have both finished
      ]
    }
  }
}

States

A state defines a group of animations to process (each of which can have it's own blend value). Each state has an optional variables section, listing any number of variables that referenced animations can use. Each state also has one or more animations, using the name given in the entity's definition json.

State Variables

Variables are either set by the game or by a user defined script that can be found in the entity definition json found in definitions/entity/.json. Variables have their value set by a Molang Expression. They can also have their value remapped via a linearly-interpolated curve.

For Example:

This defines a controller with a single state. It will create a variable `variable.ground_speed_curve` that lives on the entity only while processing the animation controller for that frame. It will take the value of `query.ground_speed`, then remap it to between 0.2 and 0.7 based on the value of `query.ground_speed` going from 0.0 to 1.0It will play one animation walk that will blend from 0.0 to 1.0 as the ground speed increases from stopped to 2.3 m/s. The remap curve can have any number of entries. The animation controller will then play the entity-referenced `wiggle_nose` animations, followed by the `walk` animation, scaling the latter by the value of `variable.ground_speed_curve`

```
{
  "format_version": "1.17.30",
  "animation_controllers": {
    "controller.animation.sheep.move": {
      "states": {
        "default": {
          "variables": {
            "ground_speed_curve": {
              "input": "query.ground_speed",
              "remap_curve": {
                "0.0": 0.2,
                "1.0": 0.7
              }
            }
          },
          "animations": [
            "wiggle_nose",
            { "walk": "variable.ground_speed_curve" }
          ]
        }
      }
    }
  }
}
```

User-Defined Script Example

This script will set foo to the result of the sine of query.life_time to later be used in the animation or animation controller.

Note: "pre_animation" tells the script to figure out the values of those variables once a frame, before animation occurs, so that the animation can use those values in their own formulas. If a variable didn't exist, it will create a new variable and its default value will be 0.0

Note in this example that because foo is equal to a sin wave, that its values will range from -1 to 1. This means that you will have a period from 0 to -1 to 0 where only "base_pose" will play and then an equal amount of time where Walk will play on top of base_pose as foo goes from 0 to 1 back to 0. Base_pose will have a blend value of 1.0.

"controller.animation.tiger.move": {
  "states": {
    "default": {
      "animations": [
        //animations are ADDITIVE unless otherwise specified
        //in this case, base_pose will always be playing in the default state
        //walk will play as well if Entity.foo is greater than 0.0
        "base_pose",
        { "walk": "variable.foo > 0.0" }
      ]
    }
  }
}

In definitions\entity\tiger.json:

{
  "custom:tiger":{
    "scripts":{
      "pre_animation": {
        "variable.foo = math.sin(query.life_time)"
      }
    }
  }
}

Channels (Rotation, Position, Scale)

The engine tracks the animation of rotation, position, and scale separately. Within a channel, one or more key frames are specified at arbitrary times, in seconds, from the start of the animation. If no key frames are specified, a single key frame is created at t=0.0 and all channel data is stored within that key frame.
Back to top

Entity Animation Format Examples

The json format for an animation is as follows. Note Matching the geometry format, units are in 1/16ths of meters.


```
<animation_name>": {
  // optional
  "loop": <bool>                                       // default = false.  Should the animation loop back to t=0.0 when it finishes?
  "blend_weight": <expression>                         // default = "1.0".  How much this animation is blended with the others.  0.0 = off.  1.0 = fully apply all transforms.  Can be an expression - see the Animation Controller section below
  "animation_length": <float>                          // default = time of last key frame.  At what time does the system consider this animation finished?
  "override_previous_animation": <bool>                // default = false.  Should the animation pose of the bone be set to the bind pose before applying this animation, thereby overriding any previous animations to this point?

  // required
  "bones": [
    {
    "<bone_name>": {                                   // must match the name of the bone specified in the geometry skeleton
      // various flavours of setting data
      // omitting a channel skips that channel for this animation of this bone
      // any number of floats below can be replaced by a string expression as described above; you don't have to replace all the floats on a line with expressions, only the ones you want to be expression-based
      "position": 1.0,                                 // set x, y, and z to 1
      "position": [1.0],                               // set x, y, and z to 1
      "position": [1.0, 2.0, 3.0],                     // set x=1 , y=2 , and z=3
      "rotation": 45.0,                                // set x, y, and z to 45 degrees
      "rotation": [45.0],                              // set x, y, and z to 45 degrees
      "rotation": [30.0, 0.0, 45.0],                   // set x, y, and z to the respective values (in degrees)
      // note: only uniform scaling is supported at this time
      "scale": 2.0,                                    // scales the bone by 2.0
      "scale": [2.0],                                  // scales the bone by 2.0
      // Key frame data is described below
      // Note that any of the above styles of values will work for "pre" and "post", and "pre" does not have to have the same format as "post"
      "rotation": {
        "0.0": [80.0, 0.0, 0.0],
        "0.1667": [-80.0, 0.0, 0.0],
        "0.333": [80.0, 0.0, 0.0]
      }
      // For discontinuous channel curve, you can specify a different value when interpolating to/from this key frame
      "rotation": {
        "0.3": {                                       // the key field is the time stamp for this key frame: the value can be any of the above examples
        "pre": [30.0, 0.0, 45.0],                      // when interpolating towards this key frame from the previous, use this value
        "post": "180.0 * Math.Sin(global.key_frame_lerp_time)"  // when at interpolating away from this key frame to the next, use this value
        }
      }
      // another example
      "rotation": {
        "0.0": [80.0, 0.0, 0.0],                       // start at an x rotation of 80 degrees
        "0.4": {
        "pre": [80.0, 0.0, 0.0],                       // stay at 80 until 0.4 seconds have elapsed
        "post": [0.0, 0.0, 0.0],                       // discontinuously pop the x rotation to 0.0 degrees
        },
        "0.8": [-80.0, 0.0, 0.0]                       // using the previous frame's lerp mode, lerp to a x rotation of -80 degrees by 0.8 seconds
      }
    }
  ]
}
```

Getting Started

Adding Animations

Animation Controller

One needs to be able to control how animations are played, when, and how they interact with other animations. to group animations While a lot of this can be managed in the entity definition `scripts/animate` section, animation controllers give you the functionality of a state machine into states and control them as a block. Animations in an animation controller state can be animation controllers themselves, allowing for arbitrarily complex animation hierarchies.

Here's a sample animation controller

{
  "format_version": "1.17.30",
  "animation_controllers": {
    "controller.animation.my_mob.move": {
      "initial_state": "moving",
      "states": {
        "moving": {
          "animations": [
            "wag_tail",
            "wiggle_ears",
            { "walk": "query.modified_move_speed" }
          ],
          "transitions": [
            { "grazing": "query.is_grazing" }
          ]
        },
        "grazing": {
          "animations": [ "grazing" ],
          "transitions": [
            { "moving": "query.all_animations_finished" }
          ]
        }
      }
    }
  }
}

Animations

At the beginning of each frame, the skeleton is reset to its default pose from its geometry definition and then animations are applied per-channel-additively in order. Note that the channels (x, y, and z) are added separately across animations first, then converted to a transform once all animations have been cumulatively applied.

Animation data can be either raw data:

By default, rotations are in degrees, in euler X-then-Y-then-Z format

"rotation": [90.0, 0.0, 0.0]

or a run-time interpreted script:

"rotation": ["cos(query.anim_pos * 38.17) * 80.0 * query.anim_speed", 0.0, 0.0]

Here is an example from quadruped.animation.json in the vanilla resource pack's animation folder:

{
  "format_version": "1.8.0",
  "animations": {
    "animation.quadruped.walk": {
      "anim_time_update": "query.modified_distance_moved",
      "loop": true,
      "bones": {
        "leg0": { "rotation": [ "Math.cos(query.anim_time * 38.17) *  80.0", 0.0, 0.0 ] },
        "leg1": { "rotation": [ "Math.cos(query.anim_time * 38.17) * -80.0", 0.0, 0.0 ] },
        "leg2": { "rotation": [ "Math.cos(query.anim_time * 38.17) * -80.0", 0.0, 0.0 ] },
        "leg3": { "rotation": [ "Math.cos(query.anim_time * 38.17) *  80.0", 0.0, 0.0 ] }
      }
    }
  }
}

Entity Definition

In order to define what animations an entity has, you must add both an `animations` and a `scripts/animate` section to an entity's entity definition file.

Here you can see the entity definition for pig.json:

{
  "format_version": "1.10.0",
  "minecraft:client_entity": {
    "description": {
      "identifier": "minecraft:pig",
      "min_engine_version": "1.8.0",
      "materials": { "default": "pig" },
      "textures": {
        "default": "textures/entity/pig/pig",
        "saddled": "textures/entity/pig/pig_saddle"
      },
      "geometry": {
        "default": "geometry.pig.v1.8"
      },
      "animations": {
        "setup": "animation.pig.setup",
        "walk": "animation.quadruped.walk",
        "look_at_target": "animation.common.look_at_target",
        "baby_transform": "animation.pig.baby_transform"
      },
      "scripts": {
        "animate": [
          "setup",
          { "walk": "query.modified_move_speed" },
          "look_at_target",
          { "baby_transform": "query.is_baby" }
        ]
      },
      "render_controllers": [ "controller.render.pig" ],
      "spawn_egg": {
        "texture": "spawn_egg",
        "texture_index": 2
      }
    }
  }
}

Note

Note: the walk animation for pig is the same for cows and sheep, and thus uses animation.quadruped.walk instead of defining its own. This means you will not see the move animation in the pig.json animation file either. If you would like to make a custom pig walk you can change this line to point to your custom animation.

Animations are specified as a short name, followed by their full resource name. The short name is used in animation controllers and the `scripts/animate` list, while the long name is used in the animations file.

In the `scripts/animate` section, you list the animations to play and in which order. You can either specify an animation directly, or specify a blend expression.
Back to top

Animation Hierarchy

Animations are channel based (rotation, position, or scale), and within that, they are key-framed:

EntityAnimation: animation name
__BoneAnimation[]: bone name to animation for this animation
____AnimationChannel[]: rotation, scale, or translation to animate
______KeyFrame[]: the value for the channel to be at, at a specific time

All of the above concepts are described in a detailed, bottom-up approach below
Back to top

Upgrade from v1.10 to v1.17.30

The major change with 1.17.30 is:
- Molang expressions inside transitions that contain capital letters are properly evaluated now. Strings inside such expressions are not forced to lowercase anymore and work as expected.
Back to top

Upgrade from v1.17.30 to v1.18.10

The major change with 1.18.10 is:
- Fixed an issue where animation controller events defined in the default state would get skipped if the controller immediately transitioned to another state.
Back to top

Upgrade from v1.18.10 to v1.18.20

The major change with 1.18.20 is:
- Molang expressions inside animation scripts for actor resource definition (pre_animation and initialize) that contain capital letters are properly evaluated now. Strings inside such expressions are not forced to lowercase anymore and work as expected.
Back to top

Upgrade from v1.7 Beta to v1.8

There have been few changes as we clean things up based on feedback and as we push the tech along the road map.To upgrade previous scripts, you'll want to do the following steps to all of your Molang scripts in the order listed:
1) entity.flags.foo --> query.foo
2) entity.member.foo --> query.foo
3) entity.foo --> variable.foo
4) params.foo --> global.foo
5) The general rule is that 'query' represents read-only values from the entity the script is running on, and 'variable' represents read-write data created by the user.
6) We've adopted snake_case for all names of things. You are welcome to use upper-case letters if you wish as we are case-insensitive, however we recommend snake_case in general.
7) Several variables previously set on mobs have been changed to use the query.foo format. Look through the updated list below to see what has been added and changed.
Back to top

Upgrade from v1.8 Beta to v1.10

The three major changes with 1.10 are
- the ability to have animations reference other animations in an arbitrarily deep hierarchy.
- the parameters section of animation controllers has been replaced with the `variables` section.
- in the entity definition file, animation controllers are now listed in the `animations` section, and a `scriptsnimate` section has been added to define which root animations to play.
The v1.8 file format is backwards-compatible with v1.10 so you don't _need_ to change anything (although we recommend refactoring your files in the spirit of v1.10 as there is a slight performance win with the new format, as well as it being simpler to understand.
Back to top

Key Frames

A key frame defines two values for a channel-specific transform to a specific bone at a specified time, one as time approaches the key frame time, and the second from that key frame time onwards.
As such, when interpolating between two key frames, one can define the slope of the animation curve in either a continuous or discontinuous manner.

Interpolation

Currently only linear interpolation is supported. Key frame "pre" and "post" settings allow control of the interpolation curve at any key frame.

Continuous Example

This example spins the bone "head" around the y axis 1 rotation in 1 second.
Note that because interpolation is linear, at .25 seconds the head will be rotated to 90 degrees.

"head": {
  "rotation": {
    "0.0":[0, 0, 0],
    "0.5": [ 0, 180, 0],
    "1.0": [0, 360, 0]
  }
}

Discontinuous Example

Discontinuous just means that there won't be a smooth transition between key frames. It is useful if you want something to happen immediately.
This example scales the bone "head":
1. From 0 to 0.5 seconds (in the "pre" tag), the head bone is set to its normal scale of 1 in all dimensions [X, Y, Z]
2. At 0.5 seconds, the bone will instantly scale up to 2 times its normal size
3. From 0.5 to 1 second ("post"), the bone will re-scale back to its normal size of scale of 1 in all dimensions

Note In the larger example above of the file format, "pre" and "post" can also be defined by a Molang expression that calculates that value at runtime, allowing you to have a mathematically defined curve instead of being purely linear.

"head": {
  "scale": {
    "0.5": {
      "pre": [1, 1, 1],
      "post": 2.0
    }
    "1.0": [ 1.0 ]
  }
}

Names

All names: animations, bones, states, etc, must all start with a letter and contain only alphanumerics, underscore, or period. It is recommended to use names in all lower-case
Back to top

Overview

The follows the current Minecraft JSON paradigms:
- Fields should be lower-case and use underscores (no spaces)
- All JSON files in the definitions directory and subtree will be read into and interpreted by the animation system
Back to top

Render Controllers

The Render Controller needs an identifier and needs to follow the format of "controller.render.". This name needs to match the name set in the Client Entity Definitions JSON.

Render Controllers are a way for the player to determine what renders on the entity. Players can set the geometry, materials, textures, and part visibility of the entity. In addition to setting the keys directly, players can use arrays to have the entity choose between different options.

Examples

Example Array for geometry from the sheep JSON

"arrays": {
  "geometries": {
    "Array.geos": ["Geometry.default", "Geometry.sheared"]
  }
},
"geometry": "Array.geos[query.is_sheared]",

Example Array for materials from the spider JSON

"arrays": {
  "materials": {
    "Array.materials": ["Material.default", "Material.invisible"]
  }
},
"materials": [{ "*": "Array.materials[query.is_invisible]" }],

Example Array for textures from the villager JSON

"arrays": {
  "textures": {
    "Array.skins": ["Texture.farmer", "Texture.librarian", "Texture.priest", "Texture.smith", "Texture.butcher"]
  }
},
"textures": ["Array.skins[query.variant]"]

Example with color for tinting of parts from Armor 1.0 render controller JSON:

"format_version": "1.8.0",
"render_controllers": {
    "controller.render.armor.chest.v1.0": {
        "arrays": {
          "materials": {
            "array.armor_material": [
              "material.armor",
              "material.armor_enchanted",
              "material.armor_leather",
              "material.armor_leather_enchanted"
            ]
          },
          "textures": {
            "array.armor_texture": [
              "texture.leather",
              "texture.chain",
              "texture.iron",
              "texture.diamond",
              "texture.gold"
            ]
          }
        },
        "geometry": "geometry.armor",
        "materials" : [
          { "body": "array.armor_material[query.armor_material_slot(1)]" },
          { "leftarm": "array.armor_material[query.armor_material_slot(1)]" },
          { "rightarm": "array.armor_material[query.armor_material_slot(1)]" }
        ],
        "part_visibility" : [
          { "*": 0 },
          { "body": "query.has_armor_slot(1)" },
          { "leftarm": "query.has_armor_slot(1)" },
          { "rightarm": "query.has_armor_slot(1)" }
        ],
        "color": {
          "r": "query.armor_color_slot(1, 0)",
          "g": "query.armor_color_slot(1, 1)",
          "b": "query.armor_color_slot(1, 2)",
          "a": "query.armor_color_slot(1, 3)"
        },
        "textures": ["array.armor_texture[query.armor_texture_slot(1)]", "texture.enchanted"]
    }
}

Example with is_hurt_color from Creeper render controller JSON:

"format_version": "1.8.0",
"render_controllers": {
    "controller.render.creeper": {
        "geometry" : "Geometry.default",
        "materials" : [{ "*": "Material.default" }],
        "textures" : "Texture.default",
        "is_hurt_color" : {
          "r": 0.0,
          "g": 0.0,
          "b": 1.0,
          "a": 0.5,
        }
    }
}

Example with on_fire_color from Fireball render controller JSON:

"format_version": "1.8.0",
"render_controllers": {
    "controller.render.fireball": {
        "geometry" : "Geometry.default",
        "materials" : [{ "*": "Material.default" }],
        "textures" : "Texture.default",
        "on_fire_color" : {
          "r": 0.0,
          "g": 0.0,
          "b": 0.0,
          "a": 0.0,
        }
    }
}

Example with overlay_color from Wither Boss render controller JSON:

"format_version": "1.8.0",
"render_controllers": {
    "controller.render.wither_boss": {
        "arrays": {
          "textures": {
            "Array.wither_state": ["Texture.invulnerable", "Texture.default"]
          }
        },
        "geometry" : "Geometry.default",
        "materials" : [{ "*": "Material.default" }],
        "textures" : ["Array.wither_state[variable.display_normal_skin]"],
        "overlay_color" : {
          "r": "variable.is_invulnerable ? 1.0 : this",
          "g": "variable.is_invulnerable ? 1.0 : this",
          "b": "variable.is_invulnerable ? 1.0 : this",
          "a": "variable.is_invulnerable ? query.overlay_alpha : this"
        }
    }
}

Example with part_visibility for turning on and off visibility of parts from Llama JSON:

"format_version": "1.8.0",
"render_controllers": {
  "controller.render.llama": {
    "arrays": {
      "textures": {
        "Array.base": ["Texture.creamy", "Texture.white", "Texture.brown", "Texture.gray"],
        "Array.decor": ["Texture.decor_none", "Texture.decor_white", "Texture.decor_orange", "Texture.decor_magenta", "Texture.decor_light_blue", "Texture.decor_yellow", "Texture.decor_lime", "Texture.decor_pink", "Texture.decor_gray", "Texture.decor_silver", "Texture.decor_cyan", "Texture.decor_purple", "Texture.decor_blue", "Texture.decor_brown", "Texture.decor_green", "Texture.decor_red", "Texture.decor_black"]
      }
    },
    "geometry": "Geometry.default", 
    "part_visibility": [{ "chest*": "query.is_chested" }],
    "materials": [{ "*": "Material.default" }],
    "textures": [
      "Array.base[query.variant]",
      "Array.decor[variable.decor_texture_index]",
      "Texture.decor_none"
    ]
  }
}

Note

NOTE: The arrays for Materials and Part visibility are applied in the order specified. Materials and Part visibility specified later in the file will override previous materials or parts.

Material array example from Horse render controllers. Saddle will override Mane, which will override TailA, etc.:

"materials": [
  { "*": "Material.default" },
  { "TailA": "Material.horse_hair" },
  { "Mane": "Material.horse_hair" },
  { "*Saddle*": "Material.horse_saddle" }
],

Getting Started

To begin create a new folder named "render_controllers" in the root of the Resource Pack you want to add the new Render Controller JSON inside.

Example render controllers JSON for the ocelot

"format_version": "1.8.0",
"render_controllers": {
  "controller.render.ocelot": {
    "arrays": {
      "textures": {
        "Array.skins": ["Texture.wild", "Texture.black", "Texture.red", "Texture.siamese"]
      }
    },
    "geometry": "Geometry.default",
    "materials": [{ "*": "Material.default" }],
    "textures": ["Array.skins[query.variant]"]
  }
}

Transforms

- Order of operations: vertices are translated, rotated, then scaled.
- Animation data is assumed to be hierarchical, and is applied to a bone by name matching the bone name in the animation data to the targeted geometry's skeleton.
- Not every bone needs to be animated
- You can animate bones that don't exist in the targeted geometry (missing bones are ignored).
- For each of scale, rotation, position, one can set the fields individually or uniformly with a single value. For example, these are equivalent.

"scale": [2.0, 2.0, 2.0]
"scale": 2.0
"scale": [2.0]

ANIMATIONS DOCUMENTATION Version: 1.21.40.3

Index

Animation Controllers

State Blending

State Transitions

States

State Variables

For Example:

User-Defined Script Example

In definitions\entity\tiger.json:

Channels (Rotation, Position, Scale)

Entity Animation Format Examples

Getting Started

Adding Animations

Animation Controller

Animations

Animation data can be either raw data:

or a run-time interpreted script:

Entity Definition

Note

Animation Hierarchy

Upgrade from v1.10 to v1.17.30

Upgrade from v1.17.30 to v1.18.10

Upgrade from v1.18.10 to v1.18.20

Upgrade from v1.7 Beta to v1.8

Upgrade from v1.8 Beta to v1.10

Key Frames

Interpolation

Continuous Example

Discontinuous Example

Names

Overview

Render Controllers

Examples

Note

Getting Started

Transforms

ANIMATIONS DOCUMENTATION
Version: 1.21.40.3