GameMaker function reference

Every public function in the library, read from the library's own comments. Setting the library up is covered in GameMaker: setup.

Starting up

sb_init

sb_init(game_id, key_prefix, secret, [on_success], [on_fail])

Authenticates against Scoreboat and gets the library ready. on_success(info) is called with { expires_at, permissions, declined } once sb_ready() is true. on_fail(error) is called with { stage, http_status, message } after the library has gone back to the uninitialized state. Returns a request handle: .success(fn) and .fail(fn) can be chained on it. Calling it while an attempt is already running joins that attempt.

sb_ready

sb_ready()

True when the current session holds a token that has not expired. Tokens are refreshed automatically shortly before they do.

sb_refresh

sb_refresh([on_success], [on_fail])

Gets a new token now instead of waiting for the automatic refresh. Joins a refresh that is already running. Fails straight away if the session has not finished sb_init. The old token stays in use until the new one arrives, and a failed refresh leaves the session as it was.

Sessions

sb_session_create

sb_session_create()

Makes a new, uninitialized Scoreboat session. Use when you need to authenticate multiple API keys at once Does not enable the created session. Pass it to sb_session_use first

sb_session_use

sb_session_use([session])

Makes every sb_* call from now on act on this session. To return to the default session, pass in nothing. Requests already sent keep the session they were made with. Returns the session that was current, so a caller can put it back:

var new_session = sb_session_create()
var _previous = sb_session_use(new_session);
sb_init(...);
sb_session_use(_previous);

sb_session_current

sb_session_current()

The session every sb_* call acts on right now: the default one, or whichever was last passed to sb_session_use.

Players

Players: the people playing the game, as Scoreboat knows them.

sb_player

sb_player()

The signed-in player, or undefined when nobody is: { id, display_name, username, email, email_verified, guest, created }. id is public: it is what score tables show and what sb_leaderboard_scores takes for its player and around options.

sb_player_signed_in

sb_player_signed_in()

True while a player is signed in on the current session.

sb_player_guest

sb_player_guest([on_success], [on_fail])

Signs this device in as a guest: a player with no account, known only by a secret Scoreboat hands out the first time and the library saves to disk. The same device is the same guest every time after that. on_success(player) is called with the player, as sb_player() returns it. on_fail(error) is called with { stage, http_status, message }. Returns a request handle: .success(fn) and .fail(fn) can be chained on it. Fails straight away if the session has not finished sb_init. A saved secret that is refused is kept. If the guest has since become an account or been removed, call sb_player_guest_forget() to start afresh.

sb_player_guest_forget

sb_player_guest_forget()

Throws away this device's saved guest secret, so that the next sb_player_guest() makes a new guest. The old guest and their scores stay on the server, but nothing can sign in as them again.

sb_player_register

sb_player_register(username, password, [options], [on_success], [on_fail])

Makes an account and signs in to it. Called while signed in as a guest it turns that guest into the account, keeping their scores and everything else they have. The guest secret stops working once it does. options is a struct, every member optional:

email          Lets the player reset a forgotten password.
display_name   The name shown to other players. The username if left out.

sb_player_login

sb_player_login(login, password, [on_success], [on_fail])

Signs in to an account. login is its username or its email. on_success(player), on_fail(error) and the return value are as for sb_player_guest. Wrong details fail with HTTP 403, and too many wrong tries in a row with HTTP 429 for a while.

sb_player_login_ticket

sb_player_login_ticket(ticket, [on_success], [on_fail])

Signs in with a ticket from the game's own server, for games that authenticate their players themselves. The server gets the ticket from Scoreboat with a key the game does not ship with; it works once and only for a couple of minutes. on_success(player), on_fail(error) and the return value are as for sb_player_guest.

sb_player_resume

sb_player_resume([on_success], [on_fail])

Signs back in as whoever was signed in when the game last ran, without asking them for anything. Call it once sb_init has succeeded. Fails straight away with HTTP -1 when nobody was, and with HTTP 403 when their sign-in has since ended. Either way, ask them to sign in again. on_success(player), on_fail(error) and the return value are as for sb_player_guest.

sb_player_logout

sb_player_logout([on_success], [on_fail])

Signs the player out. The library forgets them at once, so sb_player() is undefined as soon as this returns, whatever the server goes on to say. A guest can come back with sb_player_guest(). on_success(result) is called with { signed_out }. on_fail(error) and the return value are as for sb_player_guest.

sb_player_rename

sb_player_rename(display_name, [on_success], [on_fail])

Changes the name the signed-in player is shown under. Entries already on a leaderboard keep the name they were set with. on_success(player), on_fail(error) and the return value are as for sb_player_guest.

sb_player_password_forgot

sb_player_password_forgot(login, [on_success], [on_fail])

Mails a reset code to the account login names, if there is one and it has an email address. on_success(result) is called with { sent } either way, so that nothing is given away about which accounts exist. on_fail(error) and the return value are as for sb_player_guest.

sb_player_password_reset

sb_player_password_reset(login, code, password, [on_success], [on_fail])

Sets a new password with the code that was mailed. The player is signed out everywhere and has to sign in with it. on_success(result) is called with { reset }. on_fail(error) and the return value are as for sb_player_guest.

sb_player_email_verify

sb_player_email_verify([code], [on_success], [on_fail])

Confirms the signed-in player's email address. With no code it mails them one, and on_success(result) is called with { sent }. With the code they typed in, on_success(player) is called with the player, whose email_verified is now true. on_fail(error) and the return value are as for sb_player_guest.

Leaderboards

sb_leaderboard_details

sb_leaderboard_details(leaderboard_id, [on_success], [on_fail])

Gets a leaderboard's settings. on_success(leaderboard) is called with { id, name, description, game, ordering, secondary_ordering, unique, min_score, max_score, entries }. min_score and max_score are the lowest and highest score the leaderboard accepts, or not set when it has no such bound: a submit outside them fails. on_fail(error) is called with { stage, http_status, message }. Returns a request handle: .success(fn) and .fail(fn) can be chained on it. Fails straight away if the session has not finished sb_init.

sb_leaderboard_scores

sb_leaderboard_scores(leaderboard_id, [options], [on_success], [on_fail])

Reads the score table. on_success(page) is called with { leaderboard, count, offset, limit, next_offset, scores }, where each of scores is { id, rank, player, player_name, score, secondary_score, added, updated, extra_data }. player is the id of the player whose entry it is, as in sb_player().id. next_offset is the offset of the next page, or not set on the last one. options is a struct, every member optional:

limit, offset, page   Pagination. limit is 50 unless given and at most
                      200. page starts at 1 and overrides offset.
order                 "best" (default), "worst", "newest" or "oldest".
since, until          ISO date or datetime strings. Only scores set
                      inside them count, and rank is counted among those.
player_name, min_score, max_score
                      Narrow which entries come back. Their rank is still
                      their place on the whole table.
player                A player's id. Only that player's entries.
around                A player's id. Returns the limit entries centred
                      on that player's best one, and adds player_rank
                      and player_score (that entry's id) to the page.

Entries of banned and deleted players are left out, and not ranked against. on_fail(error) is called with { stage, http_status, message }. Returns a request handle, like sb_leaderboard_details.

sb_leaderboard_submit

sb_leaderboard_submit(leaderboard_id, player_name, score, [options], [on_success], [on_fail])

Submits a score for the signed-in player. When nobody is signed in, the device is signed in as a guest first (see sb_player_guest), so a game with no accounts needs nothing but this call. player_name is the name shown beside the entry. Pass "" to use the player's display name. on_success(entry) is called with the player's best entry on the board, which need not be the one just sent: { id, rank, player, player_name, score, secondary_score, added, updated, extra_data, improved, submitted }. improved is whether this submission is now their best. submitted is the id of the entry this call created, or not set when it updated or lost to an existing one. options is a struct, every member optional:

secondary_score   Breaks ties on score.
extra_data        Anything json_stringify can handle. Stored with the
                  entry. At most 1 MB.

on_fail(error) is called with { stage, http_status, message }. Returns a request handle, like sb_leaderboard_details.

sb_leaderboard_score_get

sb_leaderboard_score_get(score_id, [on_success], [on_fail])

Gets a single score by its id. on_success(score) is called with { id, player, player_name, score, secondary_score, added, updated, extra_data }. There is no rank here: use sb_leaderboard_scores for that. on_fail(error) is called with { stage, http_status, message }. Returns a request handle, like sb_leaderboard_details.

Files

Files. A game's files live in buckets, and a bucket is a tree of folders. Like your own little file system.

sb_file_list

sb_file_list(bucket_id, [path], [options], [on_success], [on_fail])

Lists what is in a folder. path is "/" unless given. on_success(listing) is called with { path, folders, folder_count, files, file_count, offset, limit }. Each of folders is { path, name, creator, created } and each of files is { id, path, name, size, content_type, sha256, creator, created, updated }. creator is the id of the player who made it, as in sb_player().id, or not set. Folders and files have separate rules: when the caller may see one and not the other, the one they may not see is not set, rather than empty. options is a struct, every member optional:

limit, offset   Pagination. limit is 50 unless given and at most 200.

on_fail(error) is called with { stage, http_status, message }. Returns a request handle, like sb_buckets.

sb_file_info

sb_file_info(bucket_id, path, [on_success], [on_fail])

Gets what is known about one file, without downloading it. on_success(file) is called with { id, path, name, size, content_type, sha256, creator, created, updated }. on_fail(error) is called with { stage, http_status, message }. Returns a request handle, like sb_buckets.

sb_file_delete

sb_file_delete(bucket_id, path, [on_success], [on_fail])

Deletes a file. on_success(result) is called with { deleted }, the path that was removed. on_fail(error) is called with { stage, http_status, message }. Returns a request handle, like sb_buckets.

sb_folder_create

sb_folder_create(bucket_id, path, [on_success], [on_fail])

Makes a folder. The folder it goes in has to exist already. A folder made by a signed-in player is theirs: where the rules say "the creator", they mean that player. on_success(folder) is called with { path, name, creator, created }. on_fail(error) is called with { stage, http_status, message }; a folder that is already there fails with http_status 409. Returns a request handle, like sb_buckets.

sb_file_upload

sb_file_upload(bucket_id, path, buffer, [options], [on_success], [on_fail])

Uploads the contents of a buffer as a file, replacing the file at path if there is one. The buffer is copied before this returns, so it can be deleted or reused straight away. What is sent is everything written to the buffer so far, that is, up to where buffer_tell(buffer) is; or the whole buffer when nothing has been written since it was made or loaded. on_success(file) is called with { id, path, name, size, content_type, sha256, creator, created, updated }. options is a struct, every member optional:

size           How many bytes of the buffer to send, from its start.
content_type   A media type to record with the file, such as
               "application/json". "application/octet-stream" unless given.

on_fail(error) is called with { stage, http_status, message }. A file larger than the bucket accepts fails with http_status 413, and one there is no room left for with 507. Returns a request handle, like sb_buckets.

sb_file_upload_string

sb_file_upload_string(bucket_id, path, text, [options], [on_success], [on_fail])

Uploads a string as a file. For instance json_stringify() data structures

sb_file_download

sb_file_download(bucket_id, path, [on_success], [on_fail])

Downloads a file into a new buffer. on_success(result) is called with { buffer, file }: buffer holds the file's bytes, positioned at the start, and is the caller's to buffer_delete() when done with it. file is { id, path, name, size, content_type, sha256, creator, created, updated }. on_fail(error) is called with { stage, http_status, message }. A bucket that has handed out its month's downloads fails with http_status 429. Returns a request handle, like sb_buckets.

sb_file_download_string

sb_file_download_string(bucket_id, path, [on_success], [on_fail])

Downloads a file as a string. on_success(result) is called with { text, file }. Otherwise the same as sb_file_download, with no buffer to clean up.

Rooms

Rooms. A connection to Scoreboat's socket server, where a game's clients join rooms and pass messages to everybody else in the same room.

Connect with sb_rt_connect once sb_init has succeeded (and, if the game requires it, a player has signed in). Then listen with sb_rt_on and act with sb_rt_rooms, sb_rt_create, sb_rt_join, sb_rt_leave and sb_rt_send.

Those calls do not take callbacks. The server answers each with an event, which sb_rt_on hears:

"rooms"          { rooms }, after sb_rt_rooms. Each room is
                 { id, name, members, max_members, fixed }.
"joined"         { room_info, you, members }, after sb_rt_create or sb_rt_join.
                 you is how the others see you; members are the others.
                 A member is { id, player, name }; player is the id of the
                 signed-in player, as in sb_player().id, or not set.
"left"           { room_id }, after sb_rt_leave.
"member_joined"  { room_id, member }, when somebody else comes in.
"member_left"    { room_id, member }, when somebody else goes.
"message"        { room_id, from, data }, when somebody else sends.
"refused"        { action, message }, when the server will not do
                 something: a full room, sending too fast, and so on.
"disconnected"   {}, when the connection is gone, for whatever reason.

A client is in one room at a time. Joining another leaves the one it was in.

Nothing here is called "room": that name is GameMaker's own, and setting it moves the game to another room. Fields say room_id and room_info instead.

sb_rt_connect

sb_rt_connect([on_success], [on_fail])

Connects to the game's rooms. Asks Scoreboat for a ticket with the current session, so call it after sb_init, and after signing a player in when the game requires one (it does unless its settings say otherwise). on_success({}) is called once connected. on_fail(error) is called with { stage, http_status, message }: rooms not turned on for the game fail with http_status 403. Returns a request handle: .success(fn) and .fail(fn) can be chained on it.

sb_rt_connected

sb_rt_connected()

True while connected to the socket server.

sb_rt_disconnect

sb_rt_disconnect()

Leaves whatever room this client is in and closes the connection. The "disconnected" handlers are called.

sb_rt_on

sb_rt_on(event, callback)

Calls callback(data) whenever the server sends event. See the top of this script for the events and what data holds for each. Several callbacks may listen to the same event.

sb_rt_off

sb_rt_off(event)

Stops every callback listening to event.

sb_rt_room

sb_rt_room()

The room this client is in, as { id, name, members, max_members, fixed } when it joined, or undefined.

sb_rt_rooms

sb_rt_rooms([search])

Asks for the listed rooms whose name contains search (all of them when it is ""). The answer arrives as the "rooms" event. Returns false when not connected.

sb_rt_create

sb_rt_create(name, [options])

Makes a room and joins it; "joined" follows. options is a struct, every member optional:

max_members   How many may be in it. The game's limit unless given, and
              never more than that.
listed        false to keep it out of searches, so that only those told
              its id can join. true unless given.

Returns false when not connected.

sb_rt_join

sb_rt_join(room_id)

Joins a room by its id, leaving any other; "joined" follows, or "refused" if the room is full or not there. Returns false when not connected.

sb_rt_leave

sb_rt_leave()

Leaves the room this client is in; "left" follows. Returns false when not connected.

sb_rt_send

sb_rt_send(data)

Sends data to everybody else in the room; they hear it as the "message" event. data is anything json_stringify can handle, up to the game's message size. Returns false when not connected.