phaser3-transitions

A UI transitions plugin for Phaser 3. This plugin essentialy provides a simple wrapper for some complex tweens that move UI components into and out of the scene. Each transition can also be used declaratively if you prefer not to pollute your scene with excessive plugins.

• Features
• Install and Setup
• Examples
• Plugin API
• Transition Classes
  • BaseTransition
  • FadeTransition
  • SlideTransition
  • GrowTransition
  • ExplodeTransition
  • SlideFadeTransition
• Using Declaratively
• Custom Transitions

Features

• Smooth transitions for moving UI components on and off the screen
• Simple config options for light customization
• Abstracts away repetitive and/or complex tweens
• Easily extensible via the BaseTransition class

Install

npm install --save phaser3-transitions

Setup

import Phaser from 'phaser';
import TransitionsPlugin from 'phaser3-transitions';

const gameConfig = {
    type: Phaser.WEBGL,
    parent: 'game-container',
    width: 400,
    height: 600,
    scene: [
        Preload,
        DemoScene
    ],
    plugins: {
        scene: [
            { 
                key: 'transitions', 
                mapping: 'transitions',
                plugin: TransitionsPlugin
            }
        ]
    },
};

const game = new Phaser.Game(gameConfig);

Examples

---

Slide in from the left, slide out to the bottom.

import TransitionsPlugin 'phaser3-transitions';

//In your create() function
function create(){
	
    //The transition will return the sprites to their original positions
    let sprite1 = this.add.sprite(100, 100, 'menuItem');
    let sprite2 = this.add.sprite(100, 200, 'menuItem');
    let sprite3 = this.add.sprite(100, 300, 'menuItem');
	let sprites = [sprite1, sprite2, sprite3]; //etc.
    
    let config = {
    	type: 'slide',
        duration: 500,
   		enterFrom: 'left',
        exitTo: 'bottom'
    }

	let slide = this.transitions.create(sprites, config);
    
    //This will slide all the objects in and then immediately exit
   	slide.enter().then(() => {
    	slide.exit();
    });
    
}

---

Fade into place, fade AND slide out to the top.

import TransitionsPlugin 'phaser3-transitions';

//In your create() function
function create(){
	
    //The transition will return the sprites to their original positions
    let sprite1 = this.add.sprite(100, 100, 'menuItem');
    let sprite2 = this.add.sprite(100, 200, 'menuItem');
    let sprite3 = this.add.sprite(100, 300, 'menuItem');
	let sprites = [sprite1, sprite2, sprite3]; //etc.
    
    let enterConfig = {
    	type: 'Fade', //not case sensitive
    }
    
    let exitConfig = {
    	type: 'FadeSlide',
        exitTo: 'top'
    }

	let enterTransitions = this.transitions.create(sprites, enterConfig);
    let exitTransition = this.transitions.create(sprites, exitConfig);
    
    //This will fade all the objects in and then immediately exit
   	enterTransition.enter().then(() => {
    	exitTransition.exit();
    });
    
}

Plugin API

TransitionsPlugin

The TransitionsPlugin is a factory class which creates transitions for you. Each transition extends the BaseTransition class and is essentially a wrapper over top of a (sometimes) complex tween. This plugin also has some ease-of-use methods for quick transitions when your transition are simple.

• Methods:
  • register(key, transitionClass)
  • create(targets, config) ⇒ BaseTransition
  • enter(targets, config) ⇒ Promise
  • exit(targets, config) ⇒ Promise

transitions.register(key, transitionClass)

Adds a transition class to the plugin's dictionary. A transition class must extend BaseTransition and be registered if it is not already one of the default classes.

Param	Type	Description
key	String	The key by which the transition can be referenced
transitionClass	BaseTransition	A class which extends the BaseTransition class

transitions.create(targets, config) ⇒ BaseTransition

Creates a new transition based on the given config

Returns: BaseTransition - - A transition class extending BaseTransition

Param	Type	Description
targets	Array	The targets for this transition. These cannot be changed once the transition is created.
config	Object	Settings for the transition
config.type	String	A key to one of the default transitions, which currently includes any of the following: "Fade", "Slide", "Grow", "Explode", or "FadeSlide". See the class descriptions for more info about each transition.

transitions.enter(targets, config) ⇒ Promise

Creates and starts a new enter transition

Returns: Promise - - Returns a promise which resolves when the transition is complete

Param	Type	Description
targets	Array	The GameObject targets to transition
config	Object	Settings for the transition. Must contain a transition-type key, but can also contain other config settings for the given transition type.
config.type	String	The transition key

transitions.exit(targets, config) ⇒ Promise

Creates and starts a new exit transition

Returns: Promise - - Returns a promise which resolves when the transition is complete

Param	Type	Description
targets	Array	The GameObject targets to transition
config	Object	Settings for the transition. Must contain a transition-type key, but can also contain other config settings for the given transition type.
config.type	String	The transition key

---

Transition Classes

BaseTransition

The BaseTransition class implements the tweens defined in it's child classes. This class cannot be used directly as a transition, but it's methods (namely enter() and exit()) are called to initiate transitions. None of the BaseTransition methods generally need to be overridden.

• Methods
  • new BaseTransition(params)
  • setConfig(config)
  • resetProps(targets, cachedProps)
  • enter([userConfig]) ⇒ Promise
  • exit([userConfig]) ⇒ Promise

new BaseTransition(params)

Param	Type	Description
params	Object	The config object
params.scene	Phaser.Scene	The parent scene
params.targets	Array	The target objects for the transition
params.defaults	Object	The default config options for this transition
params.config	Object	The user-defined config object, which is merged with the defaults (if provided)
params.enterConfig	function	A function which returns the tween config for the enter tween
params.exitConfig	function	A function which returns the tween config for the exit tween
params.affectedProps	Array.<String>	An array listing the props which are affected by this transition. This list is used to cache and reset those props when resetProps() is called.

baseTransition.setConfig(config)

Update the configuration for this transition. Any unset properties will be resolved to their defaults or settings from a previously set configuration.

Param	Type	Description
config	Object	An object defining transition configurations, such as duration, chain, etc.

baseTransition.resetProps(targets, cachedProps)

Returns each target object to it's initial state before either enter() or exit() was called.

Param	Type	Description
targets	Array	An array of GameObject targets
cachedProps	Array	An array of props generated by _cacheProps()

baseTransition.enter([userConfig]) ⇒ Promise

Starts the enter transition

Returns: Promise - - A promise which resolves when the transition's tween is complete

Param	Type	Description
[userConfig]	Object	A new config object for on-the-fly changes

baseTransition.exit([userConfig]) ⇒ Promise

Starts the exit transition

Returns: Promise - - A promise which resolves when the transition's tween is complete

Param	Type	Description
[userConfig]	Object	A new config object for on-the-fly changes

---

new FadeTransition(scene, targets, [config])

This transition tweens the alpha property of it's targets, fading object each into or out of view.

Param	Type	Default	Description
scene	Phaser.Scene	null	The parent scene
targets	Array	null	An array of game objects to be included in this transition
[config]	Object	FadeTransition.Defaults	The config object. Defaults will be used if not provided
[config.duration]	Number	500	The duration of this transition
[config.chain]	Bool	false	When true, each object will enter individually with overlap determined by the offset setting
[config.offset]	String	80% of duration	The amount of overlap (in ms) between transitions when chain is set to true, using this format: "-=500", "+=500", etc.
[config.fuzz]	Number	0	A number between 0 and 1 which adds randomness to the duration of this transition

new SlideTransition(scene, targets, [config])

The SlideTransition slides it's targets in and out of the scene based on the directions specified via enterFrom and exitTo. The following properties are affected: x, y

Param	Type	Default	Description
scene	Phaser.Scene	null	The parent scene
targets	Array	null	An array of game objects to be included in this transition
[config]	Object	SlideTransition.Defaults	The config object. Defaults will be used if not provided.
[config.duration]	Number	500	The duration of this transition
[config.chain]	Bool	false	When true, each object will enter individually with overlap determined by the offset setting
[config.offset]	String	80% of duration	The amount of overlap (in ms) between transitions when chain is set to true, using this format: "-=500", "+=500", etc.
[config.fuzz]	Number	0	A number between 0 and 1 which adds randomness to the duration of this transition
[config.enterFrom]	String	'left'	The direction from which the transition will enter. Valid options include: "left", "right", "top", and "bottom"
[config.exitTo]	String	'right'	The direction from which the transition will exit. Valid options include: "left", "right", "top", and "bottom"

new GrowTransition(scene, targets, [config])

The GrowTransition scales each object up from zero in place (as opposed to the ExplodeTransition which moves from the center out but also scales it's objects). The following properties are affected: scaleX, scaleY

Param	Type	Default	Description
scene	Phaser.Scene		The parent scene
targets	Array		An array of game objects to be included in this transition
[config]	Object	SlideTransition.Defaults	The config object. Defaults will be used if not provided.
[config.duration]	Number	500	The duration of this transition
[config.chain]	Bool	false	When true, each object will enter individually with overlap determined by the offset setting
[config.offset]	String	80% of duration	The amount of overlap (in ms) between transitions when chain is set to true, using this format: "-=500", "+=500", etc.
[config.fuzz]	Number	0	A number between 0 and 1 which adds randomness to the duration of this transition

new ExplodeTransition(scene, targets, [config])

The ExplodeTransition scales each object up from zero while sliding out from the center. The following properties are affected: alpha, scaleX, scaleY, x, y

Param	Type	Default	Description
scene	Phaser.Scene		The parent scene
targets	Array		An array of game objects to be included in this transition
[config]	Object	ExplodeTransition.Defaults	The config object. Defaults will be used if not provided.
[config.duration]	Number	500	The duration of this transition
[config.chain]	Bool	false	When true, each object will enter individually with overlap determined by the offset setting
[config.offset]	String	80% of duration	The amount of overlap (in ms) between transitions when chain is set to true, using this format: "-=500", "+=500", etc.
[config.fuzz]	Number	0	A number between 0 and 1 which adds randomness to the duration of this transition

new SlideFadeTransition(scene, targets, [config])

A combination of the Slide and Fade transitions. The following properties are affected: alpha, x, y

Param	Type	Default	Description
scene	Phaser.Scene		The parent scene
targets	Array		An array of game objects to be included in this transition
[config]	Object	SlideFadeTransition.Defaults	The config object. Defaults will be used if not provided.
[config.duration]	Number	500	The duration of this transition
[config.chain]	Bool	false	When true, each object will enter individually with overlap determined by the offset setting
[config.offset]	String	80% of duration	The amount of overlap (in ms) between transitions when chain is set to true, using this format: "-=500", "+=500", etc.
[config.fuzz]	Number	0	A number between 0 and 1 which adds randomness to the duration of this transition
[config.enterFrom]	String	'bottom'	The direction from which the transition will enter. Valid options include: "left", "right", "top", and "bottom"
[config.exitTo]	String	'top'	The direction from which the transition will exit. Valid options include: "left", "right", "top", and "bottom"

Using Declaratively

You can bypass the plugin altogether and use each transition class declaratively if you wish. You can import any of the transition classes directly.

import { SlideTransition } from 'phaser3-transitions';

function create(){
	
  	//The transition will return the sprites to their original positions
    let sprite1 = this.add.sprite(100, 100, 'menuItem');
    let sprite2 = this.add.sprite(100, 200, 'menuItem');
    let sprite3 = this.add.sprite(100, 300, 'menuItem');
	let sprites = [sprite1, sprite2, sprite3]; //etc.
    
    //You can omit the 'type' property when creating transition directly
    let config = {
        duration: 500,
   		enterFrom: 'left',
        exitTo: 'bottom'
    }
    
    //PARAMS: Scene, Targets, Config
    let slide = new SlideTransition(this, targets, config);
    
    slide.enter();
    
}

Custom Transitions

This section also coming soon...