![]() |
uvi-script
Musical event scripting with Lua
|
A Lottie is a vector animation in a JSON file: shapes, colours and keyframes, not pixels. A widget wearing one asks it for a single frame at a time, so the file that would otherwise be a strip of bitmaps becomes one small document that is re-rendered at whatever size the widget happens to be.
That buys three things over a strip of bitmaps (see UIRetina for how those handle screen density):
@2x variant to ship and nothing to redraw when a panel is laid out larger; the animation is rasterised at the size it is drawn, so it is as sharp at 200 px as at 40.Two file forms are read, and the same call loads either:
.json — a single animation, exported by After Effects (Bodymovin), LottieLab, Rive's Lottie export, or written by hand..lottie — a zipped package: several animations and a state machine in one file, plus whatever palettes the machine draws on.Every widget that can wear an animation takes a path, resolved exactly where image paths are: absolute, then next to the script, then next to the Program.
The property is the short form and takes the defaults. The call form differs by widget: on Button, OnOffButton and ParamOnOffButton it takes the play mode as a second argument, which is required there – setLottieAnimation(path) with the path alone raises an error on a button, so use the property for the default "toggle" mode. On the other widgets the call takes the path only and is the same as the property. Calling it again with the same path and another mode only changes the mode – the file is not read twice. Both forms are available on Button, OnOffButton, Knob, Slider, ParamKnob, ParamSlider, ParamOnOffButton and AudioMeter.
The LottieControls example dresses a knob, a slider, both kinds of button and a meter, and ships the animations it loads.
The widget decides, and each kind decides differently:
| widget | frame |
|---|---|
| Knob, Slider, ParamKnob, ParamSlider | the value, mapped across the whole animation: frame 0 at the minimum, the last frame at the maximum |
| Button, OnOffButton, ParamOnOffButton | the click. "toggle" (the default) runs up to the last frame when switched on and back down when switched off; "trigger" replays from the first frame on every click |
| AudioMeter | the level it displays, in dB, mapped over the frames |
A toggle flipped without a click — by automation, by a script writing value, by recalling a preset — catches up on its own, so the artwork always ends where the state says it should.
A plain .json has one reel and no states beyond the frame being asked for. A .lottie package can also declare a state machine, and when it does the machine runs by itself as soon as the animation is loaded. Nothing in the script asks for it.
That machine is what gives a control its hovered and pressed look: pointer events reach an animation only while its machine is running. It redresses the control from inside the file — recolouring it is what most machines do, and a package holding several reels can switch between those too — while the click or the value goes on driving the frame underneath.
Switching reel does reset the frame, so a machine that swaps reels mid-travel sends a toggle back to its first frame. Recolouring has no such effect, which is one reason it is the common choice.
What a machine may do depends on the widget hosting it: it can change how the control looks, but it cannot take over the frame — that stays the widget's job. And a Slider is told when the pointer enters and leaves but not when it is pressed, so a slider has a hovered look and no pressed one.
The whole of it lives in the file. A script gives the path and nothing else: it cannot start, stop or steer a machine, pick a reel, or set a palette — those are the asset author's business, and there is no API for them. So an animation authored as a single .json has no hovered state at all: for that, either package it with a machine, or dress the widget with a six-frame strip image, which does have explicit hovered and held frames.
The animation is fitted inside the widget with its own proportions kept, and, being vector, re-rendered at that size rather than stretched. A widget shaped unlike its asset simply leaves room empty: a square animation in a wide, short button ends up only as tall as the button.
So size the widget like the file. A 120 × 120 badge wants a square button; a 180 × 48 slider wants a wide, short one; a 30 × 200 VU wants a tall, narrow meter, and displayAsMono gives that one channel the whole width.
A widget wears one artwork at a time. While an animation path is set, the widget leaves its strip and its separate state images unused — so an animation wins, but give a widget one or the other anyway: the images are dead weight next to it.
Which to reach for:
The animation is drawn by ThorVG, and what it can draw is the practical limit on what an asset may use. Their Lottie Support page is the list to check before leaning on a feature: shapes, strokes, gradient fills, masks and mattes, trim paths and repeaters, embedded JPG, PNG and WebP images, text, and layer effects such as drop shadow, gaussian blur, tint and tritone are all there. Images have to be embedded: a script's animation is handed to the renderer as bytes, with no folder to resolve a linked file against. The gaps are mostly in expressions – a good part of the scripting API of After Effects has no equivalent – and in a few loop modes.
Falcon carries ThorVG 1.0.2, so a feature their page credits to a later release will not render here, whatever the file says.
A handful of habits make the difference between an asset that tracks a control and one that merely plays near it:
The formats themselves are specified away from us: Lottie for the animation, and dotLottie for the package – the latter is where the layout of a .lottie comes from, animations in a/ and the state machine in s/, and where the machine's own vocabulary of states, transitions, guards and inputs is defined.
A path that no resource root holds, and a file the parser refuses, are both recorded in the script log — the first also prints in the script console. If a widget stays blank, that log names the file it looked for and the roots it looked in.