# SpiderMonkey: Multi-Player Networking

This document introduces you to the SpiderMonkey networking API. You use this API when you develop games where several players compete with one another in real time. A multi-player game is made up of several clients connecting to a server:

- The central server (one headless SimpleApplication) coordinates the game in the background.
- Each player runs a game client (a standard SimpleApplication) and connects to the central server.

Each Client keeps the Server informed about its player's moves and actions. The Server centrally maintains the game state and broadcasts the state info back to all connected clients. This network synchronization allows all clients to share the same game world. Each client then displays the game state to one player from this player's perspective.

## SpiderMonkey API Overview

The SpiderMonkey API is a set of interfaces and helper classes in the 'com.jme3.network' package. For most users, this package and the 'message' package is all they need to worry about. (The 'base' and 'kernel' packages only come into play when implementing custom network transports or alternate client/server protocols, which is now possible).

The SpiderMonkey API assists you in creating a Server, Clients, and Messages. Once a Server instance is created and started, the Server accepts remote connections from Clients, and you can send and receive Messages. Client objects represent the client-side of the client-server connection. Within the Server, these Client objects are referred to as HostedConnections. HostedConnections can hold application-defined client-specific session attributes that the server-side listeners and services can use to track player information, etc.

Seen from the Client |  | Seen from the Server
--- | --- | ---
com.jme3.network.Client | == | com.jme3.network.HostedConnection

You can register several types of listeners to be notified of changes.

- MessageListeners on both the Client and the Server are notified when new messages arrive. You can use MessageListeners to be notified about only specific types of messages.
- ClientStateListeners inform the Client of changes in its connection state, e.g. when the client gets kicked from the server.
- ConnectionListeners inform the Server about HostedConnection arrivals and removals, e.g. if a client joins or quits.

## Client and Server

### Creating a Server

The game server is a "headless" com.jme3.app.SimpleApplication:

    public class ServerMain extends SimpleApplication {
      public static void main(String[] args) {
        ServerMain app = new ServerMain();
        app.start(JmeContext.Type.Headless); // headless type for servers!
      }
    }

A `Headless` SimpleApplication executes the simpleInitApp() method and runs the update loop normally. But the application does not open a window, and it does not listen to user input. This is the typical behavior for a server application.

Create a com.jme3.network.Server in the `simpleInitApp()` method and specify a communication port, for example 6143.

      public void simpleInitApp() {
        ...
        Server myServer = Network.createServer(6143);
        myServer.start();
        ...
      }

When you run this app on a host, the server is ready to accept clients. Let's create a client next.

### Creating a Client

A game client is a standard com.jme3.app.SimpleApplication.

    public class ClientMain extends SimpleApplication {
      public static void main(String[] args) {
        ClientMain app = new ClientMain();
        app.start(JmeContext.Type.Display); // standard display type
      }
    }

A standard SimpleApplication in `Display` mode executes the simpleInitApp() method, runs the update loop, opens a window for the rendered video output, and listens to user input. This is the typical behavior for a client application.

Create a com.jme3.network.Client in the `simpleInitApp()` method and specify the servers IP address, and the same communication port as for the server, here 6143.

    public void simpleInitApp() {
       ...
       Client myClient = Network.connectToServer("localhost", 6143);
       myClient.start();
       ...

The server address can be in the format "localhost" or "127.0.0.1" (for local testing), or an IP address of a remote host in the format ???123.456.78.9???. In this example, we assume the server is running on the localhost.

When you run this client, it connects to the server.

### Getting Info About a Client

The server refers to a connected client as com.jme3.network.HostedConnection objects. The server can get info about clients as follows:

Accessor | Purpose
--- | ---
myServer.getConnections() | Server gets a collection of all connected HostedConnection objects (all connected clients).
myServer.getConnections().size() | Server gets the number of all connected HostedConnection objects (number of clients).
myServer.getConnection(0) | Server gets the first (0), second (1), etc, connected HostedConnection object (one client).

Your game can define its own game data based on whatever criteria you want, typically these include player ID and state. If the server needs to look up player/client-specific information, you can store this information directly on the HostedConnection object. The following examples read and write a custom Java object `MyState` in the HostedConnection object `conn`:

Accessor | Purpose
--- | ---
conn.setAttribute("MyState", new MyState()); | Server can change an attribute of the HostedConnection.
MyState state = conn.getAttribute("MyState") | Server can read an attribute of the HostedConnection.

## Messaging

### Creating Message Types

Each message represents data that you want to transmit between client and server. Common message examples include transformation updates or game actions. For each message type, create a message class that extends com.jme3.network.AbstractMessage. Use the @Serializable annotation from com.jme3.network.serializing.Serializable and create an empty default constructor. Custom constructors, fields, and methods are up to you and depend on the message data that you want to transmit.

    @Serializable
    public class HelloMessage extends AbstractMessage {
      private String hello;       // custom message data
      public HelloMessage() {}    // empty constructor
      public HelloMessage(String s) { hello = s; } // custom constructor
    }

You must register each message type to the com.jme3.network.serializing.Serializer, in both server and client!

    Serializer.registerClass(HelloMessage.class);

### Responding to Messages

After a Message was received, a Listener responds to it. The listener can access fields of the message, and send messages back, start new threads, etc. There are two listeners, one on the server, one on the client. For each message type, you implement the responses in either Listeners??? `messageReceived()` method.

#### ClientListener.java

Create one ClientListener.java and make it extend `com.jme3.network.MessageListener`.

    public class ClientListener implements MessageListener<Client> {
      public void messageReceived(Client source, Message message) {
        if (message instanceof HelloMessage) {
          // do something with the message
          HelloMessage helloMessage = (HelloMessage) message;
          System.out.println("Client #"+source.getId()+" received: '"+helloMessage.getSomething()+"'");
        } // else...
      }

For each message type, register a client listener to the client.

    myClient.addMessageListener(new ClientListener(), HelloMessage.class);

#### ServerListener.java

Create one ServerListener.java and make it extend `com.jme3.network.MessageListener`.

    public class ServerListener implements MessageListener<HostedConnection> {
      public void messageReceived(HostedConnection source, Message message) {
        if (message instanceof HelloMessage) {
          // do something with the message
          HelloMessage helloMessage = (HelloMessage) message;
          System.out.println("Server received '" +helloMessage.getSomething() +"' from client #"+source.getId() );
        } // else....
      }

For each message type, register a server listener to the server:

    myServer.addMessageListener(new ServerListener(), HelloMessage.class);

### Creating and Sending Messages

Let's create a new message of type HelloMessage:

    Message message = new HelloMessage("Hello World!");

Now the client can send this message to the server:

    myClient.send(message);

Or the server can broadcast this message to all HostedConnection (clients):

    Message message = new HelloMessage("Welcome!");
    myServer.broadcast(message);

Or the server can send the message to a specific subset of clients (e.g. to HostedConnection conn1, conn2, and conn3):

    myServer.broadcast( Filters.in( conn1, conn2, conn3 ), message );

Or the server can send the message to all but a few selected clients (e.g. to all HostedConnections but conn4):

    myServer.broadcast( Filters.notEqualTo( conn4 ), message );

The last two broadcasting methods use com.jme3.network.Filters to select a subset of recipients. If you know the exact list of recipients, always send the messages directly to them using the Filters; avoid flooding the network with unnecessary broadcasts to all.

## Identification and Rejection

The ID of the Client and HostedConnection are the same at both ends of a connection. The ID is given out authoritatively by the Server.

    ... myClient.getId() ...

A server has a game version and game name property. Each client expects to communicate with a server with a certain game name and version. Test first whether the game name matches, and then whether game version matches, before sending any messages! If they do not match, you should refuse to connect, because unmatched clients and servers will likely miscommunicate.

Typically, your networked game defines its own attributes (such as player ID) based on whatever criteria you want. If you want to look up player/client-specific information beyond the game version, you can set this information directly on the Client/HostedConnection object (see Getting Info About a Client).

## Closing Clients and Server Cleanly

### Closing a Client

You must override the client's destroy() method to close the connection cleanly when the player quits the client:

      @Override
      public void destroy() {
          ... // custom code
          myClient.close();
          super.destroy();
      }

### Closing a Server

You must override the server's destroy() method to close the connection when the server quits:

      @Override
      public void destroy() {
          ... // custom code
          myServer.close();
          super.destroy();
      }

### Kicking a Client

The server can kick a HostedConnection to make it disconnect. You should provide a String with further info (an explanation to the user what happened, e.g. "Shutting down for maintenance") for the server to send along. This info message can be used (displayed to the user) by a ClientStateListener. (See below)

    conn.close("We kick cheaters.");

## Listening to Connection Notification

The server and clients are notified about connection changes.

### ClientStateListener

The com.jme3.network.ClientStateListener notifies the Client when the Client has fully connected to the server (including any internal handshaking), and when the Client is kicked (disconnected) from the server.

ClientStateListener interface method | Purpose
--- | ---
public void clientConnected(Client c){} | Implement here what happens as soon as this client has fully connected to the server.
public void clientDisconnected(Client c, DisconnectInfo info){} | Implement here what happens after the server kicks this client. For example, display the DisconnectInfo to the user.

First implement the ClientStateListener interface in the Client class. Then register it to myClient in MyGameClient's simpleInitApp() method:

    myClient.addClientStateListener(this);

### ConnectionListener

The com.jme3.network.ConnectionListener notifies the Server whenever new HostedConnections (clients) come and go. The listener notifies the server after the Client connection is fully established (including any internal handshaking).

ConnectionListener interface method | Purpose
--- | ---
public void connectionAdded(Server s, HostedConnection c){} | Implemenent here what happens after a new HostedConnection has joined the Server.
public void connectionRemoved(Server s, HostedConnection c){} | Implement here what happens after a HostedConnection has left. E.g. a player has quit the game and the server removes his character.

First implement the ConnectionListener interface in the Server class. Then register it to myServer in MyGameServer's simpleInitApp() method.

    myServer.addConnectionListener(this);

## UDP versus TCP

SpiderMonkey supports both UDP (unreliable, fast) and TCP (reliable, slow) transport of messages.

    message1.setReliable(true); // TCP
    message2.setReliable(false); // UDP

- Choose reliable and slow transport for messages, if you want to make certain the message is delivered (resent) when lost, and if the order of a series of messages is relevant. E.g. game actions such as "1. wield weapon, 2. attack, 3. dodge".
- Choose unreliable and fast transport for messages if the next message makes any previously delayed or lost message obsolete and synchronizes the state again. E.g. a series of new locations while walking.

## Important: Use Multi-Threading

You cannot modify the scenegraph directly from the network thread. A common example for such a modification is when you synchronize the player's position in the scene. You have to use Java Multithreading.

Multithreading means that you create a Callable. A Callable is a Java class representing any (possibly time-intensive) self-contained task that has an impact on the scene graph (such as positioning the player). You enqueue the Callable in the Executor of the client's OpenGL thread. The Callable ensures to executes the modification in sync with the update loop.

    app.enqueue(callable);

Learn more about using multithreading in jME3 here.

For general advice, see the articles
and
by the Valve Developer Community.

## Troubleshooting

If you have set up a server in your home network, and the game clients cannot reach the server from the outside, it's time to learn about
.

documentation, network, spidermonkey

view online version