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
  
• Install
  
• Usage
• Schema
• API
  • LayerManager
  • ResizeManager
  • Objects
  • Groups
• Examples

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 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.
anims - An array of animation configs, see here 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 if mapToScene 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.
• 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.
• 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, and displayHeight, 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, and displayHeight.
  • By default the ResizeManager will subscribe to the scene's resize event and resize any object w/ a resize property in it's config. This can be disabled by using phorge.resizer.stop()
  • Use a ratio string such as '50%' to maintain a certain size relative to the scene dimensions.

API

LayerManager

The LayerManager maintains a list of semantic layers by setting the 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()
  • addLayer(key, objects) ⇒ Phaser.GameObjects.Group
  • removeLayer(layerKey, [destroyObjects]) ⇒ Phaser.GameObjects.Group
  • getLayer(layerKey) ⇒ Phaser.GameObjects.Group
  • merge(layerOneKey, layerTwoKey)
  • swap(layerOne, layerTwo)
  • bringUp(layerKey)
  • bringDown(layerKey)
  • toTop(layerKey)
  • toBack(layerKey)
  • addObject(layerKey, object)
  • removeObject(object)
  • getObjLayerKey(object) ⇒ String | Bool
  • moveToLayer(object, newLayerKey)

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

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

layers.getLayer(layerKey) ⇒ Phaser.GameObjects.Group

Returns the Phaser Group representing a given layer

Returns: Phaser.GameObjects.Group - - The new layer

layers.merge(layerOneKey, layerTwoKey)

Merge two layers into one

layers.swap(layerOne, layerTwo)

Swaps the depth order of two layers

layers.bringUp(layerKey)

Switch the order of the given layer with the layer directly above it.

layers.bringDown(layerKey)

Switch the order of the given layer with the layer directly below it.

layers.toTop(layerKey)

Brings a layer to the top of stack

layers.toBack(layerKey)

Sends a layer to the bottom of stack

layers.addObject(layerKey, object)

Adds an object to the given layer

layers.removeObject(object)

Removes an object from any layer in which it resides.

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

layers.moveToLayer(object, newLayerKey)

Move an object to a different layer

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

• Methods:
  • manage(target, config)

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.

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;