Skip to content

Zone/Room Structure

We have mentioned in the previous tutorials that Zones are independent areas of the server that can run different games or applications. This way we can have multiple separate games running on the same server, instead of running multiple instances of SmartFoxServer to manage different applications.

If you're familiar with web servers, a virtual host would be a good analogy for a Zone.

Inside Zones there can be any number of Rooms, which provide a way to organize users in your applications. Rooms are in fact the main way to group users that can interact together.

ZoneRoomStruct

As per the diagram above, Rooms in one Zone are isolated and independent from those of the other Zones. Additionally Rooms can be organized further by grouping them in Room Groups. A classic use case is grouping Rooms of one type of game (say Chess) from another (Checkers) or Rooms that provide a different kind of service, such as chat Rooms.

We could think of a Room Group as a simple tag that can be applied to a Room to determine which category it belongs to.

Grouping room together has several advantages: for example it allows to send a smaller Room List upon user login, instead of sending the whole catalog of Rooms, which could be in the thousands in some applications.

In fact we can configure one or several Room Groups that are subscribed by the client at login time and avoid sending the entire list of Rooms available in the Zone.

The mechanisms for subscribing and unsubscribing to Room Groups will be explained later in this tutorial

Room types

SmartFoxServer provides three types of Rooms:

  • Regular: the most versatile and basic type that can be used for both chats and games
  • SFSGame: a specialized Room type for games that offers sophisticated match-making features for public and private games, game start/stop coordination, User invitations and more
  • MMORoom: an MMO-oriented Room type based on the AoI system (Area Of Interest) that allows hundreds or thousands of players to interact at the same time

Besides their specializations, every Room provides many fundamental features such as: renaming, resizing, locking/unlocking, life-cycle management, swear word filtering, moderation, banning and more.

Additionally each Room can have any number of Room Variables, to store custom data that is synchronized among all joined users, to share game state etc.

On the server side it's also possible to plug Room Extensions, which is custom code that can handle game logic, match making etc., making it possible to extend the server in any direction.

Static vs Dynamic Rooms

Rooms can be created in two main ways:

  • statically: by creating them via the AdminTool > Zone Configurator. In this way their configuration is stored in the local SmartFoxServer config file and they will be available as soon as the server starts up.
  • dynamically: by creating them at runtime via the client side API or the server side API. These Rooms have a limited life-cycle depending on their settings.

Dynamic Rooms are automatically removed based on their settings:

  • game Rooms: removed as soon as the last player leaves the Room
  • regular Room: removed when the Room is empty and its owner has disconnected

On the other hand static Rooms are never removed, however these defaults can be overriden at creation time, if necessary.

Room Settings

The following is a quick overview of the settings available when we create a Room. Many of these parameters are optional and can be left at their default, depending on your requirements.

These settings are found in a class called RoomSettings which is used to create a new Room.

Basic Settings

  • name: the name of the Room, must be unique
  • password: if a password is specified the Room becomes private (optional)
  • maxUsers: the maximum number of users allowed in the Room (optional, default is 20)
  • maxVariablesAllowed: the maximum number of Room Variables allowed in the Room (optional, default is 5)
  • isGame: if the Room is going to be used for games this flag should be set to true (optional)
  • maxSpectators: if this is a Game Room you should configure how many spectators are allowed inside (optional, default is 0)
  • groupId: the name of the Group to assign the Room to (optional, default is "default")

All these settings are available on both client and server side, although on the client-side a few of them are limited to prevent potential misuse.

Advanced Settings

  • allowOwnerInvitation: specify if the owner of the Room is allowed to send invitations to join the Room (optional, default = true)
  • autoRemoveMode: decides the life-cycle of a Room, i.e. when it is going to be destroyed (optional)
  • roomVariables: provide a list of Room Variables that will be added to the Room at creation time (optional)
  • extension: dynamically attach a server-side Extension to the Room, adding custom logic for your application (optional)

Fine-tuning settings

  • permissions: allows to specify specific permissions, for example to rename or resize the Room after creation (optional)
  • events: allows to toggle specific events triggered by the Room

Room Variables

Room Variables allow to store custom data in a Room to maintain application state. These variables are automatically synchronized between all users joined in the Room and can have different settings and permissions for visibility and access control.

Let's take a look at each property of a Room Variable:

  • name: the unique name of the variable
  • isPrivate: if set, the variable can only be modified or deleted by its creator (optional, default is false)
  • isPersistent: by default a user created variable is removed from the Room when the user leaves it. If this flag is turned on, the variable will persist until the user logs out or disconnects (optional, default is false)
  • isGlobal: by default variable updates are sent to all users in the Room. A global variable is also updated outside of the Room to all users in the same Room Group (optional, default is false)
  • isHidden: if set, the variable is only accessible on the server side and is not transmitted to clients (optional, default is false)
  • value: the value of the variable. The following types are supported: Null, Bool, Byte, Short, Int, Long, Float, Double, String, SFSObject, SFSArray, Vector2, Vector3

Note:

The Null type is not really a type but rather it is used to delete an existing Room Variable.

The following snippet demonstrates how to create a new Room with a number of Room Variables:

sfs.AddEventListener(SFSEvent.ROOM_ADD, OnRoomAdded);
sfs.AddEventListener(SFSEvent.ROOM_CREATION_ERROR, OnRoomCreationError);

var settings = new RoomSettings("My Room");
settings.MaxUsers = 8;
settings.MaxSpectators = 8;
settings.IsGame = true;
settings.Variables = new List<RoomVariable> { 
                        new SFSRoomVariable("minRank", 15), 
                        new SFSRoomVariable("highscore", 15000) 
                    };

sfs.Send(CreateRoomRequest(settings));

private void OnRoomAdded(ApiEvent evt) 
{
    var room = (Room) evt.Params[EventParam.Room]!;
    sfs.Logger.Info("New room added: " + room.Name);
}

private void OnRoomCreationError(ApiEvent evt)
{
    var errorMessage = (String) evt.Params[EventParam.ErrorMessage]!;
    sfs.Logger.Info("Room creation failed: " + errorMessage);
}

When a Room is added to the local Room list we receive a ROOM_ADD event with the new Room details. On the other hand if the creation of our Room fails we'll get the details from the ROOM_CREATION_ERROR event.

Room Group subscriptions

By default every Room created in the server belongs to the 'default' Room group and every User logging into a Zone is also automatically subscribed to that same group.

By subscribing or unsubscribing to specific Room groups it is possible to access the relative list of Rooms and receive the relative events (such as new Rooms being created or removed).

From the client side API this is done via one of the following requests:

sfs.Send(new SubscribeRoomGroupRequest("card games"));

or:

sfs.Send(new UnsubscribeRoomGroupRequest("card games"));

However in order for these requests to suceed Room Groups have to be defined at the server level, via the Zone Configurator in the Admin Tool. Under the General tab you'll find the following fields:

ZoneRoomStruct

  • Public Room Groups: defines which groups are publicly available to be subscribed by clients
  • Default Room Groups: defines which groups are automatically subscribed as soon as the client is logged in

It is also possible to define other Room groups that are not listed in this public list. This is done in server side Extensions and provides another level of customizability.

Room Remove modes

SmartFoxServer can automatically manage the Room life-cycle, meaning that it can remove unused Rooms at the right time, depending on the autoRemoveMode settings provided at creation time.

These are the 4 different auto-remove modes available:

  • Default: regular Rooms are removed when empty and the creator goes offline; game Rooms will be removed when empty
  • When_Empty: the Room is removed when it is empty
  • When_Empty_And_Creator_Is_Gone: the Room is removed when empty and its creator goes offline
  • Never_Remove: the Room is never auto-removed

When the remove mode is unspecified the Default mode will be used, otherwise you can set the preferred modality for each created Room. For instance you may want to choose the Never_Remove mode for a "lobby" Room that is supposed to exist at all times, regardless if it's empty or not.