Instant Games have their own special preloader. You may have seen it before. Here's a screen shot from the Instant Game Rock Paper Scissors:

The circle spinner, and percentage loaded value below it, is created by the Facebook platform automatically. The image within the circle comes from the icons you upload when creating your app.

Although you cannot change the visuals of this loader, you do have control over how it fills up. So, you can match the loading of assets in your game with the progress of the spinner.

To do this use the showLoadProgress() method. Here is an example preloader Scene:

class Preloader extends Phaser.Scene {

    constructor ()
    {
        super('Preloader');
    }

    preload ()
    {
        this.facebook.once('startgame', this.startGame, this);
        this.facebook.showLoadProgress(this);

        this.load.image('zero2', 'assets/zero-two.png');
        this.load.image('stats', 'assets/stats.png');
    }

    startGame ()
    {
        this.scene.start('MainMenu');
    }

}

Calls to this.facebook in the above code are directly referencing the Phaser Instant Games plugin. By calling showLoadProgress from within a preload method it links the progress of the Loader with the external Facebook progress circle. We then load a couple of images for demonstration purposes. You can load as many assets as you like here, although you should do your best to keep the initial load small, so the game starts as quickly as possible.

The Instant Games Plugin makes heavy use of internal Phaser events. In the code above you'll notice we wait for the startgame event:

this.facebook.once('startgame', this.startGame, this);

This event is dispatched when the asset loading completes and your Instant Game has finished handshaking with the Facebook platform.

Starting without a Preloader

If you don't need to load any assets you should call the gameStarted method instead and then wait for the startgame event:

class Preloader extends Phaser.Scene {

    constructor ()
    {
        super('Preloader');
    }

    create ()
    {
        this.facebook.once('startgame', this.startGame, this);
        this.facebook.gameStarted();
    }

    startGame ()
    {
        this.scene.start('MainMenu');
    }

}

Either way, you should still wait for this event before carrying on with your game. When the event fires it calls the startGame method, which in turn changes to the Main Menu Scene.

Here is a re-cap of the game flow:

1. Include the Instant Games SDK via a script tag in the html.
2. Wait for the FBInstant.initializeAsync promise to resolve. Once it does, create your game instance.
3. Within your game you call showLoadProgress if you wish to link your preloader to the Facebook one. Or call facebook.gameStarted() if you don't need to load assets.
4. Listen for the startgame event from the plugin. Only when you have received this are you ready to make requests to the API.

You need to plan for this flow regardless of your type of game. Once you've received the startgame event things get exciting and the power of the API is finally available to you.