2D

Lottie

Lottie is a cross-platform animation solution released by Airbnb around 2017, supporting iOS, Android, React Native, and web. It uses the Bodymovin plugin to parse Adobe After Effects (AE) animations and exports JSON files for rendering animations on mobile and web platforms. Designers create animations in AE, export JSON files via Bodymovin, and developers use these JSON files to achieve 100% faithful animation reproduction.

In Galacean, users can easily handle Lottie assets and add components.

Vector animations and masks are currently not supported.

Asset Upload

Designers are advised to export Lottie files with images embedded in Base64 format within the JSON file. Developers should upload the .json file to Galacean Editor via the Assets Panel:

Click the Upload button in the Assets Panel.
Select Lottie as the asset type.
Choose a local Lottie JSON file and upload it.

Adding Components

Select an entity and add the Lottie component.
Assign the resource property to the uploaded asset to display and play the Lottie animation.

Adjust parameters in the Properties Panel for customization:

Property	Description
`resource`	Select Lottie asset.
`autoPlay`	Auto-play on load. Default: `true`.
`isLooping`	Loop animation. Default: `true`.
`speed`	Playback speed. `1` = original speed. Higher values = faster.
`priority`	Rendering priority. Lower values = higher priority.

Runtime Configuration

To dynamically configure Lottie during runtime:

// Get the Lottie component from the entity
const lottie = lottieEntity.getComponent(LottieAnimation);
// Set properties
lottie.speed = 2;

To dynamically create a Lottie component:

// Load Lottie resource
const lottieResource = await engine.resourceManager.load({ 
  url: '/光球.json', 
  type: 'EditorLottie' 
});
// Add Lottie component to an entity
const lottie = entity.addComponent(LottieAnimation);
lottie.resource = lottieResource;

API Methods

Method	Description
`play()`	Play animation. Accepts clip names.
`pause()`	Pause animation.

Animation End Event

Use the Promise returned by play() to detect animation completion:

const lottie = lottieEntity.getComponent(LottieAnimation);
await lottie.play();
// Execute follow-up logic...

Clip Slicing

The editor supports slicing animations into segments by defining name, start, and end frames. This adds a lolitaAnimations field to the Lottie JSON:

"lolitaAnimations": [
  { "name": "clip1", "start": 0, "end": 30 },
  { "name": "clip2", "start": 50, "end": 100 }
]

Dependency Installation

Install the required package:

npm i @galacean/engine-lottie --save

Pro Code Development

For Pro Code workflows, use tools-atlas-lottie to generate an .atlas file from the JSON:

import { LottieAnimation } from "@galacean/engine-lottie";
 
engine.resourceManager.load({
  urls: [
    "https://gw.alipayobjects.com/os/bmw-prod/b46be138-e48b-4957-8071-7229661aba53.json",
    "https://gw.alipayobjects.com/os/bmw-prod/6447fc36-db32-4834-9579-24fe33534f55.atlas"
  ],
  type: 'lottie'
}).then((lottieEntity) => {
  root.addChild(lottieEntity);
  const lottie = lottieEntity.getComponent(LottieAnimation);
  lottie.isLooping = true;
  lottie.speed = 1;
  lottie.play();
});