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.
BaseTransition
classnpm install --save phaser3-transitions
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);
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();
});
}
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.
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 |
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. |
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 |
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 |
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.
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. |
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. |
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() |
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 |
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 |
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 |
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"
|
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 |
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 |
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"
|
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();
}
This section also coming soon...