SFS2X Docs / DevelopmentBasics / connection-phase

» The connection phase

A connection to SFS2X is performed in two steps.

  1. A physical TCP connection is opened to the server
  2. An "handshake" is performed between client and server exchanging a certain number of parameters

During the handshake the server verifies that the client API version is supported and sends back a number of settings that the client stores locally.

The following snippet of ActionScript 3 code is derived from the Connector example available in the examples package (similar examples are provided for the other languages).

public class Connector extends Sprite
{	
    private var sfs:SmartFox
    
    public function Connector()
    {
        // Create an instance of the SmartFox class
        sfs = new SmartFox()
    
        // Turn on the debug feature
        sfs.debug = true
        
        // Add SFS2X event listeners
        sfs.addEventListener(SFSEvent.CONNECTION, onConnection)
        sfs.addEventListener(SFSEvent.CONNECTION_LOST, onConnectionLost)
        sfs.addEventListener(SFSEvent.CONFIG_LOAD_SUCCESS, onConfigLoadSuccess)
        sfs.addEventListener(SFSEvent.CONFIG_LOAD_FAILURE, onConfigLoadFailure)
        
        // Connect button listener
        bt_connect.addEventListener(MouseEvent.CLICK, onBtConnectClick)

        dTrace("SmartFox API: " + sfs.version)
        dTrace("Click the CONNECT button to start...")
    }	
    
    private function onBtConnectClick(evt:Event):void
    {
        // Load the default configuration file, config.xml
        sfs.loadConfig()
    }

    //:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
    // SFS2X event handlers
    //:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
    
    private function onConnection(evt:SFSEvent):void
    {
        if (evt.params.success)
        {
            dTrace("Connection Success!")
        }
        else
        {
            dTrace("Connection Failure: " + evt.params.errorMessage)
        }
    }
    
    private function onConnectionLost(evt:SFSEvent):void
    {
        dTrace("Connection was lost. Reason: " + evt.params.reason)
    }
    
    private function onConfigLoadSuccess(evt:SFSEvent):void
    {
        dTrace("Config load success!")
        dTrace("Server settings: " + sfs.config.host + ":" + sfs.config.port)
    }
    
    private function onConfigLoadFailure(evt:SFSEvent):void
    {
        dTrace("Config load failure!!!")
    }

    //:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
    // Utility methods
    //:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

    private function dTrace(msg:String):void
    {
        ta_debug.text += "-- " + msg + "\n";
    }   
}

The code starts by creating the SmartFox object, which is the main API class. We then proceed by registering the server events that we want to listen for using the SFSEvent class.

The next step is loading an external .xml configuration file that contains the details of our connection. This is a convenient way of keeping the connection parameters separate from the code so that they can be changed at any time without having to recompile the code. If you are familiar with SmartFoxServer 1.x you will find this system very similar to its predecessor.

NOTE: You don't have to specify any configuration file name if you adopt the standard convention of using a file called sfs-config.xml.

Please check this tutorial for more informations.

» What to do after the connection is established?

Starting a connection with the server ensures that the client is able to "speak" the SFS2X protocol, but at this point the client is not recognized in the system as a real user. There is still one mandatory step to take before the client can start to freely interact with the server and the other users: the login.

The login phase promotes the connected client to a true user and joins him in one of the available Zones. But before we move on with this second phase there are still a few things about the connection that we need to examine.

» What could go wrong?

In a local environment it is very unlikely that any problem will arise and you should be able to connect in a snap, however in a production server with "real clients" connecting over the internet, a few issues could show up.

Typically you might find users complaining about a connection failure for one of the following reasons.

You can find other information on how to troubleshoot client connection failures in this guide.

» The BlueBox

The BlueBox technology is included in SFS2X, as a difference from its predecessor where it was an optional add-on. The BlueBox offers an high performance HTTP tunnelling engine that allows users behind proxies and other restricted network conditions to enjoy multiplayer applications and games at full speed.

You can read all the informations about the BlueBox in this dedicated document.

» The Highly Resilient Connection (HRC) system

An important feature introduced in SFS2X is a low-level mechanism that allows to resume an abrupt disconnection in a completely transparent way for the developer. When the HRC is turned on in your Zone, the client API will detect unexpected disconnections and attempt to reconnect to the server within a certain amount of time that is configured at the Zone level.

The whole process happens behind the scenes and the developer is notified with different events.

On the server side an extension developer can handle this situation in the same way, by listening to the SFSEventType.USER_RECONNECTION_TRY and SFSEventType.USER_RECONNECTION_SUCCESS events.

In order to turn on this feature you will need to configure the User reconnection timeframe parameter in the General tab of the Zone Configurator module from the AdminTool (highlighted in the following image).

hrc

The value is expressed in number of seconds and any values greater than zero will activate the system. Common settings range between 30 to 60 seconds depending on your application requirements and how susceptible is your server logic to waiting for a missing player.

In order to test the Reconnection function you can simulate a sudden disconnection by invoking the client side API method killConnection() exposed by the main SmartFox class.

NOTE: Do not attempt to test the reconnection system by pulling the ethernet cable or shutting down the WIFI connection. Both operations will not terminate your current socket connections and therefore the disconnection event will never be triggered.

For a more detailed overview of the HRC+ system read here.