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 . Scenes . ScenePlugin

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 . Scenes . ScenePlugin

A proxy class to the Global Scene Manager.

Constructor:

new ScenePlugin(scene)

Parameters:

name type description
scene Phaser.Scene

The Scene that this ScenePlugin belongs to.

Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 13)

Members

<private> _duration: number
Focus
Focus

Description:

Transition duration.

Type:
number
Since: 3.5.0
Source: src/scene/ScenePlugin.js (Line 105)
Focus
Focus
<private> _elapsed: number
Focus
Focus

Description:

Transition elapsed timer.

Type:
number
Since: 3.5.0
Source: src/scene/ScenePlugin.js (Line 85)
Focus
Focus
<private> _onUpdate: function
Focus
Focus

Description:

Transition callback.

Type:
function
Since: 3.5.0
Source: src/scene/ScenePlugin.js (Line 115)
Focus
Focus
<private> _onUpdateScope: object
Focus
Focus

Description:

Transition callback scope.

Type:
object
Since: 3.5.0
Source: src/scene/ScenePlugin.js (Line 125)
Focus
Focus
<private, nullable> _target: Phaser.Scenes.Scene
Focus
Focus

Description:

Transition elapsed timer.

Type:
Since: 3.5.0
Source: src/scene/ScenePlugin.js (Line 95)
Focus
Focus
<private> _willRemove: boolean
Focus
Focus

Description:

Will this Scene be removed from the Scene Manager after the transition completes?

Type:
boolean
Since: 3.5.0
Source: src/scene/ScenePlugin.js (Line 145)
Focus
Focus
<private> _willSleep: boolean
Focus
Focus

Description:

Will this Scene sleep (true) after the transition, or stop (false)

Type:
boolean
Since: 3.5.0
Source: src/scene/ScenePlugin.js (Line 135)
Focus
Focus
key: string
Focus
Focus

Description:

The key of the Scene this ScenePlugin belongs to.

Type:
string
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 57)
Focus
Focus

Description:

The Game's SceneManager.

Type:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 66)
Focus
Focus
scene: Phaser.Scene
Focus
Focus

Description:

The Scene that this ScenePlugin belongs to.

Type:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 30)
Focus
Focus

Description:

The settings of the Scene this ScenePlugin belongs to.

Type:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 48)
Focus
Focus

Description:

The Scene Systems instance of the Scene that this ScenePlugin belongs to.

Type:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 39)
Focus
Focus
transitionProgress: number
Focus
Focus

Description:

If this Scene is currently transitioning to another, this holds the current percentage of the transition progress, between 0 and 1.

Type:
number
Since: 3.5.0
Source: src/scene/ScenePlugin.js (Line 75)
Focus
Focus

Methods

add(key, sceneConfig, autoStart, [data])
Focus
Focus

Description:

Add the Scene into the Scene Manager and start it if 'autoStart' is true or the Scene config 'active' property is set.

Parameters:

name type arguments description
key string

The Scene key.

sceneConfig function | Phaser.Scene | Phaser.Types.Scenes.SettingsConfig | Phaser.Types.Scenes.CreateSceneFromObjectConfig

The config for the Scene.

autoStart boolean

Whether to start the Scene after it's added.

data object <optional>

Optional data object. This will be set as Scene.settings.data and passed to Scene.init.

Returns:
Description:

An instance of the Scene that was added to the Scene Manager.

Type:
Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 430)
Focus
Focus
<private> boot()
Focus
Focus

Description:

This method is called automatically, only once, when the Scene is first created. Do not invoke it directly.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 159)
Focus
Focus
bringToTop([key])
Focus
Focus

Description:

Brings a Scene to the top of the Scenes list.

This means it will render above all other Scenes.

Parameters:

name type arguments description
key string <optional>

The Scene to move.

Returns:
Description:

This ScenePlugin object.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 889)
Focus
Focus
<private> checkValidTransition(target)
Focus
Focus

Description:

Checks to see if this Scene can transition to the target Scene or not.

Parameters:

name type description
target Phaser.Scene

The Scene to test against.

Returns:
Description:

true if this Scene can transition, otherwise false.

Type:
  • boolean
Examples:
Since: 3.5.0
Source: src/scene/ScenePlugin.js (Line 336)
Focus
Focus
<private> destroy()
Focus
Focus

Description:

The Scene that owns this plugin is being destroyed. We need to shutdown and then kill off all external references.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 980)
Focus
Focus
get(key)
Focus
Focus

Description:

Retrieve a Scene.

Parameters:

name type description
key string

The Scene to retrieve.

Returns:
Description:

The Scene.

Type:
Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 931)
Focus
Focus
getIndex([key])
Focus
Focus

Description:

Retrieves the numeric index of a Scene in the Scenes list.

Parameters:

name type arguments description
key string | Phaser.Scene <optional>

The Scene to get the index of.

Returns:
Description:

The index of the Scene.

Type:
  • number
Examples:
Since: 3.7.0
Source: src/scene/ScenePlugin.js (Line 946)
Focus
Focus
isActive([key])
Focus
Focus

Description:

Checks if the given Scene is running or not?

Parameters:

name type arguments description
key string <optional>

The Scene to check.

Returns:
Description:

Whether the Scene is running.

Type:
  • boolean
Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 700)
Focus
Focus
isPaused([key])
Focus
Focus

Description:

Checks if the given Scene is paused or not?

Parameters:

name type arguments description
key string <optional>

The Scene to check.

Returns:
Description:

Whether the Scene is paused.

Type:
  • boolean
Examples:
Since: 3.17.0
Source: src/scene/ScenePlugin.js (Line 717)
Focus
Focus
isSleeping([key])
Focus
Focus

Description:

Checks if the given Scene is sleeping or not?

Parameters:

name type arguments description
key string <optional>

The Scene to check.

Returns:
Description:

Whether the Scene is sleeping.

Type:
  • boolean
Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 683)
Focus
Focus
isVisible([key])
Focus
Focus

Description:

Checks if the given Scene is visible or not?

Parameters:

name type arguments description
key string <optional>

The Scene to check.

Returns:
Description:

Whether the Scene is visible.

Type:
  • boolean
Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 734)
Focus
Focus
launch(key, [data])
Focus
Focus

Description:

Launch the given Scene and run it in parallel with this one.

This will happen at the next Scene Manager update, not immediately.

Parameters:

name type arguments description
key string

The Scene to launch.

data object <optional>

The Scene data.

Returns:
Description:

This ScenePlugin object.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 448)
Focus
Focus
moveAbove(keyA, [keyB])
Focus
Focus

Description:

Swaps the position of two scenes in the Scenes list, so that Scene B is directly above Scene A.

This controls the order in which they are rendered and updated.

Parameters:

name type arguments description
keyA string

The Scene that Scene B will be moved to be above.

keyB string <optional>

The Scene to be moved. If none is given it defaults to this Scene.

Returns:
Description:

This ScenePlugin object.

Examples:
Since: 3.2.0
Source: src/scene/ScenePlugin.js (Line 776)
Focus
Focus
moveBelow(keyA, [keyB])
Focus
Focus

Description:

Swaps the position of two scenes in the Scenes list, so that Scene B is directly below Scene A.

This controls the order in which they are rendered and updated.

Parameters:

name type arguments description
keyA string

The Scene that Scene B will be moved to be below.

keyB string <optional>

The Scene to be moved. If none is given it defaults to this Scene.

Returns:
Description:

This ScenePlugin object.

Examples:
Since: 3.2.0
Source: src/scene/ScenePlugin.js (Line 801)
Focus
Focus
moveDown([key])
Focus
Focus

Description:

Moves a Scene down one position in the Scenes list.

Parameters:

name type arguments description
key string <optional>

The Scene to move.

Returns:
Description:

This ScenePlugin object.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 870)
Focus
Focus
moveUp([key])
Focus
Focus

Description:

Moves a Scene up one position in the Scenes list.

Parameters:

name type arguments description
key string <optional>

The Scene to move.

Returns:
Description:

This ScenePlugin object.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 851)
Focus
Focus
pause([key], [data])
Focus
Focus

Description:

Pause the Scene - this stops the update step from happening but it still renders.

This will happen at the next Scene Manager update, not immediately.

Parameters:

name type arguments description
key string <optional>

The Scene to pause.

data object <optional>

An optional data object that will be passed to the Scene and emitted in its pause event.

Returns:
Description:

This ScenePlugin object.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 500)
Focus
Focus
<private> pluginStart()
Focus
Focus

Description:

This method is called automatically by the Scene when it is starting up. It is responsible for creating local systems, properties and listening for Scene events. Do not invoke it directly.

Examples:
Since: 3.5.0
Source: src/scene/ScenePlugin.js (Line 172)
Focus
Focus
remove([key])
Focus
Focus

Description:

Removes a Scene from the SceneManager.

The Scene is removed from the local scenes array, it's key is cleared from the keys cache and Scene.Systems.destroy is then called on it.

If the SceneManager is processing the Scenes when this method is called it will queue the operation for the next update sequence.

Parameters:

name type arguments description
key string | Phaser.Scene <optional>

The Scene to be removed.

Returns:
Description:

This SceneManager.

Examples:
Since: 3.2.0
Source: src/scene/ScenePlugin.js (Line 826)
Focus
Focus
restart([data])
Focus
Focus

Description:

Restarts this Scene.

This will happen at the next Scene Manager update, not immediately.

Parameters:

name type arguments description
data object <optional>

The Scene data.

Returns:
Description:

This ScenePlugin object.

Examples:
Since: 3.4.0
Source: src/scene/ScenePlugin.js (Line 211)
Focus
Focus
resume([key], [data])
Focus
Focus

Description:

Resume the Scene - starts the update loop again.

This will happen at the next Scene Manager update, not immediately.

Parameters:

name type arguments description
key string <optional>

The Scene to resume.

data object <optional>

An optional data object that will be passed to the Scene and emitted in its resume event.

Returns:
Description:

This ScenePlugin object.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 522)
Focus
Focus
run(key, [data])
Focus
Focus

Description:

Runs the given Scene, but does not change the state of this Scene.

This will happen at the next Scene Manager update, not immediately.

If the given Scene is paused, it will resume it. If sleeping, it will wake it. If not running at all, it will be started.

Use this if you wish to open a modal Scene by calling pause on the current Scene, then run on the modal Scene.

Parameters:

name type arguments description
key string

The Scene to run.

data object <optional>

A data object that will be passed to the Scene and emitted in its ready, wake, or resume events.

Returns:
Description:

This ScenePlugin object.

Examples:
Since: 3.10.0
Source: src/scene/ScenePlugin.js (Line 471)
Focus
Focus
sendToBack([key])
Focus
Focus

Description:

Sends a Scene to the back of the Scenes list.

This means it will render below all other Scenes.

Parameters:

name type arguments description
key string <optional>

The Scene to move.

Returns:
Description:

This ScenePlugin object.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 910)
Focus
Focus
setActive(value, [key], [data])
Focus
Focus

Description:

Sets the active state of the given Scene.

Parameters:

name type arguments description
value boolean

If true the Scene will be resumed. If false it will be paused.

key string <optional>

The Scene to set the active state of.

data object <optional>

An optional data object that will be passed to the Scene and emitted with its events.

Returns:
Description:

This ScenePlugin object.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 632)
Focus
Focus
setVisible(value, [key])
Focus
Focus

Description:

Sets the visible state of the given Scene.

Parameters:

name type arguments description
value boolean

The visible value.

key string <optional>

The Scene to set the visible state for.

Returns:
Description:

This ScenePlugin object.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 658)
Focus
Focus
<private> shutdown()
Focus
Focus

Description:

The Scene that owns this plugin is shutting down. We need to kill and reset all internal properties as well as stop listening to Scene events.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 963)
Focus
Focus
sleep([key], [data])
Focus
Focus

Description:

Makes the Scene sleep (no update, no render) but doesn't shutdown.

This will happen at the next Scene Manager update, not immediately.

Parameters:

name type arguments description
key string <optional>

The Scene to put to sleep.

data object <optional>

An optional data object that will be passed to the Scene and emitted in its sleep event.

Returns:
Description:

This ScenePlugin object.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 544)
Focus
Focus
start([key], [data])
Focus
Focus

Description:

Shutdown this Scene and run the given one.

This will happen at the next Scene Manager update, not immediately.

Parameters:

name type arguments description
key string <optional>

The Scene to start.

data object <optional>

The Scene data.

Returns:
Description:

This ScenePlugin object.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 188)
Focus
Focus
<private> step(time, delta)
Focus
Focus

Description:

A single game step. This is only called if the parent Scene is transitioning out to another Scene.

Parameters:

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

Examples:
Since: 3.5.0
Source: src/scene/ScenePlugin.js (Line 358)
Focus
Focus
stop([key], [data])
Focus
Focus

Description:

Shutdown the Scene, clearing display list, timers, etc.

This happens at the next Scene Manager update, not immediately.

Parameters:

name type arguments description
key string <optional>

The Scene to stop.

data any <optional>

Optional data object to pass to Scene.Systems.shutdown.

Returns:
Description:

This ScenePlugin object.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 610)
Focus
Focus
swapPosition(keyA, [keyB])
Focus
Focus

Description:

Swaps the position of two scenes in the Scenes list.

This controls the order in which they are rendered and updated.

Parameters:

name type arguments description
keyA string

The first Scene to swap.

keyB string <optional>

The second Scene to swap. If none is given it defaults to this Scene.

Returns:
Description:

This ScenePlugin object.

Examples:
Since: 3.2.0
Source: src/scene/ScenePlugin.js (Line 751)
Focus
Focus
switch(key)
Focus
Focus

Description:

Makes this Scene sleep then starts the Scene given.

This will happen at the next Scene Manager update, not immediately.

Parameters:

name type description
key string

The Scene to start.

Returns:
Description:

This ScenePlugin object.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 588)
Focus
Focus
transition(config)
Focus
Focus

Description:

This will start a transition from the current Scene to the target Scene given.

The transition will last for the duration specified in milliseconds.

You can have the target Scene moved above or below this one in the display list.

You can specify an update callback. This callback will be invoked every frame for the duration of the transition.

This Scene can either be sent to sleep at the end of the transition, or stopped. The default is to stop.

There are also 5 transition related events: This scene will emit the event transitionout when the transition begins, which is typically the frame after calling this method.

The target Scene will emit the event transitioninit when that Scene's init method is called. It will then emit the event transitionstart when its create method is called. If the Scene was sleeping and has been woken up, it will emit the event transitionwake instead of these two, as the Scenes init and create methods are not invoked when a Scene wakes up.

When the duration of the transition has elapsed it will emit the event transitioncomplete. These events are cleared of all listeners when the Scene shuts down, but not if it is sent to sleep.

It's important to understand that the duration of the transition begins the moment you call this method. If the Scene you are transitioning to includes delayed processes, such as waiting for files to load, the time still counts down even while that is happening. If the game itself pauses, or something else causes this Scenes update loop to stop, then the transition will also pause for that duration. There are checks in place to prevent you accidentally stopping a transitioning Scene but if you've got code to override this understand that until the target Scene completes it might never be unlocked for input events.

Parameters:

name type description
config Phaser.Types.Scenes.SceneTransitionConfig

The transition configuration object.

Returns:
Description:

true is the transition was started, otherwise false.

Type:
  • boolean
Examples:
Since: 3.5.0
Source: src/scene/ScenePlugin.js (Line 233)
Focus
Focus
<private> transitionComplete()
Focus
Focus

Description:

Called by step when the transition out of this scene to another is over.

Examples:
Since: 3.5.0
Source: src/scene/ScenePlugin.js (Line 386)
Focus
Focus
wake([key], [data])
Focus
Focus

Description:

Makes the Scene wake-up (starts update and render)

This will happen at the next Scene Manager update, not immediately.

Parameters:

name type arguments description
key string <optional>

The Scene to wake up.

data object <optional>

An optional data object that will be passed to the Scene and emitted in its wake event.

Returns:
Description:

This ScenePlugin object.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 566)
Focus
Focus