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

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

A Timeline combines multiple Tweens into one. Its overall behavior is otherwise similar to a single Tween.

The Timeline updates all of its Tweens simultaneously. Its methods allow you to easily build a sequence of Tweens (each one starting after the previous one) or run multiple Tweens at once during given parts of the Timeline.

Constructor:

new Timeline(manager)

Parameters:

name type description
manager Phaser.Tweens.TweenManager

The Tween Manager which owns this Timeline.

Since: 3.0.0
Source: src/tweens/Timeline.js (Line 13)

Extends


Members

<private> _pausedState: number
Focus
Focus

Description:

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

Type:
number
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 158)
Focus
Focus
callbackScope: any
Focus
Focus

Description:

The context in which all callbacks are invoked.

Type:
any
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 261)
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.

onComplete When the Timeline finishes playback fully or Timeline.stop is called. Never invoked if timeline is set to repeat infinitely. onLoop When a Timeline loops. onStart When the Timeline starts playing. onUpdate When a Timeline updates a child Tween. onYoyo When a Timeline starts a yoyo.

Type:
object
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 238)
Focus
Focus
completeDelay: number
Focus
Focus

Description:

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

Type:
number
Default: 0
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 129)
Focus
Focus
countdown: number
Focus
Focus

Description:

Countdown timer value, as used by loopDelay and completeDelay.

Type:
number
Default: 0
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 139)
Focus
Focus
data: array
Focus
Focus

Description:

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

Type:
array
Default: []
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 57)
Focus
Focus
duration: number
Focus
Focus

Description:

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

Type:
number
Default: 0
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 198)
Focus
Focus
elapsed: number
Focus
Focus

Description:

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

Type:
number
Default: 0
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 178)
Focus
Focus
isTimeline: boolean
Focus
Focus

Description:

A constant value which allows this Timeline to be easily identified as one.

Type:
boolean
Default: true
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 47)
Focus
Focus
loop: number
Focus
Focus

Description:

Loop this Timeline? Can be -1 for an infinite loop, or an integer. When enabled it will play through ALL Tweens again (use Tween.repeat to loop a single tween)

Type:
number
Default: 0
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 98)
Focus
Focus
loopCounter: number
Focus
Focus

Description:

How many loops are left to run?

Type:
number
Default: 0
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 119)
Focus
Focus
loopDelay: number
Focus
Focus

Description:

Time in ms/frames before this Timeline loops.

Type:
number
Default: 0
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 109)
Focus
Focus

Description:

The Tween Manager which owns this Timeline.

Type:
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 38)
Focus
Focus
paused: boolean
Focus
Focus

Description:

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

Type:
boolean
Default: false
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 168)
Focus
Focus
progress: number
Focus
Focus

Description:

Value between 0 and 1. The amount of progress through the Timeline, excluding loops.

Type:
number
Default: 0
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 208)
Focus
Focus
state: number
Focus
Focus

Description:

The current state of the Timeline.

Type:
number
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 149)
Focus
Focus
timeScale: number
Focus
Focus

Description:

Scales the time applied to this Timeline. 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 Timeline, it's a run-time delta adjustment only.

Type:
number
Default: 1
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 87)
Focus
Focus
totalData: number
Focus
Focus

Description:

The cached size of the data array.

Type:
number
Default: 0
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 67)
Focus
Focus
totalDuration: number
Focus
Focus

Description:

Time in ms/frames for all Tweens in this Timeline to complete (including looping)

Type:
number
Default: 0
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 218)
Focus
Focus
totalElapsed: number
Focus
Focus

Description:

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

Type:
number
Default: 0
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 188)
Focus
Focus
totalProgress: number
Focus
Focus

Description:

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

Type:
number
Default: 0
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 228)
Focus
Focus
useFrames: boolean
Focus
Focus

Description:

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

Type:
boolean
Default: false
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 77)
Focus
Focus

Methods

add(config)
Focus
Focus

Description:

Creates a new Tween, based on the given Tween Config, and adds it to this Timeline.

Parameters:

name type description
config object | Phaser.Types.Tweens.TweenBuilderConfig

The configuration object for the Tween.

Returns:
Description:

This Timeline object.

Examples:
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 337)
Focus
Focus
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:

Calculates the total duration of the timeline.

Computes all tween durations and returns the full duration of the timeline.

The resulting number is stored in the timeline, not as a return value.

Examples:
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 467)
Focus
Focus
destroy()
Focus
Focus

Description:

Stops all the Tweens in the Timeline immediately, whatever stage of progress they are at and flags them for removal by the TweenManager.

Overrides: Phaser.Events.EventEmitter#destroy
Examples:
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 880)
Focus
Focus
dispatchTimelineEvent(event, callback)
Focus
Focus

Description:

Internal method that will emit a Timeline 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
Source: src/tweens/Timeline.js (Line 271)
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
getRelativeOffset(value, base)
Focus
Focus

Description:

Parses the relative offset value, returning a positive or negative number.

Parameters:

name type description
value string

The relative offset, in the format of '-=500', for example. The first character determines whether it will be a positive or negative number. Spacing matters here.

base number

The value to use as the offset.

Returns:
Description:

The parsed offset value.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 435)
Focus
Focus
getTimeScale()
Focus
Focus

Description:

Gets the value of the time scale applied to this Timeline. 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 Timeline.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 310)
Focus
Focus
hasOffset(tween)
Focus
Focus

Description:

Checks whether a Tween has an offset value.

Parameters:

name type description
tween Phaser.Tweens.Tween

The Tween to check.

Returns:
Description:

true if the tween has a non-null offset.

Type:
  • boolean
Examples:
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 377)
Focus
Focus
hasTarget(target)
Focus
Focus

Description:

Checks if any of the Tweens in this Timeline as operating on the target object.

Returns false if no Tweens operate on the target object.

Parameters:

name type description
target object

The target to check all Tweens against.

Returns:
Description:

true if there is at least a single Tween that operates on the target object, otherwise false.

Type:
  • boolean
Examples:
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 855)
Focus
Focus
init()
Focus
Focus

Description:

Initializes the timeline, which means all Tweens get their init() called, and the total duration will be computed. Returns a boolean indicating whether the timeline is auto-started or not.

Returns:
Description:

true if the Timeline is started. false if it is paused.

Type:
  • boolean
Examples:
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 534)
Focus
Focus
isOffsetAbsolute(value)
Focus
Focus

Description:

Checks whether the offset value is a number or a directive that is relative to previous tweens.

Parameters:

name type description
value number

The offset value to be evaluated.

Returns:
Description:

true if the result is a number, false if it is a directive like " -= 1000".

Type:
  • boolean
Examples:
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 392)
Focus
Focus
isOffsetRelative(value)
Focus
Focus

Description:

Checks if the offset is a relative value rather than an absolute one. If the value is just a number, this returns false.

Parameters:

name type description
value string

The offset value to be evaluated.

Returns:
Description:

true if the value is relative, i.e " -= 1000". If false, the offset is absolute.

Type:
  • boolean
Examples:
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 407)
Focus
Focus
isPlaying()
Focus
Focus

Description:

Check whether or not the Timeline is playing.

Returns:
Description:

true if this Timeline is active, otherwise false.

Type:
  • boolean
Examples:
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 324)
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(tween)
Focus
Focus

Description:

Passed a Tween to the Tween Manager and requests it be made active.

Parameters:

name type description
tween Phaser.Tweens.Tween

The tween object to make active.

Returns:
Description:

The Timeline's Tween Manager reference.

Examples:
Since: 3.3.0
Source: src/tweens/Timeline.js (Line 604)
Focus
Focus
nextState()
Focus
Focus

Description:

Updates the Timeline's state and fires callbacks and events.

Examples:
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 651)
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 Timeline, retaining its internal state.

Calling this on a Timeline that is already paused has no effect and fires no event.

Returns:
Description:

This Timeline object.

Examples:
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 801)
Focus
Focus
play()
Focus
Focus

Description:

Starts playing the Timeline.

Examples:
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 619)
Focus
Focus
queue(tween)
Focus
Focus

Description:

Adds an existing Tween to this Timeline.

Parameters:

name type description
tween Phaser.Tweens.Tween

The Tween to be added to this Timeline.

Returns:
Description:

This Timeline object.

Examples:
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 352)
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
resetTweens(resetFromLoop)
Focus
Focus

Description:

Resets all of the timeline's tweens back to their initial states. The boolean parameter indicates whether tweens that are looping should reset as well, or not.

Parameters:

name type description
resetFromLoop boolean

If true, resets all looping tweens to their initial values.

Examples:
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 562)
Focus
Focus
resume()
Focus
Focus

Description:

Resumes a paused Timeline from where it was when it was paused.

Calling this on a Timeline that isn't paused has no effect and fires no event.

Returns:
Description:

This Timeline object.

Examples:
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 830)
Focus
Focus
setCallback(type, callback, [params], [scope])
Focus
Focus

Description:

Sets a callback for the Timeline.

Parameters:

name type arguments description
type string

The internal type of callback to set.

callback function

Timeline allows multiple tweens to be linked together to create a streaming sequence.

params array <optional>

The parameters to pass to the callback.

scope object <optional>

The context scope of the callback.

Returns:
Description:

This Timeline object.

Examples:
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 581)
Focus
Focus
setTimeScale(value)
Focus
Focus

Description:

Sets the value of the time scale applied to this Timeline. 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.

Parameters:

name type description
value number

The time scale value to set.

Returns:
Description:

This Timeline object.

Examples:
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 290)
Focus
Focus
shutdown()
Focus
Focus

Description:

Removes all listeners.

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

Description:

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

Examples:
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 790)
Focus
Focus
update(timestamp, delta)
Focus
Focus

Description:

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

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 Timeline has finished and should be removed from the Tween Manager.

Type:
  • boolean
Examples:
Since: 3.0.0
Source: src/tweens/Timeline.js (Line 700)
Focus
Focus