Class Timeline

A Timeline is a way to schedule events to happen at specific times in the future.

You can think of it as an event sequencer for your game, allowing you to schedule the running of callbacks, events and other actions at specific times in the future.

A Timeline is a Scene level system, meaning you can have as many Timelines as you like, each belonging to a different Scene. You can also have multiple Timelines running at the same time.

If the Scene is paused, the Timeline will also pause. If the Scene is destroyed, the Timeline will be automatically destroyed. However, you can control the Timeline directly, pausing, resuming and stopping it at any time.

Create an instance of a Timeline via the Game Object Factory:

const timeline = this.add.timeline();

The Timeline always starts paused. You must call play on it to start it running.

You can also pass in a configuration object on creation, or an array of them:

const timeline = this.add.timeline({
    at: 1000,
    run: () => {
        this.add.sprite(400, 300, 'logo');
    }
});

timeline.play();

In this example we sequence a few different events:

const timeline = this.add.timeline([
    {
        at: 1000,
        run: () => { this.logo = this.add.sprite(400, 300, 'logo'); },
        sound: 'TitleMusic'
    },
    {
        at: 2500,
        tween: {
            targets: this.logo,
            y: 600,
            yoyo: true
        },
        sound: 'Explode'
    },
    {
        at: 8000,
        event: 'HURRY_PLAYER',
        target: this.background,
        set: {
            tint: 0xff0000
        }
    }
]);

timeline.play();

The Timeline can also be looped with the repeat method:

timeline.repeat().play();

There are lots of options available to you via the configuration object. See the Phaser.Types.Time.TimelineEventConfig typedef for more details.

Hierarchy (View Summary)

EventEmitter
- Timeline

Index

Constructors

constructor

Properties

complete elapsed events iteration loop paused scene systems timeScale totalComplete

Constructors

constructor

new Timeline(
scene: Scene,
config?: TimelineEventConfig | TimelineEventConfig[],
): Time.Timeline
Parameters
- scene: Scene
  The Scene which owns this Timeline.
- Optionalconfig: TimelineEventConfig | TimelineEventConfig[]
  The configuration object for this Timeline Event, or an array of them.
Returns Time.Timeline
Overrides EventEmitter.constructor
- Defined in types/phaser.d.ts:117768

Properties

complete

complete: boolean

Whether the Timeline is complete (true) or not (false).

A Timeline is considered complete when all of its events have been run.

If you wish to reset a Timeline after it has completed, you can do so by calling the Timeline.reset method.

You can also use the Timeline.stop method to stop a running Timeline, at any point, without resetting it.

elapsed

elapsed: number

The elapsed time counter.

Treat this as read-only.

events

events: TimelineEvent[]

An array of all the Timeline Events.

iteration

iteration: number

The number of times this Timeline has looped.

This value is incremented each loop if looping is enabled.

loop

loop: number

The number of times this timeline should loop.

If this value is -1 or any negative number this Timeline will not stop.

paused

paused: boolean

Whether the Timeline is running (true) or active (false).

When paused, the Timeline will not run any of its actions.

By default a Timeline is always paused and should be started by calling the Timeline.play method.

You can use the Timeline.pause and Timeline.resume methods to control this value in a chainable way.

scene

scene: Scene

The Scene to which this Timeline belongs.

systems

systems: Systems

A reference to the Scene Systems.

timeScale

timeScale: number

The Timeline's delta time scale.

Values higher than 1 increase the speed of time, while values smaller than 1 decrease it. A value of 0 freezes time and is effectively equivalent to pausing the Timeline.

This doesn't affect the delta time scale of any Tweens created by the Timeline. You will have to set the timeScale of each Tween or the Tween Manager if you want them to match.

totalComplete

totalComplete: number

The total number of events that have been run.

This value is reset to zero if the Timeline is restarted.

Treat this as read-only.

Methods

add

add(config: TimelineEventConfig | TimelineEventConfig[]): this
Adds one or more events to this Timeline.

You can pass in a single configuration object, or an array of them:
```
const timeline = this.add.timeline({
    at: 1000,
    run: () => {
        this.add.sprite(400, 300, 'logo');
    }
});
```
Parameters
- config: TimelineEventConfig | TimelineEventConfig[]
  The configuration object for this Timeline Event, or an array of them.
Returns this
- Defined in types/phaser.d.ts:117967

addListener

addListener(event: string | symbol, fn: Function, context?: any): this
Add a listener for a given event.
Parameters
- event: string | symbol
  The event name.
- fn: Function
  The listener function.
- Optionalcontext: any
  The context to invoke the listener with. Default this.
Returns this
Inherited from EventEmitter.addListener
- Defined in types/phaser.d.ts:9645

clear

clear(): this
Removes all events from this Timeline, resets the elapsed time to zero and pauses the Timeline.

Any Tweens that were currently running as a result of this Timeline will be stopped.

Returns this
- Defined in types/phaser.d.ts:117975

destroy

destroy(): void
Destroys this Timeline.

This will remove all events from the Timeline and stop it from processing.

Any Tweens that were currently running as a result of this Timeline will be stopped.

This method is called automatically when the Scene shuts down, but you may also call it directly should you need to destroy the Timeline earlier.

Returns void
Overrides EventEmitter.destroy
- Defined in types/phaser.d.ts:118009

emit

emit(event: string | symbol, ...args: any[]): boolean
Calls each of the listeners registered for a given event.
Parameters
- event: string | symbol
  The event name.
- ...args: any[]
  Additional arguments that will be passed to the event handler.
Returns boolean
Inherited from EventEmitter.emit
- Defined in types/phaser.d.ts:9629

eventNames

eventNames(): (string | symbol)[]
Return an array listing the events for which the emitter has registered listeners.

Returns (string | symbol)[]
Inherited from EventEmitter.eventNames
- Defined in types/phaser.d.ts:9610

getProgress

getProgress(): number
Returns a number between 0 and 1 representing the progress of this Timeline.

A value of 0 means the Timeline has just started, 0.5 means it's half way through, and 1 means it's complete.

If the Timeline has no events, or all events have been removed, this will return 1.

If the Timeline is paused, this will return the progress value at the time it was paused.

Note that the value returned is based on the number of events that have been completed, not the 'duration' of the events (as this is unknown to the Timeline).

Returns number
- Defined in types/phaser.d.ts:117997

isPlaying

isPlaying(): boolean
Returns true if this Timeline is currently playing.

A Timeline is playing if it is not paused or not complete.

Returns boolean
- Defined in types/phaser.d.ts:117982

listenerCount

listenerCount(event: string | symbol): number
Return the number of listeners listening to a given event.
Parameters
- event: string | symbol
  The event name.
Returns number
Inherited from EventEmitter.listenerCount
- Defined in types/phaser.d.ts:9622

listeners

listeners(event: string | symbol): Function[]
Return the listeners registered for a given event.
Parameters
- event: string | symbol
  The event name.
Returns Function[]
Inherited from EventEmitter.listeners
- Defined in types/phaser.d.ts:9616

off

off(event: string | symbol, fn?: Function, context?: any, once?: boolean): this
Remove the listeners of a given event.
Parameters
- event: string | symbol
  The event name.
- Optionalfn: Function
  Only remove the listeners that match this function.
- Optionalcontext: any
  Only remove the listeners that have this context.
- Optionalonce: boolean
  Only remove one-time listeners.
Returns this
Inherited from EventEmitter.off
- Defined in types/phaser.d.ts:9671

on

on(event: string | symbol, fn: Function, context?: any): this
Add a listener for a given event.
Parameters
- event: string | symbol
  The event name.
- fn: Function
  The listener function.
- Optionalcontext: any
  The context to invoke the listener with. Default this.
Returns this
Inherited from EventEmitter.on
- Defined in types/phaser.d.ts:9637

once

once(event: string | symbol, fn: Function, context?: any): this
Add a one-time listener for a given event.
Parameters
- event: string | symbol
  The event name.
- fn: Function
  The listener function.
- Optionalcontext: any
  The context to invoke the listener with. Default this.
Returns this
Inherited from EventEmitter.once
- Defined in types/phaser.d.ts:9653

pause

pause(): this
Pauses this Timeline.

To resume it again, call the Timeline.resume method or set the Timeline.paused property to false.

If the Timeline is paused while processing the current game step, then it will carry on with all events that are due to run during that step and pause from the next game step.

Note that if any Tweens have been started prior to calling this method, they will not be paused as well.

Returns this
- Defined in types/phaser.d.ts:117902

play

play(fromStart?: boolean): this
Starts this Timeline running.

If the Timeline is already running and the fromStart parameter is true, then calling this method will reset the Timeline events as incomplete.

If you wish to resume a paused Timeline, then use the Timeline.resume method instead.
Parameters
- OptionalfromStart: boolean
  Reset this Timeline back to the start before playing. Default true.
Returns this
- Defined in types/phaser.d.ts:117889

preUpdate

preUpdate(time: number, delta: number): void
Updates the elapsed time counter, if this Timeline is not paused.
Parameters
- time: 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 void
- Defined in types/phaser.d.ts:117857

removeAllListeners

removeAllListeners(event?: string | symbol): this
Remove all listeners, or those of the specified event.
Parameters
- Optionalevent: string | symbol
  The event name.
Returns this
Inherited from EventEmitter.removeAllListeners
- Defined in types/phaser.d.ts:9677

removeListener

removeListener(
    event: string | symbol,
    fn?: Function,
    context?: any,
    once?: boolean,
): this
Remove the listeners of a given event.
Parameters
- event: string | symbol
  The event name.
- Optionalfn: Function
  Only remove the listeners that match this function.
- Optionalcontext: any
  Only remove the listeners that have this context.
- Optionalonce: boolean
  Only remove one-time listeners.
Returns this
Inherited from EventEmitter.removeListener
- Defined in types/phaser.d.ts:9662

repeat

repeat(amount?: number | boolean): this
Repeats this Timeline.

If the value for amount is positive, the Timeline will repeat that many additional times. For example a value of 1 will actually run this Timeline twice.

Depending on the value given, false is 0 and true, undefined and negative numbers are infinite.

If this Timeline had any events set to once that have already been removed, they will not be repeated each loop.
Parameters
- Optionalamount: number | boolean
  Amount of times to repeat, if true or negative it will be infinite. Default -1.
Returns this
- Defined in types/phaser.d.ts:117916

reset

reset(loop?: boolean): this
Resets this Timeline back to the start.

This will set the elapsed time to zero and set all events to be incomplete.

If the Timeline had any events that were set to once that have already been removed, they will not be present again after calling this method.

If the Timeline isn't currently running (i.e. it's paused or complete) then calling this method resets those states, the same as calling Timeline.play(true).

Any Tweens that were currently running by this Timeline will be stopped.
Parameters
- Optionalloop: boolean
  Set to true if you do not want to reset the loop counters. Default false.
Returns this
- Defined in types/phaser.d.ts:117950

resume

resume(): this
Resumes this Timeline from a paused state.

The Timeline will carry on from where it left off.

If you need to reset the Timeline to the start, then call the Timeline.reset method.

Returns this
- Defined in types/phaser.d.ts:117925

shutdown

shutdown(): void
Removes all listeners.

Returns void
Inherited from EventEmitter.shutdown
- Defined in types/phaser.d.ts:9600

stop

stop(): this
Stops this Timeline.

This will set the paused and complete properties to true.

If you wish to reset the Timeline to the start, then call the Timeline.reset method.

Returns this
- Defined in types/phaser.d.ts:117934

update

update(time: number, delta: number): void
Called automatically by the Scene update step.

Iterates through all of the Timeline Events and checks to see if they should be run.

If they should be run, then the TimelineEvent.action callback is invoked.

If the TimelineEvent.once property is true then the event is removed from the Timeline.

If the TimelineEvent.event property is set then the Timeline emits that event.

If the TimelineEvent.run property is set then the Timeline invokes that method.

If the TimelineEvent.loop property is set then the Timeline invokes that method when repeated.

If the TimelineEvent.target property is set then the Timeline invokes the run method on that target.
Parameters
- time: 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 void
- Defined in types/phaser.d.ts:117878

Class Timeline

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns Time.Timeline

Properties

complete

elapsed

events

iteration

loop

paused

scene

systems

timeScale

totalComplete

Methods

add

Parameters

Returns this

addListener

Parameters

Returns this

clear

Returns this

destroy

Returns void

emit

Parameters

Returns boolean

eventNames

Returns (string | symbol)[]

getProgress

Returns number

isPlaying

Returns boolean

listenerCount

Parameters

Returns number

listeners

Parameters

Returns Function[]

off

Parameters

Returns this

on

Parameters

Returns this

once

Parameters

Returns this

pause

Returns this

play

Parameters

Returns this

preUpdate

Parameters

Returns void

removeAllListeners

Parameters

Returns this

removeListener

Parameters

Returns this

repeat

Parameters

Returns this

reset

Parameters

Returns this

resume

Returns this

shutdown

Returns void