phaser3-phorge v1.0.1
phaser3-phorge
A layout/scene building plugin for Phaser 3. This plugin takes a user-defined config and creates the objects denoted therein. The plugin also includes a number of subsystems for manipulating the layout build. Documentation is a work in progress.
Features
- Seperate layout from game logic
- Define object position as a ratio of scene size (i.e. '25%', '50%')
- Seperate objects into and manipulate depth layers
- Create and populate groups from config
- A simple resize manager to adjust certain position/size attributes on scene resize
Default values for most objects in the [Phaser.GameObject](https://photonstorm.github.io/phaser3-docs/Phaser.GameObjects.html) namespace
Install
npm install phaser3-phorge
Usage
Setup the Plugin
import Phaser from 'phaser';
import PhorgePlugin from 'phaser3-phorge';
const gameConfig = {
type: Phaser.WEBGL,
parent: 'game-container',
width: 400,
height: 600,
scene: [
Preload,
DemoScene
],
plugins: {
scene: [
{
key: 'phorge',
mapping: 'phorge',
plugin: PhorgePlugin
}
]
},
};
const game = new Phaser.Game(gameConfig);
Build the Layout
class Main extends Phaser.Scene {
constructor() { super({key: 'Main'}); }
create(){
this.phorge.build(Layout);
}
}
Config Schema
layers
- An array of strings, representing the layers in ascending order.
groups
- An array of strings, each denoting an instance of [Phaser.GameObjects.Group](https://photonstorm.github.io/phaser3-docs/Phaser.GameObjects.Group.html).
anims
- An array of animation configs, see [here](https://photonstorm.github.io/phaser3-docs/Phaser.Animations.Animation.html) for more info about what properties an animation config can contain.
objects
- An array of object configs, with the properties:
key
- (Required) The key by which this object can be retrieved from the plugin. Also used to map the object to the scene ifmapToScene
is true in the build config (as it is by default).class
- (Required) The class to instantiate this object.- For many objects in the Phaser.GameObjects namespace, a string (case insensitive) can be used to resolve the class. This will work for any of the following:
BitmapText
,DynamicBitmapText
,Graphics
,Image
,RenderTexture
,Sprite
,Sprite3d
,Text
,TileSprite
,Zone
.
- For many objects in the Phaser.GameObjects namespace, a string (case insensitive) can be used to resolve the class. This will work for any of the following:
params
- (Optional) An array with params to pass the instantiated object.- If you need to pass the parent scene, you can use
'{scene}'
as a placeholder and it will be resolved at runtime.
- If you need to pass the parent scene, you can use
layer
- (Optional) A string corresponding to one of your layers. Defaults to the first layer.group
- (Optional) A string correspnding to one of your groups.props
- (Optional) An object containing key/value pairs for each property to assign after this object's creation.- Any property can be set here, not only those which are already owned by the object
- Property chains (i.e.
prop.nextProp.whatever
) are valid - For the properties
x
,y
,displayWidth
, anddisplayHeight
, you can pass a string such as '50%' to set the value based on a percentage of the scene dimensions.
resize
- (Optional) The plugins resize subsystem can manage the resizing of the following properties:x
,y
,displayWidth
, anddisplayHeight
.- By default the ResizeManager will subscribe to the scene's
resize
event and resize any object w/ aresize
property in it's config. This can be disabled by usingphorge.resizer.stop()
- Use a ratio string such as
'50%'
to maintain a certain size relative to the scene dimensions.
- By default the ResizeManager will subscribe to the scene's
API
LayerManager
The LayerManager maintains a list of semantic layers by setting the [depth](https://photonstorm.github.io/phaser3-docs/Phaser.GameObjects.Components.html#.Depth) property of each layer's children. The LayerManager has many methods for manipulating/reordering layers, however it can also be ignored after the initial build if desired. (You can always call restack()
to reset the depth of each layer's children.)
- Methods
- [restack()](#LayerManager+restack)
- [addLayer(key, objects)](#LayerManager+addLayer) ⇒ Phaser.GameObjects.Group
- [removeLayer(layerKey, [destroyObjects])](#LayerManager+removeLayer) ⇒ Phaser.GameObjects.Group
- [getLayer(layerKey)](#LayerManager+getLayer) ⇒ Phaser.GameObjects.Group
- [merge(layerOneKey, layerTwoKey)](#LayerManager+merge)
- [swap(layerOne, layerTwo)](#LayerManager+swap)
- [bringUp(layerKey)](#LayerManager+bringUp)
- [bringDown(layerKey)](#LayerManager+bringDown)
- [toTop(layerKey)](#LayerManager+toTop)
- [toBack(layerKey)](#LayerManager+toBack)
- [addObject(layerKey, object)](#LayerManager+addObject)
- [removeObject(object)](#LayerManager+removeObject)
- [getObjLayerKey(object)](#LayerManager+getObjLayerKey) ⇒ String | Bool
- [moveToLayer(object, newLayerKey)](#LayerManager+moveToLayer)
layers.restack()
Reapplies the parent layers depth to each of the layer's children
Kind: instance method of LayerManager
layers.addLayer(key, objects) ⇒ Phaser.GameObjects.Group
Add's a new layer to the top of the stack
Returns: Phaser.GameObjects.Group - - The new layer
Param | Type | Description |
---|---|---|
key | String | The layer key |
objects | Array.<Phaser.GameObjects.GameObject> | An array of objects that belong to this layer |
layers.removeLayer(layerKey, destroyObjects) ⇒ Phaser.GameObjects.Group
the LayerManager.Any objects in that layer will no longer be managed by
Returns: Phaser.GameObjects.Group - - The removed layer
Param | Type | Default | Description |
---|---|---|---|
layerKey | String | The layer to remove | |
destroyObjects | Bool | false | Whether to call destroy() on all objects in the group |
layers.getLayer(layerKey) ⇒ Phaser.GameObjects.Group
Returns the Phaser Group representing a given layer
Returns: Phaser.GameObjects.Group - - The new layer
Param | Type | Description |
---|---|---|
layerKey | String | The layer to get |
layers.merge(layerOneKey, layerTwoKey)
Merge two layers into one
Param | Type |
---|---|
layerOneKey | String |
layerTwoKey | String |
layers.swap(layerOne, layerTwo)
Swaps the depth order of two layers
Param | Type | Description |
---|---|---|
layerOne | String | The key of the first layer |
layerTwo | String | The key of the second layer |
layers.bringUp(layerKey)
Switch the order of the given layer with the layer directly above it.
Param | Type | Description |
---|---|---|
layerKey | String | The key of the layer to bring up |
layers.bringDown(layerKey)
Switch the order of the given layer with the layer directly below it.
Param | Type | Description |
---|---|---|
layerKey | String | The key of the layer to bring up |
layers.toTop(layerKey)
Brings a layer to the top of stack
Param | Type |
---|---|
layerKey | String |
layers.toBack(layerKey)
Sends a layer to the bottom of stack
Param | Type |
---|---|
layerKey | String |
layers.addObject(layerKey, object)
Adds an object to the given layer
Param | Type | Description |
---|---|---|
layerKey | String | The layer into which the object will be added |
object | Phaser.GameObjects.GameObject | An valid object in the Phaser.GameObjects namespace |
layers.removeObject(object)
Removes an object from any layer in which it resides.
Param | Type | Description |
---|---|---|
object | Phaser.GameObjects.GameObject | The object to remove |
layers.getObjLayerKey(object) ⇒ String | Bool
Returns the key of the layer that the given object resides in
Returns: String | Bool - - The layer key, or false
if the object resides in no layers
Param | Type | Description |
---|---|---|
object | Object | The object for which to retrieve the layer key |
layers.moveToLayer(object, newLayerKey)
Move an object to a different layer
Param | Type | Description |
---|---|---|
object | Object | The object to move |
newLayerKey | String | The destination layer key |
ResizeManager
The ResizeManager can manage the resizing of certain game object properties when the scene trigger's a resize
event. Currently the ResizeManager can manage the following properties: x
, y
, displayWidth
, and displayHeight
. In the future more complex behavior will be supported.
Properties
Name | Type | Default | Description |
---|---|---|---|
[active] | Bool | true | Set to false to stop the ResizeManager completely |
[manageCameras] | Bool | true | Indicates whether the ResizeManager should also resize the camera when the scene resizes |
- Methods:
- [manage(target, config)](#ResizeManager+manage)
resizeManager.manage(target, config)
Adds an object for the ResizeManager to manage according to the given config. Properties passed as strings will resolved as a percentage of the scene's dimensions.
Param | Type | Description |
---|---|---|
target | Phaser.GameObjects.GameObject | The target object to resize |
config | Object | The resize config w/ transform properties |
config.x | String | Number | The x position of the target object |
config.y | String | Number | The y position of the target object |
config.displayWidth | String | Number | The object's display width |
config.displayHeight | String | Number | The resize config w/ transform properties |
Config Examples
A simple layout with only two objects:
const SimpleLayout = {
layers: ['one', 'two', 'three'],
groups: ['one', 'two'],
objects: [
{
key: "healthbar",
layer: "one",
class: 'sprite',
params: ['{scene}', 0, 0, 'healthbar'], //'{scene}' will resolve to the current scene
props: { anchorX: 0.5, anchorY: 0.5, x: '50%', y: '50%' }
},
{
key: "mana",
layer: "two",
clone: 'healthbar', //Use the settings from another config
params: ["{SCENE}", 0, 0, 'mana']
},
]
}
export default LayoutTwo;