How to Create and Award Achievements via a Leaderboard.

In this exercise we'll create an Achievement that is awarded to a player when they beat their current high score in a game:

Creating an Event

To start, we'll use the Configurator to create an Event that will allow your game code to log a score for the player with the GameSparks platform.

1. Go to Configurator > Events.

2. On the Events page, click to Add a new Event. The page adjusts to allow you to add the Event.

3. Now, fill in the Event details for Short Code, Name, and Description.

4. Under the Attributes panel, click to Add an Attribute to the Event.

5. Configure the Attribute:

6. Click to Save and Close your new Event with a single Attribute.

Creating a Leaderboard

Next, we'll create a Leaderboard that will arrange the players' scores in order from highest to lowest.

1. Go to Configurator > Leaderboards and click to Add a new Leaderboard to represent the game's high score table.

2. Enter the details for the new Leaderboard:

Note: You'll use the Short Code when your game code posts scores into the GameSparks platform.

3. In the Fields panel, add a Running Total:

Note: Running Totals are an advanced topic that we don't need to worry about for this exercise.

4. Click to Save and Close your Leaderboard.

Creating and Configuring Game Currencies

Before you set up currency awards for your Achievements, you can create and configure currencies for your game.

Default Game Currencies? You can also use the default game currencies you have enabled for your game in Game Overview>Edit for Achievement currency awards. However, in this tutorial we'll work with the custom Currencies you've created for your game.

1. Go to Configurator>Currencies and click Add to add a new custom currencies:

2. For this tutorial, we'll configure a sign-up bonus amount for CURRENCY_1 of 1000 and a sign-up bonus amount for CURRENCY_2 of 400:

Creating Currencies? For more details of how to create and configure game currencies, see Currencies.

Creating an Achievement

Now, we can create an Achievement that is triggered when a new high score is posted to the Leaderboard.

1. Go to Configurator > Achievements and click to Add a new Achievement.

Enter the details of the new Achievement:

No Leaderboard? You can trigger Achievements using a Cloud Code script, if no Leaderboard was selected. To do this, you wouldn't select a Leaderboard but None - Triggered by Script instead.

Default Game Currencies? If you've enabled any of the six default game currencies in Game Overview>Edit, you can also configure an Achievement for awards in any of these default currencies.

2. In the Triggers panel, click to Add a new Trigger for the Achievement:

Enter the details for the Achievement Trigger:

By linking our High Score Achievement to the High Score Table Leaderboard, using the Score Attribute field as the trigger data, and filtering that data, we ensure players are awarded the Achievement only when they score 100 or more on that Leaderboard.

3. Click to Save and Close the new Achievement.

Testing Achievement, Leaderboard, and Event with Test Harness

In this section we'll use the Test Harness to register a test player with the preview version of the game, authorize this player and post a new high score to the GameSparks platform. We'll see the JSON requests and responses and then request the player's details to see that they have been gifted with some in-game currency.

Registering a Test Player

Select RegistrationRequest from the Test Harness > Requests > Authentication menu. Now change the userName and displayName as shown below and send this JSON request to the GameSparks platform by clicking Send Request.

The Inspector shows the request (in green text) that was sent to the GameSparks platform via the WebSocket and the response (in blue text).

Checking the Player's Current Details

Select AccountDetailsRequest from the Test Harness > Requests > Player menu. Examine the currency values for this player in the response, notice that they are all zero, except for CURRENCY_1 and CURRENCY_2, each of which have the relevant sign=up bonus amounts accredited to the player:

Log Event

Select the option on the LogEvent tab. Now select the Score Event menu option from the submenu:

Under Requests, select LogEvent to send a LogEventRequest. Now select the Score Event:

In the Inspector, you can see the request you sent in green text and the response in blue text.

There will also be two Messages: an AchievementEarnedMessage and a NewHighScoreMessage. Both are asynchronous messages that the GameSparks platform has sent to this player:

Checking the Player's Updated Details

Finally repeat the AccountDetailsRequest you performed earlier and notice that the player now has the new Achievement and 100 of each currency has been added to the player's currency amounts.