Whole document tree

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

• 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 Armagetron.

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.

Last modification: Mit Nov 15 21:39:41 CET 2000