User:RossyMiles/Flatline

Flatline is the most recent proposed multiplayer mod for Oni. This document is a work in progress.

Protocol Information

UDP port 27777 and it's surrounding ports are unallocated and are unlikely to be used by any other application.

Flatline API

Both the Flatline clients and dedicated servers will run inside Daodan inside an official build of Oni. This is because a copy of Oni is needed to fully simulate the scripting and physics in a game.

Two sets of functions will be provided. The Net* functions will provide a basic, non-blocking UDP sockets library and a basic, single-threaded, blocking UDP server. The FLr* functions will be the rest of the code required.

NetPlatform_*

These functions provide all the platform specific functionality required by Net*.

bool NetPlatform_Initalize()
This function is called when the network functionality is required. On Windows, it makes a call to WSAStartup. On other platforms it is not needed as sockets are initialized by default for every process.

void NetPlatform_Shutdown()
For every call to NetPlatform_Initalize, there has to be a corresponsing call to NetPlatform_Shutdown. On Windows, this function calls WSACleanup. On other platforms it is not needed as sockets are initialized by default for every process.

NetUPnP_*

These functions provide basic automatic port forwarding for computers behind a router.

bool NetUPnP_Initalize(char** localip, char** routerip)
Initializes the UPnP library. Places the local ip address in localip and places the router's ip address in routerip.

bool NetUPnP_Shutdown()
Closes the UPnP library. Frees the strings pointed to by localip and routerip.

NetUDPSocket_*

These functions provide a basic UDP sockets library.

int NetUDPSocket_Create(uint16_t port)
Creates a new, non-blocking, UDP socket and binds it to the port specified. If the specified port is 0, the socket is automatically bound to an unused port.

bool NetUDPSocket_Close(int socket)
Destroys a UDP socket created with NetUDPSocket_Create.

bool NetUDPSocket_Send(int socket, sockaddr* address, const char* data, uint16_t datalen)
Sends a packet of data to the specified address using the specified socket. To broadcast a message across a LAN (such as when checking for available games), send it to 255.255.255.255 (IPv4 only).

bool NetUDPSocket_Recieve(int socket, sockaddr_storage* address, char* data, uint16_t* datalen)
Recieves a single packet from the specified socket. Places the received data in data, the length of the data returned in datalen, and the address the packet was received from in address. If there are no packets in the buffer, the function returns false.

NetUDPServer_*

These functions provide a basic, single-threaded, blocking UDP server.

int NetUDPServer_Listen(uint16_t port, bool (*packet_callback)(char* data, uint16_t datalen, int from))
Starts a new UDP server on the specified port which calls packet_callback when a packet is recieved. Does not return until the server has finished running (packet_callback returns false).

bool NetUDPServer_Send(sockaddr* address, const char* data, uint16_t datalen)
Sends a packet of data to the specified address using the server running on the current thread. This function should only be called from packet_callback or functions called by packet_callback.

FLrServer_*

These functions control the Flatline server.