Application Architecture Overview

In this article we will analyze the server architecture focusing on Rooms, the most important tool to develop a wide range of applications.
We will discuss the various types of rooms available in the SmartFoxServer framework, compare their features and see how to use them in real multiplayer applications. In the second section of this article will also take a look at advanced techniques for developing more sophisticated behaviors.

» Rooms for everything!

In the SmartFoxServer framework, Rooms are the most important entities: they are responsible for grouping and connecting users together and let them interact with each other. They also provide a series of events that allow programmers to know about changes in the room properties in real time and react accordingly.

The diagram below shows how this works:


Each Zone represents a different application running in the server with its own set of rooms.
Users can perform any activity (chat, play, setup profile etc...) by connecting to one or more of these available rooms.
In order to simplify the development, SmartFoxServer already provides a set of default behaviors that can greatly speed up the process of creating typical multiplayer applications such as lobbies, chat rooms, instant messengers and games.

Typically these default behaviors don't require any server side programming.
If you wish to override them and create more advanced features you can easily write your own server extension(s) using languages such as ActionScript, Python and Java.

» Default Room Management

Room creation can happen in three different ways:

The boot-time rooms are declared inside the main config.xml file. When the server starts it parses the configuration and creates the rooms based on the specified settings. Each time a Room is created an "owner" is assigned to it, which is usually the user who created the Room. In the particular case of static rooms the owner is the server itself.

Creating rooms from a client side request is done with the createRoom() method by passing a number of parameters such as the room name, maximum number of users, room type (regular, game, limbo), etc... After a Room is successfully created the ownership is set to the User that sent the request.
The room creation may fail if the name of the room is already taken, if it contains bad words (bad words filter must be enabled), or if there are other restrictions in the number of rooms that can be created.

Finally you can create a new room from a server side extension, which is the most advanced way of the three. This technique allows more control as you can add your own logic, validation, properties etc... From the server side you can also decide the ownership of the room and perform any additional task.

» Room types and their life cycle

The SmartFoxServer framework provides three different types of room:

This is a list of properties that can be used to create a room dynamically:

Property   Description
name check check check The room name
password check check check An optional password
maxUsers check check check The maximum number of user allowed
maxSpectators --- check --- The maximum number of spectators allowed
isGame --- check --- A flag indicating if the room is a game room
exitCurrent --- check --- A flag indicating if the current room should be left before joining the new one
uCount check --- --- A flag indicating if the new room will receive the uCount update messages
vars check check --- An array of room variables
extension check check check An optional object. Specifies which extension should be dynamically attached to the room

To summarize you can check the following table of events:

Event       Description
onUserEnterRoom check check --- A user has joined the room
onUserLeaveRoom check check --- A user left the room
onSpectatorSwitched --- check --- A spectator was turned into a player
onRoomAdded check --- check A room was added in the Zone
onRoomDeleted check --- check A room has been removed from the Zone
onPublicMessage check check --- A public message has been received
onPrivateMessage check check check A private message hass been received

You can learn more about rooms and room creation by checking the following tutorials:

» Advanced room features - Room Variables

One of the most important features of Rooms is the ability to attach custom values to them, the so called Room Variables. These values can be set from both the client side and the server side and they can be very helpful to maintain the state of a Room.

A Room Variable is made up of four properties:

Room Variables are immediately available to all clients joining the Room and their change is notified in real time to all clients. A good example of Room Variable usage is the "SFSTris" game found at chapter 5.8 of this documentation.
The game board status is stored inside one or more variables, when a player makes his move the variables are modified with a client request and the changes are automatically broadcasted to all the players. Furthermore by keeping the status in Room Variables all spectators will be able to receive an up-to-date game state as soon as they join the room.

You can learn all the details about Room Variables by checking the following tutorials:

» Advanced room features - Extensions

Extensions are the most powerful tool available in SmartFoxServer. They allow developers to extend the server functionality by adding their custom code using various languages such as JavaScript / ActionScript, Python and Java.

Additionally, writing your game / application logic on the server side allows much better security and control.
Each room in the server can be controlled by its extension. The extension can receive any custom request from the client and respond to it. Also they can handle the server side events (i.e. a new user entered / left the room etc...).

You can all the details about server side extensions by reading the other chapters present in this same section of the documentation. (Section #6)

» Real-world application examples

In the second section of the article we are going to cover three different Room settings that you can use to create various types of multiplayer applications.
Each example will demonstrate how the different Room types can be combined together in various ways and be controlled by one or more server side extensions.

The following diagram illustrates the three example scenarios:


1. Simple chat:
The first example (Zone 1) shows how you can build a simple chat application with a main static room where all users are initially joined. From there, chatters will be able to create their own public or private rooms and invite other friends. This

As you can see from the diagram we only need to define one main static room in our config.xml. This is an example of such definition:

<Zone name="theChat">
		<Room name="Main Entrance" autoJoin="true" />

This will be the only room available when the server starts, all other rooms (of type "regular") will be created by users once they have logged in the application.
All other rooms can be created at runtime by the users through the chat interface. The simplest way to achieve this is by calling the createRoom() method of the client side Flash/Flex API.

The approach just shown here is the same we have used in many of the basic example applications that are available in the SmartFoxServer package.
For a full walkthrough on how to build a chat you can follow these tutorials:

2. Simple Lobby with Zone Extension:

The second example (Zone 2) shows a more advanced design, using a Lobby Room as the main entrance, a variable number of game rooms created by the players, and a Zone Level extension that manages the lobby and game logic.

The lobby room is created at boot time, by defining it statically in the config.xml file.
The following is an example of the Zone definition:

	<Zone name="theLobby">
			<Room name="Lobby" autoJoin="true" limbo="true" maxUsers="1000000"/>
			<Extension name="ext" classname="" type="script" />

You can notice that we've added the limbo flag to the room definition and a very high number for the maxUsers attribute in order to let all users to join it.

From the main lobby users will be able to create or join game rooms and interact with other users by starting a one-on-one chat in the style of MSN/ICQ and similar IMs.
More advanced features would also include the ability to create and edit a personal profile, customize an avatar, perform a search in the user list, keep a list of buddies etc... Also the application could let the user create small private chat rooms where they can invite more people and talk together.

SmartFoxServer was specifically designed with these tasks in mind and provides a number of advanced functionalities out of the box, like persistent buddy lists, the ability to easily connect to any database etc...

From the diagram you can also see that the Zone Level extension controls all the events happening in the Lobby and game rooms, allowing developers to add their custom logic for the game(s), validate user input and react to server side event.

3. Lobby with multiple games:

The third scenario (Zone 3) expands the previous application by adding multiple games to the mix.
From the diagram you can see that essentially the design is very similar to the 2nd example, except for the extensions which are plugged at Room Level. This allows the developer to create specific extensions for each game and dynamically attach them at run time when launching new game rooms.

The advantage of this approach is that we can concentrate on the logic of each game, leaving additional Lobby logic to the specific Lobby extension (if needed).
There are also a few performance considerations when using this application design:

  1. For each game running a new extension will be created.
    This means that you will need to optimize the way you use resources in your code. For example: if each game runs its own threads you may find yourself using too many resources when hundreds of games are running.
    For this reason it would be best to have a central thread/object pool where all games can borrow and return resource consuming objects.

  2. ActionScript extensions need to be compiled at runtime before running.
    This may add a significant overhead to the server when many hundreds or thousands of extensions are being created and destroyed.
    We recommend to use Java instead to optimize this process. Python extensions would also work well in this scenario as they are compiled to bytecode once and then executed as Java classes.

» Advanced room managements

In the first section of this article we've seen the various default features of each type of Room available in the SmartFoxServer framework.
Also we learned how extensions can help adding extra functionalities and logic to your applications but there's more.

A few examples could be:


doc index