Skip to content

ENIM Animations: For Resource Pack Artists

Jump to bottom
Chris Nero edited this page Jan 2, 2018 · 11 revisions

Entity animation files, known as AbieScript files, contain animation definitions. AbieScript files are located in the models/entity/animations/ directory with the extension .abie. Animations are written in a custom script. Tokens must be separated by whitespace, and files must end with a whitespace character (typically the newline). Below is the AbieScript file for the quadruped walking animation:

define front_left
define front_right
define rear_left
define rear_right

over 20
{
rotate sine front_left  +30 -0 -0
rotate sine rear_left   -30 -0 -0
rotate sine front_right -30 -0 -0
rotate sine rear_right  +30 -0 -0
}

Why AbieScript?

Customizable animations are essential to ENIM and they must work with arbitrary model parts. To this end, an animation format must be easy to write and understand as well as be flexible. The JSON model format is simply too verbose toward this end. AbieScript is a command-based language that specifies a sequence of transformations (rotations and translations) of symbolic model elements called defines. When resources are reloaded, these scripts are translated into the animations for a model.

Defines

Defines are declared with the keyword define. A define name must be unique within the animation and must be a valid identifier. Valid identifiers are made up of only letters, numbers, and underscores, and start with a letter. AbieScript identifiers must be lowercase. Define declarations must appear at the top before the frame definitions. Defines are used as aliases for model elements and are matched with model elements in model files.

Functions

Functions control how a model element is transformed. Functions are local to the file in which they are defined, unless they are defined in the special functions.abie file in any namespace. Functions are defined with this syntax.

function <name> => <body> ;

Note that, of all AbieScript commands, this is the only one to have an end token (the semicolon). The name may be any valid identifier (even one used for a define). When referring to functions defined in other mod namespaces, prefix the function the same as any resource location. The function body is a mathematical expression consisting of basic operators (+ - * / % **) and calls to other functions. Every function has one parameter, t.

AbieScript also has builtin functions in the minecraft namespace as follows. Some builtin functions take more than one parameter.

  • abs: Absolute value
  • sin: Sine
  • cos: Cosine
  • tan: Tangent
  • asin: Arcsine
  • acos: Arccosine
  • atan: Arctangent
  • arg(y, x): Angle between the point (x, y) and the x-axis
  • log: Natural logarithm
  • floor: Floor function
  • ceil: Ceiling function
  • max(a, b): Maximum of a and b
  • min(a, b): Minimum of a and b
  • clamp(a, min, max): Return the value between min and max closest to a
  • sqrt: Square root
  • cbrt: Cube root
  • sgn: Sign or signum function

There are also two builtin constant values, e and pi.

Frames

Frames compose the main body of an AbieScript file. They contain commands called anemes, which specify transformations on the defines. Frames and anemes are listed in time order. Below are some examples of frames:

rotate element -0 -0 -0

shift sine element -0 -4 -0

over 12
rotate cosine element -0 +12 -0

over 6
{
shift element -0 +6 +2
rotate element +30 -0 -0
}

{
rotate element -0 +20 -0
rotate sine element +30 -0 -0
}

A frame is composed of zero or more anemes enclosed in braces. If there is only one aneme in the frame, the braces may be elided. Multiple anemes not enclosed in braces are considered separate frames. A frame may optionally be preceded by a modifier, which changes the behavior of the whole frame.

Commands

This is the complete list of commands in AbieScript. They are divided into three sections:

  • Anemes: Define transformations for defines.
  • Modifiers: Control the behavior of frames.
  • Non-Frame: Commands not related to frames.

Anemes

<name> [<function> <period> <offset>] <define> <x> <y> <z>

Anemes are made up of three parts: the command name, style, and transformation values.
Command names:

  • rotate: Rotates the define.
  • shift: Translates the define.

The optional function is the name of a global or local function. Global functions from other mod domains must be qualified. The period for each function stretches or compresses the range of values covered by the function. For example, a period of 2 allows sinusoids to cover two periods (0 to 4pi). The offset shifts the domain over which the define is transformed, also known as a phase shift. Mathematically, the complete transformation for an aneme is given by: T(t) = <x/y/z> * <function>(<period> * t + <offset>).

Pause

pause <frames>
Although not technically an aneme, the pause command is a syntax shortcut for a frame with no transformations. The number specified is the number of ticks to pause.

Modifiers

repeat <times>
over <frames>
init

Modifiers are placed before a frame. They change the application of the frame depending on the modifier.

  • repeat: Repeats the frame transformations the given number of times.
  • over: Interpolates the frame transformations over the given number of frames.
  • init: This modifier, if present, must be used on the first frame of the animation. In this case, the first frame is treated as the initial transformation of each define before the animation begins.

Non-Frame

Non-frame statements are not directly related to frame definitions. The non-frame commands are as follows:

  • define: Declares a define. Defines are names that represent model elements.
  • function: Defines a function. Functions are optionally applied to anemes. Functions may be defined in any AbieScript file between defines and the freq, where these functions are only visible in the file. Globally visible functions are defined in the special file functions.abie, which contains only function definitions.
  • freq: Sets the length of a frame, in ticks. For example, a freq of 3 makes each frame three ticks long. This value defaults to 1 if not specified. At most one freq command may appear after define declarations and before frames, and its value applies to all frames.

Comments

Comments may appear anywhere in the file. They begin with the hash character (#) and continue until the end of the line. There are no multiline comments. Some comment examples:

#this is a comment
#this is another comment
freq 7 #yet another comment

Keyword List

Below is a list of the AbieScript keywords. These identifiers may not be used as a define name.

  • define
  • freq
  • function
  • init
  • over
  • pause
  • repeat
  • rotate
  • shift

ENIM Json Model Format

AbieScript Animations Format

The ENIM Framework

Clone this wiki locally