Getting started

Introduction

The structure followed by this library is quite classic, following this diagram:

Basically, a network can have multiple sessions. Each session will consist of one (intermediate) server and multiple clients. Just create some sessions, and some events, and you are ready to go!

Examples

There are some example projects on the examples folder. FEAR NOT! The basic-example has only one haxe file with a few lines of simple code.

If you don't want to download and execute code, then read the following section.

Examples list:

• basic-example
• tic-tac-toe

Basic usage

First of all, a server is an application which allows multiple clients to connect to it.

This library is based on sessions, so you can handle multiple connections to multiple servers.

Logging

To show the network logs on the console (stdout) to debug your networking code, define the network_logging define; just add this to your project.xml:

<haxedef name="network_logging" />

To include backtraces, use network_logging_with_backtrace instead:

<haxedef name="network_logging_with_backtrace" />

Registering sessions

To register a session as a server listening to the port 8888 to all interfaces, use:

import networking.Network;
import networking.utils.NetworkMode;

// ...

var server = Network.registerSession(NetworkMode.SERVER, {
  ip: '0.0.0.0',
  port: 8888,
  max_connections: 4
});
server.start();

To create a client that connects to that server:

import networking.Network;
import networking.utils.NetworkMode;

// ...

var server_ip = '127.0.0.1';
// You can also use host names:
// var server_ip = 'www.example.com';

var client = Network.registerSession(NetworkMode.CLIENT, {
  ip: server_ip,
  port: 8888
});
client.start();

You can check for the connection statuses.

Messages

Messages are serialized and send as dynamic objects. For example, to send a message from the client to the server:

client.send({ message: 'Hello world!', verb: 'test' });

To notify all clients of the server:

server.send({ message: 'Global message!', verb: 'test' });

To notify only the first client:

server.clients[0].send({ message: 'Pst! This is a secret', verb: 'test' })

Now, after that, it's time to add some events to handle messages. For example, to send information to a client after it has connected:

server.addEventListener(NetworkEvent.CONNECTED, function(e: NetworkEvent) {
  var connected_client = e.client();
  connected_client.send({ message: 'Welcome to the server!', verb: 'test });
});

To process the data recieved by the server:

client.addEventListener(NetworkEvent.MESSAGE_RECEIVED, function(e: NetworkEvent) {
  trace(e.data.message); // Hello world!
});

Disconnections

To disconnect a client from the server:

// Disconnect the client right after it's connected.
server.addEventListener(NetworkEvent.CONNECTED, function(e: NetworkEvent) {
  server.disconnectClient(e.client);
});

// You can also type something like this:
server.disconnectClient(server.clients[0]);

// To disconnect all clients and keep the session:
for(client in server.clients) {
  server.disconnectClient(client);
}

To disconnect from a server:

// Disconnect from the server right after it's connected.
client.addEventListener(NetworkEvent.CONNECTED, function(e: NetworkEvent) {
  client.disconnectClient();
  // or `Network.destroySession(client)` to destroy the session.
});

Clossing sessions

Finally, the sessions must be closed when required, for clients:

Network.destroySession(client);

And for the server (which will disconnect all clients):

Network.destroySession(server);

You'll probably don't want to reuse sessions; just create a new one if you need it, and destroy the old one.

More information about events on the Networking events section.

Identifiers

Each session will have an unique identifier or uuid, which will help to identify each server or client. By default, it will have assigned a random value (string).

// Server uuid
server.uuid;

// Server's client uuid
server.clients[0].uuid;

// Client uuid
client.uuid;

// Client's server uuid
client.server.uuid;

If you want to use your own identifiers (for example, loading them from a file), see Parameters for sessions.