https://github.com/jhavrick/phaser3-transitions
A Phaser 3 plugin for smooth UI enter/exit transitions.
https://github.com/jhavrick/phaser3-transitions
javascript phaser phaser3 phaserjs
Last synced: 4 months ago
JSON representation
A Phaser 3 plugin for smooth UI enter/exit transitions.
- Host: GitHub
- URL: https://github.com/jhavrick/phaser3-transitions
- Owner: JHAvrick
- Created: 2018-09-05T20:52:55.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2020-02-23T22:58:39.000Z (about 5 years ago)
- Last Synced: 2025-01-16T06:59:39.287Z (4 months ago)
- Topics: javascript, phaser, phaser3, phaserjs
- Language: JavaScript
- Size: 1.01 MB
- Stars: 13
- Watchers: 6
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
# 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](#feature)
- [Install and Setup](#install)
- [Examples](#examples)
- [Plugin API](#pluginapi)
- [Transition Classes](#transitions-classses)
- [BaseTransition](#base-transition)
- [FadeTransition](#fade-transition)
- [SlideTransition](#slide-transition)
- [GrowTransition](#grow-transition)
- [ExplodeTransition](#explode-transition)
- [SlideFadeTransition](#slidefade-transition)
- [Using Declaratively](#using-declaratively)
- [Custom Transitions](#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`
```javascript
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.
```javascript
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.
```javascript
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)](#TransitionsPlugin+register)
* [create(targets, config)](#TransitionsPlugin+create) ⇒ BaseTransition
* [enter(targets, config)](#TransitionsPlugin+enter) ⇒ Promise
* [exit(targets, config)](#TransitionsPlugin+exit) ⇒ 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 |
---
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)](#new_BaseTransition_new)
* [setConfig(config)](#BaseTransition+setConfig)
* [resetProps(targets, cachedProps)](#BaseTransition+resetProps)
* [enter([userConfig])](#BaseTransition+enter) ⇒ Promise
* [exit([userConfig])](#BaseTransition+exit) ⇒ 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"` |
You can bypass the plugin altogether and use each transition class declaratively if you wish. You can import any of the transition classes directly.
```javascript
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...