doxygen.html

/**
@defgroup Common GanefCommon
This is the Common Module, very nice.
@defgroup Client GanefClient
This is the Client Module, should be linked with the client application.
@defgroup Server GanefServer
This is the Server Module, should be linked with the server application.
*/



/**
@mainpage API

<!--h2><font color=red>Ga</font>me <font color=red>Ne</font>twork <font color=red>F</font>ramework</h2-->

The following describes how to use Ganef in a network based game, or similar application. It is highly recommended that you read these pages, and take a close look at the test-application:

<ol>
 <li> @subpage Topology </li>
 <li> @subpage ClientServerSetup </li>
 <li> @subpage Data </li>
 <li> @subpage ServerSetup </li>
 <li> @subpage ClientSetup </li>
 <li> @subpage ConnectionEvents </li>
 <li> @subpage TestApplication </li>
 <li> @subpage Plugins </li>
 <li> @subpage Installation </li>
 <li> @subpage Misc </li>
</ol>

<hr>[Next: @ref Topology ]





@page Topology The Network Topology of Ganef
Before we begin, it is important to understand that Ganef was made to facilitate server-client based games. The following assumptions are made about the game in which Ganef will be used:
<ul>
   <li>The game has only one dedicated server</li>
   <li>The server holds the "truth" about the gameworld (the server is always right)</li>
   <li>The server is the <i>only</i> one to alter the game-world</li>
   <li>The clients only send requests about what they <i>want</i> to do, not what they <i>did</i>
   <li>The server knows the whole game-world, the clients need not know all of it at any point in time.
</ul>
As you might have guessed, this means that Ganef is not made for all games, but only a subset of them. The reason for these strict assumptions is that if they hold for any game, using Ganef will make the development of the game a lot easier.

<hr>[Next: @ref ClientServerSetup ]


@page ClientServerSetup Client-Server setup
As mentioned game using Ganef will have one server, and one or more clients. To acheive this you will inherit from two classes in Ganef, ClientFramework and ServerFramework. Since we are using C++ you can inherit from more than one class, hence you could let your main game-class (if you have one such) inherit from one of these even though it is already inheriting from an other base class.

<h3>%Client</h3>
The client-class must as mentioned inherit the ClientFramework class as follows:
\code
class MyGameClient : public ClientFramework
{
   // ... your client class members and methods.
};
\endcode
<p>
The ClientFramework class declares several abstract methods:
\code
protected: // These must be implemented in a derived class
   virtual void writeHandshakeInitMessage(FrameworkPacket * fp) = 0; //give first message
   virtual void onHandshakingDiscontinue(FrameworkPacket * fp) = 0; //recieve
   virtual bool onHandshakeDescription(FrameworkPacket * fp, FrameworkPacket * reply) = 0;
   virtual void onDisconnect() = 0;
   virtual void onConnect() = 0;
\endcode
These must be implemented before you can run your client application, what you should do in each of them will be explained later.

<h3>%Server</h3>
The server class must inherit from the ServerFramework class as follows:
\code
class MyGameServer : public ServerFramework
{
   // ... your server class members and methods.
};
\endcode
Like the client, the server must implement a few abstract methods, the content of these will be discussed as we explain later:
\code
protected: // These method should be implemented on the GameServer
   /// This method should write it's reply in the reply-packet, and return true or false depending on wether it want's us to continue the handshaking.
   virtual bool onInitialHandshake(FrameworkPacket * handshake, FrameworkPacket * reply) = 0;
   /// This method will be invoked when a new client has passed the handshaking-phase.
   virtual void onClientConnected(Client * client) = 0;
   /// This method will be invoked when a client has timed out.
   virtual void onClientDisconnected(Client * client) = 0;
   /// This method should return some dirivative of the Client-class.
   virtual Client * createClient(ServerFramework *fw, const ost::InetHostAddress &addr, ost::tpport_t port) = 0;
\endcode
A thing to notice here is that you are forced to implement a method called createClient(...), this method should return an object of the class Client. But if you want to assosiate more data with a connected client, you can just inherit from the Client class and add what ever data you find usefull.

<hr>[Next: @ref Data ]


@page Data Gameworld Data
Most gameworlds are represented as a bunch of well organized data-structures. In strict server-client based games, the server holds a full copy of the world, and the client hold a subset of the data constituting the world. The datatypes might not even be the same on server and client, because the client might not need to know all about every entity in the game. This is why Ganef uses two distinct base classes for datatypes, ClientData and ServerData.
<p>
The idea is that every entity in your gameworld on the serverside inherit from ServerData. This gives you some very nice methods for replicating the data from server to one or more clients, the names and comments of these methods should explain what they do:
\code
   public:
   /// Will send a create-object packet to all clients.
   void sendCreateObjectToAll() const;
   /// Creates and sends a create-object packet to a list of clients.
   void sendCreateObject(const std::map<unsigned int, Client *> & clientlist) const;
   void sendCreateObject( Client * client) const;

   /// Will send an update packet to all clients.
   void sendUpdateToAll(char type, bool reliable) const;
   /// Creates and sends an update packet to a list of clients.
   void sendUpdate(const std::map<unsigned int, Client *> & clientlist, char type, bool reliable) const;
   void sendUpdate( Client * client, char type, bool reliable) const;

   /// Will send a destroy/delete-object packet to all clients.
   void sendDestroyToAll() const;
   /// Create and sends a destroy-object packet to a list of clients.
   void sendDestroy(const std::map<unsigned int, Client *> & clientlist) const;
   void sendDestroy( Client * client ) const;
\endcode
The important thing to notice here is that when you call the sendCreateXXX methods, a similar datastructure inheriting from ClientData will be initialized and inserted into the ClientFramework on the clients you specify. The important thing to notice here is that every class in your gameworld must have a unique id. This id should be returned by the serverside data with the virtual method:
\code
   /// This must produce a unique id for this class, it will be used on the client side to construct new objects.
   virtual const unsigned int getClassId() const = 0;
\endcode
And on the client side you should register a static method as the "constructor" for the client side class. This could be done as follows:
\code
class MyServerData : public ServerData
{
   private:
      double x,y;
      /// [... other members ...]
   public:
      virtual const unsigned int getClassId() const { return 42; };
      /// Here the data-class should fill in all data required by the constructor on the client side.
      virtual void fillCreateObjectPacket(FrameworkPacket * packet) const
      {
         packet->writeInt32((int)x);
         packet->writeInt32((int)y);
      }
      /// [... other methods ...]
};

class MyClientData : public ClientData
{
   private:
      int x,y;
   public:
      MyClientData(ClientFramework * f, FrameworkPacket * p) : ClientData(f,p)
      {
         // Here you would read your class data from the packet
         x = p->readInt32();
         y = p->readInt32();
      }
      static ClientData * constructMyData(ClientFramework * f, FrameworkPacket * p)
      {
         return new MyClientData(f,p);
      };
};

class GameClient : public ClientFramework
{
   // [... class methods and members ...]
} app;
app.registerConstructor(42, &MyData::constructMyData);
\endcode
Now if the server has an object of class MyServerData and calls "sendCreateObject(client)", a FrameworkPacket will be created and inserted in the outqueue on the server. Once the packet is sent and received on the client the packet will hint the client about what constructor method to call (based on the class id, in this case "42") and thereby accuire a new object of class MyClientData. An important thing to notice is that MyClientData calls the constructor "ClientData(ClientFramework * f, FrameworkPacket * p)" of ClientData. This is <em>very important</em> because the ClientData should get to read from the packet first, because the very first thing in the packet is the <em>unique object id</em> see @ref UniqueFrameworkID.
<p> This also gives you the option of deriving classes even more, and then in each contructor read what ever data is expected, hence reducing duplication of code. If you have the same inheritance structure on the server you must likewise call the method for writing the initial constructor packet recursively, here is an example:
\code
class MyServerBaseData : public ServerData
{
   private:
      double x,y;
   public:
      virtual const unsigned int getClassId() const = 0; // Not implemented, because this class is still abstract
      /// Here the data-class should fill in all data required by the constructor on the client side.
      virtual void fillCreateObjectPacket(FrameworkPacket * packet) const
      {
         packet->writeInt32((int)x);
         packet->writeInt32((int)y);
      }
};
class MyServerRealData1 : public MyServerBaseData
{
   private:
      std::string name;
      MyServerBaseData * best_friend;
   public:
      virtual const unsigned int getClassId() const { return 42; };
      /// Here the data-class should fill in all data required by the constructor on the client side.
      virtual void fillCreateObjectPacket(FrameworkPacket * packet) const
      {
         // Let our base class write first
         this->MyServerBaseData::fillCreateObjectPacket(packet);
         // Then we write
         packet->writeString(name);
         packet->writePtr(best_friend);
      }
};
\endcode
On the client you would have:
\code
class MyClientBaseData : public ClientData
{
   private:
      int x,y;
   public:
      MyClientBaseData(ClientFramework * f, FrameworkPacket * p) : ClientData(f,p)
      {
         // Here the base data is read (before us the ClientData class read its unique framework id)
         x = p->readInt32();
         y = p->readInt32();
      }
};

class MyClientReal1Data : public MyClientBaseData
{
   private:
      std::string name;
      MyClientBaseData * best_friend;
   public:
      MyClientBaseData(ClientFramework * f, FrameworkPacket * p) : MyClientBaseData(f,p)
      {
         // It's time to read our data
         name = p->readString();
         p->readPtr(this, &best_friend, f);
      }

      static ClientData * constructMyData(ClientFramework * f, FrameworkPacket * p)
      {
         return new MyClientReal1Data(f,p);
      };
};
\endcode

<hr>[Next: @ref ServerSetup ]


@page ServerSetup Setting up the server
When you have created your derived classes of ClientFramework and ServerFramework you should tell the server application to start listening on some port, then enter its @ref MainLoop. Then to process any incomming packets from clients, then @ref MainLoop <em>must</em> call the keepAlive(...) method. When ever this method is called any packets from clients will be processed.

<hr>[Next: @ref ClientSetup ]


@page ClientSetup Establish a Connection from a client
When you want to connect to a game server you just call the initServerConnection(...) with a hostname and port number. Then the client will start trying to connect to the server. Like on the server side, you must enter the @ref MainLoop of your game, where you <em>must</em> call the keepAlive(...) method to make sure you process any incomming packets from the server.

<hr>[Next: @ref ConnectionEvents ]


@page ConnectionEvents Connection Events
- onConnect(...)
- onDisconnect(...)
- onClientConnect(...)
To make sure that no two thread manipulate the same data at the same time, all these event-methods that you are forced to implement on server and client will not be called unless you call keepAlive(...). That is these methods will be called from the same thread of execution as your @ref MainLoop. This garanties that these methods can manipulate the gameworld data (on client or server). The threads started by the framework to handle sending, receiving and retransmitting packets will never touch the actual game-data, this <em>only</em> happens in the code you write, and this code will only be touched by one thread of execution.

<h2>Keeping the framework running</h2>
As explained earlier, you must call the keepAlive(...) method in your @ref MainLoop. If you fail to do this very often, then the connection between server and client might drop, because the heartbeats sent out by the client are sent from there. This is not very convenient, and will likely be changed in the future.

<hr>[Next: @ref TestApplication ]


@page TestApplication Complete Test Application
To better show how this is all used, we have constructed a test-application. It uses SDL and TTF so these libraries must be installed to compile the testapplication.
<p>
The "game" is rather simple: the client connects to the server and is given a "snake" consisting of 10 bites. When the client moves the mouse he request that the head of his snake be moved to that possition. The server keeps telling all connected client where all snakebites are possitioned.
<h3>%Client files</h3>
<ul>
   <li>client_main.cpp</li>
   <li>testclientframework.cpp / testclientframework.h</li>
   <li>testclientsnakebite.cpp / testclientsnakebite.h</li>
</ul>

<h3>Server Files</h3>
<ul>
   <li>server_main.cpp</li>
   <li>testserverframework.cpp / testserverframework.h</li>
   <li>testserversnakebite.cpp / testserversnakebite.h</li>
</ul>

<hr>[Next: @ref Plugins ]


@page Plugins Creating Plugins
[To be written]

<hr>[Next: @ref Installation ]


@page Installation Installation
[To be written]

<h2>Dependencies</h2>
The framework uses <a href="http://www.gnu.org/software/commoncpp/">"Common C++"</a>. And the testapplication uses SDL, SDL_image, SDL_ttf.

<hr>[Next: @ref Misc ]





@page Misc Miscellaneous
<h2>Wordlist</h2>
- @anchor UniqueFrameworkID <b> Unique object id </b>: In the server framework of Ganef, every data entity (every object of a class derived from ServerData) will be given a unique id (unsigned integer 32 bit). This id will be used to uniquely identify the object, both on the server and on the client.
- @anchor MainLoop <b> Main loop</b>: most games have some method containing a while-loop where all the game-related things are done. This would on the client often include: (process any user input) (get any data sent from the server) (draw the gameworld to the screen). On the server it could include: (get and process any actions sent from clients) (integrate the gameworld with time elapsed since last iteration) (send any updates to clients).


*/

---