Unconnected messages

Note

This is part of the Low Level Transport for advanced users only.

The netcode allows you to send unconnected messages without establishing connections with peers.

Use cases

Unconnected messages can be useful in cases where you have a list of server ip's and you want to display them to the player, but instead of just displaying the IP, you also want to display extra information like map name, player count, etc. What you can do is send a quick unconnected message to all the server ips and listen for unconnected response back that contains the server information which can then be displayed in the server list.

Another way unconnected messages can be used is for server discovery on local networks by broadcasting an unconnected message to the entire network and waiting to see if any server on the network responds.

An unconnected message has no guarantee of order or reliability and cannot be split into multiple messages so the message size must be under MTU (maximum transmission unit) or it won't be received.

Defining messages

Similar to connected messages, you need to define a message that you want to send except instead of extending from IMessage you need to extend from IWritable which only defines the Write method.

// Header byte we will write on top of every message
public enum UnconnectedType : byte {
	Ping = 1,
	Pong = 2,
}

// Empty ping message to send to servers
public class MessagePing : IWritable {
	
	// Don't read header here because we read it already
	public void Read(Reader reader) {}
	
	// Only write the header
	public void Write(Writer writer) {
		writer.WriteEnum<UnconnectedType>(UnconnectedType.Ping);
	}
	
}

// Ping response that servers respond with
public class MessagePong : IWritable {
	
	public string Map;
	public int Players;
	
	// Don't read header here because we read it already
	public void Read(Reader reader) {
		Map = reader.ReadString();
		Players = reader.ReadInt32();
	}
	
	// Write header and data
	public void Write(Writer writer) {
		writer.WriteEnum<UnconnectedType>(UnconnectedType.Pong);
		writer.Write(Map);
		writer.Write(Players);
	}
	
}

Sending unconnected messages

To send unconnected messages, simply use the Host.SendUnconnected method on a listening host:

// Create a host and start listening on a random port
HostConfig config = new HostConfig();
HostEvents events = new HostEvents();
Host host = new Host(config, events);

// Resolve server ip
IPEndPoint server = IPResolver.TryParse("192.168.1.123:1234")

// Create a ping message
MessagePing message = new MessagePing();

// Send the ping message to the resolved server ip
host.SendUnconnected(server, message);

Sending broadcast messages

A broadcast message can be sent to everybody on the local network that is listening on a specific port. To send broadcast messages HostConfig.Broadcast must be true. By default, broadcast messages are enabled.

// Create a host and start listening on a random port
HostConfig config = new HostConfig();
HostEvents events = new HostEvents();
Host host = new Host(config, events);

// Create a ping message
MessagePing message = new MessagePing();

// Send the ping message to everybody on the local network listening on port 1234
host.SendBroadcast(1234, message);

Receiving messages

To receive messages, listen for a IHostListener.OnHostReceiveUnconnected or a IHostListener.OnHostReceiveBroadcast event, check the header and read the message.

private void OnHostReceiveUnconnected(IPEndPoint remote, Reader message) {
	
	// Read the header
	UnconnectedType type = message.ReadEnum<UnconnectedType>();
	
	// Switch based on received header
	switch (type) {
		
		case UnconnectedType.Ping:
			// Read ping message
			MessagePing ping = new MessagePing();
			ping.Read(message):
			
			// Respond with pong
			MessagePong response = new MessagePong();
			response.Map = "Desert";
			response.Players = 10;
			Host.SendUnconnected(remote, response);
			break;
			
		case UnconnectedType.Pong:
			// Read pong message
			MessagePong pong = new MessagePong();
			pong.Read(message);
			break;
			
	}
	
}