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

| 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(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;