Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 36 ยท Sprites and Animation

Phaser Tweens: Easing, Chains, Stagger and Counters

Animate any property smoothly with Phaser tweens: duration, easing, delay, yoyo, repeat, callbacks, tweens.chain, stagger and counters, with runnable examples.

A frame animation swaps pictures. A tween changes numbers: the position, scale, alpha, angle or any other numeric property of any object, smoothly from a start value to an end value over time. The word comes from "in-betweening" in traditional animation: you define the key poses and the computer fills in the frames between them.

Tweens are the cheapest way to make a game feel polished: buttons that bounce, text that fades in, coins that float up, screens that slide, enemies that flash.

Your first tween

JavaScript
this.tweens.add({
  targets: sprite,      // what to change (one object or an array)
  x: 400,               // property: end value
  duration: 1000,       // milliseconds
  ease: 'Sine.easeInOut'
});

That moves sprite.x from where it is to 400 in one second. Whatever number properties you list (x, y, alpha, scale, angle, even your own health) are interpolated. You can set the start value too: x: { from: 0, to: 400 }, or a start-to-end shorthand x: { start: 0, to: 400 }. A relative end value works with strings: x: '+=100' moves 100 more to the right, angle: '-=45' rotates back 45 degrees.

Common tween options

Option Meaning
duration length in ms (default 1000)
delay wait before starting
ease the speed curve, see below
repeat extra repeats; -1 forever
repeatDelay pause between repeats
yoyo go there and back
hold wait at the end before yoyo-ing back
loop shortcut for repeat, e.g. loop: -1
paused create it stopped
persist keep it after finishing (so you can play it again)
onStart, onUpdate, onRepeat, onYoyo, onComplete callbacks

Easing: the feel of the motion

Without easing, a tween moves at constant speed ('Linear'), which looks mechanical. Easing functions bend the speed curve so things start slow, finish slow, bounce or overshoot. Names follow Family.direction:

  • In: slow start, fast end, like something falling; Out: fast start, slow end, like something sliding to a stop (the most pleasant for UI); InOut: slow at both ends.
  • Families: Sine, Quad, Cubic, Quart, Quint, Expo, Circ (increasingly strong), plus special ones: Back (overshoot), Elastic (springy), Bounce.

A good default for moving something onto the screen is 'Cubic.easeOut' or 'Back.easeOut'; for gentle looping motion use 'Sine.easeInOut'.

Easing race

All six dots cover the same distance in the same time, yet each feels different. Pick the easing before changing the duration; it matters more than you expect.

Tween callbacks and control

JavaScript
const tween = this.tweens.add({
  targets: coin, y: coin.y - 60, alpha: 0, duration: 600,
  onComplete: () => coin.destroy()
});

tween.pause();          // freeze it
tween.resume();
tween.stop();           // end now (onComplete does not fire)
tween.complete();       // jump to the end and fire onComplete
tween.progress;         // 0 to 1

onUpdate gives you (tween, target) every frame. The tween object also exposes isPlaying() and totalProgress. Use this.tweens.killTweensOf(object) to cancel everything animating an object, for example before starting a competing tween so two tweens do not fight over x.

Many targets and stagger

Pass an array of targets and a delay function to ripple an effect across a group. this.tweens.stagger(100) returns a delay function that increases by 100 ms for each target.

JavaScript
this.tweens.add({
  targets: letters,                 // an array of game objects
  y: '-=30',
  yoyo: true,
  duration: 300,
  delay: this.tweens.stagger(80)    // 0, 80, 160 ... ms
});

You can stagger from the middle (stagger(80, { from: 'center' })), in a grid, or with any custom function (target, key, value, index, total) => number.

Chains: sequences of tweens

To run tweens one after another, use tweens.chain:

JavaScript
this.tweens.chain({
  targets: ship,
  tweens: [
    { x: 400, duration: 600, ease: 'Cubic.easeOut' },
    { y: 200, duration: 400 },
    { angle: 360, duration: 800 },
    { alpha: 0, duration: 300 }
  ],
  onComplete: () => console.log('sequence finished')
});

Each entry runs after the previous one ends. Chains replaced the older "timeline" API; they can also repeat (loop/repeat) and be paused as one unit.

Counters: tweening a plain number

Sometimes there is no object to animate, just a number, such as a score that should count up or a bar that should drain. addCounter tweens a value from one number to another and calls you each frame:

JavaScript
this.tweens.addCounter({
  from: 0, to: 1000, duration: 800, ease: 'Quad.easeOut',
  onUpdate: (tween) => scoreText.setText(Math.floor(tween.getValue())),
});

The same trick colors things: tween a counter from 0 to 100 and mix two colors with Phaser.Display.Color.Interpolate.ColorWithColor(from, to, 100, tween.getValue()).

Chain, stagger and counter

Look at how little code produces a lot of motion. This "juice" is what makes the difference between a prototype and a game that feels good.

Timers versus tweens

Do not confuse the two systems: this.time.addEvent runs code at moments in time; a tween changes values over time. Combine them: a timer spawns a coin every second, and each coin gets a tween to float up and fade. Both belong to the scene and stop with it.

Common mistakes

  • Two tweens on the same property. They fight; call killTweensOf(target) first.
  • Tweening something that has been destroyed. The tween usually cleans up, but if you destroy objects manually, stop their tweens too.
  • Forgetting persist. A finished tween is removed; if you want to replay it, create it with persist: true, or create a new one.
  • A rotating object with angle going 0 to 360 each loop jumping. Reset the angle at the loop point (as the example does), or tween '+=360'.
  • Using duration in seconds. It is milliseconds.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What can a Phaser tween change?

    Tweens interpolate numbers, so any numeric property works, including custom ones.
  2. 2. Which easing is usually best for something sliding onto the screen and stopping gently?

    Out easings are fast at the start and slow at the end, which feels natural for objects coming to rest.
  3. 3. How do you run a series of tweens one after another?

    tweens.chain runs the listed tweens in sequence.
  4. 4. What is this.tweens.addCounter good for?

    A counter tweens a value and reports it through onUpdate, so you can use it for any display.
  5. 5. x: '+=100' in a tween config means:

    String values with += or -= are relative to the current value.

Summary

  • A tween interpolates numeric properties of any object over a duration with an easing curve.
  • Use delay, repeat, yoyo, hold and callbacks to shape and react to the motion; Out easings suit UI.
  • tweens.stagger ripples an effect across many targets; tweens.chain sequences tweens; tweens.addCounter animates plain numbers.
  • Stop competing tweens with killTweensOf, and remember durations are in milliseconds.

Next: Containers, Groups and Particles