|Upgrade from v1.7 Beta|
|Scripting vs Raw Data|
|Channels (Rotation, Position, Scale)|
|Entity Animation Format|
OverviewThe 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 systemBack to top
Upgrade from v1.7 BetaThere 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.foo2)entity.member.foo --> query.foo3)entity.foo --> variable.foo4)params.foo --> global.foo5)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
1.8There are a number of new directories in resource packs with the addition of animations.Animations are stored in the 'animations' folder of a resource pack in a .json format, and referenced by the entity's .json definition file. Resource packs on the stack will overwrite previously specified animations of the same name in stack order (top overwriting bottom). They can be organized in any number of files with any names (ending in .json).
Entity DefinitionIn order to define what animations an entity has, you must add both animations and animation controllers to an entity's entity definition file.
Animation ControllerOne needs to be able to control how animations are played, when, and how they interact with other animations. Animation controllers allow for blending of multiple animations based on parameters such as those exposed by the entity (eg: ground speed, rotation speed, etc). Here's Pig's animation controller
AnimationsAt the beginning of each frame, the skeleton is reset to its default pose from its geometry definition and then animations are applied additively in order.
Note that animation data can be either raw data:By default, if three values are specified, then values are in degrees, in euler X then Y then Z format
or a run-time interpreted script:
Animation HierarchyAnimations 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 timeAll of the above concepts are described in a detailed, bottom-up approach belowBack to top
NamesAll 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 lowercaseBack to top
Transforms-Order of operations: vertices are scaled, rotated, then translated.-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.
Scripting vs Raw DataWhen specifying a transform (scale, rotation, or position), one can specify either a specific value, or a script:"position": [3.0, 10.0, 2.0]"position": [3.0, "10.0 * Math.cos(query.anim_time * Math.Pi + 3.3)", 2.0]Please refer to the MoLang documentation for details on scripting
ParametersThere are a few parameters currently exposed to all scripts to help control animation:
|global.anim_time||Time into this animation|
|global.delta_time||time since this animation was last updated|
|global.key_frame_lerp_time||amount of blending between key frames from 0.0 == start key frame to 1.0 == end key frame|
|global.life_time||time since this entity was created|
Member VariablesSee the Animation Controller section below for details on how these are used
|query.variant||The variant of this Entity is (eg. which cat/horse texture)|
|query.walk_speed||How fast this Entity is moving|
|query.yaw_speed||How fast this Entity is turning(in degrees)|
Entity FlagsAnimation scripts can query the current entity for any entity flag such as is_onfire, is_baby, is_gliding, etc. These are boolean values that can be used to affect the animation via the ?: operator.For a full list of Entity Flags, please refer to the Query Functions List. For example, changing the position of a bone based on whether the Mob is a baby or not:
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 FormatThe json format for an animation is as follows: Note Matching the geometry format, units are in 1/16ths of meters.
Key FramesA 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.
InterpolationCurrently only linear interpolation is supported. Key frame "pre" and "post" settings allow control of the interpolation curve at any key frame.
Continouos ExampleThis 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.
Discontinuous ExampleDiscontinuous 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 and then3. From 0.5 to 1 second ("post"), the bone will re-scale back to its normal size of scale of 1 in all dimensionsNote 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.
Animation ControllersAnimation 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 on one or more parameters. Controller files are stored as JSON in the animation_controllers folder Animation Controller Format:
StatesA state defines how one or more animations interact with zero or more parameters. Each state has an optional parameters section, listing any number of parameters used by the animations to control their blending. Each state also has one or more animations, using the name given in the entity's definition json.
State ParametersParameters 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/
For Example:This defines a controller with a single state default that references the entity's ground speed (in metres per second).It 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.If the ground speed is greater than 2.3 m/s, the walk blend value will remain at 1.0.If the ground speed is 0.0, the blend value will be 0.0 and the animation will be skipped.
We can change the example like this:-If pig is stopped it will play the idle animation.-As the pig's speed increases to 0.1 m/s, the idle animation will be faded out.-As the pig's speed goes from 0.0 to 2.7 m/s, the walk animation will be blended in from 0.0 to 1.0.-As the pig's speed goes from 2.7 to 3.88 m/s, the walk animation will be blended out from 1.0 to 0.0 and the run animation will be blended in from 0.0 to 1.0-Any speed higher than 3.88 m/s will simply play the run animation at a blend value of 1.0.
Zero ParametersA controller with zero parameters will simply play it's animation(s).Back to top
Mult-Parameter BlendingIf the controller has multiple parameters, the resulting blend values are simply multiplied together. If you want a turn animation to play if a pig is turning, but fade it out if the pig is moving:-Blend in the turn_right animation from 0.0 to 1.0 as the yaw speed increases from 0.0 to 90.0 degrees / second.-Scale that value by 1.0 to 0.0 as the ground speed increases from 0.0 to 1.3 m/s.-So if the pig is standing still, the first parameter will result in a blend weight of 0.0 and the second will be 1.0, which, when multiplied together gives 0.0.-If the pig is rotating at 90.0 degrees per second, the first will be 1.0 and the second will be 1.0, so the turn animation will be blended at 1.0.-If the pig is turning at 30.0 degrees per second and moving forwards at 0.9 m/s, the first will be 0.333, the second will be 0.75, so the turn animation will be weighted by 0.25.
User-Defined Script ExampleThis script will set foo to the result of the sin 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
State TransitionsA 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.
Render ControllersThe Render Controller needs an identifier and needs to follow the format of "controller.render.
Getting StartedTo 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
Getting StartedAttachables are a way for you to specify what materials, textures, and geometry equipped armor will use.In the root of the Resource Pack create a new folder and name it "attachables". In the "attachables" folder create a JSON file and give it a name. The JSON file needs a format version and minecraft:attachable information.The minecraft:attachable section contains the description for the attachable. Under description there are a number of things that you can set and have the client run on the attachable.
IdentifierThe identifier is used to register the attachable with the server. In the attachables JSON the identifier sets the appearance of the entity (materials, textures, geometry, etc.) The matching identifier needs to match a corresponding identifier in the "items_client" JSON of the resource pack.Back to top
Materials, Textures, and GeometryPlayers can set the materials, textures, and geometry used for the attachable in these sections. Players can set one or more materials, textures, and geometries that can be used by the attachable. Players can set create user defined keys of when materials, textures and geometries are used. These keys are set in the Render Controllers JSON. Players can reference materials from the vanilla Resource Pack or create their own. Custom materials, textures, and geometries should be placed in the corresponding folder at the root of the Resource Pack.Back to top
ControllersSpecifies the identifier of the Render Controller. This identifier needs to match the identifier of a corresponding JSON located in the "render_controllers" folder. You can reference Render Controllers from the vanilla Resource Pack or create your own. Custom Render Controllers should be in the "textures" folder at the root of the Resource Pack.Back to top