tweens

Tweens

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

Quick Start

// 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 TweenManager instance, available in every Scene. The add() method creates a tween, adds it to the manager, and starts playback immediately.

Core Concepts

Tween Lifecycle

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).

Fire-and-Forget Design

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.

Targets

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 });