GameMaker: setup

The GameMaker library is a set of GML scripts and one object. Every call is asynchronous: it returns at once, and your callbacks run when Scoreboat answers.

Adding it to your game

1. Download the newest GameMaker package, scoreboat-gml-<version>.yymps, from Releases, or straight from this link.
2. Open your project and choose Tools → Import Local Package with the package you downloaded.
3. Import everything in it: the scoreboat folder, with the library's scripts, the hashing functions it signs with, and the object scoreboat_network_listener_object.

To update, delete the scoreboat folder from your project and import the newer package the same way.

Which version you have

sb_macro holds the version you imported:

show_debug_message("Scoreboat " + SB_VERSION);

A released package is already pointed at Scoreboat, so there is nothing to configure. sb_macro also says where signed-in players are remembered between runs (_sb_player_store, an ini file in the game's save area) and how early tokens are refreshed.

Starting up

Call sb_init once, early, with your game id and the key's prefix and secret:

sb_init("aX9k2Qp", "your-key-prefix", "your-key-secret")
    .success(function(_info) {
        show_debug_message("Scoreboat is ready");
    })
    .fail(function(_error) {
        show_debug_message("Scoreboat failed: " + _error.message);
    });

The library creates scoreboat_network_listener_object by itself. It is persistent and handles HTTP and socket replies; leave it alive.

The library only supports shared secret keys. Issue the key with Authentication: Shared secret in the dashboard.

Tokens are refreshed automatically before they expire. sb_ready() is true while the library holds a good token.

Callbacks and errors

Every call that talks to Scoreboat returns a request handle. Pass callbacks as the last two arguments, or chain them:

sb_leaderboard_scores("H7fj2Kp", { limit: 10 })
    .success(function(_page) { scores = _page.scores; })
    .fail(function(_error) { show_debug_message(_error.message); });

A failure gets { stage, http_status, message }. http_status is the HTTP status, or -1 when the call never reached Scoreboat: the library was not ready, or the network failed. The API overview explains what each status means.

Players

Most calls that write something belong to a signed-in player. The simplest setup is guests: the device becomes a player with no account, and stays the same player every time the game runs.

sb_player_resume()
    .fail(function() { sb_player_guest(); });

sb_player_resume signs back in as whoever was signed in last time, without asking. When there was nobody, fall back to a guest or to your own sign-in screen with sb_player_login and sb_player_register. A guest who registers keeps everything they have done.

sb_player() is the signed-in player, with their public id.

Leaderboards

sb_leaderboard_submit("H7fj2Kp", "", score)
    .success(function(_entry) {
        show_debug_message("Rank " + string(_entry.rank));
    });

Submitting signs the device in as a guest first if nobody is signed in, so a game without accounts needs nothing else. Passing "" as the name uses the player's display name.

Files and rooms

Files and rooms work the same way: see sb_file_* and sb_rt_* in the function reference. Folder rules decide what a game may do in a bucket, so set them up first in the dashboard; rooms must be turned on for the game.

More than one key

A game that needs two keys at once, such as a tool that also uses a server key, can make extra sessions with sb_session_create and switch between them with sb_session_use. Most games never need to.

Every function

The function reference lists every public function with what it takes and what it answers, read from the library's own source.