Warning: This version (v1) of the API will be deprecated on May 1st 2015


Rooms within the Clay.io API allow you to easily handle multiplayer rooms in games. This API feature is for client-side code only, as an easy way to group users together in a unique room ID before handling them later through your own implementation of node.js + socket.io or whichever stack you choose.

To setup rooms, create a new Clay.Rooms object and pass the function you want to be called when a room is full in the options object. This function will take an argument of an object of { count: count, id: id, success: success }

var room = new Clay.Rooms( { fullCallback: function(obj) {
    // Callback function for when a room is full
    // { count: # in room, id: unique int id for room, instance: instance of the room obj }
    // You can use instance like: obj.instance.leaveRoom(); to force a player out of the room
    // ex. Game.start();
    console.log( obj.count + " in room" );
    console.log( obj.id+ " is the room ID" );
} } );

To show the rooms modal window (with a list of rooms to join and an option to create a room), use:

// Remember that we're using room since we already set it to the Clay.Room object above
room.show( function(rooms) {
    // This callback is optional
    // Rooms is an object of room objects: { id: id, name: name, count: count }
} );

Everything else is handled for you. When you call .show() the player will have a list of rooms to choose from. They can join any of those rooms, or can create one of their own. When new rooms are created or fill up, it updates the list on every player's view instantly.

Once the room a player is in fills up, the function you pass to Clay.Rooms() is executed - this is where you'll want to put the code to start a game.

Manually Leave Room

If, for example, you would like a user to be booted from a room when the game is over you can call:

// Remember that we're using room since we already set it to the Clay.Room object above

Provide Feedback

We take customer support, and the quality of our developer tools and documentation very seriously. We want to hear how you think we can improve our documentation! Let us know if anything is missing, or unclear on this documentation page, and we'll get that fixed!