SFS2X and Websocket for HTML5 and Unity.

Websocket has become very popular thanks to the ubiquity of HTML5 technologies on desktop, mobile and even consoles. Additionally game engines such as Unity, with its WebGL build, has pushed the boundaries of what can be achieved in web-based games allowing many developers to release their titles for the browser.

In this new article we’re going to review a series of steps to set up Websocket in SmartFoxServer 2X and avoid potential pitfalls, especially when testing locally.

» The basics

SmartFoxServer 2X provides a custom socket protocol (TCP and UDP) that works with any native application (e.g. iOS, Android, Windows, PS4 etc…), via the relative client API, with the exception of browser-based games.

This is because browsers don’t allow custom TCP/UDP socket communication for security and compatibility reasons. Instead, the new Websocket protocol has been introduced in browsers as part of the HTML5 standard. It can coexist with the HTTP protocol on the same ports so that traffic is not blocked by firewalls, proxies and the like.

Websocket is supported by SmartFoxServer 2X via the Javascript API for HTML5 clients or the Unity/WebGL API, for WebGL builds.

NOTE: In this article we will often refer to Unity WebGL as this is the build name used in Unity for browser-based exports. Unity WebGL uses Websocket as the network technology for multiplayer communication.

Activating Websocket in SmartFoxServer 2X is requires only a few steps:

  • Access the SFS2X AdminTool
  • Open the Server Configurator
  • Activate the Enable WS/WSS option
  • Submit and restart SFS2X

» Testing locally

Now that Websocket is active we can try to connect with a client to the local server and start experimenting. To get going quickly you can download some of our examples, for instance the HTML5 Example pack contains a wide series of tutorials with different levels of complexity (with relative online tutorials).

Every example is already configured to connect to the localhost on TCP port 8080, so no set up is required. You can double-click or drag and drop the html file in your browser and you’re good to go.

However for Unity-based examples you will need one extra step. After building for WebGL, if you drag and drop one of the examples in your favorite browser a warning like this will show up:

What this means is that Unity WebGL examples need to be served from a web-server (for security reasons), so in order to fulfill this requirement you will need to move the exported folder under SFS2X/www/ROOT/ExampleName

Once this is done you can safely point the browser to http://localhost:8080/ExampleName where ExampleName is replaced by the actual name of the exported WebGL example.

» Secure Websocket (WSS)

The Websocket protocol comes with a more secure, encrypted variant which is the equivalent of HTTPS, called in short WSS. This is activated by deploying a valid SSL certificate in SmartFoxServer 2X, which enables both HTTPS and WSS over the chosen TCP port (more on this in the next sections).

Testing WSS locally

Local testing with WSS (and HTTPS) is very tricky and usually unrecommended , although there may be some workarounds. The main reason for this is that SSL certificates can only be issued for internet domains, and “localhost” is not one of those. Our suggestion in this case is to test locally by setting the client to standard Websocket and switching it to WSS when in production.

This is an example of how to switch the client between the two modes (WS and WSS) in Javascript:

(function () {
    // Use a flag to easily switch cryptography on and off
    var useEncryption = true;
    // Create configuration object
    var config = {};
    config.host = "mydomain.com";
    config.port = useEncryption ? 8443 : 8080;
    config.useSSL = useEncryption;
    config.zone = "BasicExamples";
    // Create the SmartFox client instance
    var sfs = new SFS2X.SmartFox(config);
    // Add connection event listener
    sfs.addEventListener(SFS2X.SFSEvent.CONNECTION, onConnection, this);
    // Connect to SmartFoxServer 2X
    // Handle connection event
    function onConnection(evtParams)

And this is the same example for Unity/WebGL:

public class ConnectionExample : MonoBehaviour
    private SmartFox sfs;
    // Use a flag to easily switch cryptography on and off
    private bool useEncryption = true;
    void Start()
        // Create the SmartFox client instance
        sfs = new SmartFox(useEncryption ? UseWebSocket.WSS : UseWebSocket.WS);
        // Add connection event listener
        sfs.AddEventListener(SFSEvent.CONNECTION, OnConnection);
        // Create configuration object
        ConfigData config = new ConfigData();
        config.host = "mydomain.com";
        config.port = useEncryption ? 8443 : 8080;
        config.zone = "BasicExamples";
        // Connect
    // Handle connection event
    private void OnConnection(BaseEvent evt)

Testing remotely

Before you can use WSS you will need to deploy a valid SSL certificate in SmartFoxServer 2X. This operations requires a number of steps:

  • Acquiring an internet domain (if you don’t already have one)
  • Acquiring an SSL certificate for such domain
  • Deploying the certificate on the SFS2X instance running on your domain

We describe this process step by step in a detailed guide in our documentation.

Once you have completed the setup you will be able to connect your client to the game server via a secure Websocket connection.

» Unity WebGL notes

Finally a couple of notes for Unity developers getting started with WebGL and SFS2X. When starting a new Unity project for the browser you will need to add multiple DLLs from our Unity API distribution to support running the code in the Unity Editor and building for WebGL.

Before getting started make sure to follow our documentation to set up your environment correctly.

» Further discussions

If you have any more questions or doubts make sure to join the conversation in our support forums and let us know your feedback.