# Structure
# dotLottie Structure
dotLottie is an open-source file format that aggregates one or more Lottie files and their associated resources (images, fonts, etc) into a single file to enable efficient and easy distribution of an animation. dotLottie files are ZIP archives compressed with the Deflate compression method and carry the file extension of .lottie
.
A dotLottie file ZIP archive has the following file and folder structure:
.
├─ manifest.json
├─ animations
│ ├─ animation-1.json
│ └─ animation-2.json
├─ images
│ ├─ img_1.json
│ └─ img_2.json
├─ themes
| ├─ theme_1.json
| └─ theme_2.json
├─ states
│ ├─ statemachine_0.json
│ └─ statemachine_1.json
├─ audio
│ └─ audio.mp3
manifest.json
— JSON file containing metadata about the animations (version, author details, list of animations in the package, playback configuration, playlist/sequencing information).animations
— Folder containing the animation(s).images
— Folder containing image assets required by the animation(s).themes
— Folder containing different themes for the animation(s).states
— Folder containing state machines.audio
— Folder containing audio asset required by the animation(s).
# manifest.json
{
// Name and version of the software that created the dotLottie
"generator": "LottieFiles 1.0",
// Target dotLottie version
"version": 1.0,
// Revision version number of the dotLottie
"revision": 1,
// Name of the author
"author": "Alibeyya",
// List of animations
"animations": [
{
// Name of the Lottie animation file without .json
"id": "test",
// Desired playback speed
"speed": 1.0,
// Theme color
"themeColor": "#ffcc00",
// Whether to loop or not
"loop": true
},
// More animation file listings, if any...
....
],
// Custom data to be made available to the player and animations
"custom": {},
// IDs of the state machines
"states": [],
// IDs of the themes
"themes": [
{
// Name of the theme file without .json
"id": "theme1",
// List of animations scoped to this theme, if any (optional)
"animations": ["test"],
}
]
}
# Interactivity Structure
# dotLottie Interactivity powered by state machines
Interactivity is currently in it's early stages of developement and not production ready. If your state machine is not working as expected please create an issue on Github. If you have any questions please create a Github ticket and we will be happy to help you get started with this new and exciting feature.
dotLottie files (.lottie) can now contain state machine definitions and be loaded at runtime. With this feature we aim to allow you to create deep, rich and interesting interactive scenarios for your Lottie animations whether on Web or Mobile. We want to empower your creativity and enable you in creating engaging Lottie animations.
State machines allow you to connect different States
and animations together via Transitions
triggered by Events
enabled with Listeners
.
# Creation and usage
dotLottie files (.lottie) can now contain state machine definitions and can be loaded at runtime. Currently the way to create and add state machines to your .lottie file is by using dotlottie-js.
Once your .lottie
file created you can load it at runtime on Web, iOS and Android.
# Content of a state machine
# States
States create the foundation of your state machine allowing you to performs different actions on your Lottie thanks to different types of states available.
# Playback State
A PlaybackState
modifies how your animation will play. You can use this state as a building block to change the following settings of your animation:
Property name | Description | Type | Required |
---|---|---|---|
name | Name of the state. | String | Yes |
animation_id | Loads the animation with this id from the current .lottie file. | String | |
loop | Loop playback. | Bool | |
autoplay | Play the animation when it loads. | Bool | |
mode | Forward , Reverse , Bounce , ReverseBounce . Changes the playback direction. | String | |
speed | Playback speed. | Float | |
marker | Loads the segements defined by the marker contained inside the animation. | String | |
segment | Define a frame interval to play. | [f32, f32] | |
background_color | Change the background color of the animation. | u32 | |
use_frame_interpolation | Enable frame interpolation for smoother playback. | Bool | |
entry_actions | Perform an Action when entering this state. | Array<Action> | |
exit_actions | Perform an Action when exiting this state. | Array<Action> | |
reset_context | Reset a context variable to it's original variable. Define the variables key here. Pass "*" to reset all context variables. | string |
# Sync State
⚠️ Not implemented
Allows you to sync the animation to a frame. The frame is fetched from a value contained inside the context of the state machine.
# Global State
⚠️ Not implemented
Transition from this state regardless of the current state.
# Final State
⚠️ Not implemented
Upon entering this state the state machine will shutdown.
# Actions
⚠️ Actions are not currently available.
Actions
are added as entry_actions
and exit_actions
inside State
s and allow you to perform operations that can be outside the context of the state machine itself.
# Theme action
Load and apply a theme from your .lottie file.
# Sound action
Play a sound.
# URL action
Open a URL.
# Transitions
Transitions make up the glue of your state machine, allowing you to move between states depending on events that are sent to the state machine.
# Transition
Define which states are connected together.
Property | Description | Type | Required |
---|---|---|---|
type | Define which type of transition this is. Currently Transition is available. | String | Yes |
from_state | Index of the origin state. | u32 | Yes |
to_state | Index of the state to transition to. | u32 | Yes |
guards | An array of TransitionGuard objects. More information is available in the Guarded Transitions section. | Array<TransitionGuard> | |
numeric_event | Define a value to compare against when receiving this event. If it is equal the transition will occur. | NumericEvent | |
string_event | Define a value to compare against when receiving this event. If it is equal the transition will occur. | StringEvent | |
boolean_event | Define a value to compare against when receiving this event. If it is equal the transition will occur. | BooleanEvent | |
on_complete_event | The transition will occur with the OnComplete player event. The event is managed internally. OnComplete will only fire if the animation is not looping. | OnCompleteEvent | |
on_pointer_down_event | Transition upon receiving this event. If a target layer is defined, the transition will only occur if the pointer coordinates are within the target layer hitbox. | OnPointerDown | |
on_pointer_up_event | Transition upon receiving this event. If a target layer is defined, the transition will only occur if the pointer coordinates are within the target layer hitbox. | OnPointerUpEvent | |
on_pointer_enter_event | Transition upon receiving this event. If a target layer is defined, the transition will only occur if the pointer coordinates are within the target layer hitbox. | OnPointerEnterEvent | |
on_pointer_exit_event | Transition upon receiving this event. If a target layer is defined, the transition will only occur if the pointer coordinates are within the target layer hitbox. | OnPointerExitEvent | |
on_pointer_move_event | Transition upon receiving this event. If a target layer is defined, the transition will only occur if the pointer coordinates are within the target layer hitbox. | OnPointerMoveEvent |
⚠️ Target layers with on_pointer events is not currently supported.
# Guarded Transitions
A Transition
can contain an array of TransitionGuard
s. The transition occurs only if the guard evaluates to true
. If there are multiple guards they all need to evaluate to true
for the transition to occur.
A TransitionGuard
contains the following properties:
Property | Type | Description |
---|---|---|
type | String | Define the data type the guard contains, as a string. Possible values are: Numeric , String , Boolean |
context_key | String | Optionally define a context key to use when evaluating the guard. The value associated with the key will then be used. If no context key is defined, the value sent with the event will be used. |
condition_type | String | Define how to evalute the two values. Accepted values are: GreaterThan , GreaterThanOrEqual , LessThan , LessThanOrEqual , Equal , NotEqual |
compare_to | String , Float , Bool | The value to compare to. |
# Context
⚠️ Context is currently only configurable with the methods listed below. Guarded transitions support use of context variables.
Every state machine can contain variables you define. These variables are then used for Guarded transitions
, special State
s and more to come.
Context variables can be set and modified with ListenerAction
s or directly via the state machines with the following methods:
setStateMachineNumericContext
setStateMachineStringContext
setStateMachineBooleanContext
# Definition
When defining your state machine variables 3 types are available for use along with a key for later access and the original value to set.
Property | Type | Description |
---|---|---|
type | String | Define the type of your variable. Accepted type values are: "Numeric ", "String ", "Boolean " |
key | String | Unique key to access your variable. |
value | f32 , String , bool | The original value for your context variable. |
# Events
Events allow you to communicate with the state machine, allowing it to perform transitions if the corrrect event is received.
You can send events to the state machine with the postEvent
method.
# Event types
Type | Content |
---|---|
Bool | {value: bool} |
String | {value: String} |
Numeric | {value: f32} |
OnPointerDown | { x: f32, y: f32} |
OnPointerUp | { x: f32, y: f32} |
OnPointerMove | { x: f32, y: f32} |
OnPointerEnter | { x: f32, y: f32} |
OnPointerExit | |
OnComplete |
The OnComplete
event is managed internally based on player events.
⚠️ Not implemented
TheOnPointer..
events can send coordinates to the state machine. If theTransition
has atarget
property these coordinates will be used to determine if the event took place within the correct layer of the animation.
# Listeners
⚠️ Listeners are currently not managed nor setup by the supported frameworks. This means currently you have to manage your own listeners and send
Event
s to the state machine via thepostEvent
method.
Listeners allow you to declare which gesture events you want the dotLottie player to listen for and notify the state machine of. If you want to modify a context variable when a gesture is captured, you can add listener actions as described below.
# Listener properties
⚠️ Target is not implemented.
Property | Type | Description | Required |
---|---|---|---|
type | String | Define the pointer event to listen for. Accepted values for type are : "PointerUp ","PointerDown ","PointerEnter ","PointerExit ","PointerMove ". | yes |
target | String | Apply the listener on a specific layer of the animation. |
# Listener Actions
⚠️ Listener actions are not implemented.
To allow you to modify context variables without depending on code, listeners can contain actions that will perform with the listener is triggered. For example you might might have a transition guard that needs a context variable to be greater than 3, defining an action on a listener can increment that counter for you.
The properties can be added on top of the ones described in the previous section.
Property | Type | Description | Required |
---|---|---|---|
action | String | Operation to perform on a context variable. Accepted values for action are : "INCREMENT ", "DECREMENT ","SET ", "NONE ". | |
value | String , Boolean , f32 | Value to use in the context variable operation. | |
context_key | String | The key of the context variable. |
# Sample dotLottie Files
← Introduction Features →