Armagetron: network code documentation
Author: Manuel Moos

DEFINE(Armagetron Advanced, Armagetron)

Introduction | Layer One | Layer Two | Layer Three

# Layer three: network aware objects

Layer three (files:`netobject.h` and `netobject.C`) uses layer two to define a base class for classes of network aware objects (NAOs). When a NAO is created on one of the computers in the network game, copies of it will be created on the other computers. If the state of the original changes, it can send sync messages to it's copies, making the same changes on them. Every NAO has an unique ID number (shared with it's copies) and an owner (usually the computer which created the original NAO, or the computer the player controlling the NAO is using). If desired, a security system (against cheating) allows the original NAO only to reside on the server, and sync messages only to flow from the server to the clients. Only the NAO's owner is then allowed to send control messages to the original NAO on the server, which will send back sync messages reporting the changes made. Confused? Let's look at it again:

### NAO class with security disabled

That's the easy part. Any computer can create/delete such an NAO and automatically owns it. Copies of the NAO will spawn/be deleted on all the other computers. The owner is allowed to change the NAO (i.e. move it one meter to the left) and issue sync commands; then, sync messages will be sent to all other computers in the game (if the NAO was created on a client, they will be directed through the server) transferring the NAO's new state. Control messages ("move one meter to the left") may be sent from the owner to the NAO's copy at the server which may interpret them, change it's (or some other NAO's) state and send syncs about the change to all clients.

### NAO class with security enabled

Here, only the server is allowed to create an NAO. The owner may still be one of the clients. As above, copies of the NAO will spawn on all clients. Only the server is allowed to change the NAO and issue sync commands, sending sync messages to the clients. The only way the NAO's owner has influence on it are the control messages it may send to the server.

The use of the security mode simply is: the server has full control over the objects. Otherwise, people in an ego shooter could just teleport themselves at will through the arena or make themselves invincible by simple modifications to the game (that's even an issue in closed source games; look at Diabolo!).

## Usage

A sample program defining a class of NAOs is `l3_demo.cpp` from the source directory. Compile it with `make l3_demo`; the syntax is `l3_demo` to start it in server mode, just listening to clients, or `l3_demo servername` to start it in client mode connecting to the server given by `servername`; it will first show you how to synchronize the NAO with sync messages, then how to control it with control messages. Try connecting multiple clients to the server! You'll see how easy it is; it's best to read this document and the sample program in parallel.

### Overview

To define a class of NAO's (let's call it `your_NAO`), you derive a class from the base class `netobject` and declare some member functions:

- A normal constructor and a virtual destructor.
- For the synchronisation messages, the send and receive functions

      virtual void write_sync(netmessage &m);
      virtual void read_sync(netmessage &m);

  where `read_sync()` should read exactly the information from `m` that `write_sync()` writes to it, and if necessary a function deciding whether a sync message should be accepted:

      virtual bool sync_is_new(netmessage &m);

- For remote creation, the send function

      virtual void write_create(netmessage &m);

  and the remote constructor

      your_NAO(netmessage &m);

  again reading exactly the information from `m` that `write_create()` wrote to it, and eventually a post-creation function

      virtual void init_after_creation();

  being called after an object has been remotely created.
- For the security system,

      virtual bool accept_client_sync() const;

  returning true if security is to be disabled. (Default: security is on.)
- You need to create one object of the template class

      class net_initialisator<your_NAO>;

  to give your class a unique identification across the network (the constructor takes the name of your class as a string argument) and the member function

      virtual netdescriptor &creator_descriptor() const;

  returning a reference to that object (`net_initialisator<your_NAO>` is derived from the class `netdescriptor`).
- And finally, if you want to use control messages, the receive function

      virtual void receive_control(netmessage &m);

  and of course some sending function.

### Details

#### Constructor

The constructor has to call call `netobject`'s constructor

    netobject::netobject(int owner=-1);

where the argument is the user ID of the object's owner; leave it blank or at `-1` if the creating computer itself should be the owner. All in all, your constructor should look something like this:

    your_NAO::your_NAO(...) :netobject(owner) {
      // normal initialisation
      ...
    }

#### Synchronisation

Whenever you feel like your NAO's copies need to be synchronised with the original (i.e. every time you change the original, or every .1 seconds), call the original's member function

    void request_sync(bool ack=true);

(inherited form `netobject`). `ack` determines whether the sync message is guaranteed to arrive; If the synchronisation is not vital (like updates of a constantly changing position where it is not fatal if one update is missed), you can set `ack` to false. To really send the sync messages, you need to call the static function

    netobject::sync_all();

every once in a while (best immediately before `receive()` from layer two). Shortly after your call of `request_sync()`, during one of your calls to `netobject::sync_all();` the network subsystem will call your original's member function `your_NAO::write_sync(netmessage &m)` and broadcast the message `m`. When the other computers receive `m`, they will simply call your NAO's copy's member function `your_NAO::read_sync(netmessage &m)`. So your sync functions should read something like

    virtual void write_sync(netmessage &m){
       // proper heritage:
       netobject::write_sync(m);

       // write all the possibly changing
       // information form your object to m:
       m << ...
    }

    virtual void read_sync(netmessage &m){
       // heritage:
       netobject::read_sync(m);

       // read the information exactly in the same
       // order as it was written in write_sync:
       m >> ....
    }

If you detect an error during your `read_sync()`, caused by the message being in a wrong format, feel free to kick the message's sender by throwing a `killhim`-exception.

Since sync messages may get lost or arrive in the wrong order, it is not a good idea to write just the information that really changed in `write_sync()`; if you decide to do that kind of bandwidth optimisation anyway, think exactly about what you are doing!

What happens now if a sync message is lost, sent again, lost again.... and receives the other computers way too late? Without protection measurements, this will i.e. cause your racing car to be set back on the track until the next sync packet arrives, correcting the mistake. This is not fatal, but disturbing, and something needs to be done. Therefore, before calling your NAO's `read_sync()`, the network subsystem calls your NAO's member function

    virtual bool sync_is_new(netmessage &m);

where you can read out `m` just like in `read_sync()` and do some checks whether you really wish to accept the sync; i.e. with every `write_sync`, you could include a time stamp (you should do that anyway in a real time game) `sync_is_new()` may check; if the timestamp is too old, you should reject the message. Only if `sync_is_new()` returns `true`, `read_sync()` is called. As the class `netobject` already implements a rudimentary check in `netobject::sync_is_new(netmessage &m)`, guaranteeing that each accepted sync message is newer than the one before, you do not need to write your own check in most cases. If you do, it should look like

    virtual bool sync_is_new(netmessage &m){
       // heritage:
       if (!netobject::sync_is_new(m))
         return false;

       // your own checks, reading EXACTLY
       // the same information as read_sync()
       // (important for derived classes)
       m >> ....
       return result;
    }

#### Remote creation

What happens now if you create a NAO with the normal constructor? During one of the next calls of `netobject::sync_all()`, remote creation messages will be sent to the other computers. They contain all the information of a sync message, plus a bit more: The sync messages are only intended to transport the part of the NAO's information that is changing during the game; other parts of the information may be fixed, i.e. the object's name, or a character's race in a RPG. This information has to be written only once, and it would be a waste of bandwidth to transmit it with every sync message. Therefore, you should write all this fixed information in your NAO's member function

    virtual void write_create(netmessage &m){
       // again: heritage
       netobject::write_create(m);

       // your fixed information
       m << ....
    }

So, when preparing a remote creation message, `netobject::sync_all()` first lets your NAO write it's fixed information with `write_create()` to it, then the changing information with `write_sync()`. After that the message is broadcasted and guaranteed to be received by the other computers. They will then call your remote constructor which should look like

    your_NAO(netmessage &m)
    :netobject(m) // heritage
    {
      // read the fixed information
      m >> ....
    }

and after that your NAO's `read_sync()`. Since you may need some of the variable information read by that function to completely initiate your NAO, it's member function

    virtual void init_after_creation();

is called after that where you can finish the construction. Again, if an error occurs, kick the message's sender by throwing a `killhim`-exception.

#### Identification

No big deal here: just write

    static net_initialisator<your_NAO> your_NAO_init("your_NAO");

somewhere in your code file, declare the member function

    virtual netdescriptor &creator_descriptor() const;

and define it as

    netdescriptor &your_NAO::creator_descriptor() const{
      return your_NAO_init;
    }

That's it. You have to repeat that for every NAO class you define.

#### Control messages

Control messages can go from the owner of the NAO (a client) to the server only. Do with them what you want, but they are mainly intended to transport the user input to the server. Before sending a control message, you'll have to create it using your NAO's member function (inherited from `netobject`)

     netmessage *new_control_message();

Then, write to it whatever you want and send it to the server. The server will call your NAO's member function

    virtual void receive_control(netmessage &m);

which can then read and interpret the message. Of course, if you do any changes to your NAO, you should call `request_sync()` at the end. It is advisable to encapsulate the sending process in an own member function (as `new_control_message` has protected heritage, you are forced to do that :-) ). As you can see, you have much freedom here (and are basically on your own).

### Pointers to netobjects

NOTE: This section is still subject to change. Many of the things you have to do manually now will be automated in future versions of armagetronad.

You will come to a point where you define a class of NAOs containing pointers to other NAOs that need to be transmitted. The first problem:

#### Transferring pointers

Obviously, you can't just transfer them like integers. Instead of writing a pointer to a NAO to a netmessage, simply write it's ID with

    m << object->my_id();

when receiving the id, it can be retransformed to a pointer with

    unsigned short id;
    m >> id;
    netobject *obj=netobject::object(id);

In case the netobject with ID `id` has not yet been created, `netobject::object(id)` will wait for it to spawn; with a bit of luck, it will be created remotely shortly. That brings us to the next problem: what if we're not lucky? There may easily be lockups if i.e. the server waits for one of the client's NAOs to spawn, while the client is waiting for some other message from the server (of course, there is a timeout in `netobject::object()`. But after that timeout, the connection is closed). An alternative routine doing about the same job is `netobject`'s static member function

    static netobject *object_dangerous(int id);

If the NAO labelled `id` does not exist, it will simply return `NULL`.

#### Waiting for NAOs to spawn remotely

Sometimes, before you send a network message transferring a pointer to a NAO, you want to make sure the NAO has been created remotely at the message's receiver before sending the message; that avoids the problems mentioned above. The NAO's member function

    bool has_been_transmitted(int user) const;

(inherited form `netobject`) does exactly this check. For example, such checks should be done before a NAO depending on another NAO (like, the rider of a horse...) is created remotely: you want to be absolutely sure the horse is there before the rider arrives. For exactly this situation, you can use your NAO's member function

    virtual bool clear_to_transmit(int user) const;

It should return false if the NAO is not yet ready to be remotely created at the computer with user ID `user`. In our example, the rider's function should be defined as

    bool rider::clear_to_transmit(int user) const{
      return netobject::clear_to_transmit() && // heritage, as always...
             horse->has_been_transmitted(user);
    }

#### Reference counters

Another problem arises with remote destruction: It is to be avoided that a NAO is destroyed while there are still pointers to it. Therefore, each NAO has a reference counter you need to set manually: call the member function

    void reg();

every time you set a pointer to a NAO, and

    void unreg();

every time you delete the pointer or let it point elsewhere.

This Page was created by Manuel Moos(
).

Introduction | Layer One | Layer Two | Layer Three