Creating Rooms from server side

In this recipe we will show how to create Rooms from your server side Extension.

» Create a standard chat/lobby Room

CreateRoomSettings cfg = new CreateRoomSettings();

cfg.setName("MyNewRoom");
cfg.setMaxUsers(50);
cfg.setDynamic(true);

try
{
	Room myNewRoom = getApi().createRoom(getParentZone(), cfg, null);
}
catch (SFSCreateRoomException)
{
	// ... handle exception
}

The CreateRoomSettings class offers many parameters to configure all aspects of a Room. In this case we only need to set the name (which must be unique), the maximum number of users and set the dynamic flag to true. The latter tells the server to automatically manage the life cycle of the Room, removing it when it’s appropriate. More details on Room management are found here.

In the createRoom() method we first pass the Zone where the Room should be created and the settings object. The third parameter specifies the creator/owner of the Room. Passing null means that the server itself will be the owner.

» Create a game Room

CreateRoomSettings cfg = new CreateRoomSettings();

cfg.setName("MyNewGame");
cfg.setGame(true);

cfg.setMaxUsers(10);
cfg.setMaxSpectators(5);

cfg.setDynamic(true);

try
{
	Room myNewRoom = getApi().createRoom(getParentZone(), cfg, null);
}
catch (SFSCreateRoomException)
{
	// ... handle exception
}

Game Rooms differ from standard ones in a few ways:

  • they allow players and spectators
  • spectators can become players and viceversa
  • their life cycle is slightly different that of regular Rooms
  • each player is auto-assigned a playerId, which is useful to keep track of turns etc.

For all the details on Game Rooms follow this article.

 » Create a password protected Room

CreateRoomSettings cfg = new CreateRoomSettings();

cfg.setName("MyProtectedRoom");
cfg.setMaxUsers(20);
cfg.setDynamic(true);
cfg.setPassword("--==StrongPassword123==--");

try
{
	Room myNewRoom = getApi().createRoom(getParentZone(), cfg, null);
}
catch (SFSCreateRoomException)
{
	// ... handle exception
}

The code is similar to the previous example with the addition of the password. Now users will need to know the password to join the Room.

» Fine tuning the Room’s permissions and events

CreateRoomSettings cfg = new CreateRoomSettings();

cfg.setName("MyNewRoom");
cfg.setMaxUsers(30);
cfg.setDynamic(true);
cfg.setRoomSettings(EnumSet.of(SFSRoomSettings.ROOM_NAME_CHANGE, SFSRoomSettings.CAPACITY_CHANGE));

try
{
	Room myNewRoom = getApi().createRoom(getParentZone(), cfg, null);
}
catch (SFSCreateRoomException)
{
	// ... handle exception
}

the CreateRoomSettings.setRoomSettings() method allows to specify a number of features we want to toggle in the Room itself. In this case we specify that we want to be able to change the name and the size of the Room dynamically, after it’s been created. There are 4 main features that can be toggled: ROOM_NAME_CHANGE, PASSWORD_STATE_CHANGE, PUBLIC_MESSAGES, CAPACITY_CHANGE.

Similarly it is possible to toggle a number of standard events that are sent to the clients:

cfg.setRoomSettings(EnumSet.of(SFSRoomSettings.USER_VARIABLES_UPDATE_EVENT,
                               SFSRoomSettings.USER_COUNT_CHANGE_EVENT));

The list of events specified in the code above toggles the client broadcasts when User Variables are updated (to all users in the same Room), and when the Room counters change (# of users and # of spectators).

For all the details of Room permissions and events check this article in the docs.

» Creating a Room with Room Variables

CreateRoomSettings cfg = new CreateRoomSettings();

cfg.setName("MyNewRoom");
cfg.setMaxUsers(30);
cfg.setDynamic(true);

List<RoomVariable> vars = Arrays.asList
(
	(RoomVariable) new SFSRoomVariable("integer", 12345),
	new SFSRoomVariable("bool", false),
	new SFSRoomVariable("string", "abcdefg")
);

cfg.setRoomVariables(vars);

try
{
	Room myNewRoom = getApi().createRoom(getParentZone(), cfg, null);
}
catch (SFSCreateRoomException)
{
	// ... handle exception
}

We can pass any number of Room Variables directly at creation time, no need to create the Room first and set the variables later.

» Creating a Room with Extension

CreateRoomSettings cfg = new CreateRoomSettings();

cfg.setName("MyNewRoom");
cfg.setMaxUsers(30);
cfg.setDynamic(true);

cfg.setExtension( new CreateRoomSettings.RoomExtensionSettings("ExtName", "my.package.MyExtension") );

try
{
	Room myNewRoom = getApi().createRoom(getParentZone(), cfg, null);
}
catch (SFSCreateRoomException)
{
	// ... handle exception
}

Attaching an Extension to a new Room is very easy. Just pass the name and main class of the Extension and it will be activated immediately.

» Create a Room in a specific Room Group

CreateRoomSettings cfg = new CreateRoomSettings();

cfg.setName("MyNewRoom");
cfg.setMaxUsers(50);
cfg.setDynamic(true);
cfg.setGroupId("Chat");

try
{
	Room myNewRoom = getApi().createRoom(getParentZone(), cfg, null);
}
catch (SFSCreateRoomException)
{
	// ... handle exception
}

Room Groups allow to organize Rooms in different sections or areas. This is particularly useful when Rooms need to be separated by topic or activity and users should only be able to see specific lists of Rooms instead of the whole list.

If you’re not familiar with Room Groups you can learn all the details here.