Phaser API Documentation

  Version: 
Filter

The Tween Manager is a default Scene Plugin which controls and updates Tweens.

A tween is a way to alter one or more properties of a target object over a defined period of time.

Tweens are created by calling the add method and passing in the configuration object.

const logo = this.add.image(100, 100, 'logo');

this.tweens.add({
  targets: logo,
  x: 600,
  ease: 'Power1',
  duration: 2000
});

See the TweenBuilderConfig for all of the options you have available.

Playback will start immediately unless the tween has been configured to be paused.

Please note that a Tween will not manipulate any target property that begins with an underscore.

Tweens are designed to be 'fire-and-forget'. They automatically destroy themselves once playback is complete, to free-up memory and resources. If you wish to keep a tween after playback, i.e. to play it again at a later time, then you should set the persist property to true in the config. However, doing so means it's entirely up to you to destroy the tween when you're finished with it, otherwise it will linger in memory forever.

If you wish to chain Tweens together for sequential playback, see the TweenManager.chain method.

Constructor:

new TweenManager(scene)

Parameters:

name type description
scene Phaser.Scene

The Scene which owns this Tween Manager.

Since: 3.0.0

Members

Description:

The Scene Systems Event Emitter.

Type:
Since: 3.60.0
Focus
Focus
gap: number
Focus
Focus

Description:

An internal value that holds the fps rate.

Type:
number
Since: 3.60.0
Focus
Focus
lagSkip: number
Focus
Focus

Description:

The amount of time, in milliseconds, that is used to set the delta when lag smoothing is applied.

See the TweenManager.setLagSmooth method for further details.

Type:
number
Default: 33
Since: 3.60.0
Focus
Focus
maxLag: number
Focus
Focus

Description:

The maximum amount of time, in milliseconds, the browser can lag for, before lag smoothing is applied.

See the TweenManager.setLagSmooth method for further details.

Type:
number
Default: 500
Since: 3.60.0
Focus
Focus
nextTime: number
Focus
Focus

Description:

The time the Tween Manager should next update.

Type:
number
Since: 3.60.0
Focus
Focus
paused: boolean
Focus
Focus

Description:

This toggles the updating state of this Tween Manager.

Setting paused to true (or calling the pauseAll method) will stop this Tween Manager from updating any of its tweens, including newly created ones. Set back to false to resume playback.

Type:
boolean
Default: false
Since: 3.60.0
Focus
Focus
prevTime: number
Focus
Focus

Description:

The time the Tween Manager previously updated.

Type:
number
Since: 3.60.0
Focus
Focus
processing: boolean
Focus
Focus

Description:

Is this Tween Manager currently processing the tweens as part of its 'update' loop? This is set to 'true' at the start of 'update' and reset to 'false' at the end of the function. Allows you to trap Tween Manager status during tween callbacks.

Type:
boolean
Default: false
Since: 3.60.0
Focus
Focus
scene: Phaser.Scene
Focus
Focus

Description:

The Scene which owns this Tween Manager.

Type:
Since: 3.0.0
Focus
Focus
startTime: number
Focus
Focus

Description:

The time the Tween Manager was started.

Type:
number
Since: 3.60.0
Focus
Focus
time: number
Focus
Focus

Description:

The time the Tween Manager was updated.

Type:
number
Since: 3.60.0
Focus
Focus
timeScale: number
Focus
Focus

Description:

The time scale of the Tween Manager.

This value scales the time delta between two frames, thus influencing the speed of time for all Tweens owned by this Tween Manager.

Type:
number
Default: 1
Since: 3.0.0
Focus
Focus
tweens: Array.<Phaser.Tweens.Tween>
Focus
Focus

Description:

An array of Tweens which are actively being processed by the Tween Manager.

Type:
Since: 3.60.0
Focus
Focus

Methods

add(config)
Focus
Focus

Description:

Create a Tween and add it to this Tween Manager by passing a Tween Configuration object.

Example, run from within a Scene:

const logo = this.add.image(100, 100, 'logo');

this.tweens.add({
  targets: logo,
  x: 600,
  ease: 'Power1',
  duration: 2000
});

See the TweenBuilderConfig for all of the options you have available.

Playback will start immediately unless the tween has been configured to be paused.

Please note that a Tween will not manipulate any target property that begins with an underscore.

Tweens are designed to be 'fire-and-forget'. They automatically destroy themselves once playback is complete, to free-up memory and resources. If you wish to keep a tween after playback, i.e. to play it again at a later time, then you should set the persist property to true in the config. However, doing so means it's entirely up to you to destroy the tween when you're finished with it, otherwise it will linger in memory forever.

If you wish to chain Tweens together for sequential playback, see the TweenManager.chain method.

Parameters:

name type description
config Phaser.Tweens.Tween | Phaser.Tweens.TweenChain | Phaser.Types.Tweens.TweenBuilderConfig | Phaser.Types.Tweens.TweenChainBuilderConfig

A Tween Configuration object, or a Tween or TweenChain instance.

Returns:
Description:

The created Tween.

Since: 3.0.0
Focus
Focus
addCounter(config)
Focus
Focus

Description:

Create a Number Tween and add it to the active Tween list.

A Number Tween is a special kind of tween that doesn't have a target. Instead, it allows you to tween between 2 numeric values. The default values are 0 and 1, but you can change them via the from and to properties.

You can get the current tweened value via the Tween.getValue() method.

Playback will start immediately unless the tween has been configured to be paused.

Please note that a Tween will not manipulate any target property that begins with an underscore.

Parameters:

name type description
config Phaser.Types.Tweens.NumberTweenBuilderConfig

The configuration object for the Number Tween.

Returns:
Description:

The created Number Tween.

Since: 3.0.0
Focus
Focus
addMultiple(configs)
Focus
Focus

Description:

Create multiple Tweens and add them all to this Tween Manager, by passing an array of Tween Configuration objects.

See the TweenBuilderConfig for all of the options you have available.

Playback will start immediately unless the tweens have been configured to be paused.

Please note that a Tween will not manipulate any target property that begins with an underscore.

Tweens are designed to be 'fire-and-forget'. They automatically destroy themselves once playback is complete, to free-up memory and resources. If you wish to keep a tween after playback, i.e. to play it again at a later time, then you should set the persist property to true in the config. However, doing so means it's entirely up to you to destroy the tween when you're finished with it, otherwise it will linger in memory forever.

If you wish to chain Tweens together for sequential playback, see the TweenManager.chain method.

Parameters:

name type description
configs Array.<object> | Array.<Phaser.Types.Tweens.TweenBuilderConfig>

An array of Tween Configuration objects.

Returns:
Description:

An array of created Tweens.

Type:
Since: 3.60.0
Focus
Focus
<private> boot()
Focus
Focus

Description:

This method is called automatically, only once, when the Scene is first created. Do not invoke it directly.

Since: 3.5.1
Focus
Focus
chain(tweens)
Focus
Focus

Description:

Create a sequence of Tweens, chained to one-another, and add them to this Tween Manager.

The tweens are played in order, from start to finish. You can optionally set the chain to repeat as many times as you like. Once the chain has finished playing, or repeating if set, all tweens in the chain will be destroyed automatically. To override this, set the persist argument to 'true'.

Playback will start immediately unless the first Tween has been configured to be paused.

Please note that Tweens will not manipulate any target property that begins with an underscore.

Parameters:

name type description
tweens object | Phaser.Types.Tweens.TweenChainBuilderConfig

A Tween Chain configuration object.

Returns:
Description:

The Tween Chain instance.

Since: 3.60.0
Focus
Focus
create(config)
Focus
Focus

Description:

Create a Tween and return it, but does not add it to this Tween Manager.

Please note that a Tween will not manipulate any target property that begins with an underscore.

In order to play this tween, you'll need to add it to a Tween Manager via the TweenManager.existing method.

You can optionally pass an array of Tween Configuration objects to this method and it will create one Tween per entry in the array. If an array is given, an array of tweens is returned.

Parameters:

name type description
config object | Array.<object> | Phaser.Types.Tweens.TweenBuilderConfig | Array.<Phaser.Types.Tweens.TweenBuilderConfig>

A Tween Configuration object. Or an array of Tween Configuration objects.

Returns:
Description:

The created Tween, or an array of Tweens if an array of tween configs was provided.

Since: 3.0.0
Focus
Focus
destroy()
Focus
Focus

Description:

The Scene that owns this plugin is being destroyed. We need to shutdown and then kill off all external references.

Since: 3.0.0
Focus
Focus
each(callback, [scope], [args])
Focus
Focus

Description:

Passes all Tweens to the given callback.

Parameters:

name type arguments description
callback function

The function to call.

scope object <optional>

The scope (this object) to call the function with.

args * <optional>

The arguments to pass into the function. Its first argument will always be the Tween currently being iterated.

Returns:
Description:

This Tween Manager instance.

Since: 3.0.0
Focus
Focus
existing(tween)
Focus
Focus

Description:

Add an existing Tween to this Tween Manager.

Playback will start immediately unless the tween has been configured to be paused.

Parameters:

name type description
tween Phaser.Tweens.Tween

The Tween to add.

Returns:
Description:

This Tween Manager instance.

Since: 3.0.0
Focus
Focus
getChainedTweens(tween)
Focus
Focus

Description:

Returns an array containing this Tween and all Tweens chained to it, in the order in which they will be played.

If there are no chained Tweens an empty array is returned.

Parameters:

name type description
tween Phaser.Tweens.Tween

The Tween to return the chain from.

Returns:
Description:

An array of the chained tweens, or an empty array if there aren't any.

Type:
Since: 3.60.0
Focus
Focus
getDelta([tick])
Focus
Focus

Description:

Internal method that calculates the delta value, along with the other timing values, and returns the new delta.

You should not typically call this method directly.

Parameters:

name type arguments Default description
tick boolean <optional> false

Is this a manual tick, or an automated tick?

Returns:
Description:

The new delta value.

Type:
  • number
Since: 3.60.0
Focus
Focus
getGlobalTimeScale()
Focus
Focus

Description:

Returns the scale of the time delta for all Tweens owned by this Tween Manager.

Returns:
Description:

The scale of the time delta, usually 1.

Type:
  • number
Since: 3.0.0
Focus
Focus
getTweens()
Focus
Focus

Description:

Returns an array containing references to all Tweens in this Tween Manager.

It is safe to mutate the returned array. However, acting upon any of the Tweens within it, will adjust those stored in this Tween Manager, as they are passed by reference and not cloned.

If you wish to get tweens for a specific target, see getTweensOf.

Returns:
Description:

A new array containing references to all Tweens.

Type:
Since: 3.0.0
Focus
Focus
getTweensOf(target)
Focus
Focus

Description:

Returns an array of all Tweens in the Tween Manager which affect the given target, or array of targets.

It's possible for this method to return tweens that are about to be removed from the Tween Manager. You should check the state of the returned tween before acting upon it.

Parameters:

name type description
target object | Array.<object>

The target to look for. Provide an array to look for multiple targets.

Returns:
Description:

A new array containing all Tweens which affect the given target(s).

Type:
Since: 3.0.0
Focus
Focus
has(tween)
Focus
Focus

Description:

Check to see if the given Tween instance exists within this Tween Manager.

Will return true as long as the Tween is being processed by this Tween Manager.

Will return false if not present, or has a state of REMOVED or DESTROYED.

Parameters:

name type description
tween Phaser.Tweens.Tween

The Tween instance to check.

Returns:
Description:

true if the Tween exists within this Tween Manager, otherwise false.

Type:
  • boolean
Since: 3.60.0
Focus
Focus
isTweening(target)
Focus
Focus

Description:

Checks if the given object is being affected by a playing Tween.

If the Tween is paused, this method will return false.

Parameters:

name type description
target object

The object to check if a tween is active for it, or not.

Returns:
Description:

Returns true if a tween is active on the given target, otherwise false.

Type:
  • boolean
Since: 3.0.0
Focus
Focus
killAll()
Focus
Focus

Description:

Destroys all Tweens in this Tween Manager.

The tweens will erase all references to any targets they hold and be stopped immediately.

If this method is called while the Tween Manager is running its update process, then the tweens will be removed at the start of the next frame. Outside of this, they are removed immediately.

Returns:
Description:

This Tween Manager instance.

Since: 3.0.0
Focus
Focus
killTweensOf(target)
Focus
Focus

Description:

Stops all Tweens which affect the given target or array of targets.

The tweens will erase all references to any targets they hold and be stopped immediately.

If this method is called while the Tween Manager is running its update process, then the tweens will be removed at the start of the next frame. Outside of this, they are removed immediately.

Parameters:

name type description
target object | array

The target to kill the tweens of. Provide an array to use multiple targets.

Returns:
Description:

This Tween Manager instance.

Since: 3.0.0
Focus
Focus
makeActive(tween)
Focus
Focus

Description:

Checks if a Tween is active and adds it to the Tween Manager at the start of the frame if it isn't.

Parameters:

name type description
tween Phaser.Tweens.Tween

The Tween to check.

Returns:
Description:

This Tween Manager instance.

Since: 3.0.0
Focus
Focus
pauseAll()
Focus
Focus

Description:

Pauses this Tween Manager. No Tweens will update while paused.

This includes tweens created after this method was called.

See TweenManager#resumeAll to resume the playback.

As of Phaser 3.60 you can also toggle the boolean property TweenManager.paused.

Returns:
Description:

This Tween Manager instance.

Since: 3.0.0
Focus
Focus
remove(tween)
Focus
Focus

Description:

Removes the given Tween from this Tween Manager, even if it hasn't started playback yet. If this method is called while the Tween Manager is processing an update loop, then the tween will be flagged for removal at the start of the next frame. Otherwise, it is removed immediately.

The removed tween is not destroyed. It is just removed from this Tween Manager.

Parameters:

name type description
tween Phaser.Tweens.Tween

The Tween to be removed.

Returns:
Description:

This Tween Manager instance.

Since: 3.17.0
Focus
Focus
reset(tween)
Focus
Focus

Description:

Resets the given Tween.

If the Tween does not belong to this Tween Manager, it will first be added.

Then it will seek to position 0 and playback will start on the next frame.

Parameters:

name type description
tween Phaser.Tweens.Tween

The Tween to be reset.

Returns:
Description:

This Tween Manager instance.

Since: 3.60.0
Focus
Focus
resumeAll()
Focus
Focus

Description:

Resumes playback of this Tween Manager.

All active Tweens will continue updating.

See TweenManager#pauseAll to pause the playback.

As of Phaser 3.60 you can also toggle the boolean property TweenManager.paused.

Returns:
Description:

This Tween Manager instance.

Since: 3.0.0
Focus
Focus
setFps([fps])
Focus
Focus

Description:

Limits the Tween system to run at a particular frame rate.

You should not set this above the frequency of the browser, but instead can use it to throttle the frame rate lower, should you need to in certain situations.

Parameters:

name type arguments Default description
fps number <optional> 240

The frame rate to tick at.

Returns:
Description:

This Tween Manager instance.

Since: 3.60.0
Focus
Focus
setGlobalTimeScale(value)
Focus
Focus

Description:

Sets a new scale of the time delta for this Tween Manager.

The time delta is the time elapsed between two consecutive frames and influences the speed of time for this Tween Manager and all Tweens it owns. Values higher than 1 increase the speed of time, while values smaller than 1 decrease it. A value of 0 freezes time and is effectively equivalent to pausing all Tweens.

Parameters:

name type description
value number

The new scale of the time delta, where 1 is the normal speed.

Returns:
Description:

This Tween Manager instance.

Since: 3.0.0
Focus
Focus
setLagSmooth([limit], [skip])
Focus
Focus

Description:

Set the limits that are used when a browser encounters lag, or delays that cause the elapsed time between two frames to exceed the expected amount. If this occurs, the Tween Manager will act as if the 'skip' amount of times has passed, in order to maintain strict tween sequencing.

This is enabled by default with the values 500ms for the lag limit and 33ms for the skip.

You should not set these to low values, as it won't give time for the browser to ever catch-up with itself and reclaim sync.

Call this method with no arguments to disable smoothing.

Call it with the arguments 500 and 33 to reset to the defaults.

Parameters:

name type arguments description
limit number <optional>

If the browser exceeds this amount, in milliseconds, it will act as if the 'skip' amount has elapsed instead.

skip number <optional>

The amount, in milliseconds, to use as the step delta should the browser lag beyond the 'limit'.

Returns:
Description:

This Tween Manager instance.

Since: 3.60.0
Focus
Focus
shutdown()
Focus
Focus

Description:

The Scene that owns this plugin is shutting down.

We need to kill and reset all internal properties as well as stop listening to Scene events.

Since: 3.0.0
Focus
Focus
stagger(value, config)
Focus
Focus

Description:

Creates a Stagger function to be used by a Tween property.

The stagger function will allow you to stagger changes to the value of the property across all targets of the tween.

This is only worth using if the tween has multiple targets.

The following will stagger the delay by 100ms across all targets of the tween, causing them to scale down to 0.2 over the duration specified:

this.tweens.add({
    targets: [ ... ],
    scale: 0.2,
    ease: 'linear',
    duration: 1000,
    delay: this.tweens.stagger(100)
});

The following will stagger the delay by 500ms across all targets of the tween using a 10 x 6 grid, staggering from the center out, using a cubic ease.

this.tweens.add({
    targets: [ ... ],
    scale: 0.2,
    ease: 'linear',
    duration: 1000,
    delay: this.tweens.stagger(500, { grid: [ 10, 6 ], from: 'center', ease: 'cubic.out' })
});

Parameters:

name type description
value number | Array.<number>

The amount to stagger by, or an array containing two elements representing the min and max values to stagger between.

config Phaser.Types.Tweens.StaggerConfig

The configuration object for the Stagger function.

Returns:
Description:

The stagger function.

Type:
  • function
Since: 3.19.0
Focus
Focus
<private> start()
Focus
Focus

Description:

This method is called automatically by the Scene when it is starting up. It is responsible for creating local systems, properties and listening for Scene events. Do not invoke it directly.

Since: 3.5.0
Focus
Focus
step([tick])
Focus
Focus

Description:

Updates all Tweens belonging to this Tween Manager.

Called automatically by update and tick.

Parameters:

name type arguments Default description
tick boolean <optional> false

Is this a manual tick, or an automated tick?

Since: 3.60.0
Focus
Focus
tick()
Focus
Focus

Description:

Manually advance the Tween system by one step.

This will update all Tweens even if the Tween Manager is currently paused.

Returns:
Description:

This Tween Manager instance.

Since: 3.60.0
Focus
Focus
update()
Focus
Focus

Description:

Internal update handler.

Calls TweenManager.step as long as the Tween Manager has not been paused.

Since: 3.0.0
Focus
Focus