• Examples (iOS)
• Examples (Java/Android)
• Examples (C++)
Server API Documentation

 

» 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 have successfully logged in the Zone.

Joining a Room from the client API requires one line of code, in which a JoinRoomRequest is sent to the Server. 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 code required to handle both cases (sfs is the SmartFox class instance).

	...
	
	// Add room-related event listeners during the SmartFox instance setup
	sfs.AddEventListener(SFSEvent.ROOM_JOIN, OnRoomJoin);
	sfs.AddEventListener(SFSEvent.ROOM_JOIN_ERROR, OnRoomJoinError);
	
	...

	...
	
	// After the successful login, send the join Room request
	sfs.Send(new Sfs2X.Requests.JoinRoomRequest("The Lobby"));

	private void OnRoomJoin(BaseEvent evt)
	{
		Room room = (Sfs2X.Entities.Room)evt.Params["room"];
		Console.WriteLine("Room joined: " + room.name);
	}
	
	private void OnRoomJoinError(BaseEvent evt)
	{
		Console.WriteLine("Room join failed: " + (string)evt.Params["errorMessage"]);
	}
	...
	
	// Add room-related event listeners during the SmartFox instance setup
	sfs.addEventListener(SFS2X.SFSEvent.ROOM_JOIN, onRoomJoin, this);
	sfs.addEventListener(SFS2X.SFSEvent.ROOM_JOIN_ERROR, onRoomJoinError, this);
	
	...

	...
	
	// After the successful login, send the join Room request
	sfs.send(new SFS2X.JoinRoomRequest("The Lobby"));

	function onRoomJoin(evt)
	{
		console.log("Room joined: " + evt.room.name);
	}
	
	function onRoomJoinError(evt)
	{
		console.warn("Room join failed: " + evt.errorMessage);
	}
	...
	
	// Add room-related event listeners during the SmartFox instance setup
	sfs.addEventListener(SFSEvent.ROOM_JOIN, onRoomJoin);
	sfs.addEventListener(SFSEvent.ROOM_JOIN_ERROR, onRoomJoinError);
	
	...

	...
	
	// After the successful login, send the join Room request
	sfs.send(new JoinRoomRequest("The Lobby"));

	private function onRoomJoin(evt:SFSEvent):void
	{
		trace("Room joined: " + evt.params.room.name);
	}
	
	private function onRoomJoinError(evt:SFSEvent):void
	{
		trace("Room 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 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 with the usual approach: add the listeners during the SmartFox class setup and send the appropriate request (CreateRoomRequest in this case).

	...
	
	// Add room-related event listeners during the SmartFox instance setup
	sfs.AddEventListener(SFSEvent.ROOM_ADD, OnRoomCreate);
	sfs.AddEventListener(SFSEvent.ROOM_CREATION_ERROR, OnRoomCreateError);
	
	...

	// Set Room configuration
	RoomSettings settings = new RoomSettings("Piggy's Chat Room");
	settings.MaxUsers = 40;
	settings.GroupId = "ChatGroup";
	
	// Send the create Room request
	sfs.Send(new Sfs2X.Requests.CreateRoomRequest(settings));

	private void OnRoomCreate(BaseEvent evt)
	{
		Room room = (Sfs2X.Entities.Room)evt.Params["room"];
		Console.WriteLine("Room added: " + room.name);
	}
	
	private void OnRoomCreateError(BaseEvent evt)
	{
		Console.WriteLine("Room creation failed: " + (string)evt.Params["errorMessage"]);
	}
	...
	
	// Add room-related event listeners during the SmartFox instance setup
	sfs.addEventListener(SFS2X.SFSEvent.ROOM_ADD, onRoomCreate, this);
	sfs.addEventListener(SFS2X.SFSEvent.ROOM_CREATION_ERROR, onRoomCreateError, this);
	
	...

	// Set Room configuration
	var settings = new SFS2X.RoomSettings("Piggy's Chat Room");
	settings.maxUsers = 40;
	settings.groupId = "ChatGroup";
	
	// Send the create Room request
	sfs.send(new SFS2X.CreateRoomRequest(settings));

	function onRoomCreate(evt)
	{
		console.log("Room added: " + evt.room.name);
	}
	
	function onRoomCreateError(evt)
	{
		console.warn("Room creation failed: " + evt.errorMessage);
	}
	...
	
	// Add room-related event listeners during the SmartFox instance setup
	sfs.addEventListener(SFSEvent.ROOM_ADD, onRoomCreate);
	sfs.addEventListener(SFSEvent.ROOM_CREATION_ERROR, onRoomCreateError);
	
	...

	// Set Room configuration
	var settings:RoomSettings = new RoomSettings("Piggy's Chat Room");
	settings.maxUsers = 40;
	settings.groupId = "ChatGroup";
	
	// Send the create Room request
	sfs.send(new CreateRoomRequest(settings));

	private function onRoomCreate(evt:SFSEvent):void
	{
		trace("Room added: " + evt.params.room.name);
	}
	
	private function onRoomCreateError(evt:SFSEvent):void
	{
		trace("Room creation failed: " + evt.params.errorMessage);
	}

The RoomSetting class allows to specify a large number of parameters to 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). A third type also exists (MMO Rooms), but we will skip them for now.

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

The SFS2X platform provides a 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.

The SFSGame class, which is found both on the client and server side of the API, 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 information.