Lidgren basics

Lidgren network library is all about messages. There are two types of messages:

  • Library messages telling you things like a peer has connected or diagnostics messages (warnings, errors) when unexpected things happen.
  • Data messages which is data sent from a remote (connected or unconnected) peer.

    • The base class for establishing connections, receiving and sending message are the NetPeer class. Using it you can make a peer-to-peer network, but if you are creating a server/client topology there are special classes called NetServer and NetClient. They inherit NetPeer but sets some defaults and includes some helper methods/properties.

    Here's how to set up a NetServer:

    NetPeerConfiguration config = new NetPeerConfiguration("MyExampleName");
    config.Port = 14242;
     
    NetServer server = new NetServer(config);
    server.Start();

    The code above first creates a configuration. It has lots of properties you can change, but the default values should be pretty good for most applications. The string you provide in the constructor (MyExampleName) is an identifier to distinquish it from other applications using the lidgren library. Just make sure you use the same string in both server and client - or you will be unable to communicate between them.

    Secondly we've set the local port the server should listen to. This is the port number we tell the client(s) what port number to connect to. The local port can be set for a client too, but it's not needed and not recommended.

    Thirdly we create our server object and fourth we Start() it. Starting the server will create a new network thread and bind to a socket and start listening for connections.

    Early on we spoke about messages; now is the time to start receiving and sending some. Here's a code snippet for receiving messages:

    NetIncomingMessage msg;
    while ((msg = server.ReadMessage()) != null)
    {
        switch (msg.MessageType)
        {
            case NetIncomingMessageType.VerboseDebugMessage:
            case NetIncomingMessageType.DebugMessage:
            case NetIncomingMessageType.WarningMessage:
            case NetIncomingMessageType.ErrorMessage:
                Console.WriteLine(msg.ReadString());
                break;
            default:
                Console.WriteLine("Unhandled type: " + msg.MessageType);
                break;
        }
        server.Recycle(msg);
    }

    So, lets dissect the above code. First we declare a NetIncomingMessage, which is the type of incoming messages. Then we read a message and handles it, looping back as long as there are messages to fetch. For each message we find, we switch on sometime called MessageType - it's a description what the message contains. In this code example we only catch messages of type VerboseDebugMessage, DebugMessage, WarningMessage and ErrorMessage. All those four types are emitted by the library to inform about various events. They all contains a single string, so we use the method ReadString() to extract a copy of that string and print it in the console.

    Reading data will increment the internal message pointer so you can read subsequent data using the Read*() methods.

    For all other message type we just print that it's currently unhandled.

    Finally, we recycle the message after we're done with it - this will enable the library to reuse the object and create less garbage.

    Sending messages are even easier:

    NetOutgoingMessage sendMsg = server.CreateMessage();
    sendMsg.Write("Hello");
    sendMsg.Write(42);
     
    server.SendMessage(sendMsg, recipient, NetDeliveryMethod.ReliableOrdered);

    The above code first creates a new message, or uses a recycled message, which is why it's not possible to just create a message using new(). It then writes a string ("Hello") and an integer (System.Int32, 4 bytes in size) to the message.

    Then the message is sent using the SendMessage() method. The first argument is the message to send, the second argument is the recipient connection - which we'll not go into detail about just yet - and the third argument are HOW to deliver the message, or rather how to behave if network conditions are bad and a packet gets lost, duplicated or reordered.

    There are five delivery methods available:

    Unreliable   This is just UDP. Messages can be lost, received more than once and messages sent after other messages may be received before them.
     
    UnreliableSequenced   Using this delivery method messages can still be lost; but you're protected against duplicated messages and if a message arrives late; that is, if a message sent after this one has already been received - it will be dropped. This means you will never receive "older" data than what you already have received.
     
    ReliableUnordered   This delivery method ensures that every message sent will be received eventually. It does not however guarantee what order they will be received; late messages may be delivered before older ones.
     
    ReliableSequenced   This delivery method is similar to UnreliableSequenced; except that is guarantees that SOME messages will be received - if you only send one message - it will be received. If you sent two messages quickly, and they get reordered in transit, only the newest message will be received - but at least ONE of them will be received guaranteed.
     
    ReliableOrdered   This delivery method guarantees that messages will always be received in the exact order they were sent.

    Here's how to read and decode the message above:

    NetIncomingMessage incMsg = server.ReadMessage();
    string str = incMsg.ReadString();
    int a = incMsg.ReadInt32();