Amazon GameOn: Setting Up

In this article we explain how to set up your development environment to work with the Amazon GameOn APIs. GameOn is a set of APIs from Amazon that are built on the AWS cloud infrastructure and that work on any operating system. The APIs are powerful yet simple to use and bring leaderboards, leagues, and multi-round competitions to your games, as well as the tools to strengthen your fanbase and community by allowing players and streamers to create their own user-generated competitions.

Note that GameOn is a paid service based on player usage, and so you will be asked to provide bank details if you wish to earn money as an Amazon developer and as part of the AWS registration you need to provide valid payment credit or debit card details (it is not possible to skip this). There are no setup fees or minimum charges, enabling you to dive in and start experimenting without worrying too much about the cost just now, as you won't be charged anything until you hit Amazon's query threshold (see here for the current thresholds and costs).

 

Setting Up Amazon

Before you can get started using the GameOn APIs, you will first need to be a registered Amazon Developer and then get your API keys from GameOn. You can become a developer from the following link:

You will also need an AWS account ID, as GameOn partners with AWS for billing to streamline the payment process across your Amazon services. This ensures you only pay for what you use. To set up an AWS account you will need to go here first (as a developer, you should already have one and so can sign in using your developer login details):

Once signed in, you need to go to your account details (from the AWS Management Console in the top-left, click your username and select Account). Here you can get your AWS ID:

GameOn_AWSAccountID.png

Take note of this as we'll need it in a moment when setting up the GameOn APIs for a project.

IMPORTANT! The GameOn app registration will send a verification message to the AWS S3 console, so you should also ensure that this is set up correctly. From the AWS dashboard, click the Services link at the top and select S3. Ensure you have supplied proper contact and billing details, otherwise the setup will not complete (and it may take a day or two even then).

Once signed-up and with your AWS ID ready, it's time to go to the GameOn page and request an API key by registering your game:

GameOnSignUp.png

Clicking that button will ask you to sign in with your Amazon account and then take you to your GameOn Dashboard where you can register your first game:

GameOn_RegisterApp.png

Clicking the Get API Keys button will then open a window requesting some basic information, which should be filled out as required for the game being registered:

GameOnGameDetails.png

It is important to note that the current implementation of the GameOn API in GameMaker Studio 2 does not support Advanced Security so you should leave that disabled.

If your game is directed at children then you may enable the second option, but be aware that there are some strict guidelines for games in this category.

Click Continue when ready.

Now you will be required to give the AWS account ID that the game should be linked to. Remember, GameOn is free to setup, but it is a paid service. For full details of the potential costs, please see the following page:

Once you supply your AWS account ID, it will need to be verified by supplying a code that will have been sent to the AWS console (follow the on-screen instructions, which contain a link to the correct page). Once that's been added, your new GameOn project should be created and you will be presented with a screen showing you the different API keys:

GameOn_GameRegistered.png 

You should take note of the Public API Key, as we'll need that for use in GameMaker Studio 2.

At this point you may now want to go on and create prizes and competitions, etc., while you're on the website, but for this tutorial we'll skip that and show you how to add the GameOn APIs to a GameMaker Studio 2 project first.

 

GameMaker Studio 2 

The first thing you will have to do in GameMaker Studio 2 is to download the GameOn asset from the Marketplace. You can find the store page from the link below:

Once you have added this free asset to your account, you should download the package via the My Library window (accessed from the Marketplace menu in GMS2). If you already had GMS2 open, remember you might need to refresh your My Library page before the GameOn asset will appear.

Download and then import the GameOn asset to a project in GMS2, and now you should take a moment to look it over and familiarise yourself with the way it works, as it is a bit different to how other assets have worked previously, since there are no Extensions with functions in this asset, just the GameOn API and a number of scripts and objects/instances that work together using a promise system.

 

Promises

Promises are helper instances that provide a simpler way of handling specific API requests without you having to manually handle the usual centralised GameMaker Studio 2 async HTTP events, and they are returned by every API call helper function in the GameOn asset.

GameOn_PromiseList.png

These promises provide specific ways for handling a GameOn API request succeeding or failing, either by allowing the user to provide callback scripts for handling the request, or by providing a "delegate" instance that handles the success/failure of a specific request in its user events.

On top of handling request success/failure, promises will also automatically parse the returned data into a helper data instance, where each data field is mapped to an instance variable, which simplifies reading returned data greatly. No more parsing DS maps in the async event, instead you'd simply poll the promise like this:

var _delegate = promise.delegate_instance
var _requestID = promise.request_id
var _status = promise.status

In the case of an error, the promise will also attempt to parse any error message/data returned and store them in the promise instance.

NOTE: You can see the initial variables defined in all promise instances by looking in the Create Event of the object oGameOnPromise.

So, essentially every GameOn API call will return an "oGameOnPromise" instance, which will be responsible for handling that particular request, parsing its data and then triggering user events or scripts to handle the request success/failure/progress. As this promise is an instance, you can process it at the time of your choosing and keep it in the room to get data from at any time, although you should destroy all instances once you no longer need the data they contain.

 

Initialising GameOn

Before making any GameOn API requests, the project will need to first initialise a GameOn client via gameon_init(). When calling this script you can specify whether to register a new player, load an existing player, or simply do nothing (in which case you would have to handle the registering and authentication yourself).

NOTE: The init script can also take 4 other optional arguments. The first one is for secure logging in only, and currently isn't supported, while the second is for supplying a different API URL to the default. The last two permit you to set callback scripts to run instead of using the "delegate" instance User Events (see below).

Let's have a look at some code to illustrate how this works, first of all using the delegate system and then an alternative using callback scripts, so then you can pick which one you prefer. Remember, you'll need your GameOn API key from when you set up the Amazon GameOn dashboard.

 

Delegate System

var _promise = undefined;
var apiKey = "fad9fb95-1a0b-4e71-b620-25d220852508";
if gameon_util_session_data_exists()
    {
    _promise = gameon_init(apiKey, eGameOnAuth.LOAD_EXISTING);
    }
else
    {
    _promise = gameon_init(apiKey, eGameOnAuth.REGISTER_NEW);
    }
if(gameon_util_object_exists(_promise))
    {
    _promise.delegate_instance = id;
    _promise.delegate_event_success = 0;
    _promise.delegate_event_failure = 1;
    }
else gameon_util_log("GameOn authentication request could not be sent");

This code would go in the Game Start event of an instance in the game, or, if you want players to opt-in to GameOn, it could go in a button press event or something like that. All it does is check to see if there is some previous session data saved and if there is it will use that to authenticate and start a session, and if not then it will register a new player and start the session. 

Now, the important thing to note here is that the gameon_init() function will return a promise (an instance ID), which can then be checked for data or have values set on it. In this case, we are telling the promise that the "delegate" instance is the same as the one that called gameon_init(), and that the success or failure of the function will be dealt with using User Event 0 and User Event 1 of that instance.

NOTE: The "delegate" instance, is an instance in your game that is designated for handling async returns from the given "promise".

 

In the delegate instance a variable will be added (or set, if it exists already) to hold the ID of the promise instance:

delegate_current_promise

Then in the relevant user events you can have something like: 

// Event USER 0
gameon_util_log("GameOn successfully initiated!");
gameon_util_object_destroy(delegate_current_promise);
delegate_current_promise = undefined;

// Event USER 1
gameon_util_log("GameOn failed to initiate!");
gameon_util_object_destroy(delegate_current_promise);
delegate_current_promise = undefined;

 

Callback System

If you wanted to use scripts instead of setting a delegate instance and events, then the initialisation code would look like this:

var _promise = undefined;
var apiKey = "fad9fb95-1a0b-4e71-b620-25d220852508";
if gameon_util_session_data_exists()
    {
    _promise = gameon_init(apiKey, eGameOnAuth.LOAD_EXISTING, undefined, undefined, scr_GameON_Callbak_True, scr_GameOn_Callback_False);
    }
else
    {
    _promise = gameon_init(apiKey, eGameOnAuth.REGISTER_NEW, undefined, undefined, scr_GameON_Callbak_True, scr_GameOn_Callback_False);
    }
if(!gameon_util_object_exists(_promise))
    {
    gameon_util_log("GameOn authentication promise could not be generated.");
    }

So, the init function will return a promise, and the promise is set to trigger User Events 0 or 1 on the calling instance - or a set of scripts - depending on the success or failure of the initialisation. How you deal with that callback will depend on the method used.

In the scripts that are used for the callback, the argument[0] will always be the ID of the promise that generated the callback, so the code you would have would look something like this:

// Script Success
gameon_util_log("GameOn successfully initiated!");
gameon_util_object_destroy(argument[0]);

// Script Failure
gameon_util_log("GameOn failed to initiate!");
gameon_util_object_destroy(argument[0]);

In both cases, this is just a simple log code to inform us that something has succeeded or failed, but in your own project you would instead add whatever code you require to be performed at this time.

 

Cleaning Up

It is worth noting that when working with the GameOn extension, all "promise" instances should be cleaned up when no longer required, and if the variable used to store the promise ID is being re-used, it should be set to undefined afterwards to prevent "instance does not exist" messages and other possible errors later on when running your game.

 You can find the Amazon documentation for the Register and Authorise endpoints here:

 

Checking The GameOn API

As you use the GameOn API it's often necessary to check whether it has been initialised correctly and the current player has been authenticated. For that, the asset provides the following two scripts:

  • gameon_is_initialized(): Call this if you want to check that the GameOn client has been initialised correctly. This will return false if it has not, and true if it has (regardless of whether a user has been authenticated or not).

  • gameon_is_logged_in(): Call this if you want to check that a user has been authenticated and logged-in. This will return true of the user has been authenticated, and false if not. Note that it will also return false if the GameOn API hasn't been initialised.

 

Getting A Player Name

By default when a player registers they will be assigned a name like "player7826" or something. This is obviously not very personal, and when it comes to submitting scores and getting leaderboard data, having the player use a name they have chosen would be better. To help with this, the GameOn API permits users to submit their own name for use, using the script gameon_player_update():

if gameon_is_logged_in()
    {
    var _promise = gameon_player_update(global.PlayerName);
    if(gameon_util_object_exists(_promise))
         {
         _promise.delegate_instance = id;
         _promise.delegate_event_success = 0;
         _promise.delegate_event_failure = 1;
        }
    else
        {
        gameon_util_log("GameOn Player Update promise could not be generated.");
        }
    }

This will set the player name to the value provided (in this case, whatever is the value of the global.PlayerName variable, but you could for example use an async dialog to ask the player for a name to use).

  You can find the Amazon documentation for the Update Player endpoint here:

 

Logging Out

Logging out of the GameOn API is done using the script:

  • gameon_destroy(removeSession)

You can call this at any time and the GameOn API will end the current session, logging out any users. When you call this script you can set the removeSession argument to true and the API will delete any session data that has been stored on the device, whilst setting it to false will not clear the data and so the next time the API is initialised the same user session data can be used.

 

Summary

That's the end of this article, and you should now have a project that can initialise and log a user into the GameOn API, as well as have an idea of how the GameOn extension works in GameMaker Studio 2. You can check that this is the case by running the project and checking the Output log in GMS2. If all has gone correctly you should see something like this:

GameOn_Output.png

Now that it's all working, you can move on and start to add in the rest of the API components that your game requires. To help you along, there is an additional article available that talks about each of the available features that Amazon GameOn offers, as well as explaining how to set them up in GameMaker Studio 2:

 

 

 

 

 

 

Have more questions? Submit a request

0 Comments

Article is closed for comments.