JavaScript Client API

The JavaScript API allows creating application and games for all modern browsers supporting HTML5.

The API can be installed manually or using NPM, the well-known package manager and installer.

API documentation

Prerequisites

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.

Manual installation

The API distribution for manual installation is a zip file available on the SmartFoxServer website. It contains the API's bundled JavaScript module, a source map file and a TypeScript declaration file. The map file can be helpful to locate and debug issues in case of errors originating in the API, while the declaration file is useful when using TypeScript language to code your application.

For sake of semplicity, let's assume that your project has a basic structure like the following:

index.html
main.js
libs/

where main.js is the application's entry point. Note that this is required to be a standard ECMAScript module in order to be able to import the SmartFoxserver API, therefore the type attribute on its <script> tag in the html file must be set to module.

Download and unzip the API package in the project's /libs folder, then add an import map to the html file. The following should be the essential structure of your index.html:

HTML

<!doctype html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <script type="importmap">
        {
            "imports": {
                "sfs3-api": "./libs/sfs3-api.js"
            }
        }
        </script>
    </head>
    <body>
        <script type="module" src="./main.js"></script>
    </body>
</html>

Import map

Using the import map is not mandatory, but it can be useful if you need to import the API classes in multiple files in your project. More information is available here.

You can now import the API in your main.js file using the standard JavaScript module syntax. You can either import the whole namespace assigning it a name (for example Sfs3), or import specific classes only. In the former case, you will access all API classes through the assigned namespace; in the latter, you can instantiate the classes directly (see example below).

JavaScript

import * as Sfs3 from "sfs3-api";

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

In case you don't use the import map, just enter the API's JavaScript relative file path in the import statement directly:

JavaScript

import * as Sfs3 from "./libs/sfs3-api.js";

NPM package setup

If your project makes use of the NPM package manager, you can get the API from its registry entry. Open your project's root folder in a terminal/console window and execute this command:

npm install sfs3-api --save

This automatically adds the sfs3-api entry in the dependancies section of your project's package.json file. You can now import the API in your application code using the standard JavaScript module syntax. You can either import the whole namespace assigning it a name (for example Sfs3), or import specific classes only. In the former case, you will access all API classes through the assigned namespace; in the latter, you can instantiate the classes directly (see example below).

JavaScript

import * as Sfs3 from "sfs3-api";

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

Basic example

The following code creates a client that connects to SmartFoxServer running on the local machine:

JavaScript

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

let sfs;

window.onload = () => {

    // Create SmartFox instance
    sfs = new SmartFox();

    // Configure client
    sfs.config.host = 'localhost';
    sfs.config.zone = 'Playground';

    // Set up event handlers
    sfs.addEventListener(SFSEvent.CONNECTION, onConnection, this);
    sfs.addEventListener(SFSEvent.CONNECTION_LOST, onConnectionLost, this);
    sfs.addEventListener(SFSEvent.LOGIN, onLogin, this);
    sfs.addEventListener(SFSEvent.LOGIN_ERROR, onLoginError, this);

    console.log(`SFS API version: ${sfs.version}`);

    // Connect to server
    sfs.connect();
}

// ----------------------------------------------------------------------
// Event Handlers
// ----------------------------------------------------------------------

function onConnection(evtParams)
{
    const success = evtParams[EventParam.Success];

    if (success)
    {
        console.log('Connection successful');

        // Login as guest
        sfs.send(new LoginRequest()); 
    }
    else
        console.log('Connection failed; is the server running?');
}

function onConnectionLost(evtParams)
{
    const reason = evtParams[EventParam.DisconnectionReason];

    console.log(`Connection lost; reason is ${reason}`);
}

function onLogin(evtParams)
{
    const user = evtParams[EventParam.User];

    console.log(`Logged in as ${user.name}`);
}

function onLoginError(evtParams)
{
    const errorMsg = evtParams[EventParam.ErrorMessage];

    console.log(`Login error: ${errorMsg}`);
}