SFS2X Docs / ExamplesUnity / connector

» Connector

» Overview

The Connector example simply shows how to load and use the SmartFox client API object and how to establish a basic connection to the server.

This example is almost the most simple application you can create. It is a single Unity scene with a single script component which sole purpose is to connect to and disconnect from the SmartFoxServer 2X instance, as well as displaying the log messages from the API.

The application is set up to connect to a SmartFoxServer 2X listening to port 9933 on the localhost address 127.0.0.1. These values are configured in the Connection GUI script component on the Connection GUI game object in the connection scene. They can be changed via the inspector as shown below.

Additionally, the minimum log level is configurable in the component via a dropdown.

>> DOWNLOAD the source files <<

» Installation

» Running the example

In order to run the application follow these steps:

  1. make sure your SmartFoxServer 2X installation contains the BasicExamples Zone definition;
  2. start SmartFoxServer 2X;
  3. make sure the client runs on the same machine as the server (the IP address can otherwise be configured as explained above via the source files);
  4. open the /deploy/Connector.html file in a browser.

» Source code setup

The complete project is contained in a Unity package. To access and build it please follow these steps:

  1. create a empty new Unity project;
  2. in the Unity project tab, right click and select Import Package -> Custom Package...;
  3. browse to the package for this example in the /source folder;
  4. open the _Scenes/Connector scene.

All relevant C# code is in the Scripts folder and the SmartFoxServer 2X client API DLL is contained in the Plugins folder.

» Code highlights

Code for this example is contained in the single script file called ConnectionGUI in the Scripts folder. The structure of the file is a basic Unity C# script with a Start(), FixedUpdate() and OnGUI() method. Additionally there are various methods registered as callbacks from the SmartFoxServer client API.

The initial part of the Start() method is required for Unity web player clients to negotiate a security policy with the server. A default SmartFoxServer 2X server can act as policy server out of the box. It is important that the security policy is negotiated prior to any network activity in the application. For standalone and mobile applications this is not required.

void Start() {
    // In a webplayer we need to setup security policy negotiation with the server first
    if (Application.isWebPlayer) {
        Security.PrefetchSocketPolicy(server, port, 500);
    }

The next part registers event listeners and the event handler methods in the client code for a given event. Additionally we register a log message listener/handler.

If you are a bit familiar with Unity then the expression "event handler" should not sound new to you. In fact many of the built-in callback methods in Unity use events to handle situations that will occur at an undefined moment in the future. For example when two objects collide in your game you have to implement the OnCollisionEnter event handler to have your code react to that particular collision event.

SmartFoxServer use events quite a lot because you can receive messages at any time from the server or from other users. All you will have to do is write the appropriate functions to manage these different situations.

    // Register for basic callbacks
    smartFox = new SmartFox(true);
    smartFox.AddEventListener(SFSEvent.CONNECTION, OnConnection);
    smartFox.AddEventListener(SFSEvent.CONNECTION_LOST, OnConnectionLost);
    
    // Also register for all debug messages from the API at the given log level
    smartFox.AddLogListener(logLevel, OnDebugMessage);

For this simple example we register event handlers when the API connects and for some reason looses the connection. Basically when the API gets connected to the server it will now execute the OnConnection method in the Unity script component.

SmartFoxServer 2X can fire many different events based in the type of request it receives, some of them are:

We'll analyze many of them as we progress with more complex tutorials.

Unity is not thread safe. This means that the programmer has to be careful not to e.g. manipulate arrays of strings while the Unity engine is accessing the same array for drawing the strings on the screen. This also is true for network events and the SmartFoxServer client API handles this by queing events for later processing. The following code is wrapped in the Unity FixedUpdate callback where Unity is in a safe state to manipulate client data. Queued network events in the API are processed and all the relevant event handlers are called.

void FixedUpdate() {
    smartFox.ProcessEvents();
}

All event callback methods have the same method signature with a single BaseEvent class as variable. It contains a Hashtable of event specific paramaters that one can access. In the SFSEvent.CONNECTION OnConnection callback one of the parameters is a "success" bool.

Which parameters are given in what events is documented in the SFSEvent documentation. 

public void OnConnection(BaseEvent evt) {
    bool success = (bool)evt.Params["success"];
    if (success) {
        statusMessage = "Connection successful!";
    } else {
        statusMessage = "Can't connect to server!";
    }
}

Connecting to the server is handled as part of the Unity GUI code as shown below.

void OnGUI() {
    
    ...
    if (!smartFox.IsConnected) {
        // Connect button
        if (GUILayout.Button("CONNECT")) {
            smartFox.Connect(server, port);
        }
    }

To see more advanced uses of SmartFoxServer you can move onwards to the next examples.

NOTE
You should read the comments to methods and properties in the example source code for additional informations and possible code optimizations.

» More resources

You can learn more about the SmartFoxServer basics by consulting the following resources: