Fifth article in series on building games, that are easy to maintain. This time we will continue on how to manage different sponsor APIs in easy way.

last checked with Phaser 3.12.0 – beta 2

Goal

Today we will continue on managing different sponsor APIs. Last time in part 1 we build solid base for handling different events by different sponsors. We also created system for loading external config file for each sponsor, that overrides default config values. Today we will add more examples, how to use it.

Adjustments

First, let’s make some small adjustments to our code. Open Preloader.ts scene and change crate() method to this:

        // --------------------------------------------------------------------
        public create(): void {
            console.log("Preloader");

            let self = this;

            // load user settings
            Utils.StorageUtils.load(App.Config.SAVE_KEY)
                .then(function (data: any) {
                    // if data is not null and not undefined
                    if (data != null) {
                        App.settings = data;
                        console.log("Settings loaded...");
                    } else {
                        console.log("No saved settings.");
                    }

                    // continue to menu
                    self.scene.start("Menu");
                });
        }

We are moving load setting code from Game.ts to here. Newly, we are waiting for loading to finish and after then, we continue to Menu scene. Let’s also delete the same code from it previous location in Game.ts:

            // load user settings
            Utils.StorageUtils.load(App.Config.SAVE_KEY)
                .then(function (data: any) {
                    // if data is not null and not undefined
                    if (data != null) {
                        App.settings = data;
                        console.log("Settings loaded...");
                    } else {
                        console.log("No saved settings.");
                    }
                });

And while we are inside Game.ts file, we will add new Play scene. Put following line into it – it will report error for now, as we did not create Play.ts file yet:

            // states
            this.scene.add("Boot", Boot);
            this.scene.add("Preloader", Preloader);
            this.scene.add("Menu", Menu);
            this.scene.add("Play", Play);

Play scene

As we will need some more buttons and pictures, assets for this part were updated. You can download it from GitHub. Graphics was made by Tomáš Kopecký and we used it in our HTML game Woodventure.
Create new file Play.ts in Scenes folder and put following code into it:

///<reference path = "SceneBase.ts" />

namespace MaintainableGame {

    export class Play extends SceneBase {

        // --------------------------------------------------------------------
        public create(): void {
            console.log("Play");

            // bacground color
            this.cameras.main.backgroundColor = Phaser.Display.Color.ValueToColor(0xB8C6FF);

            // focus on 0, 0
            this.setView();

            // back icon
            this.addControlls();

            // add some animation
            this.buildScene();
        }

        // --------------------------------------------------------------------
        private addControlls(): void {
            let y = -this.gameHeight / 2 + 50;
            let x = -this.gameWidth / 2 + 50

            // menu icon
            let menu = this.add.sprite(x, y, "Sprites", "IconMenu");
            menu.setInteractive();
            menu.on("pointerdown", function (this: Play) {
                this.backToMenu();
            }, this);
        }

        // --------------------------------------------------------------------
        private buildScene(): void {

            // create pig animation if it does not exist
            if (typeof this.anims.get("pig") === "undefined") {
                this.anims.create({
                    key: "pig",
                    frames: this.anims.generateFrameNames("Sprites", { frames: ["pig01", "pig02", "pig03", "pig04", "pig05", "pig06", "pig07"] }),
                    frameRate: 3,
                    repeat: -1
                });
            }

            // add pig sprite and play animation
            let pig = this.add.sprite(0, 0, "Sprites");
            pig.anims.play("pig");
        }

        // --------------------------------------------------------------------
        private backToMenu(): void {
            // empty for now ...
        }
    }
}

It creates simple scene with animated pig for fun in the middle of the screen. There is menu icon in top left corner that will later send you back to Menu scene. For now it just calls empty backToMenu() method. Usually, sponsors want to report when player exits game and backToMenu() method is good place, where we will place sponsor API calls.

Menu scene adjustments

Open Menu.ts file. So far we had only music and sound controls in this scene. We will add play button, so we can start Play scene. Also sponsors want to report when game started, so pressing play button is right time to report it.

First add following line in create() method:

            // sound and music icons
            this.addAudioControlls();

            // add play button
            this.addPlayButton();

Add addPlayButton() method:

        // --------------------------------------------------------------------
        private addPlayButton(): void {
            // play
            let play = this.add.sprite(0, 0, "Sprites", "IconPlay");
            play.setInteractive();
            play.on("pointerdown", function (this: Menu) {
                this.startGame();
            }, this);
        }

It simply adds interactive sprite with look of play button and it calls startGame() method when it is pressed. Method is not defined yet, so you will get error.

Calling sponsor API

Let’s continue with Menu.ts. Define startGame() method with following code:

        // --------------------------------------------------------------------
        private startGame(): void {

            let self = this;

            // report start of game
            Sponsor.api.startGameSession()
                .then(function () {
                    self.scene.start("Play");
                });
        }

        // --------------------------------------------------------------------
        private backToMenu(): void {

            let self = this;

            // report end of game
            Sponsor.api.endGameSession({ score: 12345, level: 10 })
                .then(function () {
                    self.scene.start("Menu");
                });
        }

        // --------------------------------------------------------------------
        public async startGameSession(...parameters: any[]): Promise<void> {
            console.log(`Sponsor ${eSponsorID[this.id]}: startGameSession() with parameters ${parameters}`);

            await new Promise<void>(function (resolve) {
                console.log("starting timeout - 3 secs");

                setTimeout(function () {
                    console.log("timeout over");
                    resolve();
                }, 3000);
            });
        }

        // --------------------------------------------------------------------
        public async endGameSession(...parameters: any[]): Promise<void> {
            console.log(`Sponsor ${eSponsorID[this.id]}: endGameSession() with parameters ${parameters}`);

            if (typeof parameters[0] !== "undefined") {
                console.log("pramaters = " + JSON.stringify(parameters[0]));
            }

            await new Promise<void>(function (resolve) {
                console.log("starting timeout - 3 secs");

                setTimeout(function () {
                    console.log("timeout over");
                    resolve();
                }, 3000);
            });
        }

    <span class="token comment">// sponsor</span>
    <span class="token keyword">export</span> <span class="token keyword">const</span> sponsor<span class="token punctuation">:</span> Sponsor<span class="token punctuation">.</span>eSponsorID <span class="token operator">=</span> Sponsor<span class="token punctuation">.</span>eSponsorID<span class="token punctuation">.</span>SBC_GAMES<span class="token punctuation">;</span>

    export class SponsorSBCGames extends Sponsor implements Utils.ISponsorStorage {

        // --------------------------------------------------------------------
        public constructor(features: ISponsorFeatures) {
            super(features);

            Utils.StorageUtils.sponsorStorage = this;
        }

        // #region ISponsorStorage interface implementation

        // --------------------------------------------------------------------
        public async save(key: string, data: any): Promise<void> {

            let storage = window.localStorage;

            await new Promise<void>(function (resolve) {
                console.log("saving somewhere into cloud - it will take 3 seconds");

                setTimeout(function () {
                    console.log("data saved");
                    storage.setItem(key, JSON.stringify(data));
                    resolve();
                }, 3000);
            });
        }

        // --------------------------------------------------------------------
        public async load(key: string): Promise<any> {

            let storage = window.localStorage;

            let result = await new Promise<void>(function (resolve) {
                console.log("loading from cloud - it will take 3 seconds");

                setTimeout(function () {
                    console.log("data loaded");
                    let data = storage.getItem(key);
                    console.log("data  = " + data);

                    resolve(data == null ? null : JSON.parse(data));
                }, 3000);
            });

            return result;
        }

        // --------------------------------------------------------------------
        public fallbackToStandardStorage(): boolean {
            return false;
        }

        // #endregion

        // --------------------------------------------------------------------
        private saveSettings(): void {
            Utils.StorageUtils.save(App.Config.SAVE_KEY, App.settings)
                .then(function () {
                    console.log("Settings saved...");   
                }).catch(function (e) {
                    console.log(e);
                });
        }

        // --------------------------------------------------------------------
        public someVerySpecificSponsorFunction(): void {
            console.log("Very sponsor specific function for SBCGames");
        }

        // --------------------------------------------------------------------
        private backToMenu(): void {

            let self = this;

            // report end of game
            Sponsor.api.endGameSession({ score: 12345, level: 10 })
                .then(function () {
                    self.scene.start("Menu");
                });

            // some very special SBCGames function
            if (Sponsor.is(Sponsor.eSponsorID.SBC_GAMES)) {
                (<Sponsor.SponsorSBCGames>Sponsor.api).someVerySpecificSponsorFunction();
            }
        }