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

Property Values

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

Common Patterns

Basic Tween

this.tweens.add({
    targets: this.player,
    x: 500,
    y: 300,
    duration: 1000,
    ease: 'Sine.easeInOut'
});

Multiple Properties with Per-Property Config

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

Yoyo and Repeat

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

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

// 100ms delay between each target
delay: this.tweens.stagger(100)

// From center outward
delay: this.tweens.stagger(200, { from: 'center' })

// Range: distribute 0-1000ms across targets
delay: this.tweens.stagger([0, 1000])

// Grid stagger with easing
delay: this.tweens.stagger(500, { grid: [10, 6], from: 'center', ease: 'Cubic.easeOut' })

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:

this.tweens.chain({
    targets: this.player,
    tweens: [
        { x: 300, duration: 1000, ease: 'Power2' },
        { y: 500, duration: 800, ease: 'Bounce.easeOut' },
        { scale: 2, duration: 500 },
        { alpha: 0, duration: 400 }
    ],
    loop: 1,          // loop the entire chain once (plays twice total)
    loopDelay: 500,
    onComplete: function () {
        console.log('Chain finished');
    }
});

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

this.tweens.add({
    targets: sprite,
    x: '+=200',    // add 200 to current x
    y: '-=50',     // subtract 50 from current y
    angle: '+=180',
    duration: 1000
});

Callbacks and Events

this.tweens.add({
    targets: sprite,
    x: 600,
    duration: 2000,

    // All callbacks receive (tween, targets, ...params)
    onStart: function (tween, targets) { },
    onUpdate: function (tween, targets) { },     // per-property, per-target, per-frame
    onYoyo: function (tween, targets) { },
    onRepeat: function (tween, targets) { },
    onLoop: function (tween, targets) { },
    onComplete: function (tween, targets) { },

    onCompleteParams: ['extra', 'args'],
    callbackScope: this
});

// Set callback after creation
tween.setCallback('onComplete', function (tween, targets) { }, []);

// Event emitter style (tweens extend EventEmitter)
tween.on('complete', function (tween, targets) { });

Number Tweens

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

const counter = this.tweens.addCounter({
    from: 0,
    to: 100,
    duration: 2000,
    ease: 'Linear',
    onUpdate: function (tween) {
        const value = tween.getValue();
        console.log(value);   // 0 ... 100
    }
});

Controlling and Killing Tweens

const tween = this.tweens.add({ targets: sprite, x: 600, duration: 2000, persist: true });

// Playback control
tween.pause();                  tween.resume();
tween.stop();                   // flags for removal; fires onStop
tween.restart();                // reset and replay from beginning
tween.seek(1000);               // seek to 1000ms (suppresses events by default)
tween.complete();               // immediately complete; fires onComplete
tween.completeAfterLoop(0);     // finish after current loop
tween.forward(500);             tween.rewind(500);
tween.setTimeScale(0.5);       // per-tween speed
tween.updateTo('x', 800);      // change end value mid-tween

// Manager-level control
this.tweens.killAll();                     // destroy all tweens
this.tweens.killTweensOf(sprite);          // destroy tweens on target
this.tweens.isTweening(sprite);            // boolean check
this.tweens.pauseAll();                    this.tweens.resumeAll();
this.tweens.setGlobalTimeScale(0.5);       // global speed

Configuration Reference

TweenBuilderConfig

Property	Type	Default	Description
`targets`	any / any[]	(required)	Object(s) to tween.
`duration`	number	`1000`	Duration in ms.
`delay`	number / function	`0`	Delay before start (ms). Accepts `stagger()`.
`ease`	string / function	`'Power0'`	Easing function name or custom function.
`easeParams`	array	`null`	Parameters for parameterized easing (e.g. Elastic).
`hold`	number	`0`	Hold at end value before yoyo (ms).
`repeat`	number	`0`	Per-property repeat count. `-1` = infinite.
`repeatDelay`	number	`0`	Delay before each repeat (ms).
`yoyo`	boolean	`false`	Reverse back to start after reaching end.
`flipX` / `flipY`	boolean	`false`	Toggle flip on yoyo/repeat.
`loop`	number	`0`	Tween-level loop count. `-1` = infinite.
`loopDelay`	number	`0`	Delay before each loop (ms).
`completeDelay`	number	`0`	Delay before `onComplete` fires (ms).
`paused`	boolean	`false`	Start paused. Call `play()` to begin.
`persist`	boolean	`false`	Keep alive after completion.
`props`	object	--	Explicit property config map (alt to top-level props).
`interpolation`	string / function	--	For array values: `'linear'`, `'bezier'`, `'catmull'`.
`callbackScope`	any	tween	`this` context for callbacks.
Callbacks	function	--	`onActive`, `onStart`, `onUpdate`, `onYoyo`, `onRepeat`, `onLoop`, `onComplete`, `onStop`, `onPause`, `onResume`. Each has matching `on<Name>Params` array.

TweenChainBuilderConfig

Property	Type	Default	Description
`targets`	any / any[]	--	Default targets inherited by child tweens.
`tweens`	TweenBuilderConfig[]	(required)	Array of tween configs to play in sequence.
`loop`	number	`0`	Times to loop the entire chain. `-1` = infinite.
`loopDelay`	number	`0`	Delay before each loop (ms).
`completeDelay`	number	`0`	Delay before `onComplete` fires (ms).
`paused`	boolean	`false`	Start paused.
`persist`	boolean	`false`	Keep alive after completion.
Callbacks	function	--	`onActive`, `onStart`, `onLoop`, `onComplete`, `onStop`, `onPause`, `onResume`.

NumberTweenBuilderConfig

Property	Type	Default	Description
`from`	number	`0`	Start value.
`to`	number	`1`	End value.
`duration`	number	`1000`	Duration in ms.
`ease`	string / function	`'Power0'`	Easing function.
All standard timing	--	--	`delay`, `hold`, `repeat`, `repeatDelay`, `yoyo`, `loop`, `loopDelay`, `completeDelay`, `paused`, `persist`.
All standard callbacks	--	--	Same callback set as TweenBuilderConfig.

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

Name	Equivalent
`Power0`	`Linear`
`Power1`	`Quad.easeOut` (Quadratic Out)
`Power2`	`Cubic.easeOut`
`Power3`	`Quart.easeOut` (Quartic Out)
`Power4`	`Quint.easeOut` (Quintic Out)

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 String	Constant	Fires When
`'active'`	`Phaser.Tweens.Events.TWEEN_ACTIVE`	Tween added to manager
`'start'`	`Phaser.Tweens.Events.TWEEN_START`	Playback begins (after delay)
`'update'`	`Phaser.Tweens.Events.TWEEN_UPDATE`	Property updates each frame
`'yoyo'`	`Phaser.Tweens.Events.TWEEN_YOYO`	Property begins yoyo-ing back
`'repeat'`	`Phaser.Tweens.Events.TWEEN_REPEAT`	Property repeats
`'loop'`	`Phaser.Tweens.Events.TWEEN_LOOP`	Entire tween loops
`'complete'`	`Phaser.Tweens.Events.TWEEN_COMPLETE`	Tween finishes
`'stop'`	`Phaser.Tweens.Events.TWEEN_STOP`	`tween.stop()` called
`'pause'`	`Phaser.Tweens.Events.TWEEN_PAUSE`	`tween.pause()` called
`'resume'`	`Phaser.Tweens.Events.TWEEN_RESUME`	`tween.resume()` called

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

Method	Returns	Purpose
`add(config)`	`Tween`	Create, add, and start a tween.
`addMultiple(configs[])`	`Tween[]`	Create multiple tweens at once.
`create(config)`	`Tween`	Create without adding. Use `existing()` to add later.
`chain(config)`	`TweenChain`	Create and start a sequential chain.
`addCounter(config)`	`Tween`	Number tween (no target).
`stagger(value, config?)`	`function`	Stagger function for delay/property values.
`existing(tween)`	`this`	Add a pre-created tween to the manager.
`remove(tween)`	`this`	Remove without destroying.
`has(tween)`	`boolean`	Check if tween is in manager.
`getTweens()`	`Tween[]`	All active tweens (copy).
`getTweensOf(target)`	`Tween[]`	Tweens affecting a target.
`isTweening(target)`	`boolean`	Is target being tweened?
`killAll()` / `killTweensOf(target)`	`this`	Destroy tweens.
`pauseAll()` / `resumeAll()`	`this`	Pause/resume all tweens.
`setGlobalTimeScale(v)` / `getGlobalTimeScale()`	`this` / `number`	Global speed.
`setFps(fps)`	`this`	Limit tick rate (default 240).
`setLagSmooth(limit, skip)`	`this`	Configure lag smoothing.
`each(cb, scope)`	`this`	Iterate all tweens.

Tween Instance

Method	Purpose
`play()` / `pause()` / `resume()`	Playback control.
`stop()`	Stop and flag for removal. Fires `onStop`.
`restart()`	Reset and replay.
`complete(delay?)`	Immediately complete.
`completeAfterLoop(loops?)`	Complete after N more loops.
`seek(ms, delta?, emit?)`	Seek to ms offset.
`forward(ms)` / `rewind(ms)`	Step forward/back.
`setTimeScale(v)` / `getTimeScale()`	Per-tween speed.
`setCallback(type, fn, params?)`	Set callback after creation.
`getValue(index?)`	Current TweenData value.
`updateTo(key, value, startToCurrent?)`	Change end value mid-tween.
`hasTarget(target)` / `isPlaying()` / `isPaused()`	State checks.
`remove()` / `destroy()`	Cleanup.

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

File	Purpose
`src/tweens/TweenManager.js`	Scene plugin. `add`, `chain`, `stagger`, `killAll`, etc.
`src/tweens/tween/Tween.js`	Individual tween. Targets, TweenData array, seeking, update.
`src/tweens/tween/TweenChain.js`	Sequential tween playback via ordered child Tweens.
`src/tweens/tween/BaseTween.js`	Shared base. EventEmitter, callbacks, state machine.
`src/tweens/tween/BaseTweenData.js`	Per-property state: duration, delay, yoyo, repeat, progress.
`src/tweens/tween/TweenData.js`	Numeric property tweening (extends BaseTweenData).
`src/tweens/tween/TweenFrameData.js`	Texture frame tweening (extends BaseTweenData).
`src/tweens/builders/TweenBuilder.js`	Parses config into Tween instance.
`src/tweens/builders/TweenChainBuilder.js`	Parses config into TweenChain instance.
`src/tweens/builders/NumberTweenBuilder.js`	Builds target-less number tweens.
`src/tweens/builders/StaggerBuilder.js`	Creates stagger functions.
`src/tweens/events/`	Event constants (`TWEEN_ACTIVE`, `TWEEN_START`, etc.).
`src/tweens/typedefs/`	JSDoc typedefs for all config objects.
`src/math/easing/EaseMap.js`	Maps ease string names to functions.

tweens