SFS2X Docs / ExtensionsJava / extension-api
» 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.
- API classes: they provide an organized way to access the many functionalities of the server, such as creating Rooms, setting Room/User Variables, handling game challenges, matching players and a lot more.
- Services: they manage specific elements of the server. For example the RoomManager provides access to the Rooms created in a Zone, allowing to perform searches, filtering, etc.
- Data classes: they are the most numerous in the framework and they provide abstractions to the SmartFoxServer data (e.g. User, Room, Buddy, Invitation, Event, etc).
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:
- Server side recipes: a long list of "HowTos" and examples of server side coding.
- Advanced Extension concepts document
- Java server-side API documentation, in particular the SFSApi class which represents the entry point to interact with the server
- the Tris and SpaceWar games, available for all supported platforms, which include server-side source code
- the BattleFarm and Space Race ActionScript 3 games, which include both client and server-side source code