SFS2X Docs / Overview / using-the-documentation
» How to use the documentation and examples
This document provides a quick tutorial on how to obtain the best from the provided SmartFoxServer 2X (aka SFS2X) documentation. Our first recommendation is to consult the articles provided in this section before proceeding with the examples and technical docs.
Whether you are a seasoned SmartFox developer or you have just moved your first step in the multiplayer world, you will find the initial articles particularly useful to get started. The Getting Started section will guide you in the client and server setup phase while the Advanced Topics section provides an insight on the most advanced features of the Extension system, the server API and lots more.
» The Examples
We're strong advocates of our patent-pending Learning-While-Doing™ methodology. Of course we are kidding about the patent thing, but we are serious about learning by following a series of examples of increasing complexity.
Throughout the documentation you will find many code snippets to show the discussed features. All of the client side snippets are written in C#, JavaScript and ActionScript 3. C# and JavaScript have been chosen because nowadays they are the most common ones among game developers (thanks to Unity and HTML5), while ActionScript 3 was the language we used in the first release of this documentation. These languages easily cover both developers with a scripting background and those accustomed to more structured languages.
The server side snippets instead are provided in Java, which is the native language of SmartFoxServer. Starting from version 2.13 we also introduced JavaScript as server side language, so over time we may also provide the JS versions of the Java snippets.
The client snippets have a light gray language selector, while the server ones have a dark gray selector.
Also, SmartFoxServer comes packed full with simple and advanced examples made in C#, JavaScript, Objective-C, Java, ActionScript 3 and C++, where you can learn the very basics and quickly move to the more interesting and powerful features.
Each example comes with source code for both client and server side and attempts to build on the previous examples in the serie to provide a sense of continuity.
» The API doc
Once you have gotten an idea of what the new SmartFoxServer 2X can do for you and tested some of the examples, you will be probably eager to start playing with the API and prototyping some ideas. This is of course the moment where the client and server API documentation will come in handy.
Below follows a list of tips to get started with API without getting lost in the host of packages and classes that you will encounter.
» The client side
The client-side API main object is the SmartFox class, found in the Sfs2X (C#), SFS2X (JavaScript), sfs2x.client (Java) or com.smartfoxserver.v2 (AS3) package. This is the main entry point of the client API. This object allows you to manage your event listeners, start a connection and send requests via the send() method.
Another important section of the client framework is the Sfs2X.Requests (C#), SFS2X (JavaScript), sfs2x.client.requests (Java) or com.smartfoxserver.v2.requests (AS3) package. Here you will find dozens of different classes, each one representing a specific client request such as LoginRequest, JoinRoomRequest, SendPublicMessageRequest and many more. There are also three separate subpackages (except for JavaScript), game, mmo and buddylist (Game, MMO and Buddylist for C# API), where you can find advanced API for building games, MMOs and managing buddy lists respectively.
» The server side
The classes that act as entry points to the Java server side API are found in the com.smartfoxserver.v2.api package. Specifically:
- SFSApi: here you find dozens of methods for the most common server operations: login, create/remove rooms, send messages, join users, set variables, etc.
- SFSGameApi: game specific API
- SFSBuddyApi: buddy list specific API
- MMOApi: MMO specific API
IMPORTANT NOTE
While browsing the Javadoc you might at times find fields or methods with little to no documentation. Besides a few exceptions due to the current state of the documentation, this is done on purpose to indicate that these methods shouldn't be used directly. The API classes already use these lower level methods for you behind the scenes and you don't have to deal with them directly. Using them might break the proper SFS2X functioning.
When using the JavaScript server side API instead, the same entry points mentioned before can be accessed through a few methods available in the global scope (getApi, getGameApi, etc).
» Programming to interfaces
In general, throughout the client and server API (excluding JavaScript API of course), you will notice that all important classes of the framework are backed by an interface.
For instance:
- SFSZone implements Zone
- SFSRoom implements Room
- SFSUser implements User
- SFSBuddy implements Buddy
- SFSObject implements ISFSObject
- SFSArray implements ISFSArray
- SFSRoomVariable implements RoomVariable
- SFSUserVariable implements UserVariable
You will also notice that the whole framework uses these interfaces in almost each and every method signature or return type.
We would like to encourage and emphasize the use of these interfaces in your code too. The reason is that this helps swapping different implementations easily and without side effects. In future release we might introduce new implementations to these interfaces which will affect your code minimally if you stick to this habit as much as possible.