GameStarter - Grisgram/gml-raptor GitHub Wiki

Two of the most important moments in a game are the "start" and the "end" of the game.

While the former creates your globals and prepares everything your game needs, the latter is responsible for cleaning up and maybe disconnecting from any external resources or servers.

This is, what the GameStarter is designed for.
It generalizes the moments of the game start by abstracting the initialization of the first room (rmStartup), loading your settings and invokes two callbacks: onGameStart and onGameEnd.

These functions are defined in the Game_Configuration script of the _GAME_SETUP_ folder of the project, thus taking away the need of fiddling code into any events of objects and instead provide a clean function where you can do your initialization tasks.

But the GameStarter does much more for your game. Let's start with some variables.

Edit the settings of the GameStarter in rmStartup.

Most modern games communicate with a backend, be it Steam or Firebase or your own server, maybe you are even hosting your own api. These operations are asynchronous and work through callbacks, which means, your may not simply leave the rmStartup while connect requests or other async operations are still running.

GameStarter fully supports any async startup tasks, but as those are normally made in code, I did not create variable definitions for the room designer for them. Instead, they are simply variables in the GameStarter that you can modify as needed in your async code.

Remember: You can access the (persistent) GameStarter from everywhere through the GAMESTARTER macro!

Before we dive into the details it is worth noting, that by default (if you don't change any of the variables mentioned here), GameStarter will behave purely synchronous. So, if you don't have a backend or other async things to do on startup, you don't need to do anything and it "will just work".

Overview of available variables:

Variable	Default	Description
spinner_sprite	sprLoadingSpinner	There is a default spinner animation sprite included with raptor. It can be found in the _gml_raptor/UI/default_sprites folder of the project template and its name is sprLoadingSpinner. It looks like this and rotates slowly clockwise, like a standard loading animation.
spinner_font	undefined	You must set a font to be used to render the text next to the spinner animation. If you don't set a font, no text will be drawn.
spinner_text	"Connecting to server..."	Assign any text here and it will be shown on screen. The default message is just an english generic connect message, you may want to change that with localized strings from the LG Localization during your async operations.

Here is a short example of the implementation I use for game jams when connecting to my api for cloud based high scores. It's reduced to the important parts that show the manipulation of the GameStarter variables through async startup.

function connectToApi() {
    if (USE_API) {
        GAMESTARTER.wait_for_async_tasks = true;
        GAMESTARTER.async_wait_timeout = 300; // 5 seconds
        GAMESTARTER.spinner_font = fntTitle;
        GAMESTARTER.spinner_text = "Connecting to server...";
        API.connect(api_connected, api_failed);
    } else {
        // My Jam template CAN work offline, so no wait time if no api required
        GAMESTARTER.async_min_wait_time = -1;
    }
}

function api_connected() {
    GAMESTARTER.spinner_text = "Loading Highscores...";
    HIGHSCORES = API.get_highscores(highscores_loaded, api_failed); // just the next call to the api
}

function api_failed() {
    GAMESTARTER.wait_for_async_tasks = false; // <-- proceed to next room
    GAMESTARTER.spinner_text = "Server connect failed!";
    log("Api connection for highscores failed!");
}

function highscores_loaded() {
    GAMESTARTER.wait_for_async_tasks = false; // <-- proceed to next room
}