tweens

name	tweens
description	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.

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
..(sprite);            
..();                    ..();
..();       

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

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

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.