Challenges: Getting started

Use GxGames singleton to access the platform API.

Identifying the current challenge

Create a new game object and add it to your active scene. Create a new component and add it to that game object. Add the following code to it:

private void Start()
{
    Debug.Log($"Current challenge ID: {GxGames.GetQueryParam("challenge")}");
}

The function Start will be executed by Unity on starting the scene. The code inside this function gets the ID of the current challenge and prints it into the console.

Getting query parameters

To test your challenges locally, you’re going to need the “query parameters” (or URL parameters) that are passed into your game’s URL when a challenge is activated. You only ever need to do this for testing challenges locally, and GX.Games provides you with these parameters to make testing easier.

On Dev Portal, go into your challenge’s details and activate your “private challenge page”. This will show "query parameters" with a copy icon next to it. You can click to copy the challenge parameters to your clipboard.

The copied text will be similar to this:

?game=a47df7fc-4df2-45c1-90bd-76903645b094&track=13813ccd-0dda-41b6-900c-e8e2691e6430&challenge=c92f5e78-a380-49b4-8e22-d98997f558b7

These are simple URL parameters that include your game, track and challenge IDs and can be retrieved in-game using the methods of GxGames singleton.

Activating a challenge locally

Go to Unity and build your game for WebGL, then run it on localhost. Open the link in the browser. You simply need to paste your copied query parameters at the end of this link, making sure that the parameters start with a question mark (?), and then open the resulting URL.

Your final URL will look something like this:

When the game starts, it will now detect the challenge ID given in the URL and print the challenge ID in the browser console of the developer tools.

Submitting Challenge Score

In this chapter we will use the following function of GxGames class:

GxGames.ChallengeSubmitScore

Add the button to the scene. We will use this button to send the new score.

Let's write a code in our component to submit a score on pressing this button.

public Button submitButton;

private void Awake()
{
    submitButton.onClick.AddListener(SubmitScore);
}

private void SubmitScore()
{
    // A new score. It's just constant in this example for simplicity.
    var newScore = 777;

    GxGames.ChallengeSubmitScore(newScore, null);
}

As you can see, the script has a public field submitButton. Go to the scene and drag the button we created earlier to the corresponding field of the component.

Note that it is not necessary to specify the challenge ID for ChallengeSubmitScore. In this case, this method simply uploads the given score to whichever challenge is currently active.

Make sure that this code runs only once when your game loop ends and is not constantly being executed in every frame!

Testing Score Submitting

The code above enters the new score into the challenge’s leaderboard; so go ahead and test your game locally (make sure to add the query parameters!) and submit your challenge score.

Go to GX.Games or GX.Dev and log in. Authorization is necessary to associate the new score with a player's account.

Run your game and press the button which submits the score. You can now open your private challenge page and see the leaderboard at the bottom, which will include the scores you submitted while testing locally. You can also upload your game to GX.Games and try the functionality on the game's page.

Using a Callback to Handle the Score Submission Response

When you submit the score, the plugin sends an HTTP request to the server. After a while the game receives a response. You may want to handle it as well. It could be handy if you want to let user know immediately whether the new score is best or not.

Let's add a callback to the function we have written earlier:

public Button submitButton;

private void Awake()
{
    submitButton.onClick.AddListener(SubmitScore);
}

private void SubmitScore()
{
    // A new score. It's just constant in this example for simplicity.
    var newScore = 777;

    GxGames.ChallengeSubmitScore(
        newScore,
        callback: (data, isOk, errorCodes) =>
        {
            Debug.Log($"Request completed. Is OK: {isOk}. Error codes: {string.Join("; ", errorCodes)}");
            Debug.Log($"Is new best score: {data.newBestScore}");
        });
}

This callback simply checks if the score submission was successful or not. It also writes in the console whether the new score is the new best. You may do whatever you want with this data. For example, you may show a colourful banner with congratulations to the new recordman :)

Passing Different Scores to Different Challenges

You may want to send different values depending on the active challenge. Assume that you created the following two challenges:

• Fastest Level Completion. The winner is the one who passes the level faster than everyone else.
• Highest Points. The winner is the one who earns the most points. So we need to detect the active challenge and send either time or points depending on its ID.

Let's add two constants to the component script:

// Replace "..." with the actual IDs of the challenges.
const string FASTEST_CHALLENGE_ID = "...";
const string HIGHEST_POINTS_CHALLENGE_ID = "...";

Now we need two functions to extract the necessary data. The first one extracts the time spent by the player. The second one extracts the points earned by him/her. The body of the functions is very game-specific so it's omitted:

public int GetTime()
{
    // Add the code which extracts the time taken by the player to complete the level.
}

public int GetPoints()
{
    // Add the code to get the player's points.
}

Add the function which should be invoked on the level completion. We will submit different values depending on the active challenge. If the current challenge is "Fastest Level Completion", we will submit the time. If the challenge is "Highest Points", we will submit the points.

public void SubmitScoreOnLevelCompleted()
{
    var activeChallengeId = GxGames.GetQueryParam("challenge");

    switch (activeChallengeId)
    {
        case FASTEST_CHALLENGE_ID:
            GxGames.ChallengeSubmitScore(GetTime(), null);
            break;
        case HIGHEST_POINTS_CHALLENGE_ID:
            GxGames.ChallengeSubmitScore(GetPoints(), null);
            break;
    }
}

Advanced Challenges

GX.Games API allows you to implement more functionality inside your game: to get the current global and personal scores, create leaderboards, indicate profile information (like user's name or avatar) etc. Refer to GxGames API for more details.