Notable Pastry Maker

    @kleber-swf/phaser-runtime-editor

    1.5.0 • Public • Published

    Phaser-CE Runtime Editor

    A plugin that shows a runtime editor for your Phaser-CE game.

    Phaser Runtime Editor

    What can I do with it?

    • Select, move and scale objects inside the game
    • See and edit some basic properties for object in the scene
    • See the scene object tree
    • Zoom in and out the scene
    • Use a preview image to help you build your scene

    What can't I do with it?

    • Save the changes. This will never be possible since the Editor does't know what code generated the scene
    • Update the object tree in realtime. This is quite heavy to do. Might be something for the future.
    • Select multiple objects
    • Object rotation. It's pretty hard!

    The Editor was tested mostly on Google Chrome. So it might be different in other browsers.

    Installation

    After you install Phaser-CE, use npm to install Phaser Runtime Editor:

    npm install -D @kleber-swf/phaser-runtime-editor

    The simplies setup

    Inside your game, after the Phaser's Game instance is created, add it as a Phaser plugin:

    game.plugins.add(new Phaser.Plugin.RuntimeEditor(game));

    Also, add to your index.html after the insertion of phaser.js and before your game.js:

    <script id="phaser-runtime-editor" src="/js/phaser-runtime-editor.min.js"></script>

    This will make it available for you at runtime. You will notice a small icon at the top left corner of your game. Click on it to open the editor.

    Options

    There are some options you can pass as an optional second parameter when creating the plugin:

    const config = {
        root() => game.world,
        referenceImageUrl() => 'http://some/preview/image.png',
        onShow() => console.log('reuntime editor opened'),
        onHide() => console.log('reuntime editor closed'),
        pauseGame: true,
        clearPreferences: false,
        saveLockedObjectsPath: true,
    };
    
    game.plugins.add(new Phaser.Plugin.RuntimeEditor(game, config));

    The config object can have the following properties (all of them optional):

    • root: () => PIXI.DisplayObjectContainer | Phaser.Stage

      This method returns the container where the Editor will get its objects. You can pass, for example a method that returns a specific root element.

      This method is called every time the Editor is shown, so you can return a different root depending on something your game controls.

      Default: () => game.world.

    • referenceImageUrl: (width: number, height: number, responsive: boolean) => string

      If your workflow uses reference images to build the scenes in the game, you can use this method to get their urls to be used in the Editor.

      This method returns an url to an image file. It can be inside your project or not. It just need to be something you can put in a src attribute of a <img> tag. This method is called every time the game view is resized inside the editor.

      The method accepts three parameters:

      • width: preview width
      • height: preview height
      • responsive: whether the editor is in responsive view mode

      You can use these parameter to determine which image you should return.

      Default: () => null.

    • onShow: () => void

      A method that is called right after the Editor is shown.

      Default: null.

    • onHide: () => void

      A method that is called right after the Editor is hidden.

      Default: null.

    • pauseGame: boolean

      Whether the Editor should pause your game on show or not. If this is set to true the game will come back to it's original state when the Editor is hidden.

      Default: false.

    • clearPreferences: boolean

      Whether the local preferences should be cleared when the Editor is shown.

      Default: false.

    • saveLockedObjectsPath: boolean

      Whether the locked objects should be saved between runs. Check Object Tree for more info on locking objects.

    Notice that there is an example project inside the Editor's project where you can see it in use.

    Features

    Object Tree

    Object Tree

    • A tree view of the objects in the scene. It can't be updated at runtime.

    • It has a field where you can filter the objects by their names

    • It can expand and collapse its nodes (use alt + click to expand/collapse all of its children)

    • It has an icon for each type of object to make it easy to identify them

    • Dims invisible objects

    • Actions:

      1. Collapse All. Collapses all nodes in the Object Tree.

      2. Refresh. Refreshes the Object Tree nodes. The tree is refreshed every time the Editor opens so this is useful only when the hierarchy changes while the Editor is open.

      3. Lock/unlock selected object. Locked nodes can't be selected inside the Scene View. They still can be selected inside the Object Tree. By default, locked nodes are saved between runs. If you don't want this, set the saveLockedObjectsPath to false when instantiating the Plugin.

      4. Select the selected object's parent. This is useful for when you have a huge object hierarchy and wants to select the parent of the selected object fast.

      5. Filter. Filters objects inside the tree by their names.

    Properties Panel

    Properties Panel

    • Shows some basic properties of the selected object in the scene
    • Most of the properties are editable (and updated in the object)
    • Supported types:
      • number
      • boolean
      • string
      • multiline text
      • PIXI.Point
      • PIXI.Rectangle
      • Color string
      • Enums
    • The properties shown are based on the type of the selected object and are grouped by category
    • A handful copy button for each property copies it in JSON format

    Scene View

    Scene View

    • It can visually select and edit properties from an object in the scene
    • It's possible to move and scale the selected object
    • When scaling, its possible to make it freely, proportially (holding CTRL), centered (holding ALT) or a combination of last two.
    • It shows the selected object pivot and anchor (if any)
    • The selection is made from the deepest children to its parent

    Reference Image

    Reference Image Options

    Its common to have a reference image made by the art team so the developer can make the game look like it was conceived.

    To help you with this pipeline, the Editor has a reference image parameter (referenceImageUrl) inside the initial config that lets you tell what is the url for this image.

    When you set this parameter to a valid image url, the reference image options panel is available in the Editor. These options are to adjust the image filters and opacity to make it easy to distinguish it from the real game.

    Selection

    Every time you select an object inside the Editor a global variable is set with it: selection. This variable is accessible in the browser's console by typing its name inside it. This way you can not just print its content but also get/set fields values and call methods on it.

    Selection Example

    Actions

    Actions Toolbar

    1. Panels Toogle. Toggles panel visibility to better view the game scene. It is available for both panels.

    2. Editor. Toggles the editor (its shown inside the game as a floating almost invisible button at the top left corner of the screen)

    3. Snap. Toggles the snapping to integer numbers when moving objects in the scene view

    4. Guides. Toggles guide lines around the selected object to better position it in the scene view

    5. Gizmos. Toggles gizmos visibility in scene view

    6. Hit Area. Toggles the hit area visibility of the selected object in the scene view

    7. All Hit Areas Snapshot. Shows a snapshot of all hit areas available in the scene view. It doesn't updated if objects change while it's being shown. Toggle it twice to update it.

    8. Responsive Panel: Toggle. Toggles responsive view and features. Responsive view is like the one seen on browsers. The other buttons are available when this option is selected.

    9. Responsive Panel: Orientation Toggle Change orientation of the responsive view

    10. Responsive Panel: Proportion Templates: Some common proportions for mobile devices and the custom one, where you can resize the responsive view freely

    11. Zoom Out. Zooms out the scene view

    12. Reset Zoom. Resets the scene zoom to its default value

    13. Zoom In. Zooms in the scene view

    14. Print Object to Console. Prints the selected object into the console. This is useful for when you want to see some property that is not mapped into the properties panel

    15. Reference Image Panel: Toggle. Toggles the reference image panel and the reference image inside the scene view

    16. Reference Image Panel: Options. Shows the reference image options where you can set the opacity and filters of the reference image inside the scene view

    17. Undo: Undo the last action (it has a limit of 100 actions)

    18. Help Screen. Shows the help screen with the actions shortcuts and descriptions

    Misc

    • The editor saves some preferences locally, like panels size and visibility and options selected to make you life easy when running it consecutively

    Keyboard shortcuts

    • Scene:

      • ctrl+z: undo the last action made
      • ctrl+shift+p: prints the selected object to the console
      • escape: clears the selection
      • ctrl+\`` or ctrl+.`: toggle gizmos
      • : move selected object up by 1px
      • : move selected object down by 1px
      • : move selected object left by 1px
      • : move selected object right by 1px
      • shift+⬆: move selected object up by 10px
      • shift+⬇: move selected object down by 10px
      • shift+⬅: move selected object left by 10px
      • shift+➡: move selected object right by 10px
    • View:

      • ctrl+wheel: zoom
      • ctrl+= or ctrl++: zoom in
      • ctrl+-: zoom out
      • ctrl+0: reset zoom to default
      • ctrl+[: toggle left panel visibility
      • ctrl+]: toggle right panel visibility
    • Object tree:

      • alt+click on a node: collapses/expands the node children recursively

    Development

    • Clone the project

      git clone git@github.com:kleber-swf/phaser-runtime-editor.git
    • Install dependencies

      npm install
    • Run the example project

      npm run dev

      This feature is exclusive to Teams

      Illustration of wombats

      The package file explorer is only available for Teams at the moment.

      We may support exploring this package in the future. Check back soon.

      Install

      npm i @kleber-swf/phaser-runtime-editor

      DownloadsWeekly Downloads

      3

      Version

      1.5.0

      License

      MIT

      Unpacked Size

      255 kB

      Total Files

      13

      Last publish

      Collaborators

      • kleber.swf