Phaser API Documentation

  Version: 
Filter

The PluginManager is responsible for installing and adding plugins to Phaser.

It is a global system and therefore belongs to the Game instance, not a specific Scene.

It works in conjunction with the PluginCache. Core internal plugins automatically register themselves with the Cache, but it's the Plugin Manager that is responsible for injecting them into the Scenes.

There are two types of plugin:

  1. A Global Plugin
  2. A Scene Plugin

A Global Plugin is a plugin that lives within the Plugin Manager rather than a Scene. You can get access to it by calling PluginManager.get and providing a key. Any Scene that requests a plugin in this way will all get access to the same plugin instance, allowing you to use a single plugin across multiple Scenes.

A Scene Plugin is a plugin dedicated to running within a Scene. These are different to Global Plugins in that their instances do not live within the Plugin Manager, but within the Scene Systems class instead. And that every Scene created is given its own unique instance of a Scene Plugin. Examples of core Scene Plugins include the Input Plugin, the Tween Plugin and the physics Plugins.

You can add a plugin to Phaser in three different ways:

  1. Preload it
  2. Include it in your source code and install it via the Game Config
  3. Include it in your source code and install it within a Scene

For examples of all of these approaches please see the Phaser 3 Examples Repo plugins folder.

For information on creating your own plugin please see the Phaser 3 Plugin Template.

Constructor:

new PluginManager(game)

Parameters:

name type description
game Phaser.Game

The game instance that owns this Plugin Manager.

Since: 3.0.0

Members

<private> _pendingGlobal: array
Focus
Focus

Description:

A temporary list of plugins to install when the game has booted.

Type:
array
Since: 3.8.0
Focus
Focus
<private> _pendingScene: array
Focus
Focus

Description:

A temporary list of scene plugins to install when the game has booted.

Type:
array
Since: 3.8.0
Focus
Focus
game: Phaser.Game
Focus
Focus

Description:

The game instance that owns this Plugin Manager.

Type:
Since: 3.0.0
Focus
Focus

Description:

The global plugins currently running and managed by this Plugin Manager. A plugin must have been started at least once in order to appear in this list.

Type:
Since: 3.8.0
Focus
Focus
scenePlugins: Array.<string>
Focus
Focus

Description:

A list of plugin keys that should be installed into Scenes as well as the Core Plugins.

Type:
Array.<string>
Since: 3.8.0
Focus
Focus

Methods

<protected> addToScene(sys, globalPlugins, scenePlugins)
Focus
Focus

Description:

Called by the Scene Systems class. Tells the plugin manager to install all Scene plugins into it.

First it will install global references, i.e. references from the Game systems into the Scene Systems (and Scene if mapped.) Then it will install Core Scene Plugins followed by Scene Plugins registered with the PluginManager. Finally it will install any references to Global Plugins that have a Scene mapping property into the Scene itself.

Parameters:

name type description
sys Phaser.Scenes.Systems

The Scene Systems class to install all the plugins in to.

globalPlugins array

An array of global plugins to install.

scenePlugins array

An array of scene plugins to install.

Since: 3.8.0
Focus
Focus
<protected> boot()
Focus
Focus

Description:

Run once the game has booted and installs all of the plugins configured in the Game Config.

Since: 3.0.0
Focus
Focus
<private> createEntry(key, [runAs])
Focus
Focus

Description:

Creates a new instance of a global plugin, adds an entry into the plugins array and returns it.

Parameters:

name type arguments description
key string

The key of the plugin to create an instance of.

runAs string <optional>

Run the plugin under a new key. This allows you to run one plugin multiple times.

Returns:
Description:

The plugin that was started, or null if invalid key given.

Since: 3.9.0
Focus
Focus
destroy()
Focus
Focus

Description:

Destroys this Plugin Manager and all associated plugins. It will iterate all plugins found and call their destroy methods.

The PluginCache will remove all custom plugins.

Since: 3.8.0
Focus
Focus
get(key, [autoStart])
Focus
Focus

Description:

Gets a global plugin from the Plugin Manager based on the given key and returns it.

If it cannot find an active plugin based on the key, but there is one in the Plugin Cache with the same key, then it will create a new instance of the cached plugin and return that.

Parameters:

name type arguments Default description
key string

The key of the plugin to get.

autoStart boolean <optional> true

Automatically start a new instance of the plugin if found in the cache, but not actively running.

Returns:
Description:

The plugin, or null if no plugin was found matching the key.

Type:
Since: 3.8.0
Focus
Focus
getClass(key)
Focus
Focus

Description:

Returns the plugin class from the cache. Used internally by the Plugin Manager.

Parameters:

name type description
key string

The key of the plugin to get.

Returns:
Description:

A Plugin object

Since: 3.8.0
Focus
Focus
<protected> getDefaultScenePlugins()
Focus
Focus

Description:

Called by the Scene Systems class. Returns a list of plugins to be installed.

Returns:
Description:

A list keys of all the Scene Plugins to install.

Type:
  • Array.<string>
Since: 3.8.0
Focus
Focus
<protected> getEntry(key)
Focus
Focus

Description:

Gets a global plugin based on the given key.

Parameters:

name type description
key string

The unique plugin key.

Returns:
Description:

The plugin entry.

Since: 3.8.0
Focus
Focus
<protected> getIndex(key)
Focus
Focus

Description:

Gets an index of a global plugin based on the given key.

Parameters:

name type description
key string

The unique plugin key.

Returns:
Description:

The index of the plugin within the plugins array.

Type:
  • number
Since: 3.8.0
Focus
Focus
install(key, plugin, [start], [mapping], [data])
Focus
Focus

Description:

Installs a new Global Plugin into the Plugin Manager and optionally starts it running. A global plugin belongs to the Plugin Manager, rather than a specific Scene, and can be accessed and used by all Scenes in your game.

The key property is what you use to access this plugin from the Plugin Manager.

this.plugins.install('powerupsPlugin', pluginCode);

// and from within the scene:
this.plugins.get('powerupsPlugin');

This method is called automatically by Phaser if you install your plugins using either the Game Configuration object, or by preloading them via the Loader.

The same plugin can be installed multiple times into the Plugin Manager by simply giving each instance its own unique key.

Parameters:

name type arguments Default description
key string

The unique handle given to this plugin within the Plugin Manager.

plugin function

The plugin code. This should be the non-instantiated version.

start boolean <optional> false

Automatically start the plugin running? This is always true if you provide a mapping value.

mapping string <optional>

If this plugin is injected into the Phaser.Scene class, this is the property key to use.

data any <optional>

A value passed to the plugin's init method.

Returns:
Description:

The plugin that was started, or null if start was false, or game isn't yet booted.

Since: 3.8.0
Focus
Focus
installScenePlugin(key, plugin, [mapping], [addToScene], [fromLoader])
Focus
Focus

Description:

Installs a new Scene Plugin into the Plugin Manager and optionally adds it to the given Scene as well. A Scene Plugin added to the manager in this way will be automatically installed into all new Scenes using the key and mapping given.

The key property is what the plugin is injected into Scene.Systems as. The mapping property is optional, and if specified is what the plugin is installed into the Scene as. For example:

this.plugins.installScenePlugin('powerupsPlugin', pluginCode, 'powerups');

// and from within the scene:
this.sys.powerupsPlugin; // key value
this.powerups; // mapping value

This method is called automatically by Phaser if you install your plugins using either the Game Configuration object, or by preloading them via the Loader.

Parameters:

name type arguments Default description
key string

The property key that will be used to add this plugin to Scene.Systems.

plugin function

The plugin code. This should be the non-instantiated version.

mapping string <optional>

If this plugin is injected into the Phaser.Scene class, this is the property key to use.

addToScene Phaser.Scene <optional>

Optionally automatically add this plugin to the given Scene.

fromLoader boolean <optional> false

Is this being called by the Loader?

Since: 3.8.0
Focus
Focus
isActive(key)
Focus
Focus

Description:

Checks if the given global plugin, based on its key, is active or not.

Parameters:

name type description
key string

The unique plugin key.

Returns:
Description:

true if the plugin is active, otherwise false.

Type:
  • boolean
Since: 3.8.0
Focus
Focus
registerFileType(key, callback, [addToScene])
Focus
Focus

Description:

Registers a new file type with the global File Types Manager, making it available to all Loader Plugins created after this.

This is usually called from within your Plugin code and is a helpful short-cut for creating new loader file types.

The key is the property that will be injected into the Loader Plugin and used to load the files. For example:

this.plugins.registerFileType('wad', doomWadLoaderCallback);
// later in your preload code:
this.load.wad();

The callback is what is called when the loader tries to load a file matching the given key. It's important to understand that the callback is invoked within the context of the LoaderPlugin. In this context there are several properties / methods available to use:

this.addFile - A method to add the new file to the load queue. this.scene - The Scene that owns the Loader Plugin instance.

See the LoaderPlugin class for more details. Any public property or method listed is available from your callback under this.

Parameters:

name type arguments description
key string

The key of the Game Object that the given callbacks will create, i.e. image, sprite.

callback function

The callback to invoke when the Game Object Factory is called.

addToScene Phaser.Scene <optional>

Optionally add this file type into the Loader Plugin owned by the given Scene.

Since: 3.8.0
Focus
Focus
registerGameObject(key, [factoryCallback], [creatorCallback])
Focus
Focus

Description:

Registers a new type of Game Object with the global Game Object Factory and / or Creator. This is usually called from within your Plugin code and is a helpful short-cut for creating new Game Objects.

The key is the property that will be injected into the factories and used to create the Game Object. For example:

this.plugins.registerGameObject('clown', clownFactoryCallback, clownCreatorCallback);
// later in your game code:
this.add.clown();
this.make.clown();

The callbacks are what are called when the factories try to create a Game Object matching the given key. It's important to understand that the callbacks are invoked within the context of the GameObjectFactory. In this context there are several properties available to use:

this.scene - A reference to the Scene that owns the GameObjectFactory. this.displayList - A reference to the Display List the Scene owns. this.updateList - A reference to the Update List the Scene owns.

See the GameObjectFactory and GameObjectCreator classes for more details. Any public property or method listed is available from your callbacks under this.

Parameters:

name type arguments description
key string

The key of the Game Object that the given callbacks will create, i.e. image, sprite.

factoryCallback function <optional>

The callback to invoke when the Game Object Factory is called.

creatorCallback function <optional>

The callback to invoke when the Game Object Creator is called.

Since: 3.8.0
Focus
Focus
removeGameObject(key, [removeFromFactory], [removeFromCreator])
Focus
Focus

Description:

Removes a previously registered Game Object from the global Game Object Factory and / or Creator. This is usually called from within your Plugin destruction code to help clean-up after your plugin has been removed.

Parameters:

name type arguments Default description
key string

The key of the Game Object to be removed from the factories.

removeFromFactory boolean <optional> true

Should the Game Object be removed from the Game Object Factory?

removeFromCreator boolean <optional> true

Should the Game Object be removed from the Game Object Creator?

Since: 3.19.0
Focus
Focus
removeGlobalPlugin(key)
Focus
Focus

Description:

Removes a global plugin from the Plugin Manager and Plugin Cache.

It is up to you to remove all references to this plugin that you may hold within your game code.

Parameters:

name type description
key string

The key of the plugin to remove.

Since: 3.8.0
Focus
Focus
removeScenePlugin(key)
Focus
Focus

Description:

Removes a scene plugin from the Plugin Manager and Plugin Cache.

This will not remove the plugin from any active Scenes that are already using it.

It is up to you to remove all references to this plugin that you may hold within your game code.

Parameters:

name type description
key string

The key of the plugin to remove.

Since: 3.8.0
Focus
Focus
start(key, [runAs])
Focus
Focus

Description:

Starts a global plugin running.

If the plugin was previously active then calling start will reset it to an active state and then call its start method.

If the plugin has never been run before a new instance of it will be created within the Plugin Manager, its active state set and then both of its init and start methods called, in that order.

If the plugin is already running under the given key then nothing happens.

Parameters:

name type arguments description
key string

The key of the plugin to start.

runAs string <optional>

Run the plugin under a new key. This allows you to run one plugin multiple times.

Returns:
Description:

The plugin that was started, or null if invalid key given or plugin is already stopped.

Since: 3.8.0
Focus
Focus
stop(key)
Focus
Focus

Description:

Stops a global plugin from running.

If the plugin is active then its active state will be set to false and the plugins stop method will be called.

If the plugin is not already running, nothing will happen.

Parameters:

name type description
key string

The key of the plugin to stop.

Returns:
Description:

The Plugin Manager.

Since: 3.8.0
Focus
Focus