Skip to content

Challenges

Jump to bottom
Francisco Dias edited this page Jan 24, 2023 · 1 revision

Back To Top

Challenges

Overview

A GX.games game can have several challenges, only one of which can be active when the game is being played. The functions given below are used to interact with the currently active challenge (if there is one). Note that the currently active challenge can be returned by calling gxc_get_query_param("challenge").

Functions

The following functions are given for working with challenges:

Structs

The following structs are given for working with challenges:



Back To Top

gxc_challenge_submit_score

Overview

This function is used to submit a new score to the currently active challenge, for the user that is currently logged in. You specify the score value to submit to the challenge, and an optional callback method which is called when a response arrives from the server. As explained on the Callbacks page, if you don't specify this argument, an Async Social event will be triggered when a response is received. The function will always return a request ID, which can be used to identify the request in an Async Social event if a callback method is not specified.

Options

You can optionally specify a struct as the third argument, containing options for challenge identification. You can include the following variables in that struct:

Variable Type Value
challengeId String The challenge ID to use (if not specified, defaults to the currently active challenge)

See the example given at the bottom of this page for more information.

Callback Arguments

The callback method will receive two arguments: _httpStatus and _result, where the former is the status code for the HTTP response and the latter is a struct containing all returned data. The _result struct (or the async_load map in the Async Social event if a callback is not specified) will contain the following variables:

Variable Type Value
data Struct A struct containing response data for the score submission request
errors Array<Response Error Codes> An array containing the errors that occurred for this request (see Response Error Codes)

It may have other variables too; see Callbacks & Async Events for more information. The data struct contains the following variables:

Variable Type Value
newBestScore Bool Whether the submitted score was the new best score for the challenge

The errors array contains structs indicating errors with the request. Each error struct will have a code variable containing an error message, all of which are listed on this page.


Syntax:

gxc_challenge_submit_score(score, [callback], [options]);
Argument Type Description
score Real The new score value for the currently active challenge; should be an integer, if a decimal value is provided it will be rounded
callback Function A callback method which is called when an HTTP response is received ✴️ OPTIONAL
options Struct A struct containing options for pagination (see above) ✴️ OPTIONAL

Returns:

Real (HTTP Request ID)

Example:

var _highscore_challenge = "34esa3a1-e41e-4a9f-aaaa-4da7bd24ada2";

if (gxc_get_query_param("challenge") == _highscore_challenge)
{
    gxc_challenge_submit_score(global.highscore);
}

The above code stores the ID of a challenge (retrieved from the GXC DevCloud website) and checks whether that challenge is currently active (by retrieving the "challenge" parameter from the URL). If that challenge is active, it submits the current highscore to the challenge, without a callback method (which is not required if all you need to do is submit a score). If you need to confirm that the score was uploaded and then perform a certain action, you can make use of the callback function:

if (gxc_get_query_param("challenge") == _highscore_challenge)
{
    instance_create_layer(0, 0, "GUI", obj_loading_bar);

    gxc_challenge_submit_score(global.highscore, function (_status, _result)
    {
        if (_status == 200)
        {
            instance_destroy(obj_loading_bar);
            instance_create_layer(0, 0, "GUI", obj_upload_success);
        }
    });
}

The above code creates a "loading bar" instance before submitting the score, and uses a callback function to check whether the score was successfully uploaded to the server. In that case, it destroys the loading bar and creates an "upload success" object. (Note that ideally you would also want to handle what happens if an error is returned.) The status code is being checked against 200 as that indicates that the request was successful.

If you need to submit a score to a specific challenge that is not the currently active challenge, you can use the `options` argument: 
var _options = {
    challengeId: "cysdf906bh23rkhjm"; // Your challenge ID goes in the string
}

gxc_challenge_submit_score(global.otherScore, undefined, _options);

The above code submits a new score to the specified challenge. It uses no callback function (undefined) so no checking logic will be executed.



Back To Top

gxc_challenge_get_global_scores

Overview

This function is used to retrieve all the scores for the currently active challenge. Signing into GXC is not required for this function to work. You specify an optional callback method which is called when a response arrives from the server. As explained on the Callbacks page, if you don't specify this argument, an Async Social event will be triggered when a response is received. You can also supply an optional struct as the second argument, containing parameters for pagination (returning only a specific amount of scores). The function will always return a request ID, which can be used to identify the request in an Async Social event if a callback method is not specified.

Options

You can optionally specify a struct as the second argument, which allows you to apply pagination and target a specific challenge and track. You can include the following variables in that struct:

Variable Type Value
page Real The page number to return
pageSize Real The maximum number of scores to return
challengeId String The challenge ID to use (if not specified, defaults to the currently active challenge)
trackId String The track ID to use (if not specified, defaults to the currently active track)

See the example given at the bottom of this page for more information.

Callback Result

As explained on the Callbacks & Async Events page, the callback method will get a _result argument containing a data struct. The data struct for this function's response will contain the following variables:

Variable Type Value
scores Array<Score> An array containing structs as the scores; these will be sorted from best to worst (so the best score will be the first entry in this array, and the worst will be the last)
challenge Struct.Challenge A struct containing information on the currently active challenge (see Challenge)
pagination Struct.Pagination A struct containing information on pagination

If pagination options are specified, the response may include pagination-specific errors that occur due to invalid values; please see Response Error Codes for information on such errors.


Syntax:

gxc_challenge_get_global_scores([callback, options])
Argument Type Description
callback Function A callback method which is called when an HTTP response is received ✴️ OPTIONAL
options Struct A struct containing options for pagination (see above) ✴️ OPTIONAL

Returns:

Real

Example:

var _options =
{
    page: 0,
    pageSize: 5
};

gxc_challenge_get_global_scores(function(_status, _result)
{
    if (_status == 200)
    {
        show_debug_message("Challenge: " + _result.data.challenge.name);

        var _scores_count = array_length(_result.data.scores);
        for (var i = 0; i < _scores_count; i ++)
        {
            var _score_data = _result.data.scores[i];
            show_debug_message("Score " + string(i) + " is " + _score_data.score);
        }
    }
}, _options);

The above code requests the top 5 global scores for the current challenge to be retrieved, and once they are successfully returned, loops through the array and prints the value of each score to the output log.

To load the scores for a different challenge (which is not being played at the moment), simply include its challenge ID in your options struct: 
var _options =
{
    page: 0,
    pageSize: 5,
    challengeId: "cysdf906bh23rkhjm"
};

gxc_challenge_get_global_scores(function(_status, _result)
{
    // Callback
}, _options);



Back To Top

gxc_challenge_get_user_scores

Overview

This function is used to retrieve the current user's submitted scores for the currently active challenge. Signing into GXC is required for this function to work. You specify an optional callback method which is called when a response arrives from the server. As explained on the Callbacks page, if you don't specify this argument, an Async Social event will be triggered when a response is received. You can also supply an optional struct as the second argument, containing parameters for pagination (returning only a specific amount of scores). The function will always return a request ID, which can be used to identify the request in an Async Social event if a callback method is not specified.

Options

You can optionally specify a struct as the second argument, which allows you to apply pagination and target a specific challenge and track. You can include the following variables in that struct:

Variable Type Value
page Real The page number to return
pageSize Real The maximum number of scores to return
challengeId String The challenge ID to use (if not specified, defaults to the currently active challenge)
trackId String The track ID to use (if not specified, defaults to the currently active track)

See the example given at the bottom of this page for more information.

Callback Result

As explained on the Callbacks & Async Events page, the callback method will get a _result argument containing a data struct. The data struct for this function's response will contain the following variables:

Variable Type Value
scores Array<Score> An array containing structs as the scores; these will be sorted from best to worst (so the best score will be the first entry in the array, and the worst will be the last) (see Score)
challenge Struct.Challenge A struct containing information on the currently active challenge (see Challenge)
pagination Struct.Pagination A struct containing information on pagination (see Pagination)

If pagination options are specified, the response may include pagination-specific errors that occur due to invalid values; please see Response Error Codes for information on such errors.


Syntax:

gxc_challenge_get_user_scores([callback, options])
Argument Type Description
callback Function A callback method which is called when an HTTP response is received ✴️ OPTIONAL
options Struct A struct containing options for pagination (see above) ✴️ OPTIONAL

Returns:

Real

Example:

var _options =
{
    page: 0,
    pageSize: 5
};

gxc_challenge_get_user_scores(function(_status, _result)
{
    if (_status == 200)
    {
        show_debug_message("Challenge: " + _result.data.challenge.name);

        var _scores_count = array_length(_result.data.scores);
        for (var i = 0; i < _scores_count; i ++)
        {
            var _score_data = _result.data.scores[i];
            show_debug_message("Score " + string(i) + " is " + _score_data.score);
        }
    }
}, _options);

The above code requests the top 5 scores of the user for the current challenge to be retrieved, and once they are successfully returned, loops through the array and prints the value of each score to the output log.

To load the scores for a different challenge (which is not being played at the moment), simply include its challenge ID in your options struct: 
var _options =
{
    page: 0,
    pageSize: 5,
    challengeId: "cysdf906bh23rkhjm"
};

gxc_challenge_get_user_scores(function(_status, _result)
{
    // Callback
}, _options);



Back To Top

gxc_challenge_get_challenges

Overview

This function is used to retrieve all the challenges that have been created for the game on the currently active track (or the one specified in options). You specify an optional callback method which is called when a response arrives from the server. As explained on the Callbacks page, if you don't specify this argument, an Async Social event will be triggered when a response is received. You can also supply an optional struct as the second argument, containing parameters for pagination (returning only a specific amount of challenges). The function will always return a request ID, which can be used to identify the request in an Async Social event if a callback method is not specified.

Options

You can optionally specify a struct as the second argument, containing options for pagination. You can include the following variables in that struct:

Variable Type Value
page Real The page number to return
pageSize Real The maximum number of challenges to return
trackId String The track ID to use (if not specified, defaults to the currently active track)

See the example given at the bottom of this page for more information.

Callback Result

As explained on the Callbacks & Async Events page, the callback method will get a _result argument containing a data struct. The data struct for this function's response will contain the following variables:

Variable Type Value
challenges Array<Challenge> An array containing structs for the challenges returned (see Challenge)
pagination Struct.Pagination A struct containing information on pagination (see Pagination)

If pagination options are specified, the response may include pagination-specific errors that occur due to invalid values; please see Response Error Codes for information on such errors.


Syntax:

gxc_challenge_get_challenges([callback, options])
Argument Type Description
callback Function A callback method which is called when an HTTP response is received ✴️ OPTIONAL
options Struct A struct containing options for pagination (see above) ✴️ OPTIONAL

Returns:

Real

Example:

var _options =
{
    page: 0,
    pageSize: 10
};

gxc_challenge_get_challenges(function(_status, _result)
{
    if (_status == 200)
    {
        var _challenge_count = array_length(_result.data.challenges);
        for (var i = 0; i < _challenge_count; i ++)
        {
            var _challenge = _result.data.challenges[i];
            show_debug_message("Challenge " + string(i) + " is " + _challenge.name);
        }
    }
}, _options);

The above code requests the first 10 challenges for the current game to be retrieved, and once they are successfully returned, loops through the array and prints the name of each challenge to the output log.



Back To Top

Challenge

The Challenge struct is returned by all the function that query challenge data from the server as shown on the list below,

Variable Type Value
challengeId String The ID of the challenge
coverArt String A link to the cover art for the challenge
creationDate String The date and time when the challenge was created
type String The type of the challenge (e.g., "duration")
criteria String The winning criteria for the challenge (e.g., "lowest_wins")
startsAt String The date and time when the challenge starts (if timed)
endsAt String The date and time when the challenge ends (if timed)
hasEnded Bool Has the challenge ended? (if timed)
hasStarted Bool Has the challenge started? (if timed)
isPublished Bool Is the challenge published?
isTimedChallenge Bool Is the challenge timed?
shortDescription String The short description of the challenge
longDescription String The long description of the challenge
name String The name of the challenge
players Real The amount of players who have submitted scores for this challenge



Back To Top

Score

The Score struct is returned by all the function that query score data from the server as shown on the list below,

Variable Type Value
achievementDate String The date and time when this score was submitted
countryCode String The country code of the score submitter
player Struct.Player A struct containing the following information about the submitter:
score Real The score value
scoreId Real The ID of the submitted score



YoYoGames 2023

Clone this wiki locally