Animation#

../_images/icon_animation.png

Bendy creeper#

Reference configuration for animating OptiFine’s feature Custom Entity Models.

Each model variable which is to be animated is assigned an expression. The expression is evaluated every time the model is rendered and its value is assigned to the variable.

Important

Animations must be in the parent bone, not a sub-bone.

The variables and expressions are defined in the “animations” section of the JSON entity model (JEM):

{
   "animations": [
       {
           "variable1": "expression1",
           "variable2": "expression2"
       }
   ]
}

Model variables#

Model variables are specified in the format <model>.<variable_name>

The model can be:

  • this: current custom model

  • part: the original part model to which the custom model is attached

  • <part>: original model by part name

  • <id>: custom model by ID

  • <part>:<sub_id>:<sub_sub_id>:…: (hierarchical) start with original model by part name, then find children by ID

  • <id>:<sub_id>:<sub_sub_id>:…: (hierarchical) start with model by ID, then find children by ID

The first model found by part name or ID is used if there are duplicates. The model search by ID is deep, and is also deep when used in a hierarchical specification.

The hierarchical specification allows model groups (JSON part models) to be reused for different parts. For example, one hand model (shoulder:upper_arm:elbow:forearm:palm:finger[1.5]) can be used for both left and right hands; left_hand:finger1 for the left thumb and right_hand:finger1 for the right thumb.

The intermediate parents in the hierarchical specification can be skipped.

Variable names#

  • tx, ty, tz: translation x, y, z (movement)

  • rx, ry, rz: rotation x, y, z (yaw, pitch)

  • sx, sy, sz: scale x, y, z (size)

  • visible: show model and submodels (boolean)

  • visible_boxes: show model only, does not affect submodels (boolean)

Entity variables#

Entity variables are specified in the format “var.<name>” (float) or “varb.<name>” (boolean) The name can be any string, for example “var.xyz”, “var.last_rx”, etc.

The variable is attached to the rendered entity and has a default value or 0 or false. Entity variables are useful for storing animation data between frames.

Warning

Not supported for block entities.

Render variables#

  • render.shadow_size: The size of the entity’s shadow, float from 1.0 (full) to 0.0 (invisible)

  • render.shadow_opacity: The opacity (solidness) of the entitie shadow

  • render.leash_offset_x: When leashed, where the leash end attachs to

  • render.leash_offset_y

  • render.leash_offset_z

  • render.shadow_offset_x: The entity’s shadow position

  • render.shadow_offset_z

Expressions#

Expressions are general mathematical expressions with brackets, constants, variables, operators and functions.

Constants#

Name

Type

Meaning

pi

Float, constant

Floating point, 3.1415926

true

Boolean, constant

Truthy boolean

false

Boolean, constant

False boolean

Variables#

Name

Type

Meaning

<model>.<var>

Any

Model variable, see the Model variables section.

time

Integer, ticks

Current world time, in ticks

Render parameters#

Name

Type

Meaning

limb_swing

Float

Limb animation counter

limb_speed

Float

Limb movement speed

age

Float

Age in ticks

head_yaw

Float

Head yaw

head_pitch

Float

Head pitch

player_pos_x

Float

Player’s X position (not necessarily the same entity)

player_pos_y

Float

Player’s Y position (not necessarily the same entity)

player_pos_z

Float

Player’s Z position (not necessarily the same entity)

player_rot_x

Float

Player’s yaw (left-right, not necessarily the same entity)

player_rot_y

Float

Player’s pitch (up-down, not necessarily the same entity)

frame_time

Float

0 to 20, progress of the current frame

dimension

Integer

Dimension ID, -1 = Nether, 0 = Overworld, 1 = End

Entity parameters#

Name

Type

Meaning

Floats

health

Float

Entity’s current health

hurt_time

Float

Time stage of when entity has been hurt once

death_time

Float

Time stage on entity’s death, 0 to 20

anger_time

Float

The time the entity has been angry. 0 while neutral, 720 while aggressive; counts down to 0 when the target is lost

max_health

Float

Entity’s maximum health

move_forward

Float

How much entity is moving forwards-backwards, currently broken

move_strafing

Float

How much entity is moving left-right, currently broken

pos_x

Float

Entity’s X position

pos_y

Float

Entity’s Y position

pos_z

Float

Entity’s Z position

rot_x

Float

Entity’s yaw (left-right)

rot_y

Float

Entity’s pitch (up-down)

swing_progress

Float

Time entity is in attack stage, counts from 0 to 1

id

Float

A unique numeric ID

Booleans

is_aggressive

Boolean

If entity is aggressive, applies to hostile mobs and pigmen

is_alive

Boolean

If entity is alive, not dead

is_burning

Boolean

If entity is burning

is_child

Boolean

If entity is a child

is_glowing

Boolean

If entity is glowing

is_hurt

Boolean

If entity was hit

is_in_hand

Boolean

If entity has item in hand?

is_in_item_frame

Boolean

If entity is in an item frame (items)

is_in_ground

Boolean

If entity is within a solid block; or is embedded into one (arrows, tridents, etc.)

is_in_gui

Boolean

???

is_in_lava

Boolean

If entity is submerged in lava

is_in_water

Boolean

If entity is submerged in water

is_invisible

Boolean

If entity is not visible

is_on_ground

Boolean

If entity is on the ground, not flying

is_on_head

Boolean

If entity is on an armor head slot (items)

is_on_shoulder

Boolean

If entity is on player’s shoulder (parrots)

is_ridden

Boolean

If entity is being ridden by another entity

is_riding

Boolean

If entity is riding atop of another entity

is_sitting

Boolean

If entity is sitting

is_sneaking

Boolean

If entity is crouch/sneaking

is_sprinting

Boolean

If entity is sprinting

is_tamed

Boolean

If entity is tamed (dogs, cats)

is_wet

Boolean

If entity is under rain

Operators#

Name

Meaning

+, -, *, /, %

and, subtract, multiply, divide, modulo

!, &&, ||

not, and, or

>, >=, <, <=, ==, !=

greater than, greater than or equal to, less than, less than or equal to, is equal to, is not equal to

Functions#

Name

Parameters

Return

sin(x)

x: any number

Sine of x

cos(x)

x: any number

Cosine of x

asin(x)

x: any number

Arcsine of x

acos(x)

x: any number

Arccosine of x

tan(x)

x: any number

Tangent of x

atan(x)

x: any number

Arctangent of x

atan2(y, x)

y: any number, x: any number

Two-argument arctangent of y and x

torad(deg)

deg: any degree

Radian form of degrees

todeg(rad)

rad: any radian

Degree form of radians

min(x[, y...]

x...: any number

Minimum of all parameters

max(x[, y...]

x...: any number

Maximum of all parameters

clamp(x, min, max)

x, min, max: any number

x between min and max values, if x > max, x = max, x < min, x = min

abs(x)

x: any number

Absolute value of x

floor(x)

x: any number

Floor of x

ceil(x)

x: any number

Ceiling of x

exp(x)

x: any number

Single-argument exponental function of x

frac(x)

x: any decimal

Decimal point of x, frac(11.4) 0.4

log(x)

x: any number

Logarithm of x

pow(x, y)

x: any number, y: any positive number

Raise base x to the power y

random(seed)

seed: any integer

Random number between 0 and 1, seed is optional

round(x)

x: any decimal

Rounded x

signum(x)

x: any number

Sign function of x

sqrt(x)

x: any positive number

Square root of x

fmod(x, y)

x, y: any number

Similar to Java’s floorMod function, x - (floorDiv(x, y) * y); if the signs of the arguments are the same, the results of fmod and the % operator are the same, but if the signs of the arguments are different, the results differ: floorMod(+4, -3) == -2, (+4 % -3) == +1

lerp(k, x, y)

k, x, y: any number

Linear interpolation of x and y, (1 - k) * x + k * y

if(cond, val[, cond2, val2, ...], val_else

cond: condition string, val: any value, val_else: any value

Select a value based on one of more conditions: return val if cond is true, return val_else if cond is false

print(id, n, x)

id: ?, n: n-th frame, x: value to print

Prints x every n-th frame

printb(id, n, x)

id: ?, n: n-th frame, x: boolean to print

Prints x boolean every n-th frame

Boolean functions#

Name

Parameters

Tests

between(x, min, max)

x, min, max: any number

Is x between min and max?

equals(x, y, epsilon)

x, y, epsilon: any number

Is the difference of x and y within error margin epsilon?

in(x, val1[, val2...])

x, val1...: any number

Is x equivalent to one of val1...?

Examples#

Structure#

{
  "animations": [
    {
      "this.rx": "clamp(-0.5 * part.rx, 0, 90)",
      "this.tx": "3 * sin(limb_swing / 4) - 2",
      "this:Hoof.rx": "if(leg4:Hoof.rx > 90, leg4:Hoof.rx - 90, 0)"
    }
  ]
}

Walking animation#

x is a multipler to control how fast the leg swings back and forth, and y is a multiplier to control how far it swings back and forth.

"left_leg.rx": "sin(limb_swing*x)*limb_speed*y"

Attack animation#

x is a multipler for how much it rotates.

"head.rx": "sin(swing_progress*pi)*x"

Hurt animation#

x is a multipler for how much it rotates.

"head.rx": "-sin(hurt_time/pi)*x"

Custom counter#

This is a counter that will count up while an entity is in water, and count down again when it leaves.

"var.counter": "if(is_in_water, min(20, var.counter + 0.1 * frame_time * 20), max(0, var.counter - 0.1 * frame_time * 20))"

Tutorial#

../_images/animation_ewan.webp
🆚️ This documentation assumes the latest OptiFine version. Notes are not made for legacy versions (1.8).
🔙️ This documentation is updated to commit 8410499f.
©️ This file is offered without any copyright restrictions. Please copy and modify it to suit your needs. Credit is optional, but appreciated.