phaser3-transitions v1.0.1

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.

transitions.create(targets, config) ⇒ BaseTransition

Creates a new transition based on the given config

Returns: BaseTransition - - A transition class extending BaseTransition

transitions.enter(targets, config) ⇒ Promise

Creates and starts a new enter transition

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

transitions.exit(targets, config) ⇒ Promise

Creates and starts a new exit transition

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

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)

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.

baseTransition.resetProps(targets, cachedProps)

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

baseTransition.enter(userConfig) ⇒ Promise

Starts the enter transition

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

baseTransition.exit(userConfig) ⇒ Promise

Starts the exit transition

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

new FadeTransition(scene, targets, config)

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

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

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

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

new SlideFadeTransition(scene, targets, config)

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

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