Amazon GameOn: User Generated Player Tournaments

In this article we show an overview of how to let your players create their own tournaments using the Amazon GameOn API.

You must already have a game set up on the GameOn dashboard and be able to log in to the GameOn API. If this is not the case, then please see the following article before going any further:

Additionally, this article assumes that you have already have experience of creating regular tournaments and understand the general flow of the GameON API. If you haven't yet set up any tournaments or prizes, etc., then please see here:

 

The rest of this article will give you an overview of how to set up user-generated tournaments. Note that most of the code shown is designed to explain basic functionality only and uses show_debug_message() to show some of the output that the different scripts, promises and data objects return, but you'll want to replace this with actual game code in your own projects (and certainly not show debug info to your players!).

Note, this article does not cover entering matches or submitting scores, etc., as once you have one or more player tournament IDs you would then do this as explained for developer-generated tournaments in the Usage Overview article, linked above.

 

Adding A Player Tournament

Before we show you how to get the player to find user-generated tournaments, we'll show you how to have them generate one. This is done using the script gameon_util_object_create(), which will create an instance of the object oGameOnTournament. This object can then have the tournament values set on it and be used to add the tournament to the player tournaments list:

if gameon_is_logged_in()
    {
var _time = gameon_util_get_timestamp_now();
var _tournament = gameon_util_object_create(oGameOnTournament);
_tournament.title = "Test Player Tournament";
_tournament.subtitle = "User generated tournament test.";
_tournament.description = "This is a test of a user generated tournament.";
_tournament.dateStart = int_64(_time);
_tournament.dateEnd = int64(date_inc_day(_time, 1));
_tournament.playersPerMatch = 10;
_tournament.playerAttemptsPerMatch = 100;
_tournament.metadata = "meta data test text";
_tournament.hasAccessKey = false;
var _promise = gameon_player_tournament_add(_tournament);
gameon_util_object_destroy(_tournament);
    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 tournament query promise could not be generated.");
        }
    }


Once you have created the tournament, you can see that we call the script gameon_player_tournament_add() to send off the request to add it to the list of player tournaments. Once that's done, we clean up by destroying the tournament instance.

The script will generate a success or fail callback, depending on whether it went through or not, and if it succeeded then the returned promise will hold the ID of an instance of the data object oGameOnTournamentUpdate, which can be parsed to get the new tournament ID:

var _p = delegate_current_promise;
var _data_inst = _p.request_result_data_parsed;
show_debug_message("Player Tournament ID = " + string(_data_inst.tournamentId));
gameon_util_object_destroy(_p); 

 You can find the Amazon documentation for the Add Player Tournament endpoint here:

Note that you can supply much more information for the tournament than what is shown in the above example if you want, specifying things like an image URL or the score type. To see the full list of parameters, open up the object oGameOnTournament's Create event.

 

Get Player Tournaments

The GameOn API differentiates between user-generated player tournaments and "official" tournaments made by the game publisher, and as such you need to be able to retrieve the player tournaments separately. For that, we have the script gameon_player_tournament_query():

if gameon_is_logged_in()
    {
    var _promise = gameon_player_tournament_query();
    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 tournament query promise could not be generated.");
        }
    }

Here we call it with no arguments and so the returned promise will request all the available player tournaments for the project, but it can also be called with any of the optional arguments to get the data for a single tournament or to filter the results in multiple ways (see the GameOn asset's PDF manual for precise details).

When it is completed, the promise will trigger a user event and in that event we can then get the tournament data:

var _p = delegate_current_promise;
var _tournament_list = _p.request_result_data_parsed;
for (var i = 0; i < ds_list_size(_tournament_list); ++i;)
    {
    if _tournament_list[| i].canEnter == true
        {
        var _id = _tournament_list[| i].tournamentId;
show_debug_message("Tournament Id = " + string(_id.tournamentId));
show_debug_message("Tournament Title = " + string(_id.title));
show_debug_message("Player Can Enter = " + string(_id.canEnter));
        }
    }
gameon_util_object_destroy(_p);

In this code we are looping through the contents of the parsed data list for the data instance IDs of the GameOn object "oGameOnTournament". When we parse this list we check the variable "canEnter" and if that is true, we then show some of the returned data in the output console for the tournament.

Note that here we show only a few values, but you can see all the different return values by opening the Create event of the object oGameOnTournament.

Once you have a list of all tournament ID strings, you can then supply them to gameon_player_tournament_query() as the first argument to get back a data instance specific to that tournament. When doing this, instead of a list of tournaments in the "request_result_data_parsed" variable, you'll get back a data instance ID for an instance of "oGameOnTournament", which can then be parsed as above. 

You can find the Amazon documentation for the Get Player Tournaments endpoint here:

Note that player tournaments do not have access to any prizes, nor do they use any type of requirement groups, unlike the regular tournaments.

 

Updating A Player Tournament

Once a player tournament has been created it can have certain details updated at any time using the script gameon_player_tournament_update() with a tournament object oGameOnTournament:

if gameon_is_logged_in()
    {
    var _tournament = gameon_util_object_create(oGameOnTournament);
    _tournament.title = "Updated Player Tournament";
    _tournament.subtitle = "Updated player tournament subtitle");
    _tournament.tournamentId = global.Player_Tournament;
    var _promise = gameon_player_tournament_update(_tournament);
    gameon_util_object_destroy(_tournament);
    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 tournament update promise could not be generated.");
        }
    }

The only data that can be changed in this way is the following:

  • Tournament title
  • Tournament sub-title
  • Tournament metadata
  • Tournament description
  • Reset the access key (set to true/false and this will return a new access key value in the callback)

This script will generate a callback where the promise data contains an instance ID for the data object oGameOnTournamentUpdate, which can be parsed to get the tournament ID and the new access key (if one was generated):

var _p = delegate_current_promise;
var _tournament_inst = _p.request_result_data_parsed;
show_debug_message("Tournament Id = " + string(_tournament_inst.tournamentId));
show_debug_message("Access Key = " + string(_tournament_inst.accessKey));
gameon_util_object_destroy(_p);

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

 

Entering A Player Tournament

Once you have the list of available player tournaments, you'll want to present these to the user in some way and permit them to select one of them to enter and get a match ID. This selection would use the script gameon_player_tournament_enter() along with the tournament ID (and the access key if required):

if gameon_is_logged_in()
    {
    var _promise = gameon_player_tournament_enter(_tournament_list[| num]);
    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 tournament entry promise could not be generated.");
        }
    }

This will return a promise which will trigger the user events for the delegate instance when the callback has been completed. If the promise has succeeded, then you will need to retrieve the unique match ID from the returned data object (oGameOnMatchEntry) and then store it, as this will be required for all further match API calls:

var _p = delegate_current_promise;
var _match_data = _p.request_result_data_parsed;
global.match_id = _match_data.matchId;
gameon_util_object_destroy(_p);

This simply gets the match ID from the data instance that the promise returns and then stores it in a global variable for further use. This match ID will be associated with the player for the duration of the tournament, and so in subsequent runs of the game you can simply use the same match ID until the tournament finishes or the player has no attempts left.

Note that if the player has used up all their permitted attempts for the given tournament the script will trigger a fail callback.

You can find the Amazon documentation for the Enter Player Tournament endpoint here:

 

Summary

The workflow for user-generated player tournaments is very similar to that for "official" tournaments, and once you have the generated a tournament and gotten its ID you would then have the player enter it to get their match ID. This is then used to enter the match, submit a score, get prizes, etc., as outlined in the article Amazon GameOn: Usage Overview

 

 

 

Have more questions? Submit a request

0 Comments

Article is closed for comments.