Skip to content

Zone Configurator

The AdminTool's Zone Configurator module allows configuring Zones and static Rooms that will be generated automatically every time SmartFoxServer is started. Administrators can create new Zones and Rooms, or modify the existing ones.

Zone Configurator screenshot

Usage

When the module is opened, the tree of currently configured Zones and their static Rooms is requested to the server. The tree is automatically updated should another administrator add or remove a Zone/Room (proper notifications are displayed too).

Entities showing a Toggle ( or ) button are not active yet (see the note below too). This can happen if they have been added after the last server restart, or if an error occurred when created during the server's startup process (for example a Room with an invalid name length).

The following controls are available for each entity:

  • Activate Zone () button — (Zone only) Activate the Zone.
  • Add Room () button — (Zone only) Add a new Room to the Zone.
  • Remove Zone/Room () button — Delete the Zone or Room; removing a Zone also deletes all its Rooms automatically.

Note that also Rooms can show a greyed-out Activate () button, but it is always disabled because Rooms can never be activated individually. This is just a visual reminder that the Room is inactive.

Click on the Add Zone button at the bottom of the panel to create a new Zone.

Click on a Zone or Room name to edit it. When editing is entered, the right area of the module shows the configurations settings. Settings can be reloaded at any time by clicking the Reload button located at the bottom of the editing area. Click on the Cancel button () to interrupt the editing.

In order to submit your changes to the entity configuration, click the Submit button. In case of concurrent changes made by different administrators, an alert message is displayed and overwriting is prevented.

Apply changes

Configuration changes are not applied automatically by SmartFoxServer when submitted. You need to restart the server for the changes to take effect or, in case of a newly created Zone, click on the Activate Zone () button near the Zone name in the tree. A notification in the top right corner reminds you that a restart is needed upon configuration update.

If selected, the Zone backup checkbox located near the Submit button allows creating a backup copy of the existing Zone settings before saving the updated configuration. This is highly recommended. There's a single checkbox for both Zone and Room editing, because Room settings are a subset of the parent Zone configuration. A backup is always saved automatically when a Zone or Room is deleted. The backup files are located under the zones/_backups folder with the date and time of the backup in their name.

In order to restore a backup, rename it to zone-name .zone.xml (for example MyGame.zone.xml) and move it to the zones folder, overwriting the existing file. Then restart SmartFoxServer.

Configuration settings

The Zone and Room configuration settings are both divided into a number of tabs. Most of the settings are self-explanatory, anyway they are all accompanied by an Help () icon: hovering the mouse pointer shows a brief description in a tooltip. Reading such notes is highly recommended.

The following sections show the screenshots of all Zone and Room tabs, delving deeper into the less straightforward settings.

Zone configuration tabs

General

This tab contains the basic Zone settings.

General

Additional information

  • The Use encryption and Use custom login settings require specific setup before they are enabled; check the Configuring SSL/TLS document and the How to create an Extension based custom login recipe respectively for more information.
  • The Apply word filter to... switches have effect if the Words Filter is active only; also, applying the words filter to the public messages can be turned on or off in the Room configuration settings.
  • The User reconnection timeframe indicates the number of seconds SmartFoxServer will "wait" before dispatching the CONNECTION_LOST event, thus allowing client reconnection in case of a temporary network issue (check the Reconnection System documentation for more information).
  • The Public room groups are the only Groups that clients are allowed to register to. This field should contain names matching those entered in the Room configuration's Group ID setting; in fact there isn't a pre-defined list of all available Groups: SmartFoxServer creates it "on-the-fly" by retrieving all the Group IDs entered in the configuration of all the Rooms contained in the Zone (plus a standard default Group).
  • The Default room groups are the Groups to which all clients logging into the Zone will be automatically registered to. This field should contain names matching those entered in the Room configuration's Group ID setting.

Advanced

This tab contains the advanced Zone settings.

Advanced

Additional information

  • When the Allow file uploading setting is enabled, clients can upload files to the server via HTTP requests as described in the Uploading files with SmartFoxServer tutorial. Other than this setting, the file uploading feature requires the internal web server to be running and the HTTP protocol to be active; both options can be set in the Web Server tab of the Server Configurator module.

Words Filter

This tab allows configuring the words filter. SmartFoxServer comes with a built-in and highly customizable words filter allowing automatic moderation: when active, it can be applied to usernames, Room names, private messages and Buddy messages (in the General tab), and to public chat messages (in Room configuration settings).

Words Filter

Additional information

  • The bottom section of the tab provides an editor to add/remove/modify words files. A specific file can be assigned to the words filter by selecting it in the table and clicking the rightmost button under the table (). The file name is written in the Words file configuration field above. The configuration must be submitted as usual to activate the new words file for the current Zone.

Flood Filter

SmartFoxServer features an anti-flood filter which can be configured in this tab: it allows automatic banning of clients that are trying to flood your applications with the same requests over and over.

Flood Filter

Additional information

  • The flood filter can be applied to specific requests only by means of the Request filters setting.

Zone Extension

This tab allows attaching a custom Extension to the Zone, containing your server-side logic. More information on Extensions is available in the Extension Development section of this documentation.

Zone Extension

Additional information

  • The AdminTool auto-discovers all available Extensions and classes and populates the Name and Main class dropdowns; this facilitates the selection and helps avoiding typing errors.
  • If JAVA is selected in the Type dropdown, all jar files contained in the Extension's folder are processed, provided their name ends with ...Extension.jar (for example MyExtension.jar); all other jar files are skipped. This is required to avoid receiving useless data (like the list of classes contained in library jar files).
  • The Use naming convention setting is not an actual Zone parameter (in fact it isn't saved in the Zone configuration – that's why it is displayed in light grey color), but it is used by the AdminTool to filter the classes listed in the Main class field, showing only those ending with the Extension suffix (for example BattleFarmExtension or MyPythonExtension.py).

Database Manager

SmartFoxServer can easily connect to any external database. Enter the settings in this tab in order to setup your database connection for the current Zone.

Database Manager

Buddy List

This tab activates and configures the Buddy List system. The Buddy List allows each client to keep a list of friends and know in realtime if they are online, their status, etc. More information can be found in the Buddy List API documentation.

Buddy List

Privilege Manager

This tab can be used to create different profiles with different permissions as it regards the interaction with the server. Each permission profile contains a list of denied API calls for each client belonging to a specific category. More information is available in the Privilege manager documentation.

Privilege Manager

Room configuration tabs

General

This tab contains the basic Room settings.

General

Additional information

  • The Group ID parameter contains the name of the Room Group to which the Room belongs; note that there isn't a pre-defined list of all available Groups: SmartFoxServer creates this list "on-the-fly" by retrieving all the Group IDs entered in the configuration of all the Rooms in the same Zone. If left empty, the Room is assigned to the predefined default Group.

Permissions & Events

This tab allows configuring the events that can be fired by the Room and the operations that can be executed on a Room at runtime.

Permissions & Events

Room Variables

A Room can have a number of variables attached to it, where application-specific information that should be shared among all the clients which joined the Room can be stored. This tab allows creating Room Variables on static Rooms.

Room Variables

Room Extension

This tab allows attaching a custom Extension to the Room, containing your server-side logic. More information on Extensions is available in the Extension Development section of this documentation.

Room Extension

Additional information

  • The AdminTool auto-discovers all available Extensions and classes and populates the Name and Main class dropdowns; this facilitates the selection and helps avoiding typing errors.
  • If JAVA is selected in the Type dropdown, all jar files contained in the Extension's folder are processed, provided their name ends with ...Extension.jar (for example MyRoomExtension.jar); all other jar files are skipped. This is required to avoid receiving useless data (like the list of classes contained in library jar files).
  • The Use naming convention setting is not an actual Room parameter (in fact it isn't saved in the configuration – that's why it is displayed in light grey color), but it is used by the AdminTool to filter the classes listed in the Main class field, showing only those ending with the Extension suffix (for example TrisRoomExtension or MyPythonRoomExtension.py).

MMO Settings

This tab can be used to activate the "MMO" features for the current Room. More information is available in the MMO API documentation.

MMO Settings

Additional information

  • When a Room is turned into an MMORoom by activating the Is MMO Room switch, the following standard features are not available anymore:
    • Spectators: even if the MMORoom is a Game Room (see the General tab), users can't join it as spectators.
    • USER_ENTER event: this event is never dispatched; other clients entering the current client's Area of Interest (AoI) are notified through the PROXIMITY_LIST_UPDATE event.
    • USER_EXIT event: this event is dispatched to the client leaving the Room only; other client leaving the current client's Area of Interest are notified through the PROXIMITY_LIST_UPDATE event.