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

The Scene Plugin is the main interface to the Scene Manager and allows you to control any Scene running in your game. You should always use this plugin. By default, it is mapped to the Scene property this.scene. Meaning, from within a Scene, you can call methods such as this.scene.start().

Note that nearly all methods in this class are run on a queue-basis and not immediately. For example, calling this.scene.launch('SceneB') will try to launch SceneB when the Scene Manager next updates, which is at the start of the game step. All operations are queued and run in the order in which they are invoked here.

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 113)
Focus
Focus
<private> _elapsed: number
Focus
Focus

Description:

Transition elapsed timer.

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

Description:

Transition callback.

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

Description:

Transition callback scope.

Type:
object
Since: 3.5.0
Source: src/scene/ScenePlugin.js (Line 133)
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 103)
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 153)
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 143)
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 65)
Focus
Focus

Description:

The Game's SceneManager.

Type:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 74)
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 38)
Focus
Focus

Description:

The settings of the Scene this ScenePlugin belongs to.

Type:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 56)
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 47)
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 83)
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 Default description
key string

A unique key used to reference the Scene, i.e. MainMenu or Level1.

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

The config for the Scene

autoStart boolean <optional> false

If true the Scene will be started immediately after being added.

data object <optional>

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

Returns:
Description:

The added Scene, if it was added immediately, otherwise null.

Type:
Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 438)
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 167)
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 | Phaser.Scene <optional>

The Scene to move.

Returns:
Description:

This Scene Plugin instance.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 897)
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 344)
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 989)
Focus
Focus
get(key)
Focus
Focus

Description:

Retrieve a Scene.

Parameters:

name type description
key string | Phaser.Scene

The Scene to retrieve.

Returns:
Description:

The Scene.

Type:
Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 939)
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 954)
Focus
Focus
isActive([key])
Focus
Focus

Description:

Checks if the given Scene is running or not?

Parameters:

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

The Scene to check.

Returns:
Description:

Whether the Scene is running, or null if no matching Scene was found.

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

Description:

Checks if the given Scene is paused or not?

Parameters:

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

The Scene to check.

Returns:
Description:

Whether the Scene is paused, or null if no matching Scene was found.

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

Description:

Checks if the given Scene is sleeping or not?

Parameters:

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

The Scene to check.

Returns:
Description:

Whether the Scene is sleeping, or null if no matching Scene was found.

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

Description:

Checks if the given Scene is visible or not?

Parameters:

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

The Scene to check.

Returns:
Description:

Whether the Scene is visible, or null if no matching Scene was found.

Type:
  • boolean
Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 742)
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 | Phaser.Scene

The Scene to launch.

data object <optional>

The Scene data.

Returns:
Description:

This Scene Plugin instance.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 456)
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 | Phaser.Scene

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

keyB string | Phaser.Scene <optional>

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

Returns:
Description:

This Scene Plugin instance.

Examples:
Since: 3.2.0
Source: src/scene/ScenePlugin.js (Line 784)
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 | Phaser.Scene

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

keyB string | Phaser.Scene <optional>

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

Returns:
Description:

This Scene Plugin instance.

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

Description:

Moves a Scene down one position in the Scenes list.

Parameters:

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

The Scene to move.

Returns:
Description:

This Scene Plugin instance.

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

Description:

Moves a Scene up one position in the Scenes list.

Parameters:

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

The Scene to move.

Returns:
Description:

This Scene Plugin instance.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 859)
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 | Phaser.Scene <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 Scene Plugin instance.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 508)
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 180)
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 Scene Plugin instance.

Examples:
Since: 3.2.0
Source: src/scene/ScenePlugin.js (Line 834)
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 Scene Plugin instance.

Examples:
Since: 3.4.0
Source: src/scene/ScenePlugin.js (Line 219)
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 | Phaser.Scene <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 Scene Plugin instance.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 530)
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 | Phaser.Scene

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 Scene Plugin instance.

Examples:
Since: 3.10.0
Source: src/scene/ScenePlugin.js (Line 479)
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 | Phaser.Scene <optional>

The Scene to move.

Returns:
Description:

This Scene Plugin instance.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 918)
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 | Phaser.Scene <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 Scene Plugin instance.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 640)
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 | Phaser.Scene <optional>

The Scene to set the visible state for.

Returns:
Description:

This Scene Plugin instance.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 666)
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 971)
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 | Phaser.Scene <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 Scene Plugin instance.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 552)
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 | Phaser.Scene <optional>

The Scene to start.

data object <optional>

The Scene data.

Returns:
Description:

This Scene Plugin instance.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 196)
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 366)
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 | Phaser.Scene <optional>

The Scene to stop.

data any <optional>

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

Returns:
Description:

This Scene Plugin instance.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 618)
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 | Phaser.Scene

The first Scene to swap.

keyB string | Phaser.Scene <optional>

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

Returns:
Description:

This Scene Plugin instance.

Examples:
Since: 3.2.0
Source: src/scene/ScenePlugin.js (Line 759)
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 | Phaser.Scene

The Scene to start.

Returns:
Description:

This Scene Plugin instance.

Examples:
Since: 3.0.0
Source: src/scene/ScenePlugin.js (Line 596)
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 241)
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 394)
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 | Phaser.Scene <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 Scene Plugin instance.

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