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

 

» The Extension API

In this article we are taking a look at the most useful elements in the Extension API and how to harness the server-side framework and the accompanying javadoc.

» Zone level / Room level

Server extensions can be plugged into a Zone (we call it Zone-level Extension) to govern the whole application or into a single Room (Room-level Extension) in order to only manage that particular Room.

The difference between the two approaches is exclusively in scope. A Zone-level Extension can listen to any event in the Zone and control all the Rooms and users that it manages. On the other hand a Room-level Extension can only listen to the events in that Room and manage the users contained in it.

A typical use of Room-level Extension is to manage the logic of a game running in that Room.

» Working with the server API

The SFS2X framework is mainly composed of three different elements.

We will now take a closer look to each one and discuss them briefly.

» API Classes

The simplest way to access the API is via the getApi() method in your Extension code, which provides a reference to the server core API. You can learn all its methods by checking the SFSApi class javadoc.
Here is a quick example showing how to create a Room:

void makeRoom() throws SFSCreateRoomException
{
    CreateRoomSettings settings = new CreateRoomSettings();
    settings.setName("The music Room");
    settings.setMaxUsers(20);
    
    getApi().createRoom(getParentZone(), settings, null);
}

SFS2X also provides specialized API for the Buddy List and the Game Matching features. In the following paragraph we explain how you can access them.

» The SmartFoxServer class

The next important element in the framework is the SmartFoxServer class which provides access to the many services running in the system. Although working with services is a quite advanced topic, we can also use this object to access the specialized API.

The following code snippet shows how to access the the Game API, Buddy List API and MMO API:

void getMoreApi(User owner) throws SFSCreateRoomException
{
    ISFSGameApi gameApi = SmartFoxServer.getInstance().getAPIManager().getGameApi();
    ISFSBuddyApi buddyApi = SmartFoxServer.getInstance().getAPIManager().getBuddyApi();
    IMMOApi mmoApi = SmartFoxServer.getInstance().getApiManager().getMMOApi();
    
    CreateSFSGameSettings settings = new CreateSFSGameSettings();
    settings.setName("PongRoom");
    settings.setMaxUsers(2);
    settings.setMaxSpectators(8);
    
    // ...more game settings here...
    
    gameApi.createGame(getParentZone(), settings, owner);
}

» Data classes

There are many different data classes in the framework that provide an abstraction for various elements of the API: Zone, Room, User, Session etc. They are mainly found under the com.smartfoxserver.v2.entities.* package.

One important facet of server-side development is that data classes should always be used for reading properties but rarely for writing them. For example making direct changes to the values of a Zone or Room will cause only a local change but no update is going to be sent to the clients.

NOTE: data classes expose lots of getters and setters but for Extension development, only getters are really significant. The changes instead, must applied via the API which provide a mechanism for updating the relevant clients about the state updates.

A practical example is setting User Variables for a client. If you consult the javadoc, you will notice that the User object exposes a setVariable method which you might be tempted to use. There is nothing wrong with it, but the change will exclusively take its effect on the server-side, and no updates will be sent to the clients (which is necessary to keep the correct synchronization).

The proper way to proceed is to use the API setUserVariables method, which enables to automatically notify all the clients that require an update and even fire a server event, where necessary.

To summarize never do this:

User kermit = getParentZone().getUserByName("Kermit");

List<UserVariable> vars = new ArrayList<>();
vars.add(new SFSUserVariable("nickname", "The Frog"));

kermit.setVariables(vars);

Instead do this:

User kermit = getParentZone().getUserByName("Kermit");

List<UserVariable> vars = new ArrayList<>();
vars.add(new SFSUserVariable("nickname", "The Frog"));

getApi().setUserVariables(kermit, vars);

» More resources

Now that you have learned the basics of Extension development it is time for the fun stuff, writing your own and experimenting with the framework.

Also we highly recommend the following resources to learn more: