Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Changes between Version 1 and Version 2 of code/doc/network/Synchronisable


Ignore:
Timestamp:
Sep 13, 2008, 3:54:20 PM (16 years ago)
Author:
scheusso
Comment:

—

Legend:

Unmodified
Added
Removed
Modified

  • code/doc/network/Synchronisable

    v1 v2  
    11= Synchronisable =
    2 The most important part of the Network API is the Synchronisable Class (see also [wiki:network/Synchronisable Synchronisable]):
    3  * This class provides the functionality for objects to get synchronised over the network:
    4    * REGISTERDATA/REGISTERSTRING: these functions register a variable (to the Network Engine) that needs synchronisation
    5    * setObjectMode: this function sets the direction of synchronisation (server->client / server<->client / server<-client)
    6  * Every class that needs synchronisation must fullfill some dependencies:
    7    * It must (public) inherit from Synchronisable
    8    * It must have a default constructor
    9    * All steps in object creation that need data (from the levelfile or the network) must be in the create() function
    10    * It must implement the following functions:
    11      * registerAllVariables: register all variables (currently only basic types and strings), that need synchronisation, to the network engine by calling REGISTERDATA and/or REGISTERSTRING
    12      * create: (as described above)
    13      * set appropriate synchronisation direction (default: server->client) by calling setObjectMode
     2== Purpose ==
     3The most important part of the Network API is the Synchronisable Class. It provides the functionality for objects to get synchronised over the network.
     4== Contents of Synchronisable ==
     5 * objectID: this is a unique id identifying the object inside alls synchronisables
     6 * classID: this is a unique id identifying the class of the object
     7== Synchronisation ==
     8There are different modes of synchronisation:
     9 * network::direction::toclient (== 0x1) sync only from server to client
     10 * network::direction::toserver (== 0x2) sync only to server (not really recommended)
     11 * network::direction::bidirectional (==0x3) sync in both directions
    1412
     13Every object and every registered variable have a syncdirection (default: toclient).
    1514
    16 ''' Synchronisable functions:'''[[BR]]
    17 ''REGISTERDATA(varname)''[[BR]]
    18 Use this makro to synchronise a membervariable of a class (like position, velocity, ...). This makro sets the sync-direction of the variable to server->client
     15In order to synchronise a variable in a class, these steps must be done:
     16 * The class must (public) inherit from Synchronisable
     17 * Every variable that needs synchronisation must be registered to the network engine (see below)
     18 * Make sure the syncdirection of the object is set correctly (setObjectMode, see below)
     19
     20== Register Variables ==
     21There are two methods of synchronisation:
     22 * Data synchronisation: use this for every type of linear allocated object (e.g. no pointers)
     23 * String synchronisation: use this for strings only ;)
     24
     25If you need to synchronise different types of objects, you can synchronise it's membervariables manually. But make sure, the object (to be synchronised) exists when creating an instance of your class.
     26
     27The registrations must be done in the function registerAllVariables(). Also call this function in your constructor.
     28
     29  Example: Synchronisation of a basic type (membervariable)
     30{{{
     31int SomeClass::i;
     32REGISTERDATA(i);  //this sets the syncdirection to toclient
     33}}}
     34  Example: Synchronisation of a Ogre::Vector3
     35{{{
     36Ogre::Vector3 SomeClass::v;
     37REGISTERDATA( v.x );
     38REGISTERDATA( v.y );
     39REGISTERDATA( v.z );
     40}}}
     41
     42=== Register linearly allocated object / basic type ===
     43To register an object, that is linearly allocated (e.g. from 0x20 to 0x50, no pointers outside this range) you can use REGISTERDATA(varname) or REGISTERDATA_WITHDIR(varname, direction) (if you want a non-default sync. direction).
    1944{{{
    2045int SomeClass::i; // membervariable i
    … …  
    3257}}}
    3358
    34 ''REGISTERSTRING(stringname)''[[BR]]
    35 same as REGISTERDATA but for strings
     59=== Register Strings ===
     60To register a string object use REGISTERSTRING(stringname) or REGISTERSTRING_WITHDIR(stringname, direction).
    3661
    37 ''REGISTERSTRING_WITHMODE(stringname, mode)''[[BR]]
    38 same as REGISTERDATA_WITHMODE but for strings
     62=== Synchronisation Direction ===
     63As mentioned above, the default direction of the Synchronisation is toclient. If you want to change this, you need to register the variable with either REGISTERDATA_WITHDIR or REGISTERSTRING_WITHDIR (normally per-class, see below). Additionally you have to set the global syncdirection (per-object, see below) to directional or toclient (again: not recommended
     64{{{
     65int SomeClass::syncback;
     66REGISTERDATA_WITHDIR(i, network::direction::bidirectional); // put this inside registerAllVariables
     67this->setObjectMode(network::direction::bidirectional); // put this wherever you want (it is possible to do this only for specific objects specified by objectID)
     68}}}
    3969
    40 ''setObjectMode''[[BR]]
    41 this sets the sync direction of the whole object (default: server->client).
    42 '''Note:''' if you don't call setObjectMode with a value other than network::direction::toclient then the variables will only be synchronised to the client (if at all)
     70== The create function ==
     71When synchronising an object the first time to a client (or server) the following steps occur:
     72 * A new object gets created with the appropriate class
     73 * by calling the constructor of the class also registerAllVariables gets called (make sure this is in your constructor)
     74 * After construction of the object finished the data get updated (all variables previously registered by registerAllVariables)
     75 * After that the create() function gets called.
     76
     77Because we don't have the data at construction time, all functions that need member variables (with data from the server) must be called inside create(). See example class for details.
     78
     79== Preconditions ==
     80To make a class A synchronisable make sure these conditions are fullfilled:
     81 * A has a default constructor A::A()
     82 * A implements the function registerAllVariables which has all the calls of REGISTERXXX
     83 * Make sure all you put all critical calls into the create function
     84 * If you have nondefault sync directions make sure you called setObjectMode
     85
     86== Example Class ==
     87
     88{{{
     89#include "network/Synchronisable.h"
     90class ExampleClass : public network::Synchronisable, public SomeOtherClass{
     91public:
     92  ExampleClass(){ registerAllVariables(); }
     93  ~ExampleClass(){}
     94
     95  .......
     96  void registerAllVariables(){
     97      REGISTERDATA(i);
     98      REGISTERDATA_WITHDIR(v.x, network::direction::bidirectional);
     99      REGISTERDATA_WITHDIR(v.y, network::direction::bidirectional);
     100      REGISTERDATA_WITHDIR(v.z, network::direction::bidirectional);
     101      REGISTERSTRING(s);
     102  }
     103  bool create(){
     104      Synchronisable::create();
     105      SomeOtherClass::create();
     106      //do all the critical stuff here
     107      //eg set meshsrc or whatever (see Model for details)
     108  }
     109private:
     110  int i;
     111  Vector3 v;
     112  String s;
     113};
     114
     115}}}
     116