Phaser API Documentation

  Version: 
Filter
This is a beta release of our new docs system. Found an issue?
Please tell us about it in the #📖-newdocs-feedback channel on the Phaser Discord

Phaser . Tweens . Tween

This is a beta release of our new docs system. Found an issue?
Please tell us about it in the #📖-newdocs-feedback channel on the Phaser Discord

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.

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.

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

Extends


Members

<private> _pausedState: number
Focus
Focus

Description:

The state of the tween when it was paused (used by Resume)

Type:
number
Since: 3.0.0
Focus
Focus
calculatedOffset: number
Focus
Focus

Description:

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

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
callbackScope: any
Focus
Focus

Description:

The context in which all callbacks are invoked.

Type:
any
Since: 3.0.0
Focus
Focus
callbacks: object
Focus
Focus

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:
object
Since: 3.0.0
Focus
Focus
completeDelay: number
Focus
Focus

Description:

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

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
countdown: number
Focus
Focus

Description:

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

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus

Description:

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)
Focus
Focus
duration: number
Focus
Focus

Description:

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

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
elapsed: number
Focus
Focus

Description:

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

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
<readonly> hasStarted: boolean
Focus
Focus

Description:

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
Focus
Focus
<readonly> isSeeking: boolean
Focus
Focus

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:
boolean
Since: 3.19.0
Focus
Focus
loop: number
Focus
Focus

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:
number
Default: 0
Since: 3.0.0
Focus
Focus
loopCounter: number
Focus
Focus

Description:

How many loops are left to run?

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
loopDelay: number
Focus
Focus

Description:

Time in ms/frames before the tween loops.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
offset: number
Focus
Focus

Description:

Set only if this Tween is part of a Timeline.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus

Description:

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)
Focus
Focus
parentIsTimeline: boolean
Focus
Focus

Description:

Is the parent of this Tween a Timeline?

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

Description:

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

Type:
boolean
Default: false
Since: 3.0.0
Focus
Focus
progress: number
Focus
Focus

Description:

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

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
startDelay: number
Focus
Focus

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:
number
Default: 0
Since: 3.19.0
Focus
Focus
state: number
Focus
Focus

Description:

The current state of the tween

Type:
number
Since: 3.0.0
Focus
Focus
targets: Array.<object>
Focus
Focus

Description:

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)
Focus
Focus
timeScale: number
Focus
Focus

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:
number
Default: 1
Since: 3.0.0
Focus
Focus
totalData: number
Focus
Focus

Description:

The cached length of the data array.

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

Description:

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

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
totalElapsed: number
Focus
Focus

Description:

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

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
totalProgress: number
Focus
Focus

Description:

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

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
totalTargets: number
Focus
Focus

Description:

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)
Focus
Focus
useFrames: boolean
Focus
Focus

Description:

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

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

Methods

addListener(event, fn, [context])
Focus
Focus

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.

Inherited from: Phaser.Events.EventEmitter#addListener
Examples:
Since: 3.0.0
Focus
Focus
calcDuration()
Focus
Focus

Description:

Internal method that calculates the overall duration of the Tween.

Examples:
Since: 3.0.0
Focus
Focus
complete([delay])
Focus
Focus

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.

Examples:
Since: 3.2.0
Focus
Focus
destroy()
Focus
Focus

Description:

Removes all listeners.

Inherited from: Phaser.Events.EventEmitter#destroy
Examples:
Since: 3.0.0
Focus
Focus
dispatchTweenDataEvent(event, callback, tweenData)
Focus
Focus

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 null or undefined to skip invocation.

tweenData Phaser.Types.Tweens.TweenDataConfig

The TweenData object that caused this event.

Examples:
Since: 3.19.0
Focus
Focus
dispatchTweenEvent(event, callback)
Focus
Focus

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 null or undefined to skip invocation.

Examples:
Since: 3.19.0
Focus
Focus
emit(event, [args])
Focus
Focus

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
Inherited from: Phaser.Events.EventEmitter#emit
Examples:
Since: 3.0.0
Focus
Focus
eventNames()
Focus
Focus

Description:

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

Type:
  • Array.<(string
  • symbol)>
Inherited from: Phaser.Events.EventEmitter#eventNames
Examples:
Since: 3.0.0
Focus
Focus
getTimeScale()
Focus
Focus

Description:

Returns the scale of the time applied to this Tween.

Returns:
Description:

The timescale of this tween (between 0 and 1)

Type:
  • number
Examples:
Since: 3.0.0
Focus
Focus
getValue([index])
Focus
Focus

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
Examples:
Since: 3.0.0
Focus
Focus
hasTarget(target)
Focus
Focus

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
Examples:
Since: 3.0.0
Focus
Focus
init()
Focus
Focus

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
Examples:
Since: 3.0.0
Focus
Focus
isPaused()
Focus
Focus

Description:

Checks if the Tween is currently paused.

Returns:
Description:

true if the Tween is paused, otherwise false.

Type:
  • boolean
Examples:
Since: 3.0.0
Focus
Focus
isPlaying()
Focus
Focus

Description:

Checks if the Tween is currently active.

Returns:
Description:

true if the Tween is active, otherwise false.

Type:
  • boolean
Examples:
Since: 3.0.0
Focus
Focus
listenerCount(event)
Focus
Focus

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
Inherited from: Phaser.Events.EventEmitter#listenerCount
Examples:
Since: 3.0.0
Focus
Focus
listeners(event)
Focus
Focus

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.
Inherited from: Phaser.Events.EventEmitter#listeners
Examples:
Since: 3.0.0
Focus
Focus
makeActive()
Focus
Focus

Description:

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

Examples:
Since: 3.19.0
Focus
Focus
nextState()
Focus
Focus

Description:

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

Examples:
Since: 3.0.0
Focus
Focus
off(event, [fn], [context], [once])
Focus
Focus

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.

Inherited from: Phaser.Events.EventEmitter#off
Examples:
Since: 3.0.0
Focus
Focus
on(event, fn, [context])
Focus
Focus

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.

Inherited from: Phaser.Events.EventEmitter#on
Examples:
Since: 3.0.0
Focus
Focus
once(event, fn, [context])
Focus
Focus

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.

Inherited from: Phaser.Events.EventEmitter#once
Examples:
Since: 3.0.0
Focus
Focus
pause()
Focus
Focus

Description:

Pauses the Tween immediately. Use resume to continue playback.

Returns:
Description:
  • This Tween instance.
Examples:
Since: 3.0.0
Focus
Focus
play([resetFromTimeline])
Focus
Focus

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.

Examples:
Since: 3.0.0
Focus
Focus
remove()
Focus
Focus

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.

Examples:
Since: 3.17.0
Focus
Focus
removeAllListeners([event])
Focus
Focus

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.

Inherited from: Phaser.Events.EventEmitter#removeAllListeners
Examples:
Since: 3.0.0
Focus
Focus
removeListener(event, [fn], [context], [once])
Focus
Focus

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.

Inherited from: Phaser.Events.EventEmitter#removeListener
Examples:
Since: 3.0.0
Focus
Focus
resetTweenData(resetFromLoop)
Focus
Focus

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?

Examples:
Since: 3.0.0
Focus
Focus
restart()
Focus
Focus

Description:

Restarts the tween from the beginning.

Returns:
Description:

This Tween instance.

Examples:
Since: 3.0.0
Focus
Focus
resume()
Focus
Focus

Description:

Resumes the playback of a previously paused Tween.

Returns:
Description:
  • This Tween instance.
Examples:
Since: 3.0.0
Focus
Focus
seek(toPosition, [delta])
Focus
Focus

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.

Examples:
Since: 3.0.0
Focus
Focus
setCallback(type, callback, [params], [scope])
Focus
Focus

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.

Examples:
Since: 3.0.0
Focus
Focus
setStateFromEnd(tween, tweenData, diff)
Focus
Focus

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
Examples:
Since: 3.0.0
Focus
Focus
setStateFromStart(tween, tweenData, diff)
Focus
Focus

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
Examples:
Since: 3.0.0
Focus
Focus
setTimeScale(value)
Focus
Focus

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.
Examples:
Since: 3.0.0
Focus
Focus
shutdown()
Focus
Focus

Description:

Removes all listeners.

Inherited from: Phaser.Events.EventEmitter#shutdown
Examples:
Since: 3.0.0
Focus
Focus
stop([resetTo])
Focus
Focus

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.

Examples:
Since: 3.0.0
Focus
Focus
update(timestamp, delta)
Focus
Focus

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
Examples:
Since: 3.0.0
Focus
Focus
updateTo(key, value, [startToCurrent])
Focus
Focus

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.
Examples:
Since: 3.0.0
Focus
Focus
updateTweenData(tween, tweenData, delta)
Focus
Focus

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
Examples:
Since: 3.0.0
Focus
Focus