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.
- Ease Map — shortcut names
- Phaser.Math.Easing — constant namespace
- Easing demos
- Easing plots
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.