Filter
Phaser . Tweens . TweenManager
Phaser . Tweens . TweenManager
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. |
Members
Description:
An internal value that holds the fps rate.
Type:
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:
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:
Description:
The time the Tween Manager should next update.
Type:
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:
Description:
The time the Tween Manager previously updated.
Type:
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:
Description:
The time the Tween Manager was started.
Type:
Description:
The time the Tween Manager was updated.
Type:
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:
Description:
An array of Tweens which are actively being processed by the Tween Manager.
Type:
Methods
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.
Type:
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.
Type:
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:
- Array.<Phaser.Tweens.Tween>
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 'persists' 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.
Type:
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.
Type:
Description:
The Scene that owns this plugin is being destroyed. We need to shutdown and then kill off all external references.
Description:
Passes all Tweens to the given callback.
Parameters:
| name | type | arguments | description |
|---|---|---|---|
| callback | function |
The function to call. |
|
| scope | object | <optional> |
The scope ( |
| 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.
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.
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:
- Array.<Phaser.Tweens.Tween>
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
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
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:
- Array.<Phaser.Tweens.Tween>
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:
- Array.<Phaser.Tweens.Tween>
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
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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? |
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.
Description:
Internal update handler.
Calls TweenManager.step as long as the Tween Manager has not
been paused.