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. The Tween completes or loops after every TweenData completes. If a TweenData repeats infinitely, the Tween will never complete or loop.

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.

If you set delay, duration, hold, repeat, repeatDelay, or yoyo directly in the Tween config, these are applied to each TweenData in the Tween.

this.add.tween({
  repeat: -1,
  x: 1,
  y: 2,
  // …
})

// means

this.add.tween({
  x: { value: 1, repeat: -1 },
  y: { value: 2, repeat: -1 },
  // …
})

Staggers

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

Easing

Generally, the "in" functions are slow–fast (start-biased). The "out" functions are fast–slow (end-biased). The "in-out" functions are slow–fast–slow, so they work well with yo-yos.

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.