Every building block
Everything the Studio can put into a state machine or a theme, and what the dotLottie player does with it. Each row names the example that shows it. Every behaviour was played in dotlottie-web 0.80 on files the panel wrote.
Examples: the templates, the music player, the thermostat, Themes lab.
Starting points
| What you get | Shown in | |
|---|---|---|
| Blank | One state; build the rest yourself. | Music player |
| Toggle, Hover, Click → segment, Number → segment, Sequence, Idle → action → Idle, Intro → loop, Hover + click, Button, Loading → done, Carousel, Toggle with two segments | A finished machine for one common pattern. | All templates, one page each |
States
| Setting | What it does | Shown in |
|---|---|---|
| plays something | Plays a segment (a marker) or the whole animation. | every example |
| plays nothing — wait on a frame | Parks the playhead on a frame and plays nothing. Timers keep running. | Thermostat: the dial |
| Waits instead of playing | Parks on the segment instead of playing it: where the playhead already is inside it, otherwise on its first frame. | Hover + click: rest and sent |
| Listener (only listens) | Plays nothing. Its rules apply from every state. A machine can have one. | Music player, Thermostat |
| Start here | The state the machine starts in. | Music player |
| Direction: forwards / backwards | Backwards plays the segment from its end to its start. It reports finishing only some of the time (measured), so don't make anything wait for it. Two states on the same segment, one each way, carry the playhead on. | Hold to confirm |
| Direction: there and back | Forwards, then back. Never reports finishing, so nothing may wait for it: use it for loops such as a hover. The Studio flags a when it finishes rule on it. | Music player |
| Repeat: once / for ever | For ever loops the segment. | Music player |
| Speed | 2 plays twice as fast. | Thermostat |
| Background | A colour painted behind the animation while the state runs, cleared when it leaves. | Thermostat: the canvas glows while boosting |
| Ends the machine | The machine stays in this state for good: no rule leaves it. The page can start the machine again. | Thermostat |
When a rule fires
| Trigger | What it does | Shown in |
|---|---|---|
| click (on a layer, or anywhere) | Pressed and released over the target. | Music player |
| pointer down | The moment the button goes down. | Thermostat |
| pointer up | The moment it is released over the target. For press-and-hold, use it on the whole canvas. | Thermostat |
| pointer enter / pointer exit | The pointer comes onto / leaves the target. | Hover, Music player |
| pointer move | Any movement over the animation; the whole canvas only. | Thermostat |
| it finishes / it finishes one loop | The state's segment played out / one pass of a loop. | Sequence, Thermostat |
| another step finishes | A rule on the listener that waits for a different state to finish. | Thermostat: the listener waits for wakeup |
| a number of seconds passes | After N seconds, or when the clock passes a time stored in an input. | Carousel, Thermostat |
| an input changes | An input reaches a value, or an event fires. Set by your page, or by the machine itself. | Number → segment, Music player |
| straight away | A rule with nothing to wait for: the state is left the moment it is entered. With conditions, it picks where to go — a routing state. | Music player: start, track-1…3, ended |
A layer click is caught anywhere in the layer's box: a layer that encloses a button also catches its clicks. Two interactions on the same layer both run.
Conditions
All conditions on a rule must be true together.
| Compare | Works on | Shown in |
|---|---|---|
| is, is not | numbers, text, true/false | Thermostat |
…another input ($name) | compare with an input instead of a value | Music player: track is not $prev; Thermostat: temp is not $shown |
| is more than, is at least | numbers | Thermostat, Music player |
| is less than, is at most | numbers | Thermostat |
| fires | events | Music player |
Transitions
| What it does | Shown in | |
|---|---|---|
| cut to it | Jumps straight to the next state's first frame. | every example |
| blend into it (over N s) | Plays the timeline from the current frame to the next state's first frame in that time — not a cross-fade. | Music player: Stop rewinds; its preview settles back |
| back to the same state | Enters again and runs the entering actions again. | Thermostat |
Actions
Actions run when something happens (Advanced → Interactions), or on a state: entering, leaving (whenever one of its own rules takes the machine out of it; not when the listener does), when it finishes, on every loop. In an interaction the player checks the rules after each action, so order them so that every step is safe. See the thermostat's timer.
| Action | What it does | Shown in |
|---|---|---|
| Set a number / boolean / string | Writes a value. A number may be @elapsedTime (the clock) or $name (another input). | Thermostat |
| Toggle a boolean | Flips true/false. | Toggle, Music player |
| Fire an event | Signals once; a rule waiting on it goes through. | Music player |
| Reset an input | Back to the value it was declared with. (Not on the first state's entering when the machine is restarted — use Set there.) | Thermostat |
| Increment / Decrement | Adds / subtracts — 1 unless you type another number. | Music player |
| Multiply, Floor | Scales; rounds down. | Thermostat |
| Clamp to a range | Keeps a number between min and max. | Thermostat (+ and − stay within 16–28) |
| Set a random number | Anything from min to max; Floor it for a whole number. | Music player |
| Jump to a frame | Moves the playhead to frame N — or to $name, an input's value. With wait on a frame, the state stays there. While the state plays a segment, only a frame inside that segment sticks. | Thermostat: the dial |
| Jump to progress | Moves the playhead to a percentage of the whole animation: 50 is half way. Takes $name too. | State machines → page recipes |
| Switch theme | Repaints with a theme. From a state or straight from a click. On a parked state it shows only when the frame changes (why). | Music player, Thermostat |
| Open a URL | Opens a link. The page must allow the address (openUrlPolicy). | Music player |
| Fire a custom event | Tells your page something (stateMachineCustomEvent). | Music player, Thermostat |
Themes
| What it does | Shown in | |
|---|---|---|
| Colour token | Re-colours fills and strokes. | Themes by example |
| Number token | Opacity, rotation, fill opacity… | Themes lab |
| Position, Scale tokens | Move or resize a layer. | Themes lab, Thermostat |
| Animated token: follow / Capture / freeze | Play the comp's animation, the theme's own keys, or one still value. | Themes lab, Thermostat |
| Several themes switched by the machine | Switch theme per track, or per mode button. | Music player, Thermostat |
| Not a token | Shape geometry, trim, repeater, anchor point (the file would draw nothing), and stroke width (a theme drops the stroke). | Themes lab |
Files and pages
| Shown in | |
|---|---|
Several machines in one file; the page picks one with stateMachineLoad(id). | Music player |
Driving inputs from the page: stateMachineSet…Input, stateMachineFireEvent. | Music player, Number → segment |
Listening: custom events, input changes (stateMachineNumericInputValueChange). | Thermostat |
Starting again after a machine ended: stateMachineStart(). | Thermostat |
Sending pointer events from code: stateMachinePostClickEvent(x, y) (canvas pixels). | State machines → From a web page |
Reading the state: stateMachineGetCurrentState(), event stateMachineStateEntered. | State machines → From a web page |
Themes and slots from code: setTheme, resetTheme, setColorSlot, setScalarSlot. | Slots and themes → From a web page |
Traps
- There and back never reports finishing, so nothing may wait for it. Back and there was measured playing forwards once and finishing, so it does not do what its name says; use Backwards or There and back instead.
- A layer click counts anywhere in the layer's box.
- Actions in an interaction are checked one by one.
- More: How the player behaves.