Start to Finish With Backend

This is a guide for how we integrated Clay.io into our first game, Slime Volley. Your integration of the API will vary a bit since every game is different, but hopefully this is helpful!

<

p>If you want to see an example of Clay.io integrated into a less complicated game, see this tutorial.

This was all implemented after the game was completed, and is just how we integrated Clay.io, nothing to do with the actual game mechanics. We wrote the game in CoffeeScript, but I've translated that to JavaScript for this tutorial. If you want to view the entire source code, we have it on GitHub! Since we had a backend for the game, we're using Clay.io's encryption method for the backend to prevent false leaderboard scores and achievements.

Part 1 - Including Clay.io

Inluding Clay.io is as easy as copying and pasting this into your section of your index file. You'll of course want to change 'slime' to the API key of your game (you will get this after uploading your game):

<script type="text/javascript">
Clay = {};
Clay.gameKey = "slime";
Clay.readyFunctions = [];
Clay.ready = function( fn ) {
    Clay.readyFunctions.push( fn );
};
( function() {
    var clay = document.createElement("script"); clay.async = true;
    clay.src = ( "https:" == document.location.protocol ? "https://" : "http://" ) + "clay.io/api/api.js"; 
    var tag = document.getElementsByTagName("script")[0]; tag.parentNode.insertBefore(clay, tag);
} )();
</script>

Part 2 - Backend Initiation

Since we're using a backend (with node.js) both to enable multiplayer, and to prevent falsified scores, we use a JSON Web Token to encrypt the data that's sent to the Clay.io server. We make it pretty simple with a node module, but we do need to specify a few things first.

Client Side

Once a multiplayer room is joined, we pass this object to the server that contains the unique identifer for the current player of the game:

var obj = { roomID: this.roomID, playerID: Clay.Player.identifier };

Server Side

The code below is in our method on the server that's called when a user joins a room - passed to that method is the obj parameter which was passed from above:

// Store the unique identifier for this player
var playerID = obj.playerID;
var secret = 'REMOVED_FOR_TUTORIAL'; // Secret key for this game
this.clay = new Clay( playerID, secret ); // This associates the clay encode method with this player

Click here for more documentation on backend encryption.

Part 2 - Leaderboards

Showing the leaderboard

We have a button on the menu screen of the game that when clicked executes this JavaScript:

new Clay.Leaderboard( { id: 6 } ).show();

This brings up the leaderboard with two tabs, one for the number of single player wins, the other for the number of multiplayer wins.

Posting to the leaderboard

First, we added the leaderboard in the Clay.io developer dashboard (so all scores are stored under that ID):

Here's how our backend looks when the game ends and the player is a winner:

// Increment leaderboard by 1 for player 1 (since player 1 won in this instance)
var jwt = this.room.p1.clay.encode( { score: 1 } ); // the clay property holds the object from part 2 of this guide
// jwt is then sent back to the client

Here's our client side code (the action the client takes when the server hits it with the information we passed (the jwt variable is passed as a parameter to the function that calls this):

var lb = new Clay.Leaderboard( { id: 6 } );
lb.post( { jwt: jwt } );

Click here for more documentation on leaderboards.

Part 3 - Achievements

First, we added the achievements in the Clay.io developer dashboard. Each game is given 100 point to give out, so split those among your achievements (points are a type of notoriety for members):

Right now we're actually not verifying achievements for the game via the backend, so to award achievements, say the "Win a game" achievement, we just call the award method for it:

// We put this on the client side when we determine if they've won the game
( new Clay.Achievement( { id: 15 } ) ).award();

Click here for more documentation on achievements.

Part 4 - Multiplayer Rooms

We have rooms for multiplayer, so two people can face each other in a game. First, when Clay.io is loaded, we create the rooms object, with a callback specifying what to do when the room is full:

Clay.ready( function() {
    this.clayRooms = new Clay.Rooms( function( roomInfo ) {
        networkGame = new NetworkSlimeVolleyball()
        networkGame.roomID = roomInfo.id; // unique identifier for room
        networkGame.rooms = roomInfo.instance; // instance of the room, so we can manually remove players from room
        Globals.Manager.pushScene( networkGame );
    }
} );

Next, when they click the button for "Multiplayer", we load up the rooms UI with:

this.clayRooms.show();

It's as easy as that! Once a room is full, the unique room ID, number of players, and instance object of that room are passed in a single object as a parameter for your callback function.

Click here for more documentation on rooms.

Part 5 - Social Integration

For the social integration in the game, we just have two buttons, one to tweet about the game, and one to post to Facebook. You can get a lot more crafty with this (for example, we post screenshots for our Word Wars game). Here's the code we have, and we just point links to call the functions.

function tweet()
{
    var twitter = new Clay.Twitter();
    twitter.post( "Check out this game, Slime Volley, on Clay.io - http://slime.clay.io" );
}
function facebook()
{
    var facebook = new Clay.Facebook();
    facebook.post( "Check out this game, Slime Volley, on Clay.io - http://slime.clay.io" );
}

Click here for more documentation on social integration.

Part 6 - Other random API enhancements

We also have links for taking a screenshot and rating the game.

<a href='javascript: void( 0 );' onclick='new Clay.Screenshot();'>Screenshot</a>
<a href='javascript: void( 0 );' onclick='Clay.Ratings();'>Ratings</a>

Here is the documentation for: screenshots and ratings.

Part 7 - Packaging for Clay.io

To get your game on Clay.io, we require a manifest.json file from you that includes some info about your game. The manifest file, along with all your game assets, and a couple of images of your game are packaged into a .zip file and uploaded to clay.

Here's the file we had:

{
  "name": "Slime Volley",
  "description": "Volleyball...between two slimes.",
  "version": "0.2.0",
  "app": {
    "launch": {
      "local_path": "index.html"
    }
  },
  "icons": {
    "128": "icon_128.png"
  }
}

Click here for more documentation on the manifest file.

Inside the .zip file were all the necessary Javascript/CSS files, index.html, icon_128.png, and the manifest.json file.

If you have any comments on how we can improve this tutorial, please let us know at contact@clay.io. Your feedback helps us make a better product!