Animated Images

Related reference: Scene API / Animated Images

The current advanced Web API provides creation and playback control for GIF animated-image objects.

Create an Animated Image

const gif = await api.createAnimatedImage('https://your.domain.com/fireworks.gif');
await api.add(gif);

ArrayBuffer input is also supported.

Playback Control

Read the Paused State

const paused = await api.getAnimatedImagePaused(gif);

Play

await api.playAnimatedImage(gif, 0);

playAnimatedImage() also supports a second loopCount argument, which is useful when you want the animation to play only a certain number of times.

0 means infinite looping. If you omit the argument, the GIF's built-in loop value is used.

Pause

await api.pauseAnimatedImage(gif);

Stop

await api.stopAnimatedImage(gif);

After stopping, the animation usually returns to its initial state.

Object Events

• play - fires when the animated image starts playing

function onPlay(event) {
  const { type, target } = event;
}

await api.on('play', onPlay, gif);

• pause - fires when the animated image pauses

function onPause(event) {
  const { type, target } = event;
}

await api.on('pause', onPause, gif);

• ended - fires when the animated image finishes naturally

function onEnded(event) {
  const { type, target } = event;
}

await api.on('ended', onEnded, gif);

• loop - fires when the animated image completes one loop during looping playback

function onLoop(event) {
  // loopedTimes - how many loops have completed
  const { type, target, loopedTimes } = event;
}

await api.on('loop', onLoop, gif);

Object Capabilities Are Largely the Same as Standard Images

Animated-image objects can still use the common object APIs:

await api.setPosition(gif, 0, 1, 0);
await api.setScale(gif, 1.5, 1.5, 1.5);
await api.setObjectVisible(gif, true);

Suitable Use Cases

• replacing simple particle effects
• building 2D decorative layers
• creating short one-shot feedback animations after a click

Notes

If you need finer-grained control, such as frame-by-frame control or alpha channels, video or glTF animation is usually a better fit than GIF.