SFS2X Docs / DevelopmentBasics / join-and-create-rooms

» Join and create Rooms

One of the fundamental building blocks in the SFS2X framework is the Room object. Rooms allow to arrange players so that they can "see" each other and interact together. A typical use of Rooms is to create different categories in a chatting application, different meeting locations in a Virtual World or different places where to challenge other friends in all sort of games.

Rooms are created in two different ways.

For example, in our BasicExamples Zone (that we provide by default) there is one static Room called "The Lobby" which can be joined by any client after they heve successfully logged in the Zone.

Joining a Room from the client API requires one line of code (sfs is the SmartFox class instance):

sfs.send( new JoinRoomRequest("The Lobby") );

The server will in turn respond with one of the following events:

As usual we will need to register the events in our main SmartFox class instance to be notified of the result of the join operation. This is the full ActionScript 3 code required to handle both cases (very similar for other languages).

This code is usually executed during the application initialization:

var sfs:SmartFox = new SmartFox();
sfs.addEventListener(SFSEvent.ROOM_JOIN, onJoin);
sfs.addEventListener(SFSEvent.ROOM_JOIN_ERROR, onJoinError);
...

This code is executed after a successful login:

sfs.send( new JoinRoomRequest("The Lobby") );

And these are the event listeners:

public function onJoin(evt:SFSEvent):void
{
	trace("Joined Room: " + evt.params.room.name);
}

public function onJoinError(evt:SFSEvent):void
{
	trace("Join failed: " + evt.params.errorMessage);
}

What could go wrong?

There are a number of possible things that could invalidate the attempt to join a Room.

Joining one or more Rooms at the same time

In most cases the client will probably move from one Room to another leaving the previous Room after the new one is joined. This is the default mode in which SFS2X and its API operate by default.

There are situations, however, in which we need the client to remain joined in a Room (typically a Lobby) while entering in another Room (maybe a game or chat Room). Let's examine the JoinRoomRequest constructor from the client API. The following arguments are available.

In order to keep track of the joined Rooms on the client-side, the API provide a couple of useful tools:

Finally the roomManager object in the SmartFox class allows to query the local Room List data.

Creating Rooms dynamically

Rooms can be created from code at any time (after the login) on both client and server-side. This is a quick example in ActionScript 3 (for simplicity the required listeners are added just before creating the Room, but this should be made during the application initialization):

smartFox.addEventListener(SFSEvent.ROOM_ADD, onRoomAdded)
smartFox.addEventListener(SFSEvent.ROOM_CREATION_ERROR, onRoomCreationError)

// Create a new Chat Room
var settings:RoomSettings = new RoomSettings("Piggy's Chat Room")
settings.maxUsers = 40
settings.groupId = "ChatGroup"

smartFox.send(new CreateRoomRequest(settings))

These are the event listeners:

function onRoomAdded(evt:SFSEvent):void
{
	trace("A new Room was added: " + evt.params.room )
}

function onRoomCreationError(evt:SFSEvent):void
{
	trace("An error occurred while attempting to create the Room: " + evt.params.errorMessage)
}

The RoomSetting class allows to specify a large number of parametersto fine tune all major and minor aspects of a Room. If the creation is successful the SFSEvent.ROOM_ADD event will be sent back to the client, otherwise an error message is notified in the SFSEvent.ROOM_CREATION_ERROR event. There could be several reasons why the Room cannot be created.

You can learn all the details about the RoomSettings parameters in the API documentation (both client and server).

Basic Room concepts

In the SFS2X framework Rooms are a quite sophisticated tool that can be configured in every minor detail. This article is not intended to analyze all these aspects. If you want to learn all the details we suggest to consult this guide to Room architecture.

In this section we are going to mention two different types of Rooms: game Rooms and non-games Rooms (or "regular" Rooms).

When creating a game Room always remember to set the isGame flag and configure the maximum number of players and spectators allowed in that Room.

Advanced Game Rooms and the Game API

With respect to SmartFoxServer 1, the SFS2X platform provides a new set of client and server APIs specifically designed for game creation and management, including public and private games, game invitations, user and Room matching and lots more.

A new type of game Room was introduced via the SFSGame class which is found both on the client and server side of the API. The new class extends the Room object providing dozens of new functionalities that enable developers to create advanced player matching, challenges and game invitations in a snap.

We highly recommend to take a look at the Game API article for more informations.