# 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 using the Deflate compression method, with the file extension .lottie and the MIME type application/zip+dotlottie.

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:

# 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.

⚠️ 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:

# 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.

# 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

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.

# 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.

# Sample dotLottie Files