Canvas, The Scene Editor

Canvas is a visual (WYSWYG) game level/object editor for Phaser. With this tool you can create a level or the prefabs (reusable objects) of the game, layout sprites and edit object properties like transformation, physics body and animation. The scenes are compiled to Phaser code, in JavaScript or TypeScript. ` There are three type of Canvas files: states (compiled to a Phaser.State code), sprite prefabs (compiled to Phaser.Sprite code) and group prefabs (compiled to`Phaser.Group` code). These Phaser classes contain the code that create the objects of the game world. It is not like other tools like Tiled that uses a custom format to represent the objects layout and properties, else it compiles to a code that mimics what a developer can write with his “own hands”. This method has the advantage that the user can read and understand what is behind the scene and like in other tools provided in Phaser Editor, the developer can learn Phaser or reuse his current Phaser learnings.

When you create a scene (let’s say one named Level) you get two files: Level.canvas and Level.js. The Level.canvas file contains the objects of the scene and uses a custom Phaser Editor format. The Level.js file is compiled from the Level.canvas file and contains all the Phaser code that creates the real scene. Note that in a game distribution only the Level.js file is needed, since Level.canvas is only for design purpose.

Read in Zenva GameDev Academy Make a Mario-Style Platformer with the Phaser Editor

Canvas.

Play the demos

To play around with a Canvas demo you can create a project with the Phaser Example Project wizard. There you can select any of the templates under the Phaser Editor Demos category:

Project with a Canvas demo.

States, sprites and groups

In this section we are going to do a quick explanation of the difference and purpose of each type of Canvas: states, sprites and groups.

The state scene

A Phaser game is divided by states, for example the menu screen is coded in a state, a game level is coded in a state, the “game over” screen… What the user does is to write a special class that extends the Phaser.State type, and implement some special methods where the creation and logic of the game is coded. These methods are the preload, create, update and others.

This is an example of a state scene and the code compiled by Canvas:

A state with two coins…

State demo with two coins.

… is compiled into this code:

// -- user code here --

/* --- start generated code --- */

// Generated by Phaser Editor v1.4.0 (Phaser v2.6.2)


/**
 * DemoState.
 */
function DemoState() {

        Phaser.State.call(this);

}

/** @type Phaser.State */
var DemoState_proto = Object.create(Phaser.State.prototype);
DemoState.prototype = DemoState_proto;
DemoState.prototype.constructor = DemoState;

DemoState.prototype.init = function () {

};

DemoState.prototype.preload = function () {

        this.load.pack('level', 'assets/pack.json');

};

DemoState.prototype.create = function () {
        this.add.sprite(119, 23, 'coins', 0);

        this.add.sprite(334, 129, 'coins', 0);

};

/* --- end generated code --- */
// -- user code here --

To create a State scene click in the main menu the File > New > State File option, it opens the State File wizard. The first page of that wizard asks for the parent folder and the name of the scene. Usually we create a WebContent/assets/canvas folder where to place all the scenes and prefabs, but you are free to use any folder inside the WebContent directory. In the next picture we use Level as the name of the scene, that will create a Level.canvas file. This is very important: the name of the file will be used to create the name of the state class.

State wizard (file page)

If you press Finish the state file is created with the default parameters, but we recommend that you press the Next button, to do some customization of the scene:

State wizard settings page.

Many of the parameters shown in that page come from the Phaser API, however there are other parameters like the Base Class Name or Code Format that are used by the scene-to-code compiler.

All these settings can be changed later in the configuration tab of the editor.

Sate scenes will be displayed in the Assets window under the State section.

The sprite scene (prefab)

The sprite scene or sprite prefab is a Canvas file with a unique object that compiles to a Phaser.Sprite sub-class. In the Phaser examples it is called as “custom sprite”, in other tutorials and examples about Phaser it is called also “prefab”. We like the word “prefab” since it is a concept used in other game visual tools, but the purpose is the same, to write resuable components that can be used in different parts of the game, without the need to duplicate code. For example you can create a Coin prefab with the coin animations, so you can use that animated coin in any other scene.

This is an example of how an sprite canvas file is compiled into a custom Phaser.Sprite:

The coin scene (with a rotate animation)…

Coin prefab.

… is compiled into a custom Sprite class:

// -- user code here --

/* --- start generated code --- */

// Generated by Phaser Editor v1.4.0 (Phaser v2.6.2)

/**
 * Coin.
 * @param {Phaser.Game} aGame A reference to the currently running game.
 * @param {Number} aX The x coordinate (in world space) to position the Sprite at.
 * @param {Number} aY The y coordinate (in world space) to position the Sprite at.
 * @param {any} aKey This is the image or texture used by the Sprite during rendering. It can be a string which is a reference to the Cache entry, or an instance of a RenderTexture or PIXI.Texture.
 * @param {any} aFrame If this Sprite is using part of a sprite sheet or texture atlas you can specify the exact frame to use by giving a string or numeric index.
 */
function Coin(aGame, aX, aY, aKey, aFrame) {

        var pKey = aKey === undefined? 'coins' : aKey;
        var pFrame = aFrame === undefined? 1 : aFrame;

        Phaser.Sprite.call(this, aGame, aX, aY, pKey, pFrame);
        this.scale.setTo(0.5, 0.5);
        var _anim_rotate = this.animations.add('rotate', [0, 1, 2, 3, 4, 5], 5, true);

        // public fields

        this.fCoins = this;
        this.fAnim_rotate = _anim_rotate;

}

/** @type Phaser.Sprite */
var Coin_proto = Object.create(Phaser.Sprite.prototype);
Coin.prototype = Coin_proto;
Coin.prototype.constructor = Coin;

/* --- end generated code --- */
// -- user code here --

To create a sprite prefab in the main menu select the File > New > Sprite Prefab File option. It opens a wizard that in its first page ask for the container folder and the name of the file.

Press the Next button to set some needed parameters, the most important is the texture of the sprite:

Sprite prefab wizard

In the current version of Canvas the sprites cannot have children, so a sprite prefab cannot have children neither, it is a file with single object.

The group scene (prefab)

In Phaser a group is an object with different purpose. It can be used as a pool of objects or like a transformation list of objects. As well as the sprites, you can create “custom groups”, or what we name group prefabs. These group prefabs can be added to other scenes so they are a way to write reusable components. For example you can create a tree with fruits and use it in different levels.

This group prefab…

Group prefab.

… is compiled into this code:

// -- user code here --

/* --- start generated code --- */

// Generated by Phaser Editor v1.4.0 (Phaser v2.6.2)


/**
 * Tree.
 * @param {Phaser.Game} aGame A reference to the currently running game.
 * @param {Phaser.Group} aParent The parent Group (or other {@link DisplayObject}) that this group will be added to.
    If undefined/unspecified the Group will be added to the {@link Phaser.Game#world Game World}; if null the Group will not be added to any parent.
 * @param {string} aName A name for this group. Not used internally but useful for debugging.
 * @param {boolean} aAddToStage If true this group will be added directly to the Game.Stage instead of Game.World.
 * @param {boolean} aEnableBody If true all Sprites created with {@link #create} or {@link #createMulitple} will have a physics body created on them. Change the body type with {@link #physicsBodyType}.
 * @param {number} aPhysicsBodyType The physics body type to use when physics bodies are automatically added. See {@link #physicsBodyType} for values.
 */
function Tree(aGame, aParent, aName, aAddToStage, aEnableBody, aPhysicsBodyType) {

        Phaser.Group.call(this, aGame, aParent, aName, aAddToStage, aEnableBody, aPhysicsBodyType);
        this.game.add.sprite(41, 6, 'objects', 'Tree_3', this);

        this.game.add.sprite(103, 87, 'objects', 'fruit', this);

        this.game.add.sprite(147, 34, 'objects', 'fruit', this);

        this.game.add.sprite(190, 91, 'objects', 'fruit', this);

        this.game.add.sprite(243, 47, 'objects', 'fruit', this);

        this.game.add.sprite(95, 221, 'objects', 'Bush (1)', this);

}

/** @type Phaser.Group */
var Tree_proto = Object.create(Phaser.Group.prototype);
Tree.prototype = Tree_proto;
Tree.prototype.constructor = Tree;

/* --- end generated code --- */
// -- user code here --

To create a group prefab select in the main menu the File > New > Group Prefab File option. It opens a wizard that ask in the first page for the name of the file. You can press the Finish button to create the file or press Next to customize some options, like the base class name (other than Phaser.Group) or the code format (JavaScript 5, JavaScript 6 or TypeScript).

Objects creation

In general, a Canvas scene is formed by a tree of objects (sprites) and a couple of configuration parameters. In this section we are going to explain how to add the objects.

By dropping a texture asset

The common way to create an object is by getting a texture from somewhere and droping it into the scene. In the next sections we explain the different sources of the textures.

From the Assets window

In the Assets explorer you will find all the assets declared in the pack files. To create a common sprite you can drag a texture from that window and drop it into the scene:

Add objects from the Assets window.

Note a texture could be represented by an image key, a sprite-sheet frame key or a texture atlas frame key.

The objects created by dropping an asset in the scene are simple sprites, direct instances of Phaser.Sprite. In the next sections we explain how to create specialized sprites like buttons and tiles.

From the Assets view you can add prefabs too. Look for the Sprites and Group sections of that window. When the prefab is dropped into the scene then a prefab instance is created. This is how looks a code compiled from a Sate scene that contains prefab instances. Note the difference between to add a sprite from a texture (bg) and a sprite from a prefab (Tree):

Level.prototype.create = function () {
        this.add.sprite(0, 0, 'bg');

        var _tree = new Tree(this.game);
        _tree.position.setTo(39, 130);
};

From the Preview window

The Preview window allow you you to get a closer look to the assets. Like in the Assets window, you can drag an asset key from the Preview and drop it to the scene. For example, you can drop “cells” from a sprite-sheet of a retro game into the scene. This method could be easier than getting it from the Assets tree:

Add object from the Preview window.

You can drag the objects from an image, a texture atlas or a sprite-sheet.

From the Palette

The Palette is a docked window at the right of the scene and is used to keep at hand a selection of assets that you use often. You can add assets to the palette in the same way you add them to the scene. One time the assets are in the palette you can drag them from there and drop them into the scene. To show the palette you can click on the palette icon.

Add the assets from the palette.

From the context menu

If you like to work without distracting windows around you can maximize the scene editor (Ctrl+M) so it gets all the application space. In this mode you have the option to add the objects by using the Add Sprite dialog, just right-click on the scene and select Sprite > Add... > Sprite:

Context menu to open the Add Sprite dialog.

It shows a dialog with all the assets that can be used to create the sprite:

Add Sprite dialog.

As you can see in the previous menu, you can add other type of objects like buttons (Phaser.Button), tiles (Phaser.TileSprite) and prefabs. It does the same, to open a dialog with the asstes or prefabs to be added but it creates an object of different type.

Selecting the container

It is a very common case when you want to add the new object to a specific group. To do this just select the group and then add the object to the scene. For example if you want to add more blocks to the ground group, then select ground and then add the objects to the scene. If instead of a group you select a sprite and add a new object, this object will be added to the parent of the selected sprite. For example, if you select a block sprite and add a new object then it will be inserted into the block’s parent group, in this case the ground group.

Group creation

You can create an empty group or a group with the selected objects as children:

Add group menu.

Note to create a group with the selection objects you can press the G key.

Other group operations are:

  • Break group (Shift+G): it reparent the children and destroy the group.
  • Trim group (T): it remove the blank spaces around the children.

Object morphing

The common way to create an object is by adding an asset into the scene and it create a regular sprite (Phaser.Sprite). If you want to create a different type of object (like a button or a tile) you have two options: the From the context menu option or the morphing option.

To morphing an object mean to convert an object from one type to other type, for example, to morph a sprite into a button or into a tile sprite. When you morph an object into other type it keeps the same proprties, like transformation, texture, body.

To morph an object right click on it and select one of the options displayed in the Sprite > Morph To... menu:

Morph object to other type.

In addition you can press the L key to morph the selected sprite to a tile sprite, and resize it. It is a handy shortcut for games based on fixed-size art. If the sprite is already a tile sprite it just show the handlers to resize it.

Dynamic object creation

Many genres of games create the levels dynamically, or part of the levels. With Canvas you can design the sprite and group prefabs and then create instances of them dinamically.

Dynamic creation of sprite prefab objects

To create a sprite prefab dynamically follow this syntax:

var coin = new Coin(game, 10, 10);
game.add.existing(coin);

Where game is a reference to the Phaser.Game instance and 10, 10 is the location of the object, and Coin is the name of a sprite prefab.

If you want to add the sprite to a group, then the syntax is:

var coin = new Coin(game, 10, 10);
parentGroup.add(coin);

You can also create the sprite with a different texture:

var coin = new Coin(game, 10, 10, 'atlas', 'blue-coin');

Where 'atlas' is the name of a texture loaded with the atlas key, and 'blue-coin' is the name of a frame of the texture.

Dynamic creation of group prefab objects

Just like sprite prefabs you can create group prefabs like this:

var group = new SkyBackground(game);

Where game is an instance of the Phaser game and SkyBackground is a group prefab.

If you want to add the new group to a parent group then this is the syntax:

var group = new SkyBackground(game, parentGroup);

Scene navigation

For large scenes it is very important to navigate the tree of objects and quickly find specific objects. In the next section we show the tools provided by Phaser Editor for this purpose.

The Outline window

In the top/left corner of the editor there is the Outline window. It shows the hierarchy of the scene objects. There you can filter, select, delete, group and move the objects of the scene:

Outline window.

The Quick Outline window

In addition there is the Quick Outline window. It is opened by the user with the key sequence Ctrl+O. The object selected by the user is focused in the scene, so it can be used as a search tool too.

This quick window is very useful when the scene left panel is hidden to gain on space.

Quick outline window.

Object properties

To edit the scene object properties there is the Properties Grid window. The Phaser objects contain a lot of properties, but in Canvas we just support a subset of them, specially those that have an impact on the visuality of the objects.

To edit the properties of an object follow these steps:

  • Select the object -you cannot edit many objects at the same time- in the scene or in the Outline window.
  • The object’s properties are shown in the Property Grid.
  • Click on the value of a property and change it. Then press ENTER to apply that change. In case of numeric properties, you can write a math expression like 15*30, then it is evaluated and the result is set as value.
  • Some properties have special editors that open in a separated window.
  • You always can undo the change by pressing Ctrl+Z.
Edit the sprite properties.

As you can note, in the top of the grid there is a text field with a “type filter text” message, it helps to filter the list of properties and find the one of your interest.

As alternative to the Property Grid, you can open the Quick Edit dialog (by pressing Q or clicking in the button of the toolbar). It is actually the same thing of the Property Grid but it is shown in a popup dialog.

A nice feature is that you can hover the mouse over a property and it displays the help of it. This help is the same of the Phaser API, actually, that help is taken from the Phaser metadata generated by Phaser Editor, by parsing the Phaser sources.

The help of a property in the grid.

When you change a property it is highlighted with a bold font, and generated in the code in this way:

var sprite = this.add.sprite(10, 20, "wall");
sprite.tint = 0xfcfcfc; // modified property

Common object properties

All the objects in the scene share a common set of properties:

Property Documentation
name A user defined name. This value isn’t ever used internally by Phaser or Phaser Editor.
x/y The position of the Game Object on the x axis relative to the local coordinates of the parent.
angle The angle property is the rotation of the object in degrees.
scale.x/y The scale of the object.
pivot.x/y The pivot point of this object that it rotates around.
alpha The alpha value of the object. 0 is transparent, 1 is fully opaque.
fixedToCamera If true the Game Object will appear to be ‘fixed’ to the camera, regardless of where in the game world the camera is viewing. Useful for backgrounds or UI elements in scrolling games.
renderable Whether this object is renderable or not. Often used in Phaser Editor to create hidden layers with physics bodies.

Transformation tools

In addition to set the values directly in the property grid you can change the transformation of an object by selecting it and executing one of the transformation commands. It shows little handlers that you can drag to transform the object. The commands can be executed from the context menu under the Object > Transform menu, or by pressing the key shortcuts: scale (S), rotate (N).

Object transformations. Transformation handlers.

Prefab instance properties

By default the properties of a prefab instance cannot be changed, the position and override properties are the exception. The override property contains the list of properties that can be changed in that prefab instance. It means, that if you want to change the scale of a prefab instance then first step is to “open” the scale property by checking it on the override list. Note that when a property is not checked in the override list it is shown as disabled in the Property Grid and cannot be edited.

To reset the value of a property to the initial value in the prefab just deselect the property in the override list.

Override a prefab instance property.

Sprite properties

The Phaser.Sprite is the common class for all the game objects based on textures. In this section we show the properties supported by Phaser Editor and the some dedicated property editors.

Property Documentation
anchor.x/y The anchor sets the origin point of the texture. The default is 0,0 this means the texture’s origin is the top left Setting than anchor to 0.5,0.5 means the textures origin is centered Setting the anchor to 1,1 would mean the textures origin points will be the bottom right corner.
tint The tint applied to the sprite. This is a hex value. A value of 0xFFFFFF (white) will remove any tint effect. To edit this value the editor shows the native color dialog.
animations A list of animations. This property is explained in the Animations section.
data An empty object where the user can add custom properties. See the User data section.
frameName This property is shown only for sprites with a texture based on a texture atlas frame. When the user edits this property it shows a dialog with all the frames of the atlas. Read more in the Texture section.
frame This property is shown only for sprites with a texture based on a sprite-sheet frame index. When the user edits this property it shows a dialog with all the frames of the sprite-sheet. Read more in the Texture section.

Arcade Physics

For now the scene editor only supports Arcade physics. It does not mean that you cannot add other type of physics to your game, else that you should setup the other physics bodies by hand, without any special tool.

To enable Arcade physics on a sprite you have two options:

  • Set true the physicsGroup property of the parent group of the sprite. Physics bodies are automatically enabled in objects added to a physics group.
  • Select the object and open the context menu, in the Sprite > Arcade menu there are two commands: Set Arcade Body - Rectangular and Set Arcade Body - Circular, both commands enable a physics body (rectangular or circular) in the selected object.
Set Arcade physics body to sprite.

When you add a body to a sprite, a new section Arcade is added to the Property Grid. This section contains many properties related to the Arcade physics body of the sprite and can be edited. In addition you can visually edit the size and offset of the body, just right click on the sprite and select Sprite > Arcade > Edit Body or press the B key.

Edit Arcade body size and offset.

Animations

The animations property is reference to the Phaser.AnimationManager of the sprite. This manager contains a list of sprite animations and provide methods to manipulate the animations like add, play, stop and others.

When the user click to edit the animations of a sprite it opens a dialog with the list of the animations together with an area to preview them:

The animations dialog.

As you can see in the dialog you can add/remove animation, add/remove frames to an animation sequence, edit each animation properties and play an animation. The animations properties you can edit are:

Property Documentation
Frame Rate The animation speed in frames per second.
Loop To repeat the animation.
Kill On Complete If checked the animation will be played once and then destroyed.
Auto Play If checked the animation will be played just after it is created. Only one animation can be auto-played.
Public If checked a field will be generated to reference this animation. Useful if you want to publish animations of prefabs.

The animations are compiled into code in this way:

var _dino = this.add.sprite(10, 10, 'dino', 1);
var _dino_walk = _dino.animations.add('walk', [0, 1], 5, true);
_dino_walk.play(); // the "walk" animation was set to Auto Play
_dino.animations.add('jump', [2], 5, false);
_dino.animations.add('stay', [3], 5, false);

If the animation jump was set to Public then a field fDino_jump will be generated:

var _dino_jump = _dino.animations.add('jump', [2], 5, false);
_dino.animations.add('stay', [3], 5, false);

// public fields

this.fDino_jump = _dino_jump;

User data

The data property of the sprites is a reference to an empty object where the user can put any attribute. Often this data is used top create small variations between the sprites without the need to create new sprite types (or prefabs). In Phaser Editor you can set the JSON value of that property. When the user click it to edit it opens a dialog with a text editor where you can write the JSON values:

The dialog to edit the data content.

For example, if you have some enemies in a level that walk from one side to other, you can set in the data property the velocity and the left and right borders of the enemy walk. Each enemy will get a different movement range. In the update method of the level you can read that information for each enemy and update its position.

Texture

Canvas support three different type of textures: image, sprite-sheet frame and atlas frame. If the sprite is based on atlas or sprite-sheet, the user can change the frame by editing the frameName or frame property. In addition there is a Change Texture command that allow the user to replace the texture for any other texture type. This command is available in the context menu Sprite > Change Sprite Texture or can be executed by pressing Ctrl+T. It opens a dialog with all the textures declared in the asset pack. This command allow to select more than one sprite so you can change the texture of all of them.

A dialog to change the texture of the selected sprites.

Another nice command is Sprite > Select All Sprites With Same Texture, it selects all the sprites in the same scene with the same texture of the selection. It helps to replace demo textures by final textures.

In addition Phaser Editor provides texture refactorings, it is a process that allow to change the texture of all the sprites of all the scenes. You can read more about it the Global replace texture section.

Button properties

The button object (Phaser.Button) inherites all the properties from the sprite and adds the following:

Property Documentation
callback The function to call when the button is pressed.
callbackContext The context which the callback will be called (this by default).
overFrame The frame/frameName when the button is in the Over state.
outFrame The frame/frameName when the button is in the Out state.
downFrame The frame/frameName when the button is in the Down state.
upFrame The frame/frameName when the button is in the Up state.

When the user click to edit any of the (over/out/down/up)Frame parameters it shows a dialog to select the new frame, from the list of frames of the same texture, atlas or sprite-sheet.

TileSprite properties

These are the tile properties supported by Canvas:

Property Documentation
tilePosition.x/y The offset position of the image that is being tiled.
width The width of the tiling sprite.
height The height of the tiling sprite.
tileScale.x/y The scaling of the image that is being tiled.

You can convert any sprite on a tile sprite by selecting it and press L. This command also can be used to resize the tile. It is very helpful in games with a lot of tiles. In combination with tiles you can set the scene snapping, to create scenes based on fixed-size textures.

Resizing a tile.

Group properties

Many time groups are used as proxy to apply properties or operations to all the children. Here we show the properties supported by the scene editor:

Property Documentation
physicsGroup Set to true if you want to create this group as a Physics Group. A Physics Group is the same as an ordinary Group except that is has enableBody turned on by default, so any Sprites it creates are automatically given a physics body.
physicsBodyType If physicsGroup is true this is the type of physics body that is created on new Sprites.
physicsSortDirection If this Group contains Arcade Physics Sprites you can set a custom sort direction via this property.
setAll A list of key/value pairs to generate a call to the setAll method.

Physics groups

Physics groups are created with a different syntax:

var _ground = this.add.physicsGroup(Phaser.Physics.ARCADE);
_ground.physicsSortDirection = Phaser.Physics.Arcade.LEFT_RIGHT;

And as mentioned in the previous section, the goal of these kind of groups is to automatically enable physics bodies on the children.

The setAll property

The setAll method is often used on the creation of scenes to initialize some values of the children objects. For example, if you are creating a platformer game you can group all the ground sprites on a group and set all the children to body.immovable = true in this way:

groundSprites.setAll("body.immovable", true);

Now you don’t need to write it, you can click on the groundSprites group and edit the setAll property.

The setAll property editor is very simple, it is a dialog with a key/value table. For each row of the table a new setAll method call will be generated, the first column will be generated as the property name and the second column as the property value. Note that the name is generated inside a string expression "..." but the value of the property is generated verbatim, so you can write any expression there, a string literal, a number, a boolean, a function call, the name of a variable, whatever you want.

SetAll property dialog.

Design-time object properties

There are special properties that are not directly related to any Phaser API, else these are parameters provided to customize some editor’s behaviors like code generation of objects manipulation. These properties are under the “Editor” section of the Property Grid and we are explain them here:

Parameter Documentation
varName Used as var name in the generated code and label in the Outline window. Do not confuse it with the name parameter, which is part of the Phaser API.
public To make public an object in the generated code. By default the objects variables are declared is local in the creation method, however public objects will be referenced by instance fields, so they are accesible from any other context.
pick If set to false then it cannot be selected in the scene.
generate Set to false if you need to keep the object in the scene but exclude it from the generated code.
show Set to false if you want to hide the object in the scene, but it will be included in the code generation. Useful when you want to temporarily hide distracting elements from the scene, like background objects.
closed It only applies to groups. If set to true, the group and the children are going to perform like a single object in operations like selection and dragging. It means, if you pick a child, the group is selected. Yet you can select the children in the Outline window.

Scene configuration

As you can note the scene editor has two tabs: Design and Configuration. The Design tab contains everything about the objects and the Configuration tab contains other parameters not related with any object in particular else with the scene.

The Configuration tab is splitted in two panels, the left panel show a list of sections and the right panel a grid of properties of the selected section.

The configuration of sprites and group scenes are the same, it contains only an Editor section with design/code-generation specific parameters. The state scene contains the Editor section in addition to a State section with Phaser.State related parameters.

The Editor section

This section contains a couple of parameters that are not related to any Phaser API else they are related to code generation or design functionalities:

Parameter Documentation
Scene  
width The width of the scene.
height The height of the scene.
backgroundColor The background color.
gridColor The grid color
showGrid Show the grid lines.
Snapping  
enable The snapping make it easy to place objects in a grid. You can toggle this parameter with the E key. The W key enable the snapping and set the stepWidth and stepHeight with the size of the selected object
stepWidth The X step. Press W to set this with the width of the selected object.
stepHeight The Y step. Press W to set this with the height of the selected object.
Source  
className The name of the generated class. It does not change the name of the file.
baseClass The name of the extended class, for example a custom MySprite class that extends Phaser.Sprite.
userCode A series of chunk of codes that the user can insert into the generated code. In the User code section we explain this in details.
lang The language or format of the code: JavaScript 5, JavaScript 6 or TypeScript.
generateOnSave By setting it to false it disable the automatic code generation.

State scene configuration

The configuration of sprite and group scenes are pretty the same, it only contains an Editor section. However the state scene has a State section with some paremeters related to the Phaser.State API. At the moment this section only contains a few parameters but the ideal is to have a bigger set of parameters so it makes easy to the user to configure a state. Let’s see the list of parameters supported rigth now:

Scale A section dedicated to the Phaser.ScaleManager API (game.scale).
scaleMode The scaling method used by the ScaleManager when not in fullscreen.
pageAlignHorizontally When enabled the Display canvas will be horizontally-aligned in the Parent container.
pageAlignVertically When enabled the Display canvas will be vertically-aligned in the Parent container.
Physics A section dedicated to the Phaser.Physics API (game.physics).
startSystem To start one of the selected physics engines (P2JS, NINJA, BOX2D, ARCADE).
Stage A section dedicated to the Phaser.Stage API (game.stage)
backgroundColor Gets and sets the background color of the stage. Note that it does not change the color of the scene in design-time.
Preload A section related to the Phaser loader API.
pack Like in Phaser.Loader.pack() this parameter accepts a list of sections of the pack files of the project. When you drop an asset to the scene it loads its pack section automatically, however it is possible that you create other sections with other kind of assets so in this parameter you can declare them to be loaded.
isPreloader Set to true if you like to use this state as a preloader state. More is explained in the Preloader state configuration section.
preloadSprite This parameter is shown onny if the isPreloader parameter is true. When you edit this parameter it shows a dialog to select one of the scene sprites. This sprite will be used as the preload sprite as is explained in the Phaser.Loader.setPreloadSprite() method: Set a Sprite to be a “preload” sprite by passing it to this method. A “preload” sprite will have its width or height crop adjusted based on the percentage of the loader in real-time. This allows you to easily make loading bars for games. The sprite will automatically be made visible when calling this.
preloadSprite.direction The direction parameter of the Phaser.Loader.setPreloadSprite() method. It should be HORIZONTAL or VERTICAL.

Preloader state configuration

Often games load and process all the assets in a loading screen. In Phaser this loading screen is coded in a preloader state. A preloader state is just like any other Phaser state, but the sprites are created in the preload method (instead of the create method) and the game.load.setPreloadSprite() method is used to set the sprite to be used as progress bar.

The Phaser Project wizard of the editor provides a few project layout options, one of them is the Multiple states with preloader (for larger games). We recommend to use that layout if you like to add a loading screen to your game. If you want to see a demo just select the Include demo assets parameter, it will create a project with a loading screen with a dino progress bar:

Create a project with a preloader state.

The created project contains a Preloader.canvas file with the preload sprite (the dino kid):

Preloader scene with the preload sprite.

In the Configuration tab, in the State section, you can see the isPreloader is set to true and the preloadSprite is set to logo:

Configuration of a preloader state.

When you run the project you will see how the dino is cropped from left to right as a progress of the loading. We recommend to test it on Chrome and enable the Network > Throttling parameter, because serving from localhost is too fast to see the progress.

As we commented before, a key difference between a preloader state and a common state is that the sprites are created in the preload method. Why? Because the create is called only when all the assets are loaded, but what we need is to show the progress of the assets loading. Usually what is coded in the create method is code to start the next state of the game. So the code of the Preloader.js state of the previous project looks like this:

// -- user code here --

/* --- start generated code --- */

// Generated by Phaser Editor v1.4.0 (Phaser v2.6.2)


/**
 * Preloader.
 */
function Preloader() {

        Phaser.State.call(this);

}

/** @type Phaser.State */
var Preloader_proto = Object.create(Phaser.State.prototype);
Preloader.prototype = Preloader_proto;
Preloader.prototype.constructor = Preloader;

Preloader.prototype.init = function () {

        this.scale.scaleMode = Phaser.ScaleManager.SHOW_ALL;
        this.scale.pageAlignHorizontally = true;
        this.scale.pageAlignVertically = true;

};

Preloader.prototype.preload = function () {

        this.load.pack('preloader', 'assets/pack.json');


        var _logo = this.add.sprite(299, 231, 'logo');

        this.load.setPreloadSprite(_logo, 0);

};

Preloader.prototype.create = function () {

        this.nextState();


};

/* --- end generated code --- */
// -- user code here --

User code

Usually tools like Canvas provide a dedicated runtime to load the scenes in the Phaser games, however, that practice is not in the Phaser Editor’s philosophy of support plain Phaser, so we decided to use a compiler technique. This means that the scenes files are compiled into plain Phaser code, that can be integrated into the game as any other code written by the user.

The scenes are compiled into Sprite, Group and State classes, however there are many aspects of the game that are out of the scope of the tool, like for example the logic of the game is something that you have to write yourself. In this section we explain how you can insert your own code into the files generated by the editor.

There are two main ways to insert your code: (1) by writting it directly in certain parts of the file or (2) by writing it in the userCode parameter of the scene configuration.

Writting into the code file

You are always allowed to write in any part of the generated file, but if you do not follow certain rules that code could be overwritten (lost) in the next compilation. There are very well defined sections of the file where you can write your code and it is preserved from compilation to compilation.

  • As general rule just write your code in sections where it says // -- user code here --.

  • All the files have a /* --- start generated code --- */ line at the begining of the file, you can write your code before that.

  • All the files have a /* --- end generated code --- */ line at the end of the file, you can write your code after that.

  • In JavaScript 6 and TypeScript generated files you can write your code between the comments:

    • /* sprite-methods-begin */ and /* sprite-methods-end */
    • /* group-methods-begin */ and /* group-methods-end */
    • /* state-methods-begin */ and /* state-methods-end */

These sections are created in places that allow the user to add more elements to the classes, like methods or fields.

Writting into the configuration

The other way to insert user code into the generated file is to write it in the configuration of the scene (look at the Configuration tab the Editor section). The compiler reads the content of the userCode parameter and write it into the file. In this case there is not risk to lost the code because it is saved in the Canvas file.

The userCode parameter is divided by sections that refers to different points of the generated code. The idea is to insert code into the generated methods, before and after the method’s body. For example you can add code after the body of the method create to perform other initialization routines, like create tween objects or audio objects or set other parameters to the current objects.

When you click to edit the userCode parameter it opens a dialog with a tab for method, and each tab has two text boxes, one to write the before code and other to write the after code. For example a state scene userCode has a tab for Constructor, Init, Preload and Create. All these tabs denote a method generated by the editor, so you can write your own code there.

For example let’s see a case of user code inserted in a state scene via configuration:

User code dialog.

The code set there is inserted in the create method of the compiled code:

Level.prototype.create = function () {

        this.beforeCreate();

        this.add.sprite(-175, -85, 'bg');

        var _tree_ = this.add.sprite(10, 127, 'environ', 'tree-1');
        _tree_.scale.setTo(2.0687500039674838, 2.072000037051153);

        this.add.sprite(453, 306, 'environ', 'bridge');

        this.addKeyboardShortcuts();

};

We recommend to write just few lines of code via the userCode configuration, specially because that dialog does not provide advanced features like code completion. In our demos and games what we do is to write a call to a method that was defined at the end of the file, in a protected zone, using the method explained in the Writting into the code file section.

You can open the user code dialog directly from the scene, press Ctrl+Shift+U or right click and select the Edit User Code menu option.

Public objects

In the Object properties section we mentioned the public property of an object. It is a design time property used to publish the objects beyond its context. To publish objects is needed to access a particular objects outside the create method. The concept is simple, for each public object is created an instance fild that reference it. These public fields follow the format f<ObjectName>, for example, if the object star is marked as public a field fStar is generated:

Level.prototype.create = function() {
        var _star = this.add.sprite(67, 197, 'environ', 'star');

        // public fields

        this.fStar = _star;

};

/* --- end generated code --- */

Level.prototype.update = function() {
        this.fStar.angle += 5;
};

Objects aligment and depth order

Position commands are always a powerful resource to build the layout of scenes. In Canvas we support some basic commands for alignment (left, right, top, bottom, center and middle) and for depth order (rise, rise to top, lower and lower to bottom).

Aligment

The alignment commands are avilable in the conext menu and the Canvas toolbar:

Align objects.

The aligment commands are related to the parent group of the target object. If the sprite “head” belongs to the group “dino”, and we select the “left” aligment, then the local X position of “dino” will be set to 0, it means, that it will be at the left border of the group. Note that objects with no parent are set explicity belong to the global scene group.

Depth order

Pretty similar to aligment commands there are the order commands. To apply them first you select the target objects and click on the corresponfing toolbar button or context menu option.

The “order” commands send an object back and forward, in the display list of its group.

NOTE: In Phaser there are some aligment constants and methods, but they are more (we think) about to align an object in runtime. It is a great resource for those who set the game layout “by hand”. We are exploring this new features and in future versions of Canvas we can take advantage of it or reuse some concepts, like align in a grid.

Common editing operations

Canvas support common editing operations like:

  • Cut, Copy and Paste of the objects.
  • Undo, Redo of all major operations on nodes.
  • Zoom in/out/restore. Scroll the wheel of the mouse to zoom in/out, and the Zoom 1:1 button in the toolbar.
  • Pan the scene, by hodling the middle mouse button and dragging in any direction.
  • Object selection, by clicking it or dragging the mouse and create a selection box.
  • Object moving, first you select the objects and then you drag them.

Removing distractions

The default layout in Phaser Editor is a bit charged, it opens the Project Explorer, Chains view, Problems view, Preview view and Assets view, in addition to the editor area. However, Eclipse (the platform behind Phaser Editor) has a very customizable and flexible layout. You can minimize windows and open them with a quick look, or dock the windows (the right term for them is “views”) in the screen corners or stack them. We encourage you to read the Workbench User Guide bundled in Phaser Editor.

Drag the windows to a corner or fold it with other windows:

Docked windows.

A window (like the scene editor) can be detached from the main application by dragging it away from the main window:

Stand-alone scene editor.

Double click in the scene editor tab (or press Ctrl+M), it maximizes the editor window and minimizes all the other windows around. You will get all the space for the scene editor but at the same time you can do a quick look (by clicking on its icon) to the minimized windows (like the Assets or Preview windows):

Fast view.

Other elements you can remove are the property grid and the outline windows that are inside the scene editor. To do this just click on the “side panel” icon of the toolbar:

Buttons for remove distractions.

Really you don’t need these panels all the time open, you always can edit the properties of an object by pressing Q, it opens a quick edit dialog with the the property grid inside:

Edit the object in place.

To navigate the scene you can open the Quick Outline window by pressing Ctrl+O:

Quick navigate the scene.

To quicly add objects to the scene you can use the fast view to the minimized windows but also you can use the Palette, that is a small panel where you can collect the assets to be used in the scene. In the section from the palette it is explained in details.