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