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 14)

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 211)

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 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.

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

callbackScope :any

The context in which all callbacks are invoked.

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

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 181)

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 191)

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 59)

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 270)

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 250)

<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 158)

<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 169)

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 116)

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 137)

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 127)

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 201)

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 40)

parentIsTimeline :boolean

Is the parent of this Tween a Timeline?

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

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 240)

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 280)

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 147)

state :integer

The current state of the tween

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

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 77)

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 105)

totalData :integer

The cached length of the data array.

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

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 290)

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 260)

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 300)

totalTargets :integer

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

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

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 95)

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.Events.EventEmitter

calcDuration()

Internal method that calculates the overall duration of the Tween.

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

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 1018)
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 1228)

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 1253)

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

getTimeScale()

Returns the scale of the time applied to this Tween.

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

The Tween Data to return the value from.

Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 347)
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 420)
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 583)
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 407)
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 394)
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

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 636)
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 651)
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.Events.EventEmitter

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.Events.EventEmitter

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.Events.EventEmitter

pause()

Pauses the Tween immediately. Use resume to continue playback.

Since: 3.0.0
Source: src/tweens/tween/Tween.js (Line 695)
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 719)
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 1054)
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.Events.EventEmitter

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.Events.EventEmitter

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 796)

restart()

Restarts the tween from the beginning.

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

seek(toPosition [, delta])

Seeks to a specific point in the Tween.

Note: You cannot seek a Tween that repeats or loops forever, or that has an unusually long total duration.

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 876)
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 986)
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 1277)
Fires:
Returns:

The state of this Tween.

Type
integer

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 1364)
Fires:
Returns:

The state of this Tween.

Type
integer

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 364)
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 1073)
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 1117)
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 435)
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 1421)
Fires:
Returns:

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

Type
boolean