Class PixelPerfectPlugin

Per-scene Phaser plugin and the public entry point for the library inside a Phaser game.

Register the plugin once at game creation:

import * as Phaser from 'phaser';
import { PixelPerfectPlugin } from 'pixel-perfect';

const game = new Phaser.Game({
    // ...
    plugins: {
        scene: [
            {
                key: 'PixelPerfectPlugin',
                plugin: PixelPerfectPlugin,
                mapping: 'pixelPerfect',
            },
        ],
    },
});

After registration, scene.pixelPerfect.terrain(options) is available inside any scene the plugin is mapped into. The factory supplies the scene to DestructibleTerrain automatically and registers the returned terrain for automatic update: the plugin subscribes to the scene's POST_UPDATE event and calls terrain.update() on every terrain it owns. Users do not need to wire the per-frame flush themselves.

Lifecycle: terrain bodies/render layers created via this plugin are destroyed when the scene shuts down or the scene is destroyed. User-spawned dynamic bodies (debris, balls, etc.) are not the plugin's responsibility — the caller still owns those, same as before.

Phaser-side type augmentation is included in this module so that scene.pixelPerfect is typed correctly without each downstream consumer having to write their own declare global block. Importing this file from anywhere in the project is enough.

Hierarchy

  • ScenePlugin
    • PixelPerfectPlugin

Constructors

constructor

Properties

game pluginKey pluginManager scene systems

Methods

boot destroy destroyTerrain init sprite start stop terrain

Constructors

constructor

  • new PixelPerfectPlugin(scene, pluginManager, pluginKey): PixelPerfectPlugin

  • Parameters

    • scene: Scene

      A reference to the Scene that has installed this plugin.

    • pluginManager: PluginManager

      A reference to the Plugin Manager.

    • pluginKey: string

      The key under which this plugin has been installed into the Scene Systems.

    Returns PixelPerfectPlugin

Properties

Protectedgame

game: Game

A reference to the Game instance this plugin is running under.

ReadonlypluginKey

pluginKey: string

The key under which this plugin was installed into the Scene Systems.

This property is only set when the plugin is instantiated and added to the Scene, not before. You can use it during the boot method.

ProtectedpluginManager

pluginManager: PluginManager

A handy reference to the Plugin Manager that is responsible for this plugin. Can be used as a route to gain access to game systems and events.

Protectedscene

scene: null | Scene

A reference to the Scene that has installed this plugin. Only set if it's a Scene Plugin, otherwise null. This property is only set when the plugin is instantiated and added to the Scene, not before. You can use it during the boot method.

Protectedsystems

systems: null | Systems

A reference to the Scene Systems of the Scene that has installed this plugin. Only set if it's a Scene Plugin, otherwise null. This property is only set when the plugin is instantiated and added to the Scene, not before. You can use it during the boot method.

Methods

boot

  • boot(): void

  • Called once when the scene boots. Wires up the auto-update and shutdown handlers; users should not need to override or invoke this directly.

    Returns void

destroy

  • destroy(): void

  • Destroys this plugin and releases all references it holds, including the Scene, Scene Systems, and Plugin Manager. This method is called automatically when the Scene is destroyed.

    If you extend this class you should override this method, clean up any resources your plugin has created, and then call BasePlugin.destroy via super.destroy() or the prototype chain.

    Returns void

destroyTerrain

  • destroyTerrain(terrain): void

  • Removes a terrain from the plugin's auto-update set and destroys it. Callers can also let scene shutdown handle cleanup, which destroys every tracked terrain in one pass.

    Parameters

    Returns void

init

  • init(data?): void

  • The PluginManager calls this method on a Global Plugin when the plugin is first instantiated. It will never be called again on this instance. In here you can set-up whatever you need for this plugin to run. If a plugin is set to automatically start then BasePlugin.start will be called immediately after this. On a Scene Plugin, this method is never called. Use Phaser.Plugins.ScenePlugin#boot instead.

    Parameters

    • Optionaldata: any

      A value specified by the user, if any, from the data property of the plugin's configuration object (if started at game boot) or passed in the PluginManager's install method (if started manually).

    Returns void

sprite

  • sprite(x, y, textureKey, frame?): PixelPerfectSprite

  • Creates an alpha-aware PixelPerfectSprite attached to this scene's display list. Same arguments as the Phaser Sprite constructor minus the scene (which is supplied automatically). Sprites are not tracked for auto-destroy by the plugin — Phaser's regular GameObject lifecycle handles that on scene shutdown.

    Parameters

    • x: number
    • y: number
    • textureKey: string
    • Optionalframe: string | number

    Returns PixelPerfectSprite

start

  • start(): void

  • The PluginManager calls this method on a Global Plugin when the plugin is started. If a plugin is stopped, and then started again, this will get called again. Typically called immediately after BasePlugin.init. On a Scene Plugin, this method is never called.

    Returns void

stop

  • stop(): void

  • The PluginManager calls this method on a Global Plugin when the plugin is stopped. The game code has requested that your plugin stop doing whatever it does. It is now considered as 'inactive' by the PluginManager. Handle that process here (i.e. stop listening for events, etc) If the plugin is started again then BasePlugin.start will be called again. On a Scene Plugin, this method is never called.

    Returns void

terrain

  • terrain(options): DestructibleTerrain

  • Creates a destructible terrain for this scene.

    Same options as new DestructibleTerrain({ scene, ...options }) but scene is supplied automatically. The returned terrain is tracked by the plugin and update() is called on it once per frame at POST_UPDATE. Callers can still call update() manually if they need a flush at a different time.

    Parameters

    Returns DestructibleTerrain

Settings

Member Visibility

On This Page

Constructors
Properties
Methods