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

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.

Property Values

Array values use linear interpolation by default; override with the interpolation config ('linear', 'bezier', 'catmull').

Common Patterns

Basic Tween

Multiple Properties with Per-Property Config

Yoyo and 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

Stagger offsets a value across multiple targets via this.tweens.stagger():

StaggerConfig: start (offset), ease (string/function), from ('first'/'center'/'last'/index), grid ([w, h]).

Tween Chain

A TweenChain plays tweens in sequence. Each tween in the chain starts after the previous one completes:

Each entry in tweens is a standard TweenBuilderConfig. Chain-level config supports loop, loopDelay, completeDelay, paused, persist, and chain-level callbacks. Per-tween callbacks (onUpdate, onRepeat, onYoyo) belong on individual entries. Use chain.add(tweenConfigs) to append dynamically.

Relative Values

Callbacks and Events

Number Tweens

A Number Tween has no target object. It tweens between two numeric values:

Controlling and Killing Tweens

Configuration Reference

TweenBuilderConfig

TweenChainBuilderConfig

NumberTweenBuilderConfig

TweenPropConfig (Per-Property Object)

Used when a property value is an object instead of a number/string. Supports: value, getActive, getEnd, getStart, ease, delay, duration, yoyo, hold, repeat, repeatDelay, flipX, flipY, interpolation. All override the tween-level defaults for that one property.

Easing Functions

All easing names are case-insensitive. Use the string name in the ease config property.

Power Aliases

Full Easing List

Each type supports .easeIn, .easeOut, .easeInOut variants. The bare name defaults to Out.

Types: Quad, Cubic, Quart, Quint, Sine, Expo, Circ, Elastic, Back, Bounce.

Usage: 'Sine.easeInOut', 'Bounce.easeIn', 'Cubic.easeOut', 'Back' (same as 'Back.easeOut').

Special: Linear (no easing), Stepped (discrete steps -- easeParams: [numSteps]).

Custom: ease: function (t) { return t * t; } where t is 0 to 1.

Events

Tweens (and TweenChains) extend EventEmitter. You can listen via .on():

Event listener signature for Tween events: function(tween, targets). During seeking (tween.isSeeking === true), events and callbacks are suppressed by default.

API Quick Reference

TweenManager (this.tweens)

Tween Instance

Key properties: targets, duration, elapsed, progress (0-1), totalProgress (0-1 including loops), totalDuration, timeScale, paused, persist, data (TweenData[]), isInfinite, isNumberTween.

TweenChain Instance

Extends BaseTween. Has all tween playback methods (play, pause, resume, stop, restart, complete, etc.) plus add(tweenConfigs) to append tweens dynamically. Properties: currentTween, currentIndex.

Gotchas

• Underscore properties are ignored. A tween will skip any property whose name starts with _.
• Tweens auto-destroy. If you store a reference to a tween and try to use it after completion, it may be destroyed. Set persist: true to keep it alive, but you must destroy() it yourself when done.
• repeat vs loop. repeat is per-property (on TweenData). loop restarts the entire tween. A repeat of 1 means the property plays twice total.
• loop: -1 means onComplete never fires. An infinitely looping tween never completes. Use completeAfterLoop() to end it gracefully.
• Seeking suppresses events. When calling tween.seek(), events and callbacks are not dispatched unless you pass true as the third argument.
• Stagger only works with multiple targets. Using this.tweens.stagger() on a single-target tween has no visible stagger effect.
• Destroyed targets. A tween completes early if its target has isDestroyed set to true. Always clean up tweens before destroying the objects they reference, or rely on this auto-check.
• TweenManager.timeScale multiplies with Tween.timeScale. The effective speed is managerTimeScale * tweenTimeScale. Setting either to 0 freezes the tween.
• Duration cannot be zero. Internally clamped to a minimum of 0.01ms.
• TweenChain targets are inherited. If you set targets at the chain level, individual tweens in the chain inherit them unless they specify their own.

Source File Map