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


» Room architecture

The Room object is one of the most important building blocks in the structure of any multiplayer applications. It is responsible for grouping and connecting users together and make them interact with each other. From a developer's perspective it provides useful events that help building the application logic and each Room can be governed by a different server side Extension.

In this chapter we are going to dissect the many features provided by the Room object and the new powerful functionalities offered in the SFS2X framework.

» General architecture

We have introduced in other articles of this documentation a key element in SFS2X, the Room Groups:

The above diagram should clarify what these Room Groups are all about. As we can see Rooms are still all contained in the Zone and they look like they are at the "same level". This is actually the best way to represent the general structure of Room Groups: in fact a Group is just an extra ID applied to each Room which acts as a "category" thus allowing filtering and separation.

This feature allows clients to limit their local view of the entire Zone structure just to one or more groups, instead of the whole catalog. The use cases are countless: separating game Rooms of different types, creating different areas of the application, hiding certain Rooms for certain type of users, etc.

The advantages of Room grouping are that we can minimize the Room data that is transmitted to the clients and reduce the number of update events, making the application more efficient.

» Room types

SFS2X provides three types of Rooms: Regular, Game and MMO, each with a very high level of control. With the ability to set every minute detail of a Room, developers are enabled to quickly create many different behaviors, sophisticated interactions and complex structures for all kind of games.

Among the Room features in SFS2X we have the ability to rename, resize and lock/unlock each Room dynamically at runtime. Additionally we can select which events the Room will send to the clients and precisely control the Room life-cycle.

Room Variables are available to store custom data and the server side API offers advanced features to search Rooms by custom criteria, match making, challenges, invitations and lots more.

» Game Rooms

Game Rooms are a specialized type of Rooms with additional features:

» MMO Rooms

MMO Rooms extend the functionality of regular Rooms by adding an Area of Interest (AoI in short) to determine the range of the events that will be received by users. The AoI parameter represents the area within which users will affect each other, for example when sending public messages, updating User Variables, etc. MMO Rooms are particularly suitable for large virtual worlds where thousands of players are exploring and interacting on a vast map with minimal network overhead.

» Introducing the Room settings

In order to create a Room as described in this article, there are just a few mandatory parameters, all the others can be left to their default values if you are not interested in more advanced options.

Let's see all the available settings, which are all contained in the RoomSettings class (see the API documentation). All these settings are available on both client and server side, although on the client-side a few of them are limited to prevent malicious code from harming the server with spam or other nasty attacks.

» Basic settings

The following is the list of all the basic settings.

» Advanced settings

The following is the list of the more advanced settings. More details are provided further on.

» Fine-tuning settings

The following is the list of some additional settings. More details are provided further on.

» The Room advanced settings

» Auto-remove mode

The AutoRemoveMode option allows you to choose 4 different ways in which the Room life cycle can be handled.

In order for the auto-remove feature to be active, the isDynamic flag of the Room must be set to true.

The AutoRemoveMode setting is available only in the server-side API. On the client-side the DEFAULT mode is always used.

» Room Variables

Room Variables are a useful tool to store custom data in a Room to maintain application state. These variables are automatically synchronized between all users in the Room, making it a powerful tool to quickly change game states, scores and other values that are propagated to all players.

The SFS2X API also provide several settings to control the access, life cycle and visibility of each Room Variable. Let's see each property of a RoomVariable in detail.

On the client side (ActionScript 3), setting variables is straightforward:

private function setSomeVariables(room:Room):void
	var listOfVars:Array = new Array()
	listOfVars.push( new SFSRoomVariable("bgImage", "coolBackground.jpg") )
	listOfVars.push( new SFSRoomVariable("stars", 4) )
	// nested object
	var chatSettings:SFSObject = new SFSObject()
	chatSettings.putUtfStringArray("allowedFonts", ["Verdana", "Arial", "Times New Roman"])
	chatSettings.putIntArray("allowedFontSizes", [10,11,12,13])
	chatSettings.putBool("isBoldAllowed", true)
	chatSettings.putBool("isItalicAllowed", true)
	chatSettings.putBool("isUnderlineAllowed", false)
	listOfVars.push( new SFSRoomVariable("settings", chatSettings))
	// Set variables
	sfs.send( new SetRoomVariablesRequest(listOfVars, room) )

On the server side it is possible to create Room Variables that are owned by the SmartFoxServer instance itself. This is like a "virtual user" that never leaves the system thus allowing to create Room Variables that are never removed. In order to do so you need to pass a null as the owner of the variable.

This is a quick example showing how to set Room Variables in a server side Java Extension:

private void setSomeVariables(Room room)
	List<RoomVariable> listOfVars = new ArrayList<RoomVariable>();
	listOfVars.add( new SFSRoomVariable("bgImage", "coolBackground.jpg") );
	listOfVars.add( new SFSRoomVariable("stars", 4) );
	RoomVariable hiddenVar = new SFSRoomVariable("isPremiumUsersOnly", true);
	// Set variables
	sfsApi.setRoomVariables(null, room, listOfVars)

As you can see the Room Variable called hiddenVar is marked as hidden and it will not be transmitted to the client. The server side code will be able to check it and see if the Room is for premium users only.

» Server-side Extension

A server side Extension can be dynamically plugged into the Room upon creation. This enables the developer to attach custom logic to the Room and control its usage. Typically this is used for running games, enabling advanced moderation controls, filtering messages and tons more.

For a full discussion on Extensions please make sure to consult the server side Extensions documentation here (Java) or here (JavaScript).

» The Room fine-tuning settings

» Permissions and events

In SmartFoxServer 2X you have full control over the events fired by each Room.
This is an example from the Room configuration in the Administration Tool:


The above interface shows how you can fine tune each Room-level event and permission when creating a new Room. According to the above configuration users will be able to change the name and password of the Room, while the resizing (capacity change) will be denied. Public messages are also allowed in the Room and all available events will be notified.
In another Room you may want to configure these settings differently, suppressing some of the events and providing a different set of permissions.

Rooms define two categories of settings: Events and Permissions.

Events indicate which events the Room will notify to the joined clients:

The USER_COUNT_CHANGE_EVENT event is one of the most bandwidth-eating notifications under heavy traffic. SmartFoxServer provides a couple of engine-level optimizations that reduce its impact by a large degree.

  • Packet Priority: the SmartFoxServer 2X engine allows to specify a priority level for each packet, allowing low-priority responses such as the user count change event to be discarded if the client queue is getting too busy. This significantly reduces the dropped-messages problem when the client is using a slow connection.
  • User Count Event Throttling: to further increase the level of control over this event SmartFoxServer 2X can be configured to "slow down" the pace at which these updates are sent by aggregating the messages and only sending the significant ones. In other words you are able to specify the interval of time after which the event should be fired. All updates between two intervals will be aggregated discarding the stale ones.
    The default is real-time; in order to save bandwidth you might want to reduce these updates to 1 time per second or less. Check the Zone Configurator in the AdminTool for more on this.

Turning off USER_ENTER and USER_EXIT events will stop Public / Private Messages from working correctly. You can still communicate via Buddy messages.

The USER_ENTER and USER_EXIT events should always be used in conjunction. If you decide to turn one of them off the other should also be set in the same way as they are two sides of the same notification.

Permissions indicate which Room-related operations can be executed at runtime:

» Removal mode

Rooms have a way of defining their removal mode, which indicates if and when the Room should be auto-removed (destroyed). The following settings are available:

» Bad words filter

If a Words Filter is configured at the Zone level, developers are be able to apply it to public messages exchanged in the Room.

» Player ID generator

Finally, for very advanced game logic, developers can provide an alternative PlayerId Generator class that uses custom code to handle and distribute player IDs in the Room. The class is required to implement the com.smartfoxserver.v2.util.IPlayerIdGenerator class provided in the SFS2X server-side API.

» More resources

If you want to learn more details about the many aspects we have presented in this overview we suggest these articles: