The scene compiler

Traditionally, a game engine has its file format to create scenes and part of its API is focused on the integration with a scene editor.

Phaser is not a traditional game engine, it is a framework, and is not attached to any particular tool. To create a Phaser game you only need a simple text editor.

Of course, Phaser provides API to interact with some widely used, third-party formats like texture atlas, tilemap, bitmap fonts, etc… But there is not a complete scene format where all the elements could be integrated.

For the Scene Editor, we use a custom scene-file format, but instead of creating a custom library to parse and create the Phaser scenes on the fly, we created a compiler.

The scene compiler takes as input the custom scene files (based on JSON) and generates well-written Phaser code. In other words, the scene compiler writes the Phaser code for you.

This has some advantages:

Your game doesn’t need to load an extra, third-party library.
You have full comprehension of how the scene objects are created.
A modern JavaScript editor can process the scene code and integrates it with the content assist tools.
You can customize certain aspects of the generated code and/or insert your code.

Executing the compiler

You have multiple options to compile a scene file:

When you save the modifications of a scene file in the Scene Editor the scene is compiled automatically.
In the context menu of the Scene Editor you can click on the Compile Scene command.
The Compile Project command compiles all the files of the project, including the scene files. You can execute the command with the Ctrl+Alt+B keys. It is also available in the Main menu.

User code

The Scene Editor helps to build game levels, but it is far away to cover all aspects of a game. Especially, the game logic should be implemented by you, writing code.

In Phaser programming, it is common to see, in the same file, code to create the objects of the level (what the Scene Editor is good for) and code to handle the interaction between the objects (the game logic, that is not targeted by the Scene Editor).

We designed the scene compiler to allow you to merge the generated code with your code, in the same file.

The concept is simple:

The scene compiler creates the initial JavaScript file.
The initial file contains protected regions, where the user can insert its code. These regions are delimited by JavaScript comments like /* START-USER-CODE */ and /* END-USER-CODE */.
You can insert your code inside the protected regions.
The next time the file is updated by the compiler, the user protected regions are preserved, it means, your code is not changed, only the code generated by the compiler is updated.

The scene compiler uses different comments to delimit the user code:

From the beginning of the file to the start of the /* START OF COMPILED CODE */ comment.
From the end of the /* END OF COMPILED CODE */ comment to the end of the file.
From the end of the /* START-USER-IMPORT */ comment to the start of the /* END-USER-IMPORT-CODE */ comment.
From the end of the /* START-USER-CTR-CODE */ comment to the start of the /* END-USER-CTR-CODE */ comment.
From the end of the /* START-USER-CODE */ comment to the start of the /* END-USER-CODE */ comment.

The next image is an example. Look that you can import a MyUtils class and use it in the create() method:

User code.

Editing the generated code

The code generated by the scene compiler can be edited in an external editor (like Visual Studio Code) or using the Monaco editor that is built-in in Phaser Editor.

We recommend you to read the Code Editor chapter.

The Scene Editor provides two commands to quickly edit the code file generated by the scene compiler:

The Open Output File command opens the generated file in a new Code Editor, in the traditional way.

The Open Output File in VS Code (Ctrl+Alt+E) command launches a local Visual Studio Code instance (or any other configured external editor) that opens the generated file.

The Quick Edit Output File command (bound to the Q key) opens the generated file in a Code Editor that is embedded in a modal dialog. This way is perfect for quick modifications, however, intellisense and all the other Monaco editor features are enabled, so you have a similar experience in comparison with the traditional way of editing.

Quick editing of compiled code.

Compiler settings

The scene compiler uses two different sets of parameters to refine the code generation of a Phaser scene and a prefab file. However, there are general, or shared settings, used in both cases:

General settings.

The parameters:

Generate Code: un-check it if you don’t want the compiler to compile the file. In the Using a prefab as a black box section there is an example that uses a scene file without code generation.
Output Language: you can select if the scene is compiled into JavaScript or TypeScript. In case you select TypeScript, you need to compile yourself the TypeScript generated files, with the TypeScript compiler (tsc).
Fields In Constructor (JS): enable this for generating the initialization of the attributes in the class constructor. By default it is false and the fields are initialized in the class declaration. This parameter is used only when the output language is JavaScript.
Declare Fields (JS): disable this field to skip declaring the fields in the class. This is useful when you want to use the fields in the class without declaring them. This parameter is used only when the output language is JavaScript.
Export Class (ES Module): includes the export default class modifiers.
Auto Import (ES Module): adds “import” statements for importing the types used in different parts of the code generation. Code written by the user is not processed. If you use other types, you should import them manually.
Super Class: you can force the generated class (prefab or scene), to extends the given class. If empty, the compiler will detect the appropriate class.
Insert Spaces: if checked, the tabs will be converted to spaces.
Tab Size: the number of spaces to be used if the Insert Spaces option is checked.

By the way, the name of the file and the class that is generated by the compiler is the same as the scene file. For example, a Zombie.scene file is compiled into Zombie.js (or Zombie.ts) and the name of the class will be Zombie.

Scene settings

The compilation of a Phaser scene can be tweaked with the Compiler Scene Settings:

Scene settings.

Scene Key: you can set the Phaser.Scene configuration key. Is optional.
Only Generate Methods: if checked, instead of generate a Phaser.Scene class, the compiler generates only the create and preload methods:

Only generate methods.

This could be useful if you want to create the objects using any context:

create.call(anySceneLikeContext);

Create Method: the compiler generates all the “creation code” in a method with the name you set in this parameter. By default, the name is editorCreate. The first time you create a scene, it has a create method that calls the editorCreate method generated by the editor:

/* START OF COMPILED CODE */

class Level2 extends Phaser.Scene {

    constructor() {
        super("Level2");

    }

    editorCreate() {

        // dino
        const dino = this.add.image(346, 233, "dino");

        // fields
        this.dino = dino;
    }

    /* START-USER-CODE */

    // this is the method called by Phaser,
    // when the scene is created.
    create() {

        this.editorCreate();

        // you can add more code here

        this.dino.setInteractive()
            .on("pointerdown", () ={
                // do something
            });
    }

    /* END-USER-CODE */
}

/* END OF COMPILED CODE */

Preload Pack Files: you can select the pack files to be loaded in the scene. If you click on the button, it opens the Select Pack Files dialog:

Load asset pack files.

If you select to load a pack file, then the compiler generates a preload method:

class Level extends Phaser.Scene {

    preload() {
        this.load.pack("asset-pack", "assets/asset-pack.json");
    }

    create() {
        // ...
    }
}

Preload Method: like the Create Method, you can change the name of the preload method generated by the compiler. Then, you can write your own preload method and call the one of the editor.