The connection phase

Connecting to SmartFoxServer requires two main parameters: the host and a port number

• the host is any valid URL pointing to the machine running SmartFoxServer. If we're working on a dev machine we can use "localhost", otherwise we'll use the IP address or domain name of the machine running SmartFoxServer

• the port number is the TCP port value, which by default is 9977 for TCP and 8088 for WebSocket

Using TCP or WebSocket

We've briefly mentioned in the Overview that a connection can be done using either TCP or WebSocket, so what is the difference and what should we choose?

Essentially we recommend to always use TCP if it's available and use WebSocket as the second best choice. This is mainly dictated by which game engine you're working with and what's your target device. For reference see the table below:

Platform	Client API	Deployment	Connection type
Unity	DotNet	Desktop/Mobile	TCP
Unity	DotNet	WebGL	WebSocket
Godot	DotNet	Desktop	TCP
HTML5	JavaScript	Browser	WebSocket
Java/Android	Java	Desktop/Mobile	TCP
macOS/iOS	Swift	macOS/iOS/tvOS	TCP

Making a connection

Below is an example using C# and our DotNet API. Other languages might slightly differ syntactically, but they all work in the same way:

C#

var sfs = new SmartFox();
sfs.AddEventListener(SFSEvent.CONNECTION, OnConnection);

var cfgData = new ConfigData();
cfgData.Host = "myserver.com"
sfs.Connect(cfgData);

private void OnConnection(ApiEvent evt)
{
    bool success = (bool) evt.GetParam(EventParam.Success)!;

    if (success)
        Log("Connection successful -- Mode is " + sfs.ConnectionMode);

    else
        Log("Connection failed: " + evt.GetParam(EventParam.ErrorMessage));        
}

What could go wrong?

Normally you shouldn't have any issues connecting to the server, especially when working on a local machine. However connection issues can arise when connecting to a production server from different devices, countries etc...

• Firewall issues: if the client is behind a firewall that doesn't allow connections to the default server port (TCP 9977, WS 8088). In this case adding a rule that allows traffic on that port will solve the problem. On the other hand if the client is behind a corporate firewall the SmartFox API can detect the issue and use a BlueBox connection instead (more on this later).
• Proxy issues: a Proxy server might stand between the client and SmartFoxServer making it impossible to establish a direct TCP connection. This is another situation that can happen in corporate or school networks and the BlueBox can come to the rescue as well.

HTTP Tunneling, a.k.a the BlueBox

SmartFoxServer offers a backup mechanism for TCP connection failures called the BlueBox, which allows to open an HTTP/S tunnel towards the server and bypassing the firewall or proxy that is blocking the attempt.

As shown here when the connection is blocked by a firewall (or proxy) the SmartFoxServer Client API can automatically switch to an HTTP based connection which is more likely to succeed, since most firewalls don't block regular HTTP traffic. The tunnel will transport our requests and responses transparently although at the cost of some extra latency due to the slower nature of HTTP.

Please Note:

The Bluebox is only available as a backup system for TCP connections. It's not available for WebSocket connections: this is because WS is already part of the HTTP protocol and as such it is less likely to be blocked.

If you want to learn more about the BlueBox we have a dedicated article in this same documentation section.

The HRC (Highly Resilient Connection)

Another important aspect of connectivity is dealing with unexpected disconnection caused by network issues, typically on the client side. For this purpose we have introduced the HRC system that allows to resume an abrupt disconnection in a completely transparent way for players.

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 (configurable at the Zone level).

The whole process happens behind the scenes and the developer is notified with a couple of events:

• CONNECTION_RETRY: this is dispatched when the API has detected an abrupt loss of connection and the reconnection to the server is carried on.

• CONNECTION_RESUME: this event is notified when the reconnection is successful. In case the reconnection fails a SFSEvent.CONNECTION_LOST event will be sent instead.

When the player is reconnected all the messages that could not be delivered are re-transmitted so the application logic doesn't miss any update and the game can continue.

If you're interested in learning more check this in-depth article about the HRC system