Use this skill when animating properties over time in Phaser 4. Covers tweens, tween chains, easing functions, stagger, yoyo, repeat, callbacks, number tweens, and the TweenManager. Triggers on: tween, ease, animate, this.tweens.add, tween chain, stagger.
Animating properties over time in Phaser 4 -- TweenManager, creating tweens, tween config, easing functions, tween chains, stagger, yoyo, repeat, callbacks, and tween targets.
Key source paths: src/tweens/TweenManager.js, src/tweens/tween/Tween.js, src/tweens/tween/TweenChain.js, src/tweens/tween/BaseTween.js, src/tweens/builders/, src/tweens/typedefs/, src/tweens/events/, src/math/easing/
Related skills: ../sprites-and-images/SKILL.md, ../animations/SKILL.md
// In a Scene's create() method:
const logo = this.add.image(100, 300, 'logo');
// Basic tween -- move the logo to x:600 over 2 seconds
this.tweens.add({
targets: logo,
x: 600,
duration: 2000,
ease: 'Power2'
});
this.tweens is the scene's instance, available in every Scene. The method creates a tween, adds it to the manager, and starts playback immediately.
TweenManageradd()Created -> Active (onActive) -> Start Delayed (delay) -> Playing (onStart, onUpdate per frame) -> Yoyo/Repeat (onYoyo, onRepeat) -> Loop (onLoop) -> Complete (onComplete, then auto-destroyed unless persist: true).
Tweens auto-destroy after completion. You do not need to store a reference unless you want to control them later. Set persist: true in the config to keep a tween alive after completion for replay via tween.play() or tween.restart(). You must manually call tween.destroy() on persisted tweens when done.
The targets property accepts a single object, an array of objects, or a function that returns either. Targets are typically Game Objects but can be any JavaScript object with numeric properties. A tween will not manipulate any property that begins with an underscore.
// Single target
this.tweens.add({ targets: sprite, alpha: 0, duration: 500 });
// Multiple targets
this.tweens.add({ targets: [sprite1, sprite2, sprite3], y: 100, duration: 1000 });
this.tweens.add({
targets: sprite,
x: 400, // absolute value
y: '-=100', // relative (subtract 100 from current)
rotation: '+=3.14', // relative (add to current)
alpha: { value: 0, duration: 300, ease: 'Cubic.easeIn' }, // per-property config
scale: [0.5, 1.5, 1], // array: interpolates through values over duration
angle: function (target, key, value, targetIndex, totalTargets, tween) {
return targetIndex * 90; // function: called once per target
},
duration: 1000
});
Array values use linear interpolation by default; override with the interpolation config ('linear', 'bezier', 'catmull').
this.tweens.add({
targets: this.player,
x: 500,
y: 300,
duration: 1000,
ease: 'Sine.easeInOut'
});
this.tweens.add({
targets: this.enemy,
x: { value: 600, duration: 1500, ease: 'Bounce.easeOut' },
y: { value: 200, duration: 1000, ease: 'Power2' },
alpha: { value: 0.5, duration: 500, delay: 1000 }
});
this.tweens.add({
targets: this.coin,
y: '-=50',
duration: 600,
ease: 'Sine.easeInOut',
yoyo: true, // returns to start value after reaching end
hold: 200, // pause 200ms at the end value before yoyo-ing back
repeat: -1, // -1 = infinite, 0 = play once, 1 = play twice, etc.
repeatDelay: 300 // pause 300ms before each repeat
});
repeat controls how many extra times each property plays. A repeat of 1 means the tween plays twice total. The loop property (on BaseTween) restarts the entire tween from scratch, including all properties. Use repeat for property-level looping and loop for tween-level looping.
Stagger offsets a value across multiple targets via this.tweens.stagger():
// 100ms delay between each target