NetworkDesign

Basic idea behind Networking

The idea behind arianne network protocol is to use a single stream of UDP packets to comunicate server and clients, to allow the different kind of actions we create different types of messages that are then interpreted at the opposite peer.

UDP Packet Format

The Network design is based on Messages being transmitted using UDP Packets. There are two types of streams, one is Server to Client and another one that is Client to Server.

UDP Client to Server communication stream

Each message is self contained in a SINGLE UDP Packet. There is no mechanism for recovery of lost or repeated messages.

Each UDP Packet is composed of:

• Protocol version ( 1 byte )
• Type of Message ( 1 byte )
• Client ID ( 4 bytes )
• Rest of Message ( up to 1494 bytes )

UDP Server to Client communication stream

Each message is contained in one or more UDP Packets, and the UDP Packet format is as follows:
1st UDP Packet is composed of:

• Total number of packets (1 byte)
• Position of this message (1 byte)
• Signature of the message (1 byte)
• Protocol version (1 byte)
• Type of Message (1 byte)
• Client ID (4 bytes)
• Rest of Message (up to 1491 bytes)

The following UDP Packets are composed of:

• Total number of packets (1 byte)
• Position of this message (1 byte)
• Signature of the message (1 byte)
• Rest of Message (up to 1497 bytes)

The idea is to send the serialized message inside several UDP Packets and then rebuild the full message on the Client. There is no kind of error recovery, or retransmission.

Messages are sent from the Server by simply serializing them. So the message itself contains the protocol version, the type of message and the Client id.

Receiving the message is a bit more complex. First we need to determine that we are running a compatible version of the protocol. Once we have agreed that the protocol is compatible we read the type of message and we ask a Message Factory ( "Java Design Patterns" ) to build an object of that type with the coresponding data. Once the message is build we simply store it in a queue of incoming messages waiting to be processed.

Network Manager

The Network Manager is our router that sends and receives messages to and from the network. The manager exposes the interfaces that allow:

• Reading a message from the network
• Sending a message to the network
• Finalizing the manager

The read operation is a blocking type operation so we have two options, either Polling and Blocking. We choose Blocking because we don't want to waste CPU time Polling the network for messages, we just want to sleep until messages are available. Hence we create a Thread to read from the Network, let's call it Network Manager Read.

To write messages to the network so we can safely code it simply as a method of Network Manager as write is an operation that is non blocking by nature.

The Network Manager opens a Socket from which it will receive all the messages from the network, and to where it will write all the messages to the network. Both write and read use the same Socket.

To encapsulate all this we create both the Read and Write methods as inner classes of Network Manager.

NetworkManager
  {
  socket
  messages
  pendingToSendMessages

  NetworkManagerRead isa Thread
    {
    read socket
    build message
    store in messages
    }

  NetworkManagerWrite isa Thread
    {
    get from pendingToSendMessages
    build UDP from message
    send socket
    }
  }

As you can see, messages are stored in a list when they are received, hence access to the list is synchronized.

Now lets get back to the interface as exposed to other objects. The Write method is immediate, just call it with the message to send, making sure that you have correctly filled SourceAddress and ClientID, and it will be sent to the Client.

It is important to notice that as the transport is based on UDP there are no guarantees that the message is correctly sent. This situation is in the protocol itself.

The Read method is blocking, when you call the Read method it either returns a message from the queue or if the queue is empty the thread blocks until one arrives.

That is the basic idea of the Network Manager; however, the manager gets a bit more complex as a result of the need to support Server to Client messages that are bigger than one UDP package, the manager just sends the stream of packets once, and doesn't confirm if any of the messages are received. Please refer to UDP Packet Format for more info about it.

Message Types

To communicate, the Client and Server of Marauroa use a stream of UDP packets. The message system belongs to the marauroa.common.net package, so refer to code.

We have Client to Server, aka C2S, and Server to Client, aka S2C, messages.
Most messages have two versions of themselves: the C2S and S2C versions.

Communication Model

Client                   Server
------ 	                 ------
--onConnect:
Send C2S Login           If C2S Login is correct
                           Send S2C Login ACK
                         else
                           Send S2C Login NACK
                         end if

                         Send S2C Character List

                         Send S2C Server Info

Send Choose Character    If character is correct
                           Send Choose Character ACK
                         else
                           Send Choose Character NACK
                         Finish

--onTimer:
Send Perception ACK      Send Perception

--on RPManager request:
                         Send TransferREQ         
Send TranferACK
                         Send Transfer

--onEvent:
Send Action              Send Action ACK

--onExit:
Send Logout              If Client can logout
                           Send Logout ACK
                         else
                           Send Logout NAC

Let's discuss in detail each message type.

Message C2S Login

The login Message is sent from the Client to the Server to request the right to access to the game. The message is composed of a username and password. The Username is a string that is already registered on Server as the name of a user account, and password is a string that is associated with that account. If the username/password combination is correct then Server must send a Login ACK Message to indicate to the Client that the message has been correctly processed. On the contrary, if the username/password is wrong the Server will send a Login NACK.

Message S2C Login ACK

The LoginACK Message is sent from the Server to the Client to indicate that the login process has been completed correctly and that it can proceed to the next step. It has no params.

Message S2C Login NACK

The LoginNACK Message is sent from the Server to the Client to tell the Client that its login message is incorrect because either the username or password is wrong or because Server has decided to reject the login request, e.g. if the Server is full or because the IP is banned.

The message is composed of: Message indicating the resolution.

Message S2C Character List

The CharacterList Message is sent from the Server to the Client to give the Client a choice of character to play with. This feature models the behavior of having several characters associated with a single account.

The message is composed of: A List of Character names

Each character name must be unique at Server level, and it is assigned when the character is created.

Message S2C Server Info

The Server Info Message is send from the Server to the Client to tell the Client about what Server is running, and how to inform Server administrator of problems.

The message is composed of: A List of strings of the type "attribute=value"

Message C2S Choose Character

The ChooseCharacter Message is sent from the Client to the Server to indicate what character the user wishes to play the game with.

The message is composed of: the name of the character

The name of the character must be one of the names listed in the Character List Message or the Server will reply with a Choose Character NACK message. Once the character has been chosen and the acknoledge has been recieved the Client is ready to start the game.

The Server will reply to this message with a Choose Character ACK or a Choose Character NACK message. The Client must have already logged in before receiving this message, if not the Server will send a Choose Character NACK.

Once a character is chosen, the only way to choose a new one is by logging out and logging in again.

Message S2C Choose Character ACK

The Choose Character ACK Message is sent from the Server to the Client to notify the Client that the character has been chosen. The message is composed of: the object.ID of the character

We need this value to track our own character.

Message S2C Choose Character NACK

The Choose Character NACK Message is sent from the Server to the Client to notify the Client that the character has not been chosen. This also implies to the Client that it should send another ChooseCharacter Message.

It has no params.

Message C2S Logout

The Logout Message is sent from the Client to the Server to indicate that it wants to finish the session. It has no params.

If the Client can logout the Server will send a Logout ACK Message and the Client can safely close the connection, but if the Server sends a Logout NACK Message, the Client should keep playing as disconnecting at that moment will leave its avatar in the game uncontrolled ( idle ).

Message S2C Logout ACK

The Logout ACK Message is sent from the Server to the Client to notify the Client that the logout has been accepted.

It has no params.

Message S2C Logout NACK

The Logout NACK Message is sent from the Server to the Client to tell the Client that the logout has not been accepted, possibly because something related to the RP entity, for example, combat is in progress.

It has no params.

Message C2S Action

The Action message is sent from the Client to the Server to notify the Server of the Clients desire to execute an action. The message is simply composed of a single action.

!!Message S2C Action ACK The Action ACK is sent from the Server to the Client to identify that the action has been received in the Server. It doesn't acknowledge that the action has been accepted by the RP Manager, it just means that the action successfully arrived at the Server.

It has 1 param: action_id - is used to identify to which action you referred. In Marauroa you can command several actions per turn.

Message S2C Perception

The Perception message is a message sent from the Server to the Client to notify the Client about changes to the objects that exist near it. The message is based on the idea explained in Delta perception document.

The message is composed of:

• A type that can be DELTA or TOTAL
• A string indicating the name of the zone the perception is related to.
• A time stamp value that will be just one unit bigger than the previous perception
• A List of RPObject that contains added object
• A List of RPObject that contains modified added object attributes
• A List of RPObject that contains modified deleted object attributes
• A List of RPObject that contains deleted object
• A RPObject that describe the things the rest of players don't see about OUR own object.

Read the Delta perception algorithm to understand what it is for.

Message C2S Perception ACK

The perception ACK message is sent from the Client to the Server. We use this message to inform the Server that the Client is still there and listening. It has no params.

Message S2C TransferREQ

The TransferREQ message is a message sent from the Server to the Client to notify the Client about the request of the server to send content useful for the game where play will happen.

The message is composed of: An array of TransferContent objects containing all the name of each resource, its timestamp and if the resource is cacheable or not.

Message C2S TransferACK

The TransferACK message is a message sent from the Client to the Server to notify the Server about what of the given TransferContent elements recieved from TransferREQ should be sent.

The message is composed of: An array of TransferContent objects containing all the name of each resource and a flag indicating ack or not.

Message S2C Transfer

The Transfer message is a message sent from the Server to the Client to send the Client content useful for the game where play will happen.

The message is composed of: An array of TransferContent objects containing all the name of each resource, its timestamp, a flag indicating if the resource is cacheable or not and a byte array with the content itself.

Versioning and port numbering

A problem arises when we need to have two versions of Marauroa on the same machine. This happens for example when you run a release version and a development version on the same machine.

So to avoid port collisions we will use different ports for each release. The release version will run on the standard game port bu the development version will run on the (standard game port)*10

For example: release version of gladiators runs at 3214 development version runs at 32140

To allow different servers of Marauroa to run on the same machine running different games we will assign an unique port number to each game.

gladiators runs at 3214 mapacman runs at 3215 stendhal runs at 3216

Feel free to follow or disgregard these port rules if you wish. They may not apply to you.