Integrating Leaderboards, Achievements, and Social Features

Favourite 108 favourites
Tutorial written by austinOriginally published on 17th, July 2012 - 5 revisions

Clay.io is a hub for HTML5 games that provides both a marketplace and API. This guide will explain how to integrate features like high scores and achievements into your game.

For the purposes of this tutorial, I will be using the demo game, "Space Blaster".

Signing Up

The first step towards using the Clay.io API is to signup for Clay.io and create a game key to work with.

You can signup for Clay.io here: http://clay.io/join

Once that's completed, head over to the developers' page and click "Upgrade Account to Developer".

You'll be asked to specify your developer name (For example: "Vigil Games"), Unique Key/URL Location (your developer page will be accessible at clay.io/developer/TheKeyYouMake), URL (if you have a website) and Bio (a short description about your, or your game studio).

Next up, you have to add your game (you don't have to upload the files just yet, but we need a record of your game). You can do that here.

Subdomain is where your game will be located on Clay.io (if you pick "mygame", you'll be able to access it from http://mygame.clay.io)
Price leave this at 0.00 unless you plan on charging for your game, if so, set the price you wish to charge
Zip File skip this for now - this is for completed games that are being uploaded, since we're implementing the API first, there is no need to do that yet.

Now you're ready to get started

Installing the plugin

You can download the Clay.io Construct 2 plugin here (you'll also find further documentation on that page)

Once downloaded, extract the zip file, and copy the "clay" folder into your Construct 2 install plugin folder (often: C:\Program Files\Construct 2\exporters\html5\plugins)

Next, open up your Construct 2 project, right click inside the layout tab, and "Insert new object". Clay.io will show up as an option in the "Web" section.
Clay.io object
In the properties panel, put in the API key (what you entered for the subdomain earlier, this is also accessible from the settings for your game).
Properties Panel
Having debug mode means any achievements you earn will not show up in the Clay.io feed, and high scores aren't posted to the live data for your leaderboard. Just be sure to disable this when you publish your game if you choose to enable it during development.

Leaderboards

The first step in adding high scores to your game is to go to the developers' page, click "Leaderboards" then click "Add a Leaderboard".

You'll see something like this:
Adding a Leaderboard
The Name field will show in the header of the leaderboard in your game like so:
Leaderboard Title
The Type field has two options: "Default" and "Incrementing". Default is your typical high score system where a user can have, for example, 7 different high scores posted (since they played 7 times) - each is individual. With incrementing, each time a new score is posted, it is added to that player's previous score. An example of when this can be used is to get a cumulative number of wins.

Once you hit the "Add Leaderboard" button, you'll see a success message like: "Your leaderboard was successfully added with ID: 26" (with a different number than 26 - you'll need this ID in the next step).

Next, in your Construct 2 project under "Events", attach the following action to whichever event condition you would like to post a high score following (in Space Blaster, this happens when the player's health hits 0, and the game is over). Select the action: "Clayio -> Post Leaderboard Score).

Post Leaderboard Score Action


Player Name can be left blank. If it's blank Clay.io will ask the user for their name (or if they're logged into Clay.io, it will use that account). If you specify a name variable, Clay.io will use that instead to associate the score with.
Player Score is going to be the variable/expression that the score is stored in. In the case of Space Blaster, that's "score".
Leaderboard ID is what was returned in the above step - for this game, it was 26.

That's all it takes to get high scores to point, but now we'll want to show the leaderboard. For some games it makes sense to show the leaderboard after every score is posted, for others, you might want to bind it to a key press. For this tutorial, we're going to have it show each time a score is posted.

Create a new event with the condition "Clayio -> Leaderboard Score Posted". Next, add an action to that event: "Clayio -> Show Leaderboard"

Show Leaderboard Scores


Leaderboard ID again is what was shown after adding your leaderboard on Clay.io (26 for this game, yours will be different)
Time Frame lets you narrow down how far back you would like to grab results from/ You can show the high scores from the past 30 days, 7 days, and 24 hours (as well as all-time).
High Score can be individual or cumulative. If it's cumulative, and a user has posted 3 high scores: 15, 25 and 11 -- 1 listing of 51 will show for them rather than the 3 separate scores.
Scores From lets you narrow down who to display the high scores from. You can have it select from 1) Everyone who has played the game, 2) Just the person viewing, or 3) Just the friends of the person viewing (they'll need to be logged into Clay.io so we can tell who their friends are).

That's it! Your leaderboard is setup and good to go.

Achievements

For this example, we're going to award an achievement for the first time a player kills an enemy in Space Blaster.

First up, you'll need to create the achievement in the Clay.io Developers' Area. Click "Achievements" for your game, then "Add an Achievement".

Add Achievements
For reference, the achievement will show up like this:
Achievement
Title will show up in the achievement header
Description will show up in the achievement content area
Clay.io bronze points are similar to Xbox Live GamerScore - they're a measure of credibility a player on Clay.io has. You can give out up to 100 points per game
Icon is an optional 50x50 icon you can upload that will show up to the left of the description when an achievement is awarded.

Once you hit "Add Achievement", you will be given a success message with the newly created achievement's ID. You'll need this for the next step (in this case it's 125).

In your Construct 2 project, find a condition when you'd like to award an achievement. For this tutorial, that's when an enemy dies.

For the action, select "Clayio -> "Award Achievement".

Achievement Action


Achievement ID is what we got after adding the achievement on Clay.io (125 in this case)

That's it! When an enemy dies, players will be awarded an achievement.

Screenshots

Construct 2 already lets you take screenshots, but once the screenshot is taken, you can't post to Facebook, or have a link to the screenshot. The Clay.io plugin will upload screenshots your players take to our server, and give you a link to use.

To achieve this, first tie the "System -> Snapshot canvas" action to an event (for this tutorial, I used the the "S" keydown for the condition)

Next, create an event with the condition of: "System -> On Canvas Snapshot", and the action: "Clayio -> Post Screenshot to Clay.io".

Screenshots


It will ask you for a "Screenshot Data URL" - use the expressions window, and select "System -> CanvasSnapshot"

Once you hit done, you're good to go - the screenshot will be posted to a player's Clay.io account (if they're logged in, otherwise it will ask them to login). Details on posting to Facebook are at the end of this tutorial.

Posting to Facebook and Twitter

The processes for posting to Facebook, Twitter and the Clay.io stream are all virtually identical, so to refrain from being repetitive, I will just explain posting to Facebook.

Create an event with whatever condition you'd like to start the posting process (for this tutorial I chose the "F" keydown).

Next, set the action to "Clayio -> Post to Facebook Wall".

Posting to Facebook


Message is the content of the post that will be made to Facebook
Link is an optional URL you specify that will show up with the Facebook post
Picture is an optional image URL you specify that will be associated with the post

Screenshots Posted to Facebook

To tie together the previous two features listed, let's have screenshots be posted to Facebook.

First, follow the steps under the "Screenshots" section above. Once that's done, create another event with the condition: "Clayio -> Screenshot Posted". Now set the action to: "Clayio -> Post to Facebook Wall".

This time, we'll do exactly what we did last time, only, we'll use the expression: "Clayio -> ScreenshotSrc" in the Picture field.

Facebook Screenshot


Voila, we're done!

Facebook Result
For an example of a game using the API, see Word Wars.

This tutorial doesn't cover everything the plugin does, so be sure to read over the official documentation.

Unlock your full gamedev potential

Upgrade to the Personal Edition of Construct 2, it has way more features and won't holding back from making money and using your full creativity like the free edition does. It's a one off payment and all Construct 2 editor updates are free for life!

View deals

Plus, it's got a lot of additional features that will help you save time and make more impressive games!

Congratulations on finishing this tutorial!

Did you learn a lot from it? Share it now with your friends!

Comments

3
jogosgratispro 23.3k rep

Can you post a link for a game with achievements from Clay.io?

Tuesday, July 17, 2012 at 5:33:47 PM
5
austin 6,387 rep

Sure, I updated the tutorial with a link to: http://wordwars.clay.io

Tuesday, July 17, 2012 at 5:50:44 PM
5
gaboduarte 13.8k rep

I'm so using this!
Tests begin today! :-D

Tuesday, July 17, 2012 at 6:38:42 PM
3
sheepy 6,903 rep

I´ll test the metrics today, clay.io ease to use is impressive. ;]

Tuesday, July 17, 2012 at 7:00:52 PM
4
jwilburn 2,738 rep

This looks very promising. I'm going to jump into it tomorrow. Are the Rooms and Payments feature implemented in the plugin or coming in the future? I didn't see them mentioned on the plugin page.

Wednesday, July 18, 2012 at 2:03:21 AM
2
austin 6,387 rep

They're not in the current version, but are on the todo list

Wednesday, July 18, 2012 at 2:24:45 AM
4
Joannesalfa 28.4k rep

Nice tutorial, it makes me wonder about Clay.io is compatible for mobile devices, isn't?

Thursday, July 19, 2012 at 4:27:02 AM
4
austin 6,387 rep

It most definitely is!

Thursday, July 19, 2012 at 6:02:46 AM
3
blackmwana 2,523 rep

@austin Clay.io is really great, i wanted to ask if the other remaining features will find their way into the plugin or this is it as far as the construct2 plugin is concerned,im refering to rooms etc

Thursday, July 19, 2012 at 11:26:00 PM
3
austin 6,387 rep

@blackmwana it's on the todo list, hopefully soon

Friday, July 20, 2012 at 2:05:41 AM
3
EyeHawk 7,762 rep

Nice work thanks for this tutorial Austin - I'll definitely be using this service.

Sunday, July 22, 2012 at 10:52:27 AM
1
BoogieMAN2K 2,127 rep

I'm checking the plug-ins but I'm having some problems using it. It's saying something about 'console' being undefined just when I start the game...

Wednesday, July 25, 2012 at 12:55:08 AM
2
austin 6,387 rep

@BoogieMAN2K what browser are you trying it out in?

Wednesday, July 25, 2012 at 1:29:42 AM
2
mmarcati 2,726 rep

I'm trying it out and it seems really great! But there's one thing that's troubling me: when I leave the Player Name field empty, Construct complaints that the field cannot be left empty. What's up with that?

Friday, July 27, 2012 at 10:06:58 PM
2
austin 6,387 rep

It has to be left empty between quotes, so: ""

Friday, July 27, 2012 at 10:28:47 PM

Leave a comment

Everyone is welcome to leave their thoughts! Register a new account or login.