Tweens - samme/phaser3-faq GitHub Wiki

Tweens

Tweens are a timed change in one or more numeric properties of one or more target objects. The targets are often game objects, but they can be anything.

// Fade a sound's volume to 0 over 2 seconds.
this.tweens.add({
  targets: sound,
  duration: 2000,
  volume: 0,
});

Tweens contain TweenData, which represent the state of one property on one target.

// Change 2 sprites' coordinates and alpha over 1 second.
// This makes 6 TweenData (2 targets × 3 properties).
this.tweens.add({
  targets: [ sprite1, sprite2 ],
  duration: 1000,
  x: -1,
  y: 1,
  alpha: 0
});

Tweens are discarded immediately once they complete. If you want to restart or seek a tween after it completes, create it with { persist: true } or set its persist to true before it completes.

Properties

You can put the target properties directly in the config:

this.tweens.add({
  x: 1,
  y: 2
  // …
});

or in props:

this.tweens.add({
  props: { x: 1, y: 2 }
  // …
});

You can give relative values instead of end values:

this.tweens.add({
  x: '+=1',
  y: '-=1'
  // …
});

The implicit start values are the current values of the target properties (when the tween is created), but you can give both start and end as from and to:

this.tweens.add({
  x: { from: 0, to: 1 },
  // …
});

If the tween also has a start delay, you can also give a start value (which means active):

this.tweens.add({
  delay: 500,
  x: { start: -1, from: 0, to: 1 },
  // …
});

This is applied to the target as soon as the tween activates, and until the start delay has expired.

You can tween the properties independently:

this.tweens.add({
  x: { value: 1, duration: 500, delay: 500, repeat: 1 },
  y: { value: 2, duration: 2000 }
  // …
});

Timing

A Tween can loop and have a loopDelay and completeDelay.

A TweenData can repeat or yoyo and have a delay, hold, or repeatDelay. Yoyo means it plays forward for 1 duration, holds, then plays backward for 1 duration.

Staggers

Each TweenData (property per target) can have a different delay.

Easing

The "in" functions are accelerating. The "out" functions are decelerating. The "in-out" functions are accelerating then decelerating, so they work well with yoyos.

Callbacks and events

The Tween events are active, start, loop, and complete. They all pass (tween, targets).

The TweenData events are update, repeat, and yoyo. They all pass (tween, target, key, current, previous). Each TweenData sends its own event, so there is one call per property per target. You can test the property key to be more specific:

this.tweens.add({
  // …
  onYoyo: function (tween, target, key) {
    if (key === 'x') target.toggleFlipX();
  }
});

Reusing tweens, or not

You can restart a tween. Sometimes an alternative is to create a new tween, reusing a single tween config.

Counters

Counters are "number tweens" with a built-in target, e.g, { value: 0 }.

You can get the current value of the counter in the current argument of the onUpdate callback or elsewhere from counter.getValue().

Chains

Chains are sequences of tweens.

Unlike tweens, they don't have duration, elapsed, or progress, etc., and they can't seek, but they can be paused, stopped, or restarted.