SFS3 JavaScript Client API

Welcome to the SmartFoxServer 3 JavaScript Client API documentation.

Here you will find a complete reference to the JavaScript Client API, with clear explanations of classes, methods, events and data structures to easily integrate SmartFoxServer in your HTML5 multiplayer games and applications.

Install the API

Setup the latest version of the JavaScript API as described in the installation instructions provided on the SmartFoxServer documentation website. The page also contains the same information to get started you will find in the next section.

Getting started

First of all, make sure that WebSocket protocol is active in SmartFoxServer configuration. If not, enable it using the AdminTool's Server Configurator module (Web Server tab > Enable WS/WSS setting) and restart the SmartFoxServer instance.

With manual installation

This API uses the standard JavaScript module syntax. If you added the API's JavaScript bundle to your project manually by copying the sfs3-api.js file to the libs folder (for example) and assuming that the main JavaScript file of your application is called main.js and it is located in the root folder, you can follow this steps to get started:

• Add an import map to your project's main HTML page by means of the <script> tag with its type attribute set to importmap:

<script type="importmap">
{
	"imports": {
		"sfs3-api": "./libs/sfs3-api.js"
	}
}
</script>

• Add the reference to the main.js file to the HTML page by means of the <script> tag, setting its type to module:

<script type="module" src="./main.js"></script>;

• Inside main.js, import the API object:

import * as Sfs3 from "sfs3-api";

Note that using the import map is not mandatory, but it can be useful if you need to import the API classes in multiple files. If you don't use it, just enter the API's JavaScript relative file path in the import statement directly.

With npm package

If you installed the API as an npm package, you can use a module bundler (we recommend Webpack) and the standard module loading syntax:

import * as Sfs3 from "sfs3-api";

Classes instantiation

Whatever import method you use, you can then access all instantiable classes from your project's code by means of the Sfs3 namespace (or any other name you entered in the import statement). The following example shows how to create an instance of the main SmartFox class, add a few listeners and establish a connection with SmartFoxServer.

let sfs = new Sfs3.SmartFox();
sfs.addEventListener(Sfs3.SFSEvent.CONNECTION, onConnection, this);
sfs.addEventListener(Sfs3.SFSEvent.CONNECTION_LOST, onConnectionLost, this);

const config = new Sfs3.ConfigData();
config.host = "127.0.0.1";
config.port = 8088;

sfs.connect(config);

function onConnection(evtParams)
{
 	if (evtParams[Sfs3.EventParam.Success])
 		console.log("Connected to SmartFoxServer!");
 	else
 		console.log("Connection failed. Is the server running at all?");
}

function onConnectionLost(evtParams)
{
 	console.log("Connection lost. Reason is: " + evtParams[Sfs3.EventParam.DisconnectionReason]);
}

You can also import specific classes instead of the whole namespace, like this:

import { SmartFox, SFSEvent, ConfigData, EventParam } from "sfs3-api";

In this case, just skip the namespace reference when instantiating or accessing those classes:

let sfs = new SmartFox();

Explore the documentation

You can start exploring the API from the SmartFox class. The other relevant classes you will often use are those with names ending with ...Request, for example the LoginRequest class.

Some of the classes listed in this reference are never instantiated by developers directly (you won't find a constructor documented); their instances are returned by methods or as event parameters as needed (for example instances of SFSUser or SFSRoom). You can use this API reference to learn what properties and methods are available on those instances.