Formulas

Reference manual for the advanced Custom formula feature.

When choosing an interaction type, one of the options is a Custom formula. This allows you to create a mapping that uses the full power of the scripting engine in Lottielab Interactivity.

With a custom formula mapping, you get a text field where you can type in a formula whose result will be used to control the selected parameter (playhead position, blending with another state, or playback speed):

Custom formula UI

These formulas use a simple expression language. At each frame, the value of the expression is calculated, and the output (typically 0-1) is applied to the selected parameter:

• For the "Time (progress)" mapping, 0 means the beginning of the state's segment, and 1 means the end of the state's segment (with intermediate values in-between.)

• For the "Playback speed" mapping, the value is directly applied as a speed coefficient (1.0 = normal speed, 0.5 = twice as slow, etc.)

• For the "Blend" mapping, the value is applied as the blending coefficient between this state and the other selected state (0.0 = fully display this state, 1.0 = fully display the other state, 0.5 = blend 50/50 between the states, etc.).

Lottielab Player also exposes several built-in variables based on user input, and allows you to provide custom variables that can be re-used from the formula.

Formula language

The formula language follows the expression rules of a C-like language. You can use parentheses and specify literal numbers.

Types

All types are floating point numbers. For the purposes of boolean operations, all non-0 numbers are interpreted as truthy (and 0 numbers as falsy).

Operators

These operators are available, from highest to lowest precedence:

• Logical negation (!)

• Exponent/power operation (^)

• Multiplication and division (*, /)

• Addition and subtraction (+, -)

• Comparisons (>, <, >=, <=, ==)

• Logical (||, &&)

• Ternary conditional (?:, as in condition ? a : b)

Built-in functions and constants

The language provides support for all functions and constants inside the JavaScript Math namespace. This includes trigonometric functions, constants such as PI, logarithms, and others. These functions and constants are available without the `Math.` prefix. For example, a valid formula can be: sin(PI * mouse.progress.x).

Built-in variables

The Lottielab Player runtime provides several variables that can be used in the formula to respond to user input:

• time: Time in seconds since this state started.

• time.abs: Time in seconds since the animation first started.

• playhead: The current playhead position in this state, in seconds.

• playhead.progress: The current playhead position in this state, as a

• value from 0 to 1 within the segment (0 = start, 1 = end).

• playhead.abs: Global position of the playhead in seconds.

• mouse.x, mouse.y: The current mouse position, relative to the top-left

• of the lottie, in pixels

• mouse.progress.x, mouse.progress.y: The current mouse position, as a value from 0 to 1 within the lottie's bounds (0 = left/top, 1 = right/bottom)

• mouse.abs.x, mouse.abs.y: The current mouse position, relative to the top-left of the whole viewport rather than the lottie itself

• mouse.buttons.left, mouse.buttons.right, mouse.buttons.middle: Whether the left, right, or middle mouse buttons are currently pressed

Custom variables

You can use a variable name that doesn't appear in the list above. In this case, the variable is treated as a custom variable, and you should provide the value at runtime using the interactivity.inputs.set() API of the Lottielab player.

Note that, when using custom variables, the Lottielab preview page won't work properly, as it doesn't have a value for this variable. For testing purposes, you can temporarily change the variable name to something like mouse.progress.x in order to be able to test the interaction, and then change it back to your custom variable name before export.