Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/jhavrick/phaser3-phorge

A layout/scene building plugin for use with Phaser 3.
https://github.com/jhavrick/phaser3-phorge
javascript layout phaser phaser3 scenebuilder
Last synced: 9 days ago
JSON representation
A layout/scene building plugin for use with Phaser 3.
Host: GitHub
URL: https://github.com/jhavrick/phaser3-phorge
Owner: JHAvrick
Created: 2018-09-03T17:40:36.000Z (over 6 years ago)
Default Branch: master
Last Pushed: 2020-02-23T22:56:51.000Z (almost 5 years ago)
Last Synced: 2024-11-12T20:23:04.636Z (2 months ago)
Topics: javascript, layout, phaser, phaser3, scenebuilder
Language: JavaScript
Size: 2.89 MB
Stars: 3
Watchers: 3
Forks: 0
Open Issues: 1
Metadata Files:
- Readme: README.md
Awesome Lists containing this project

README

        # phaser3-phorge

A layout/scene building plugin for [Phaser 3](https://photonstorm.github.io/phaser3-docs/index.html). 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](#features) 


 - [Install](#install) 


 - [Usage](#usage)

 - [Schema](#schema)

 - [API](#api)

    - [LayerManager](#layermanager)

    - [ResizeManager](#resizemanager)

    - Objects

    - Groups

 - [Examples](#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](https://photonstorm.github.io/phaser3-docs/Phaser.GameObjects.html) namespace

  



## Install

`npm install phaser3-phorge`



## Usage 

### Setup the Plugin

```javascript

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

```javascript

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 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](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](#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:

```javascript

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;

```