Phaser API Documentation

  Version: 
Filter

As the name implies, this is the base Tween class that both the Tween and TweenChain inherit from. It contains shared properties and methods common to both types of Tween.

Typically you would never instantiate this class directly, although you could certainly use it to create your own variation of Tweens from.

Constructor:

new BaseTween(parent)

Parameters:

name type description
parent Phaser.Tweens.TweenManager | Phaser.Tweens.TweenChain

A reference to the Tween Manager, or Tween Chain, that owns this Tween.

Since: 3.60.0

Extends


Members

callbackScope: any
Focus
Focus

Description:

The scope (or context) in which all of the callbacks are invoked.

This defaults to be this Tween, but you can override this property to set it to whatever object you require.

Type:
any
Since: 3.60.0
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.

The types available are:

onActive - When the Tween is first created it moves to an 'active' state when added to the Tween Manager. 'Active' does not mean 'playing'. onStart - When the Tween starts playing after a delayed or paused state. This will happen at the same time as onActive if the tween has no delay and isn't paused. onLoop - When a Tween loops, if it has been set to do so. This happens after the loopDelay expires, if set. onComplete - When the Tween finishes playback fully. Never invoked if the Tween is set to repeat infinitely. onStop - Invoked only if the Tween.stop method is called. onPause - Invoked only if the Tween.pause method is called. Not invoked if the Tween Manager is paused. onResume - Invoked only if the Tween.resume method is called. Not invoked if the Tween Manager is resumed.

The following types are also available and are invoked on a TweenData level - that is per-object, per-property, being tweened.

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. onUpdate - When a TweenData updates a property on a source target during playback.

Type:
Since: 3.60.0
Focus
Focus
completeDelay: number
Focus
Focus

Description:

The time in milliseconds before the 'onComplete' event fires.

This never fires if loop = -1 as it never completes because it has been set to loop forever.

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

Description:

An internal countdown timer (used by loopDelay and completeDelay)

Type:
number
Default: 0
Since: 3.60.0
Focus
Focus

Description:

The main data array. For a Tween, this contains all of the TweenData objects, each containing a unique property and target that is being tweened.

For a TweenChain, this contains an array of Tween instances, which are being played through in sequence.

Type:
Since: 3.60.0
Focus
Focus
<readonly> hasStarted: boolean
Focus
Focus

Description:

Has this Tween started playback yet?

This boolean is toggled when the Tween leaves the 'start delayed' state and begins running.

Type:
boolean
Since: 3.60.0
Focus
Focus
loop: number
Focus
Focus

Description:

The number of times this Tween will loop.

Can be -1 for an infinite loop, zero for none, or a positive integer.

Typically this is set in the configuration object, but can also be set directly as long as this Tween is paused and hasn't started playback.

When enabled it will play through ALL Tweens again.

Use TweenData.repeat to loop a single element.

Type:
number
Default: 0
Since: 3.60.0
Focus
Focus
loopCounter: number
Focus
Focus

Description:

Internal counter recording how many loops are left to run.

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

Description:

The time in milliseconds before the Tween loops.

Only used if loop is > 0.

Type:
number
Default: 0
Since: 3.60.0
Focus
Focus

Description:

A reference to the Tween Manager, or Tween Chain, that owns this Tween.

Type:
Since: 3.60.0
Focus
Focus
paused: boolean
Focus
Focus

Description:

Is the Tween currently paused?

A paused Tween needs to be started with the play method, or resumed with the resume method.

This property can be toggled at runtime if required.

Type:
boolean
Default: false
Since: 3.60.0
Focus
Focus
persist: boolean
Focus
Focus

Description:

Will this Tween persist after playback? A Tween that persists will not be destroyed by the Tween Manager, or when calling Tween.stop, and can be re-played as required. You can either set this property when creating the tween in the tween config, or set it prior to playback.

However, it's up to you to ensure you destroy persistent tweens when you are finished with them, or they will retain references you may no longer require and waste memory.

By default, Tweens are set to not persist, so they are automatically cleaned-up by the Tween Manager.

Type:
boolean
Since: 3.60.0
Focus
Focus
startDelay: number
Focus
Focus

Description:

The time in milliseconds before the 'onStart' event fires.

For a Tween, this is the shortest delay value across all of the TweenDatas it owns. For a TweenChain, it is whatever delay value was given in the configuration.

Type:
number
Default: 0
Since: 3.60.0
Focus
Focus

Description:

The current state of the Tween.

Type:
Since: 3.60.0
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.

The value isn't used when calculating total duration of the tween, it's a run-time delta adjustment only.

This value is multiplied by the TweenManager.timeScale.

Type:
number
Default: 1
Since: 3.60.0
Focus
Focus
totalData: number
Focus
Focus

Description:

The cached size of the data array.

Type:
number
Since: 3.60.0
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
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 don't 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.

Since: 3.2.0
Focus
Focus
completeAfterLoop([loops])
Focus
Focus

Description:

Flags the Tween as being complete only once the current loop has finished.

This is a useful way to stop an infinitely looping tween once a complete cycle is over, rather than abruptly.

If you don't have a loop then call Tween.stop instead.

Parameters:

name type arguments description
loops number <optional>

The number of loops that should finish before this tween completes. Zero means complete just the current loop.

Returns:
Description:

This Tween instance.

Since: 3.60.0
Focus
Focus
destroy()
Focus
Focus

Description:

Handles the destroy process of this Tween, clearing out the Tween Data and resetting the targets. A Tween that has been destroyed cannot ever be played or used again.

Overrides: Phaser.Events.EventEmitter#destroy
Since: 3.60.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
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
Since: 3.0.0
Focus
Focus
getTimeScale()
Focus
Focus

Description:

Gets the value of the time scale applied to this Tween. A value of 1 runs in real-time. A value of 0.5 runs 50% slower, and so on.

Returns:
Description:

The value of the time scale applied to this Tween.

Type:
  • number
Since: 3.60.0
Focus
Focus
isActive()
Focus
Focus

Description:

Returns true if this Tween has a current state of ACTIVE, otherwise false.

Returns:
Description:

true if this Tween has a current state of ACTIVE, otherwise false.

Type:
  • boolean
Since: 3.60.0
Focus
Focus
isCompleteDelayed()
Focus
Focus

Description:

Returns true if this Tween has a current state of COMPLETE_DELAY, otherwise false.

Returns:
Description:

true if this Tween has a current state of COMPLETE_DELAY, otherwise false.

Type:
  • boolean
Since: 3.60.0
Focus
Focus
isDestroyed()
Focus
Focus

Description:

Returns true if this Tween has a current state of DESTROYED, otherwise false.

Returns:
Description:

true if this Tween has a current state of DESTROYED, otherwise false.

Type:
  • boolean
Since: 3.60.0
Focus
Focus
isFinished()
Focus
Focus

Description:

Returns true if this Tween has a current state of FINISHED, otherwise false.

Returns:
Description:

true if this Tween has a current state of FINISHED, otherwise false.

Type:
  • boolean
Since: 3.60.0
Focus
Focus
isLoopDelayed()
Focus
Focus

Description:

Returns true if this Tween has a current state of LOOP_DELAY, otherwise false.

Returns:
Description:

true if this Tween has a current state of LOOP_DELAY, otherwise false.

Type:
  • boolean
Since: 3.60.0
Focus
Focus
isPaused()
Focus
Focus

Description:

Checks if the Tween is currently paused.

This is the same as inspecting the BaseTween.paused property directly.

Returns:
Description:

true if the Tween is paused, otherwise false.

Type:
  • boolean
Since: 3.60.0
Focus
Focus
isPending()
Focus
Focus

Description:

Returns true if this Tween has a current state of PENDING, otherwise false.

Returns:
Description:

true if this Tween has a current state of PENDING, otherwise false.

Type:
  • boolean
Since: 3.60.0
Focus
Focus
isPendingRemove()
Focus
Focus

Description:

Returns true if this Tween has a current state of PENDING_REMOVE, otherwise false.

Returns:
Description:

true if this Tween has a current state of PENDING_REMOVE, otherwise false.

Type:
  • boolean
Since: 3.60.0
Focus
Focus
isPlaying()
Focus
Focus

Description:

Checks if this Tween is currently playing.

If this Tween is paused, or not active, this method will return false.

Returns:
Description:

true if the Tween is playing, otherwise false.

Type:
  • boolean
Since: 3.60.0
Focus
Focus
isRemoved()
Focus
Focus

Description:

Returns true if this Tween has a current state of REMOVED, otherwise false.

Returns:
Description:

true if this Tween has a current state of REMOVED, otherwise false.

Type:
  • boolean
Since: 3.60.0
Focus
Focus
isStartDelayed()
Focus
Focus

Description:

Returns true if this Tween has a current state of START_DELAY, otherwise false.

Returns:
Description:

true if this Tween has a current state of START_DELAY, otherwise false.

Type:
  • boolean
Since: 3.60.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
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.<function()>
Inherited from: Phaser.Events.EventEmitter#listeners
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.

Since: 3.60.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
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
Since: 3.0.0
Focus
Focus
onCompleteHandler()
Focus
Focus

Description:

Internal method that handles this tween completing and emitting the onComplete event and callback.

Since: 3.60.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
Since: 3.0.0
Focus
Focus
pause()
Focus
Focus

Description:

Pauses the Tween immediately. Use resume to continue playback.

You can also toggle the Tween.paused boolean property, but doing so will not trigger the PAUSE event.

Returns:
Description:

This Tween instance.

Since: 3.60.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 is at. 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. If you no longer require it, call Tween.destroy() on it.

Returns:
Description:

This Tween instance.

Since: 3.60.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
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
Since: 3.0.0
Focus
Focus
resume()
Focus
Focus

Description:

Resumes the playback of a previously paused Tween.

You can also toggle the Tween.paused boolean property, but doing so will not trigger the RESUME event.

Returns:
Description:

This Tween instance.

Since: 3.60.0
Focus
Focus
setActiveState()
Focus
Focus

Description:

Sets this Tween state to ACTIVE.

Since: 3.60.0
Focus
Focus
setCallback(type, callback, [params])
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 first created it moves to an 'active' state when added to the Tween Manager. 'Active' does not mean 'playing'. onStart - When the Tween starts playing after a delayed or paused state. This will happen at the same time as onActive if the tween has no delay and isn't paused. onLoop - When a Tween loops, if it has been set to do so. This happens after the loopDelay expires, if set. onComplete - When the Tween finishes playback fully. Never invoked if the Tween is set to repeat infinitely. onStop - Invoked only if the Tween.stop method is called. onPause - Invoked only if the Tween.pause method is called. Not invoked if the Tween Manager is paused. onResume - Invoked only if the Tween.resume method is called. Not invoked if the Tween Manager is resumed.

The following types are also available and are invoked on a TweenData level - that is per-object, per-property, being tweened.

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. onUpdate - When a TweenData updates a property on a source target during playback.

Parameters:

name type arguments description
type Phaser.Types.Tweens.TweenCallbackTypes

The type of callback to set. One of: onActive, onComplete, onLoop, onPause, onRepeat, onResume, onStart, onStop, onUpdate or onYoyo.

callback function

Your callback that will be invoked.

params array <optional>

The parameters to pass to the callback. Pass an empty array if you don't want to define any, but do wish to set the scope.

Returns:
Description:

This Tween instance.

Since: 3.60.0
Focus
Focus
setCompleteDelayState()
Focus
Focus

Description:

Sets this Tween state to COMPLETE_DELAY.

Since: 3.60.0
Focus
Focus
setDestroyedState()
Focus
Focus

Description:

Sets this Tween state to DESTROYED.

Since: 3.60.0
Focus
Focus
setFinishedState()
Focus
Focus

Description:

Sets this Tween state to FINISHED.

Since: 3.60.0
Focus
Focus
setLoopDelayState()
Focus
Focus

Description:

Sets this Tween state to LOOP_DELAY.

Since: 3.60.0
Focus
Focus
setPendingRemoveState()
Focus
Focus

Description:

Sets this Tween state to PENDING_REMOVE.

Since: 3.60.0
Focus
Focus
setPendingState()
Focus
Focus

Description:

Sets this Tween state to PENDING.

Since: 3.60.0
Focus
Focus
setRemovedState()
Focus
Focus

Description:

Sets this Tween state to REMOVED.

Since: 3.60.0
Focus
Focus
setStartDelayState()
Focus
Focus

Description:

Sets this Tween state to START_DELAY.

Since: 3.60.0
Focus
Focus
setTimeScale(value)
Focus
Focus

Description:

Sets the value of the time scale applied to this Tween. A value of 1 runs in real-time. A value of 0.5 runs 50% slower, and so on.

The value isn't used when calculating total duration of the tween, it's a run-time delta adjustment only.

This value is multiplied by the TweenManager.timeScale.

Parameters:

name type description
value number

The time scale value to set.

Returns:
Description:

This Tween instance.

Since: 3.60.0
Focus
Focus
shutdown()
Focus
Focus

Description:

Removes all listeners.

Inherited from: Phaser.Events.EventEmitter#shutdown
Since: 3.0.0
Focus
Focus
stop()
Focus
Focus

Description:

Stops the Tween immediately, whatever stage of progress it is at.

If not a part of a Tween Chain it is also flagged for removal by the Tween Manager.

If an onStop callback has been defined it will automatically invoke it.

The Tween will be removed during the next game frame, but should be considered 'destroyed' from this point on.

Typically, you cannot play a Tween that has been stopped. If you just wish to pause the tween, not destroy it, then call the pause method instead and use resume to continue playback. If you wish to restart the Tween, use the restart or seek methods.

Returns:
Description:

This Tween instance.

Since: 3.60.0
Focus
Focus
updateCompleteDelay(delta)
Focus
Focus

Description:

Internal method that handles the processing of the complete delay countdown timer and the dispatch of related events. Called automatically by Tween.update.

Parameters:

name type description
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.60.0
Focus
Focus
updateLoopCountdown(delta)
Focus
Focus

Description:

Internal method that handles the processing of the loop delay countdown timer and the dispatch of related events. Called automatically by Tween.update.

Parameters:

name type description
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.60.0
Focus
Focus
updateStartCountdown(delta)
Focus
Focus

Description:

Internal method that handles the processing of the start delay countdown timer and the dispatch of related events. Called automatically by Tween.update.

Parameters:

name type description
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.60.0
Focus
Focus