Filter
A Tween is able to manipulate the properties of one or more objects to any given value, based on a duration and type of ease. They are rarely instantiated directly and instead should be created via the TweenManager.
Constructor:
new Tween(parent, data, targets)
Parameters:
| name | type | description |
|---|---|---|
| parent | Phaser.Tweens.TweenManager | Phaser.Tweens.Timeline |
A reference to the parent of this Tween. Either the Tween Manager or a Tween Timeline instance. |
| data | Array.<Phaser.Types.Tweens.TweenDataConfig> |
An array of TweenData objects, each containing a unique property to be tweened. |
| targets | array |
An array of targets to be tweened. |
Extends
Members
Description:
Set only if this Tween is part of a Timeline. The calculated offset amount.
Type:
Description:
The context in which all callbacks are invoked.
Type:
Description:
An object containing the different Tween callback functions.
You can either set these in the Tween config, or by calling the Tween.setCallback method.
onActive When the Tween is moved from the pending to the active list in the Tween Manager, even if playback paused.
onStart When the Tween starts playing after a delayed state. Will happen at the same time as onActive if it has no delay.
onYoyo When a TweenData starts a yoyo. This happens after the hold delay expires, if set.
onRepeat When a TweenData repeats playback. This happens after the repeatDelay expires, if set.
onComplete When the Tween finishes playback fully. Never invoked if tween is set to repeat infinitely.
onUpdate When a TweenData updates a property on a source target during playback.
onLoop When a Tween loops. This happens after the loopDelay expires, if set.
Type:
Description:
Time in ms/frames before the 'onComplete' event fires. This never fires if loop = -1 (as it never completes)
Type:
Description:
Countdown timer (used by timeline offset, loopDelay and completeDelay)
Type:
Description:
An array of TweenData objects, each containing a unique property and target being tweened.
Type:
Description:
Time in ms/frames for the whole Tween to play through once, excluding loop amounts and loop delays.
Type:
Description:
Elapsed time in ms/frames of this run through the Tween.
Type:
Description:
Has this Tween started playback yet? This boolean is toggled when the Tween leaves the 'delayed' state and starts running.
Type:
Description:
Is this Tween currently seeking?
This boolean is toggled in the Tween.seek method.
When a tween is seeking it will not dispatch any events or callbacks.
Type:
Description:
Loop this tween? Can be -1 for an infinite loop, or an integer. When enabled it will play through ALL TweenDatas again. Use TweenData.repeat to loop a single element.
Type:
Description:
How many loops are left to run?
Type:
Description:
Time in ms/frames before the tween loops.
Type:
Description:
Set only if this Tween is part of a Timeline.
Type:
Description:
A reference to the parent of this Tween. Either the Tween Manager or a Tween Timeline instance.
Description:
Is the parent of this Tween a Timeline?
Type:
Description:
Does the Tween start off paused? (if so it needs to be started with Tween.play)
Type:
Description:
Value between 0 and 1. The amount through the Tween, excluding loops.
Type:
Description:
Time in ms/frames before the 'onStart' event fires.
This is the shortest delay value across all of the TweenDatas of this Tween.
Type:
Description:
The current state of the tween
Type:
Description:
An array of references to the target/s this Tween is operating on.
Type:
Description:
Scales the time applied to this Tween. A value of 1 runs in real-time. A value of 0.5 runs 50% slower, and so on. Value isn't used when calculating total duration of the tween, it's a run-time delta adjustment only.
Type:
Description:
The cached length of the data array.
Type:
Description:
Time in ms/frames for the Tween to complete (including looping)
Type:
Description:
Total elapsed time in ms/frames of the entire Tween, including looping.
Type:
Description:
Value between 0 and 1. The amount through the entire Tween, including looping.
Type:
Description:
Cached target total (not necessarily the same as the data total)
Type:
Description:
If true then duration, delay, etc values are all frame totals.
Type:
Methods
Description:
Add a listener for a given event.
Parameters:
| name | type | arguments | Default | description |
|---|---|---|---|---|
| event | string | symbol |
The event name. |
||
| fn | function |
The listener function. |
||
| context | * | <optional> | this |
The context to invoke the listener with. |
Returns:
Description:
this.
Type:
Description:
Internal method that calculates the overall duration of the Tween.
Description:
Flags the Tween as being complete, whatever stage of progress it is at.
If an onComplete callback has been defined it will automatically invoke it, unless a delay
argument is provided, in which case the Tween will delay for that period of time before calling the callback.
If you don't need a delay, or have an onComplete callback, then call Tween.stop instead.
Parameters:
| name | type | arguments | description |
|---|---|---|---|
| delay | number | <optional> |
The time to wait before invoking the complete callback. If zero it will fire immediately. |
Returns:
Description:
This Tween instance.
Type:
Description:
Removes all listeners.
Description:
Internal method that will emit a TweenData based Event and invoke the given callback.
Parameters:
| name | type | description |
|---|---|---|
| event | Phaser.Types.Tweens.Event |
The Event to be dispatched. |
| callback | function |
The callback to be invoked. Can be |
| tweenData | Phaser.Types.Tweens.TweenDataConfig |
The TweenData object that caused this event. |
Description:
Internal method that will emit a Tween based Event and invoke the given callback.
Parameters:
| name | type | description |
|---|---|---|
| event | Phaser.Types.Tweens.Event |
The Event to be dispatched. |
| callback | function |
The callback to be invoked. Can be |
Description:
Calls each of the listeners registered for a given event.
Parameters:
| name | type | arguments | description |
|---|---|---|---|
| event | string | symbol |
The event name. |
|
| args | * | <optional> |
Additional arguments that will be passed to the event handler. |
Returns:
Description:
true if the event had listeners, else false.
Type:
- boolean
Description:
Return an array listing the events for which the emitter has registered listeners.
Type:
- Array.<(string
- symbol)>
Description:
Returns the scale of the time applied to this Tween.
Returns:
Description:
The timescale of this tween (between 0 and 1)
Type:
- number
Description:
Returns the current value of the specified Tween Data.
Parameters:
| name | type | arguments | description |
|---|---|---|---|
| index | number | <optional> |
The Tween Data to return the value from. |
Returns:
Description:
The value of the requested Tween Data.
Type:
- number
Description:
See if this Tween is currently acting upon the given target.
Parameters:
| name | type | description |
|---|---|---|
| target | object |
The target to check against this Tween. |
Returns:
Description:
true if the given target is a target of this Tween, otherwise false.
Type:
- boolean
Description:
Called by TweenManager.preUpdate as part of its loop to check pending and active tweens. Should not be called directly.
Returns:
Description:
Returns true if this Tween should be moved from the pending list to the active list by the Tween Manager.
Type:
- boolean
Description:
Checks if the Tween is currently paused.
Returns:
Description:
true if the Tween is paused, otherwise false.
Type:
- boolean
Description:
Checks if the Tween is currently active.
Returns:
Description:
true if the Tween is active, otherwise false.
Type:
- boolean
Description:
Return the number of listeners listening to a given event.
Parameters:
| name | type | description |
|---|---|---|
| event | string | symbol |
The event name. |
Returns:
Description:
The number of listeners.
Type:
- number
Description:
Return the listeners registered for a given event.
Parameters:
| name | type | description |
|---|---|---|
| event | string | symbol |
The event name. |
Returns:
Description:
The registered listeners.
Type:
- Array.<function()>
Description:
Internal method that makes this Tween active within the TweenManager and emits the onActive event and callback.
Description:
Internal method that advances to the next state of the Tween during playback.
Description:
Remove the listeners of a given event.
Parameters:
| name | type | arguments | description |
|---|---|---|---|
| event | string | symbol |
The event name. |
|
| fn | function | <optional> |
Only remove the listeners that match this function. |
| context | * | <optional> |
Only remove the listeners that have this context. |
| once | boolean | <optional> |
Only remove one-time listeners. |
Returns:
Description:
this.
Type:
Description:
Add a listener for a given event.
Parameters:
| name | type | arguments | Default | description |
|---|---|---|---|---|
| event | string | symbol |
The event name. |
||
| fn | function |
The listener function. |
||
| context | * | <optional> | this |
The context to invoke the listener with. |
Returns:
Description:
this.
Type:
Description:
Add a one-time listener for a given event.
Parameters:
| name | type | arguments | Default | description |
|---|---|---|---|---|
| event | string | symbol |
The event name. |
||
| fn | function |
The listener function. |
||
| context | * | <optional> | this |
The context to invoke the listener with. |
Returns:
Description:
this.
Type:
Description:
Pauses the Tween immediately. Use resume to continue playback.
Returns:
Description:
- This Tween instance.
Type:
Description:
Starts a Tween playing.
You only need to call this method if you have configured the tween to be paused on creation.
If the Tween is already playing, calling this method again will have no effect. If you wish to
restart the Tween, use Tween.restart instead.
Calling this method after the Tween has completed will start the Tween playing again from the start.
This is the same as calling Tween.seek(0) and then Tween.play().
Parameters:
| name | type | arguments | Default | description |
|---|---|---|---|---|
| resetFromTimeline | boolean | <optional> | false |
Is this Tween being played as part of a Timeline? |
Returns:
Description:
This Tween instance.
Type:
Description:
Immediately removes this Tween from the TweenManager and all of its internal arrays,
no matter what stage it as it. Then sets the tween state to REMOVED.
You should dispose of your reference to this tween after calling this method, to free it from memory.
Returns:
Description:
This Tween instance.
Type:
Description:
Remove all listeners, or those of the specified event.
Parameters:
| name | type | arguments | description |
|---|---|---|---|
| event | string | symbol | <optional> |
The event name. |
Returns:
Description:
this.
Type:
Description:
Remove the listeners of a given event.
Parameters:
| name | type | arguments | description |
|---|---|---|---|
| event | string | symbol |
The event name. |
|
| fn | function | <optional> |
Only remove the listeners that match this function. |
| context | * | <optional> |
Only remove the listeners that have this context. |
| once | boolean | <optional> |
Only remove one-time listeners. |
Returns:
Description:
this.
Type:
Description:
Internal method that resets all of the Tween Data, including the progress and elapsed values.
Parameters:
| name | type | description |
|---|---|---|
| resetFromLoop | boolean |
Has this method been called as part of a loop? |
Description:
Restarts the tween from the beginning.
Returns:
Description:
This Tween instance.
Type:
Description:
Resumes the playback of a previously paused Tween.
Returns:
Description:
- This Tween instance.
Type:
Description:
Seeks to a specific point in the Tween.
Note: Be careful when seeking a Tween that repeats or loops forever, or that has an unusually long total duration, as it's possible to hang the browser.
The given position is a value between 0 and 1 which represents how far through the Tween to seek to. A value of 0.5 would seek to half-way through the Tween, where-as a value of zero would seek to the start.
Note that the seek takes the entire duration of the Tween into account, including delays, loops and repeats. For example, a Tween that lasts for 2 seconds, but that loops 3 times, would have a total duration of 6 seconds, so seeking to 0.5 would seek to 3 seconds into the Tween, as that's half-way through its entire duration.
Seeking works by resetting the Tween to its initial values and then iterating through the Tween at delta
jumps per step. The longer the Tween, the longer this can take.
Parameters:
| name | type | arguments | Default | description |
|---|---|---|---|---|
| toPosition | number |
A value between 0 and 1 which represents the progress point to seek to. |
||
| delta | number | <optional> | 16.6 |
The size of each step when seeking through the Tween. A higher value completes faster but at a cost of less precision. |
Returns:
Description:
This Tween instance.
Type:
Description:
Sets an event based callback to be invoked during playback.
Calling this method will replace a previously set callback for the given type, if any exists.
The types available are:
onActive When the Tween is moved from the pending to the active list in the Tween Manager, even if playback paused.
onStart When the Tween starts playing after a delayed state. Will happen at the same time as onActive if it has no delay.
onYoyo When a TweenData starts a yoyo. This happens after the hold delay expires, if set.
onRepeat When a TweenData repeats playback. This happens after the repeatDelay expires, if set.
onComplete When the Tween finishes playback fully or Tween.stop is called. Never invoked if tween is set to repeat infinitely.
onUpdate When a TweenData updates a property on a source target during playback.
onLoop When a Tween loops. This happens after the loopDelay expires, if set.
Parameters:
| name | type | arguments | description |
|---|---|---|---|
| type | string |
Type of the callback to set. |
|
| callback | function |
The function to invoke when this callback happens. |
|
| params | array | <optional> |
An array of parameters for specified callbacks types. |
| scope | any | <optional> |
The context the callback will be invoked in. |
Returns:
Description:
This Tween instance.
Type:
Description:
Internal method used as part of the playback process that sets a tween to play in reverse.
Parameters:
| name | type | description |
|---|---|---|
| tween | Phaser.Tweens.Tween |
The Tween to update. |
| tweenData | Phaser.Types.Tweens.TweenDataConfig |
The TweenData property to update. |
| diff | number |
Any extra time that needs to be accounted for in the elapsed and progress values. |
Returns:
Description:
The state of this Tween.
Type:
- number
Description:
Internal method used as part of the playback process that sets a tween to play from the start.
Parameters:
| name | type | description |
|---|---|---|
| tween | Phaser.Tweens.Tween |
The Tween to update. |
| tweenData | Phaser.Types.Tweens.TweenDataConfig |
The TweenData property to update. |
| diff | number |
Any extra time that needs to be accounted for in the elapsed and progress values. |
Returns:
Description:
The state of this Tween.
Type:
- number
Description:
Set the scale the time applied to this Tween. A value of 1 runs in real-time. A value of 0.5 runs 50% slower, and so on.
Parameters:
| name | type | description |
|---|---|---|
| value | number |
The scale factor for timescale. |
Returns:
Description:
- This Tween instance.
Type:
Description:
Removes all listeners.
Description:
Stops the Tween immediately, whatever stage of progress it is at and flags it for removal by the TweenManager.
Parameters:
| name | type | arguments | description |
|---|---|---|---|
| resetTo | number | <optional> |
If you want to seek the tween, provide a value between 0 and 1. |
Returns:
Description:
This Tween instance.
Type:
Description:
Internal method that advances the Tween based on the time values.
Parameters:
| name | type | description |
|---|---|---|
| timestamp | number |
The current time. Either a High Resolution Timer value if it comes from Request Animation Frame, or Date.now if using SetTimeout. |
| delta | number |
The delta time in ms since the last frame. This is a smoothed and capped value based on the FPS rate. |
Returns:
Description:
Returns true if this Tween has finished and should be removed from the Tween Manager, otherwise returns false.
Type:
- boolean
Fires:
Description:
Updates the 'end' value of the given property across all matching targets.
Calling this does not adjust the duration of the tween, or the current progress.
You can optionally tell it to set the 'start' value to be the current value (before the change).
Parameters:
| name | type | arguments | Default | description |
|---|---|---|---|---|
| key | string |
The property to set the new value for. |
||
| value | * |
The new value of the property. |
||
| startToCurrent | boolean | <optional> | false |
Should this change set the start value to be the current value? |
Returns:
Description:
- This Tween instance.
Type:
Description:
Internal method that advances the TweenData based on the time value given.
Parameters:
| name | type | description |
|---|---|---|
| tween | Phaser.Tweens.Tween |
The Tween to update. |
| tweenData | Phaser.Types.Tweens.TweenDataConfig |
The TweenData property to update. |
| delta | number |
Either a value in ms, or 1 if Tween.useFrames is true. |
Returns:
Description:
True if the tween is not complete (e.g., playing), or false if the tween is complete.
Type:
- boolean