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

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

The core runner class that Phaser uses to handle the game loop. It can use either Request Animation Frame, or SetTimeout, based on browser support and config settings, to create a continuous loop within the browser.

Each time the loop fires, TimeStep.step is called and this is then passed onto the core Game update loop, it is the core heartbeat of your game. It will fire as often as Request Animation Frame is capable of handling on the target device.

Note that there are lots of situations where a browser will stop updating your game. Such as if the player switches tabs, or covers up the browser window with another application. In these cases, the 'heartbeat' of your game will pause, and only resume when focus is returned to it by the player. There is no way to avoid this situation, all you can do is use the visibility events the browser, and Phaser, provide to detect when it has happened and then gracefully recover.

Constructor:

new TimeStep(game, config)

Parameters:

name type description
game Phaser.Game

A reference to the Phaser.Game instance that owns this Time Step.

config Phaser.Types.Core.FPSConfig
Since: 3.0.0
Source: src/core/TimeStep.js (Line 14)

Members

<private> _coolDown: number
Focus
Focus

Description:

An internal counter to allow for the browser 'cooling down' after coming back into focus.

Type:
number
Default: 0
Since: 3.0.0
Source: src/core/TimeStep.js (Line 256)
Focus
Focus
<private> _min: number
Focus
Focus

Description:

The minFps value in ms. Defaults to 200ms between frames (i.e. super slow!)

Type:
number
Since: 3.0.0
Source: src/core/TimeStep.js (Line 112)
Focus
Focus
<private> _pauseTime: number
Focus
Focus

Description:

The timestamp at which the game became paused, as determined by the Page Visibility API.

Type:
number
Default: 0
Since: 3.0.0
Source: src/core/TimeStep.js (Line 245)
Focus
Focus
<private> _target: number
Focus
Focus

Description:

The targetFps value in ms. Defaults to 16.66ms between frames (i.e. normal)

Type:
number
Since: 3.0.0
Source: src/core/TimeStep.js (Line 123)
Focus
Focus
<readonly> actualFps: number
Focus
Focus

Description:

An exponential moving average of the frames per second.

Type:
number
Default: 60
Since: 3.0.0
Source: src/core/TimeStep.js (Line 134)
Focus
Focus

Description:

A callback to be invoked each time the Time Step steps.

Type:
Default: NOOP
Since: 3.0.0
Source: src/core/TimeStep.js (Line 168)
Focus
Focus
delta: number
Focus
Focus

Description:

The delta time, in ms, since the last game step. This is a clamped and smoothed average value.

Type:
number
Default: 0
Since: 3.0.0
Source: src/core/TimeStep.js (Line 267)
Focus
Focus
deltaHistory: Array.<number>
Focus
Focus

Description:

Internal array holding the previous delta values, used for delta smoothing.

Type:
Array.<number>
Since: 3.0.0
Source: src/core/TimeStep.js (Line 287)
Focus
Focus
deltaIndex: number
Focus
Focus

Description:

Internal index of the delta history position.

Type:
number
Default: 0
Since: 3.0.0
Source: src/core/TimeStep.js (Line 277)
Focus
Focus
deltaSmoothingMax: number
Focus
Focus

Description:

The maximum number of delta values that are retained in order to calculate a smoothed moving average.

This can be changed in the Game Config via the fps.deltaHistory property. The default is 10.

Type:
number
Default: 10
Since: 3.0.0
Source: src/core/TimeStep.js (Line 296)
Focus
Focus
<readonly> forceSetTimeOut: boolean
Focus
Focus

Description:

You can force the Time Step to use Set Timeout instead of Request Animation Frame by setting the forceSetTimeOut property to true in the Game Configuration object. It cannot be changed at run-time.

Type:
boolean
Default: false
Since: 3.0.0
Source: src/core/TimeStep.js (Line 178)
Focus
Focus
<readonly> frame: number
Focus
Focus

Description:

The current frame the game is on. This counter is incremented once every game step, regardless of how much time has passed and is unaffected by delta smoothing.

Type:
number
Default: 0
Since: 3.0.0
Source: src/core/TimeStep.js (Line 221)
Focus
Focus
<readonly> framesThisSecond: number
Focus
Focus

Description:

The number of frames processed this second.

Type:
number
Default: 0
Since: 3.0.0
Source: src/core/TimeStep.js (Line 157)
Focus
Focus
<readonly> game: Phaser.Game
Focus
Focus

Description:

A reference to the Phaser.Game instance.

Type:
Since: 3.0.0
Source: src/core/TimeStep.js (Line 43)
Focus
Focus
<readonly> inFocus: boolean
Focus
Focus

Description:

Is the browser currently considered in focus by the Page Visibility API? This value is set in the blur method, which is called automatically by the Game instance.

Type:
boolean
Default: true
Since: 3.0.0
Source: src/core/TimeStep.js (Line 233)
Focus
Focus
lastTime: number
Focus
Focus

Description:

The time, as returned by performance.now of the previous step.

Type:
number
Default: 0
Since: 3.0.0
Source: src/core/TimeStep.js (Line 211)
Focus
Focus
minFps: number
Focus
Focus

Description:

The minimum fps rate you want the Time Step to run at.

Type:
number
Default: 5
Since: 3.0.0
Source: src/core/TimeStep.js (Line 88)
Focus
Focus
<readonly> nextFpsUpdate: number
Focus
Focus

Description:

The time at which the next fps rate update will take place. When an fps update happens, the framesThisSecond value is reset.

Type:
number
Default: 0
Since: 3.0.0
Source: src/core/TimeStep.js (Line 145)
Focus
Focus
now: number
Focus
Focus

Description:

The time, as returned by performance.now at the very start of the current step. This can differ from the time value in that it isn't calculated based on the delta value.

Type:
number
Default: 0
Since: 3.18.0
Source: src/core/TimeStep.js (Line 334)
Focus
Focus
panicMax: number
Focus
Focus

Description:

The number of frames that the cooldown is set to after the browser panics over the FPS rate, usually as a result of switching tabs and regaining focus.

This can be changed in the Game Config via the fps.panicMax property. The default is 120.

Type:
number
Default: 120
Since: 3.0.0
Source: src/core/TimeStep.js (Line 308)
Focus
Focus

Description:

The Request Animation Frame DOM Event handler.

Type:
Since: 3.0.0
Source: src/core/TimeStep.js (Line 53)
Focus
Focus
rawDelta: number
Focus
Focus

Description:

The actual elapsed time in ms between one update and the next.

Unlike with delta, no smoothing, capping, or averaging is applied to this value. So please be careful when using this value in math calculations.

Type:
number
Default: 0
Since: 3.0.0
Source: src/core/TimeStep.js (Line 321)
Focus
Focus
<readonly> running: boolean
Focus
Focus

Description:

A flag that is set once the TimeStep has started running and toggled when it stops. The difference between this value and started is that running is toggled when the TimeStep is sent to sleep, where-as started remains true, only changing if the TimeStep is actually stopped, not just paused.

Type:
boolean
Default: false
Since: 3.0.0
Source: src/core/TimeStep.js (Line 74)
Focus
Focus
smoothStep: boolean
Focus
Focus

Description:

Apply smoothing to the delta value used within Phasers internal calculations?

This can be changed in the Game Config via the fps.smoothStep property. The default is true.

Smoothing helps settle down the delta values after browser tab switches, or other situations which could cause significant delta spikes or dips. By default it has been enabled in Phaser 3 since the first version, but is now exposed under this property (and the corresponding game config smoothStep value), to allow you to easily disable it, should you require.

Type:
boolean
Since: 3.22.0
Source: src/core/TimeStep.js (Line 345)
Focus
Focus
startTime: number
Focus
Focus

Description:

The time at which the game started running. This value is adjusted if the game is then paused and resumes.

Type:
number
Default: 0
Since: 3.0.0
Source: src/core/TimeStep.js (Line 200)
Focus
Focus
<readonly> started: boolean
Focus
Focus

Description:

A flag that is set once the TimeStep has started running and toggled when it stops.

Type:
boolean
Default: false
Since: 3.0.0
Source: src/core/TimeStep.js (Line 63)
Focus
Focus
targetFps: number
Focus
Focus

Description:

The target fps rate for the Time Step to run at.

Setting this value will not actually change the speed at which the browser runs, that is beyond the control of Phaser. Instead, it allows you to determine performance issues and if the Time Step is spiraling out of control.

Type:
number
Default: 60
Since: 3.0.0
Source: src/core/TimeStep.js (Line 98)
Focus
Focus
time: number
Focus
Focus

Description:

The time, calculated at the start of the current step, as smoothed by the delta value.

Type:
number
Default: 0
Since: 3.0.0
Source: src/core/TimeStep.js (Line 190)
Focus
Focus

Methods

blur()
Focus
Focus

Description:

Called by the Game instance when the DOM window.onBlur event triggers.

Examples:
Since: 3.0.0
Source: src/core/TimeStep.js (Line 362)
Focus
Focus
destroy()
Focus
Focus

Description:

Destroys the TimeStep. This will stop Request Animation Frame, stop the step, clear the callbacks and null any objects.

Examples:
Since: 3.0.0
Source: src/core/TimeStep.js (Line 705)
Focus
Focus
focus()
Focus
Focus

Description:

Called by the Game instance when the DOM window.onFocus event triggers.

Examples:
Since: 3.0.0
Source: src/core/TimeStep.js (Line 373)
Focus
Focus
getDuration()
Focus
Focus

Description:

Gets the duration which the game has been running, in seconds.

Returns:
Description:

The duration in seconds.

Type:
  • number
Examples:
Since: 3.17.0
Source: src/core/TimeStep.js (Line 661)
Focus
Focus
getDurationMS()
Focus
Focus

Description:

Gets the duration which the game has been running, in ms.

Returns:
Description:

The duration in ms.

Type:
  • number
Examples:
Since: 3.17.0
Source: src/core/TimeStep.js (Line 674)
Focus
Focus
pause()
Focus
Focus

Description:

Called when the visibility API says the game is 'hidden' (tab switch out of view, etc)

Examples:
Since: 3.0.0
Source: src/core/TimeStep.js (Line 386)
Focus
Focus
resetDelta()
Focus
Focus

Description:

Resets the time, lastTime, fps averages and delta history. Called automatically when a browser sleeps them resumes.

Examples:
Since: 3.0.0
Source: src/core/TimeStep.js (Line 410)
Focus
Focus
resume()
Focus
Focus

Description:

Called when the visibility API says the game is 'visible' again (tab switch back into view, etc)

Examples:
Since: 3.0.0
Source: src/core/TimeStep.js (Line 397)
Focus
Focus
sleep()
Focus
Focus

Description:

Sends the TimeStep to sleep, stopping Request Animation Frame (or SetTimeout) and toggling the running flag to false.

Examples:
Since: 3.0.0
Source: src/core/TimeStep.js (Line 618)
Focus
Focus
start(callback)
Focus
Focus

Description:

Starts the Time Step running, if it is not already doing so. Called automatically by the Game Boot process.

Parameters:

name type description
callback Phaser.Types.Core.TimeStepCallback

The callback to be invoked each time the Time Step steps.

Examples:
Since: 3.0.0
Source: src/core/TimeStep.js (Line 439)
Focus
Focus
step()
Focus
Focus

Description:

The main step method. This is called each time the browser updates, either by Request Animation Frame, or by Set Timeout. It is responsible for calculating the delta values, frame totals, cool down history and more. You generally should never call this method directly.

Examples:
Since: 3.0.0
Source: src/core/TimeStep.js (Line 472)
Focus
Focus
stop()
Focus
Focus

Description:

Stops the TimeStep running.

Returns:
Description:

The TimeStep object.

Examples:
Since: 3.0.0
Source: src/core/TimeStep.js (Line 687)
Focus
Focus
tick()
Focus
Focus

Description:

Manually calls TimeStep.step.

Examples:
Since: 3.0.0
Source: src/core/TimeStep.js (Line 607)
Focus
Focus
wake([seamless])
Focus
Focus

Description:

Wakes-up the TimeStep, restarting Request Animation Frame (or SetTimeout) and toggling the running flag to true. The seamless argument controls if the wake-up should adjust the start time or not.

Parameters:

name type arguments Default description
seamless boolean <optional> false

Adjust the startTime based on the lastTime values.

Examples:
Since: 3.0.0
Source: src/core/TimeStep.js (Line 634)
Focus
Focus