udprotean

A UDP-based protocol for multiplayer games, with reliable in-order message delivery.
https://gitlab.com/haath/udprotean

To install, run:

haxelib install udprotean 0.3.3 

See using Haxelib in Haxelib documentation for more information.

README.md

pipeline status coverage report license release


  • Low-latency communication over UDP.
  • Reliable delivery, regardless of packet loss on the network.
  • Messages are handled in-order, as they were sent.
  • Under-the-hood fragmentation handling: send up to 137KB or more in a single message.
  • Virtual TCP-like connection established with a handshake.
  • Minimal and efficient API, similar to WebSockets.
  • Synchronous single-threaded processing. Make it run in parallel any way you wish.
  • Dependency-free native Haxe code, compile and use on any target that supports UDP.

Performance

  • Samples: 1000
  • Ping time: 40-50ms
  • Transmission every: 16ms
  • Target: Neko
Round-Trip Time
Packet LossMinMeanMax
0%37ms41ms56ms
5%32ms42ms144ms
10%36ms52ms196ms
20%30ms66ms240ms
40%38ms122ms451ms
60%35ms241ms701ms

Install

$ haxelib install udprotean

Usage

Server

import udprotean.server.UDProteanClientBehavior;

class EchoClientBehavior extends UDProteanClientBehavior
{
    // Called after the constructor.
    override function initialize() { }

    // Called after the connection handshake.
    override function onConnect() { }

    override function onMessage(message: Bytes) {
        // Repeat all messages back to the client.
        send(message);
    }

    override function onDisconnect() { }
}
var server = new UDProteanServer("0.0.0.0", 9000, EchoClientBehavior);

server.start();

while (running)
{
    // Synchronously read and process incoming datagrams.
    server.update();
}

server.stop();

It is also possible to register notification callbacks on the server.

server.onClientConnected(client -> { });

server.onClientDisconnected(client -> { });

Client

import udprotean.client.UDProteanClient;

class MyClient extends UDProteanClient
{
    // Called after the constructor.
    override function initialize() { }

    // Called after the connection handshake.
    override function onConnect() { }

    override function onMessage(message: Bytes) { }

    override function onDisconnect() { }
}
var client = new MyClient("127.0.0.1", 9000);

client.connect();

while (running)
{
    // Synchronously read and process incoming datagrams.
    client.update();

    client.send(bytes);
}

client.disconnect();

Synchronous or with a Timeout

The update() method only returns when there is no data left to read on the socket. For continuous communication, the updateTimeout() method may be preferable.

// Process incoming data for up to 16ms.
client.updateTimeout(0.016);

This method is useful, when the load on the incoming buffer is not enough to cause a growing backlog, because it lets you synchronously handle the networking, and with a more-or-less fixed interval execute the rest of the application logic, all on a single thread. For example, a game loop could look like the following:

while (gameIsRunning)
{
    // Process incoming data for up to 10ms.
    udproteanClient.updateTimeout(0.010);

    var input = getUserInput();

    // Send the user's input to the server.
    udproteanClient.send(input);

    // Update things in the game, like moving the player, physics etc.
    updateGame(input);
    render();
}

The send() method

By default, the send() method will write the necessary datagrams to the UDP socket immediately.

// Will block for a few ms.
client.send(Bytes.alloc(1024));

The alternative is to provide it with false as its second argument. This way, outgoing datagrams will only be stored in the underlying buffers and the method will return immediately without writing anything on the socket.

// Will retun immediately.
client.send(Bytes.alloc(1024), false);

// Now update will transmit the previous message for the first time.
client.update();

Unreliable Sending

The option to send unreliable UDP messages is still available through the sendUnreliable() method. Messages sent this way will bypass the sequential communication protocol, will not be stored in the local buffers, and instead will just be transmitted immediately as plain UDP datagrams.

udproteanClient.sendUnreliable(bytes);

This can be useful for certain types of messages, such as for example position updates sent by the server to the clients, as this could significantly lower the server's memory usage. Additionally, loss of such messages is generally acceptable, since newer more recent position updates are more or less sent out continuously.

Contributors
Haath
Version
0.3.3
Published
5 years ago
License
MIT

All libraries are free

Every month, more than a thousand developers use Haxelib to find, share, and reuse code — and assemble it in powerful new ways. Enjoy Haxe; It is great!

Explore Haxe

Haxe Manual

Haxe Code Cookbook

Haxe API documentation

You can try Haxe in the browser! try.haxe.org

Join us on GitHub!

Haxe is being developed on GitHub. Feel free to contribute or report issues to our projects.

Haxe on GitHub

⌂