# 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 States 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 TransitionGuards. 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 States and more to come.

Context variables can be set and modified with ListenerActions 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
The OnPointer.. events can send coordinates to the state machine. If the Transition has a target 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 Events to the state machine via the postEvent 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

Simple Animation
animation.lottie
13KB (88%reduced)
Download
Animation with Image asset
animation-external-image.lottie
584KB (16%reduced)
Download
Animation with Image(base64)
animation-inline-image.lottie
835KB (66%reduced)
Download