Class: Tween

Phaser.Tweens. Tween

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.

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.
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 15)

Extends

Members

calculatedOffset :number

Set only if this Tween is part of a Timeline. The calculated offset amount.

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/tweens/tween/Tween.js (Line 212)

callbacks :object

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:
  • object
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 311)

callbackScope :any

The context in which all callbacks are invoked.

Type:
  • any
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 339)

completeDelay :number

Time in ms/frames before the 'onComplete' event fires. This never fires if loop = -1 (as it never completes)

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/tweens/tween/Tween.js (Line 182)

countdown :number

Countdown timer (used by timeline offset, loopDelay and completeDelay)

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/tweens/tween/Tween.js (Line 192)

data :Array.<Phaser.Types.Tweens.TweenDataConfig>

An array of TweenData objects, each containing a unique property and target being tweened.

Type:
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 60)

duration :number

Time in ms/frames for the whole Tween to play through once, excluding loop amounts and loop delays.

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/tweens/tween/Tween.js (Line 271)

elapsed :number

Elapsed time in ms/frames of this run through the Tween.

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/tweens/tween/Tween.js (Line 251)

<readonly> hasStarted :boolean

Has this Tween started playback yet? This boolean is toggled when the Tween leaves the 'delayed' state and starts running.

Type:
  • boolean
Since: 3.19.0
Source: src/tweens/tween/Tween.js (Line 159)

<readonly> isSeeking :boolean

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:
  • boolean
Since: 3.19.0
Source: src/tweens/tween/Tween.js (Line 170)

loop :number

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:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/tweens/tween/Tween.js (Line 117)

loopCounter :number

How many loops are left to run?

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/tweens/tween/Tween.js (Line 138)

loopDelay :number

Time in ms/frames before the tween loops.

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/tweens/tween/Tween.js (Line 128)

offset :number

Set only if this Tween is part of a Timeline.

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/tweens/tween/Tween.js (Line 202)

parent :Phaser.Tweens.TweenManager|Phaser.Tweens.Timeline

A reference to the parent of this Tween. Either the Tween Manager or a Tween Timeline instance.

Type:
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 41)

parentIsTimeline :boolean

Is the parent of this Tween a Timeline?

Type:
  • boolean
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 51)

paused :boolean

Does the Tween start off paused? (if so it needs to be started with Tween.play)

Type:
  • boolean
Since: 3.0.0
Default Value:
  • false
Source: src/tweens/tween/Tween.js (Line 241)

progress :number

Value between 0 and 1. The amount through the Tween, excluding loops.

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/tweens/tween/Tween.js (Line 281)

startDelay :number

Time in ms/frames before the 'onStart' event fires. This is the shortest delay value across all of the TweenDatas of this Tween.

Type:
  • number
Since: 3.19.0
Default Value:
  • 0
Source: src/tweens/tween/Tween.js (Line 148)

state :number

The current state of the tween

Type:
  • number
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 222)

targets :Array.<object>

An array of references to the target/s this Tween is operating on.

Type:
  • Array.<object>
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 78)

timeScale :number

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:
  • number
Since: 3.0.0
Default Value:
  • 1
Source: src/tweens/tween/Tween.js (Line 106)

totalData :number

The cached length of the data array.

Type:
  • number
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 69)

totalDuration :number

Time in ms/frames for the Tween to complete (including looping)

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/tweens/tween/Tween.js (Line 291)

totalElapsed :number

Total elapsed time in ms/frames of the entire Tween, including looping.

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/tweens/tween/Tween.js (Line 261)

totalProgress :number

Value between 0 and 1. The amount through the entire Tween, including looping.

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/tweens/tween/Tween.js (Line 301)

totalTargets :number

Cached target total (not necessarily the same as the data total)

Type:
  • number
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 87)

useFrames :boolean

If true then duration, delay, etc values are all frame totals.

Type:
  • boolean
Since: 3.0.0
Default Value:
  • false
Source: src/tweens/tween/Tween.js (Line 96)

Methods

addListener(event, fn [, context])

Add a listener for a given event.

Parameters:
Name Type Argument Default Description
event string | symbol

The event name.
fn function

The listener function.
context * <optional>
 this

The context to invoke the listener with.
Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 111)
Returns:

this.

Type
Phaser.Tweens.Tween

calcDuration()

Internal method that calculates the overall duration of the Tween.

Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 512)

complete( [delay])

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 Argument Default Description
delay number <optional>
 0

The time to wait before invoking the complete callback. If zero it will fire immediately.
Since: 3.2.0
Source: src/tweens/tween/Tween.js (Line 1014)
Fires:
Returns:

This Tween instance.

Type
Phaser.Tweens.Tween

destroy()

Removes all listeners.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 42)

dispatchTweenDataEvent(event, callback, tweenData)

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 null or undefined to skip invocation.
tweenData Phaser.Types.Tweens.TweenDataConfig

The TweenData object that caused this event.
Since: 3.19.0
Source: src/tweens/tween/Tween.js (Line 1226)

dispatchTweenEvent(event, callback)

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 null or undefined to skip invocation.
Since: 3.19.0
Source: src/tweens/tween/Tween.js (Line 1251)

emit(event [, args])

Calls each of the listeners registered for a given event.

Parameters:
Name Type Argument Description
event string | symbol

The event name.
args * <optional>
<repeatable>

Additional arguments that will be passed to the event handler.
Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 86)
Returns:

true if the event had listeners, else false.

Type
boolean

eventNames()

Return an array listing the events for which the emitter has registered listeners.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 55)
Returns:
Type
Array.<(string|symbol)>

getTimeScale()

Returns the scale of the time applied to this Tween.

Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 383)
Returns:

The timescale of this tween (between 0 and 1)

Type
number

getValue( [index])

Returns the current value of the specified Tween Data.

Parameters:
Name Type Argument Default Description
index number <optional>
 0

The Tween Data to return the value from.
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 349)
Returns:

The value of the requested Tween Data.

Type
number

hasTarget(target)

See if this Tween is currently acting upon the given target.

Parameters:
Name Type Description
target object

The target to check against this Tween.
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 422)
Returns:

true if the given target is a target of this Tween, otherwise false.

Type
boolean

init()

Called by TweenManager.preUpdate as part of its loop to check pending and active tweens. Should not be called directly.

Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 585)
Returns:

Returns true if this Tween should be moved from the pending list to the active list by the Tween Manager.

Type
boolean

isPaused()

Checks if the Tween is currently paused.

Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 409)
Returns:

true if the Tween is paused, otherwise false.

Type
boolean

isPlaying()

Checks if the Tween is currently active.

Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 396)
Returns:

true if the Tween is active, otherwise false.

Type
boolean

listenerCount(event)

Return the number of listeners listening to a given event.

Parameters:
Name Type Description
event string | symbol

The event name.
Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 75)
Returns:

The number of listeners.

Type
number

listeners(event)

Return the listeners registered for a given event.

Parameters:
Name Type Description
event string | symbol

The event name.
Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 64)
Returns:

The registered listeners.

Type
Array.<function()>

makeActive()

Internal method that makes this Tween active within the TweenManager and emits the onActive event and callback.

Since: 3.19.0
Source: src/tweens/tween/Tween.js (Line 638)
Fires:

nextState()

Internal method that advances to the next state of the Tween during playback.

Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 653)
Fires:

off(event [, fn] [, context] [, once])

Remove the listeners of a given event.

Parameters:
Name Type Argument 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.
Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 151)
Returns:

this.

Type
Phaser.Tweens.Tween

on(event, fn [, context])

Add a listener for a given event.

Parameters:
Name Type Argument Default Description
event string | symbol

The event name.
fn function

The listener function.
context * <optional>
 this

The context to invoke the listener with.
Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 98)
Returns:

this.

Type
Phaser.Tweens.Tween

once(event, fn [, context])

Add a one-time listener for a given event.

Parameters:
Name Type Argument Default Description
event string | symbol

The event name.
fn function

The listener function.
context * <optional>
 this

The context to invoke the listener with.
Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 124)
Returns:

this.

Type
Phaser.Tweens.Tween

pause()

Pauses the Tween immediately. Use resume to continue playback.

Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 697)
Returns:
  • This Tween instance.
Type
Phaser.Tweens.Tween

play( [resetFromTimeline])

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 Argument Default Description
resetFromTimeline boolean <optional>
 false

Is this Tween being played as part of a Timeline?
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 721)
Returns:

This Tween instance.

Type
Phaser.Tweens.Tween

remove()

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.

Since: 3.17.0
Source: src/tweens/tween/Tween.js (Line 1050)
Returns:

This Tween instance.

Type
Phaser.Tweens.Tween

removeAllListeners( [event])

Remove all listeners, or those of the specified event.

Parameters:
Name Type Argument Description
event string | symbol <optional>

The event name.
Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 165)
Returns:

this.

Type
Phaser.Tweens.Tween

removeListener(event [, fn] [, context] [, once])

Remove the listeners of a given event.

Parameters:
Name Type Argument 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.
Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 137)
Returns:

this.

Type
Phaser.Tweens.Tween

resetTweenData(resetFromLoop)

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?
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 798)

restart()

Restarts the tween from the beginning.

Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 475)
Returns:

This Tween instance.

Type
Phaser.Tweens.Tween

resume()

Resumes the playback of a previously paused Tween.

Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 854)
Returns:
  • This Tween instance.
Type
Phaser.Tweens.Tween

seek(toPosition [, delta])

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 Argument 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.
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 878)
Returns:

This Tween instance.

Type
Phaser.Tweens.Tween

setCallback(type, callback [, params] [, scope])

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 Argument 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.
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 982)
Returns:

This Tween instance.

Type
Phaser.Tweens.Tween

setStateFromEnd(tween, tweenData, diff)

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.
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 1275)
Fires:
Returns:

The state of this Tween.

Type
number

setStateFromStart(tween, tweenData, diff)

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.
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 1362)
Fires:
Returns:

The state of this Tween.

Type
number

setTimeScale(value)

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.
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 366)
Returns:
  • This Tween instance.
Type
Phaser.Tweens.Tween

shutdown()

Removes all listeners.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 31)

stop( [resetTo])

Stops the Tween immediately, whatever stage of progress it is at and flags it for removal by the TweenManager.

Parameters:
Name Type Argument Description
resetTo number <optional>

If you want to seek the tween, provide a value between 0 and 1.
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 1069)
Returns:

This Tween instance.

Type
Phaser.Tweens.Tween

update(timestamp, delta)

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.
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 1115)
Fires:
Returns:

Returns true if this Tween has finished and should be removed from the Tween Manager, otherwise returns false.

Type
boolean

updateTo(key, value [, startToCurrent])

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 Argument 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?
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 437)
Returns:
  • This Tween instance.
Type
Phaser.Tweens.Tween

updateTweenData(tween, tweenData, delta)

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.
Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 1419)
Fires:
Returns:

True if the tween is not complete (e.g., playing), or false if the tween is complete.

Type
boolean