Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdegames@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 407 insertions, 0 deletions

diff --git a/libkdegames/kgame/DESIGN b/libkdegames/kgame/DESIGN
new file mode 100644
index 00000000..b1c48146
--- /dev/null
+++ b/libkdegames/kgame/DESIGN
@@ -0,0 +1,407 @@
+This document tries to describe the design of KGame - the KDE multiplayer
+library.
+This document has been written by:
+ Andreas Beckermann <[email protected]>
+ M. Heni <[email protected]>
+ Burkhard Lehner <[email protected]>
+
+This document is published under the terms of the GNU FDL
+
+!!!
+Note that this is the initial version of this document and has not yet been
+aproved by all core developers (and is far from being complete)
+AB: please remove this comments as soon as all KGame hackers have read the
+document
+!!!
+
+Please refer the API documentation of every KGame class if you want up tp date
+information.
+
+
+0. Contents
+-----------
+
+1. DEFINITIONS
+1.1 Message Server
+1.2 Client or Message Client
+1.3 Master
+1.4 Admin
+1.5 Server
+1.6 Player
+
+2. Game Negotiation (M.Heni 20.05.2001)
+
+AB: 3.x is obsolete!
+3. Game Properties (Andreas Beckermann 28.07.2001) ( not yet completed )
+3.1 Using KGameProperty
+3.2 Custom Classes
+3.3 Concepts
+
+4. KGameIO (Andreas Beckermann 10.08.2001)
+
+5. Debugging (Andreas Beckermann 06.10.2001) TODO!
+5.1 KGameDebugDialog
+5.1.1 Debug KGame
+5.1.3 Debug Messages
+
+---------------------------------------------------------------------
+1. DEFINITIONS
+--------------
+
+First we have to clear some words. The main expressions used in KGame which
+need a definition are
+
+1.1 Message Server
+1.2 Client or Message Client
+1.3 Master
+1.4 Admin
+1.5 Server
+1.6 Player
+
+The most important and confusing ones are Master, Admin and Server. We make
+quite big differerences between those inside KGame.
+
+1.1 Message Server:
+-------------------
+A game has always exactly one object of this class, for local games as well as
+for network games. For network games, this object can be on one of the users
+processes (usually inside KGame), or it can also be on an independant computer,
+that has no idea about what game is played on it.
+
+A KMessageClient object can connect to it. It's main purpose is transmitting
+messages between KMessageClient objects.
+
+The Message Server is the main communication object. It is represented by the
+class KMessageServer. Note that there is also a "Master" and a "Server" which
+both differ heavily from the Message Server!
+
+1.2 Client, Message Client:
+---------------------------
+Each process that wants to take part in the game must have a
+KMessageClient object, that is connected to the Message Server. KGame creates
+this object and connects it to the Messager Server, so that you usually don't
+need to create these of your own. Even in a local game (no network) there
+must be a message server and one message client connected to it. This is usually
+done by the KGame object itself.
+
+Each message client has a unique ID number (a positive integer value, not zero).
+The KMessageClient object, which does the communication with the Message Server
+is called "Message Client" and to simplify the use we call any KGame object (or
+even the game process) that is connected to a game (i.e. even the Master) just
+"Client".
+
+The main purpose of a Client is to connect to a Master (i.e. to a game) and to
+communicate with it. A client has always a KGame object.
+
+1.3 Master:
+-----------
+The process that contains the Message Server is called "Master". In any local
+game this is the game process. The Message Server is started by KGame using
+KGame::setMaster(true) which is automatically done on startup. The Message
+Server is deleted automatically as soon as you connect to another Master.
+So in most cases there is exactly one KGame object / Client which is Master. But
+in one case there can be no KGame object / Client that is Master - if the
+Message Server is started as an own process. This "Message-Server-only" process
+is called "Master" then, although there is no KGame object which is Master. See
+also the definition of Admin!
+
+1.4 Admin:
+----------
+One (and only one) of the Clients is the Admin. He can configure the Message
+Server and the game in general in several ways. He can limit the maximum number
+of connected message clients and can drop the connection to some other clients,
+as well as he can configure game specific ssettings (like max/min players, start
+money, ...). The Admin also initializes newly connected Clients. If the Admin
+himself disconnects, another Client becomes Admin (The Admin can himself elect
+some other Client to become Admin. He himself loses that Admin status then).
+An Admin is *alway* a KGame object. The Admin is usually the same as the Master,
+but if the Master is an own process (i.e. the Message Server has been started
+outside KGame) then Master and Admin differ. An Admin *must* be a KGame object
+while the Master doesn't have to be.
+
+1.5 Server:
+-----------
+The definition of Server differs quite much from the definition of Master.
+A Master just accepts connections and forwards messages. The Server on the other
+side checks these messages, calculates results and sends the results to the
+Clients. That means the Server does all game calculations and doesn't directly
+forward the messages from one Clients to all other Clients.
+KGamer makes it possible to write multiplayer games even without a Server. All
+Clients just send their moves to the Master which forwards them to all Clients.
+Now all Clients calculate the result.
+E.g. in a poker game a player selects two of five cards to be exchanges and
+clicks on "draw" then the client sends the message "Exchange Card-1 and Card-2"
+to the Master. A no-Server solution forwards this to all Clients, and these
+Clients exchange the cards of the player. Note that in a no-Server solution
+(you can also see it as a "every-Client-is-a-Server solution") all Clients must
+have the same random seed and must be of the same version, i.e. the result must
+be the same on all Clients.
+In a Server-Solution on the other hand the Master forwards the Message
+("Exchange Card-1 and Card-2") to the Server only. This Server now calculates
+the result, and sends the new cards back to the Client.
+Both concepts have advantages and disadvantages. It is on you - the game
+developer - to decide which way is better for you.
+E.g. the Server-Solution makes it easier for you to write games. The version
+must not necessarily be the same, you have one central computer which does the
+calcultations. The No-Server-Solution on the other hand decreases network
+traffik as the Clients just send their moves and all Clients can calculate the
+reactions. I'm sure there are a lot of advantages/disadvantages more for both
+concepts.
+
+1.6 Player:
+-----------
+A KPlayer object is always connected to a KGame object and represents a
+player that participates the game. In a network game, every KPlayer object is
+duplicated on every other KGame object connected to the message server with
+virtual KPlayer objects. So at every time in the game, every KGame object has
+the same number of KPlayer objects.
+
+
+2. Game negotiation
+-------------------
+Upon connection  of a client the admin and the client try to negotiate
+the game setup. Basically this means the game of the admin is transferred
+(saved) on the client. However, the client's players are added to the game
+as far as possible. If the addition of the client's players would add more
+players than allowed some players are inactivated. Which players are
+inactivated depends on their networkPriority(). This procedure allows
+easy replacement of players in a constant number game (e.g. chess). If
+this feature is of no interest simply keep the priorities equal (all 0)
+and the client will only add only players if the number of players is
+less or equal the maximum player number.
+
+The following is the negotiation procedure as started by the connection
+of a client. It is initiated in the negotiateNetworkGame() virtual function
+of KGame:
+
+admin:                client:
+------------          ------------
+IdSetupGame
+  QINT16 Library
+         Version
+  QINT32 Application
+         cookie
+                      IdSetupGameContinue;
+                        QValueList<int> player id's
+                        QValueList<int> network priority's
+
+IdGameLoad
+  all game data
+
+IdGameReactivate
+  QValueList<int> id's
+
+IdSyncRandom
+  int randomseed
+
+
+3. Game Properties
+------------------
+A very hard task in a network game is consistency. You have to achieve that all
+properties of the game and of all players have the same value on all clients
+every time. This is because 
+a) the user might be confused if he sees "Player has $0" on client A but 
+"Player has $10" on client B and 
+b) Often game handling depends on those values, e.g. if the example above
+happens the computer might quit the game for the Player on client A because
+he/she doesn't have enough money. But the game continues on client B. 
+Another not that easy task is the network protocol itself. You have to write
+several send() and receive() functions which apply changed values of properties
+to the local property. 
+
+KGameProperty is designed to do all of this for you. KGameProperty is
+implemented as a template so you can use it theoretically for every type of data
+- even for your self defined classes. 
+
+
+3.1 Using KGameProperty
+-----------------------
+It is basically very easy to use a KGameProperty. You first create your own
+class containing the property, e.g:
+class MyGame : public KGame
+{
+[...]
+protected:
+	KGamePropertyInt money;
+	KGamePropertyQString name;
+	KGameProperty<AntotherClass> myProperty;
+};
+KGamePropertyInt is just a typedef for KGameProperty<int> - just like
+KGamePropertyQString. Now you need to register the properties in the constructor
+of the class to the KGamePropertyHandler:
+MyGame::MyGame() : KGame(myCookie)
+{
+ money.registerData(KGamePropertyBase::IdUser+1, dataHandler(), "Money");
+ name.registerData(KGamePropertyBase::IdUser+2, this, "Name");
+ myProperty.registerData(KGamePropertyBase::IdUser+3, dataHandler(), "MyProperty");
+}
+-> You need to specify a *unique* ID. This ID must be greater than
+KGamePropertyBase::IdUser. IDs below this are reserved for KGame. Probably this
+will be changed so that you cannot use IDs below IdUser in the future. Then you
+have to specify the dataHandler(). You can also use a KGame or KPlayer pointer.
+This will automatically use KGame::dataHandler() or KPlayer::dataHandler().
+Finally you *can* provide a name for the property. This will be used for
+debugging in KGameDebugDialog. If you want to save some memory you can leave
+this out.
+Note that if you use pointers to create the properties dynamically they are
+*not* deleted automatically! You MUST delete them yourself!
+Now you can use the KGameProperty like every variable else. See also Section 
+"3.3 Concepts" for restrictions in use.
+
+3.2 Custom Classes
+------------------
+To make custom classes possible you have to implement several operators for your
+them: you need at least << and >> for QDataStream as well as "==" for your own
+class. To overload the "<<" you would e.g. do something like this:
+QDataStream& operator<<(QDataStream& stream, MyData& data)
+{
+ int type = data.type;
+ QString name = data.name;
+ stream << type << name;
+ return stream;
+}
+So you basically just have to split your class to several basic types and stream
+them.
+
+3.3 Concepts
+------------
+You can use KGameProperty basically in two completely different ways. You can
+also use a mixture of both but this is not recommended. The default behaviour
+and therefore also the recommended is the "clean" way: 
+a) Always Consistent. This means that a KGameProperty has always the same value
+on *every* client. This is achieved by using KGameProperty::send() whenever you
+want to change the value using "=". You can still use changeValue() or
+setLocal() but send() will be the default. If you use send() then the value of
+the property does *NOT* change immediately. It is just sent to the
+KMessageServer which forwards the value to all clients. As soon as the new value
+is received from the message server the KGamePropertyHandler (a collection class
+for KGameProperty) calls KGameProperty::load() and changes the value of the
+property. So the game first has to go into the event loop, where the message is
+received. This means to you that you cannot do this:
+myIntProperty = 10;
+int value = myIntProperty;
+As myIntPoperty still has the old value when "value = myIntProperty" is called.
+This might seem to be quite complex, but 
+KGamePropertyHandler::signalPropertyChanged() is emitted whenever a new value is
+assigned so you can connect to this and work immediately with the new value.
+You gain the certainty that the value is the same on every client every time.
+That will safe you a lot of time debugging!
+Another way is the "dirty" way:
+b) Not Always Consistent. Sometimes you really *want* to do something like
+myIntProperty = 10;
+int value = myIntProperty;
+but this is not possible with the default behaviour. If you call
+KGameProperty::setAlwaysConsistent(false) in the constructor (right after
+registerData()) you get another behaviour. "=" means changeValue() now.
+changeValue() also uses send() to change the value but additionally calls
+setLocal() to create a local copy of the property. This copy now has the value
+you supplied with "=" and is deleted again as soon as any value from the network
+is received. 
+
+4. KGameIO
+----------
+The class KGameIO is used to let the players communicate with the server. You
+can plug as many KGameIO objects into a player as you want, e.g. you can plug a
+KGameMouseIO and a KGameKeyIO into a player so that you can control the player
+with the mouse and the keyboard - e.g. in a breakout game. 
+You can probably see the advantage: as most of the control stuff is common in a
+lot of games you can use the same IO class in many different games with very
+small adjustments. 
+You could also put all the IO stuff directly into your KPlayer object, like
+sendBet(int money) for a poker game. But there is a major disadvantage and I'm
+very sure you don't want to use a KPlayer object for your IO stuff as soon as
+you know which disadvantage:
+KGameIO is designed to be able to switch between different IOs "on the fly". So
+you might have a KGamePlayerIO, derived from KGameIO, for your game. But now
+this player (who "owns"/uses the KGamePlayerIO) leaves the game (e.g. because he
+was a remote player). So now the game would be over for every player as one
+player is now out of order. But with KGameIO you can just let any of the
+remaining clients create a KGameComputerIO and plug this into the player. So the
+player now is controlled by the computer and the game can continue. 
+
+Think about it! You don't have to care about removing players when a player
+leaves as you can just replace it! The same works the other way round: imagine a
+game with 10 player (e.g. 5 human and 5 computer players) that has already
+started. You cannot add any further players without restarting. So if there are
+any additional player you can just call KPlayer::removeGameIO() which removes
+the IO of a computer player and then call KPlayer::addGameIO() for the same
+player which adds a GameIO for new human player. That's all!
+
+To achieve this you just have to make sure that you make *all* of your IO
+operations through a KGameIO! So instead of using MyPlayer::sendBet(int money)
+you should use something like MyIO::sendBet(). The amount of money would
+probably be calculated by the game IO itself.
+
+
+
+5. Debugging
+------------
+The general debugging concept (if there is one at all) or general debugging
+hints are not yet written. Feel free to do so
+
+5.1 KGameDebugDialog
+--------------------
+A nice way of debugging a KGame based game is the KGameDebugDialog. Basically
+all you have to do is to add something like "Debug" to your game's menu and add
+a slot like
+slotDebug()
+{
+ KGameDebugDialog* dialog = new KGameDebugDialog(mGame, this);
+ connect(dialog, SIGNAL(finished()), dialog, SLOT(slotDelayedDestruct()));
+ dialog->show();
+}
+that's it.
+You can now click on that menu entry and you get a non-modal dialog where you
+can start to debug :-)
+The dialog consist of several pages. You can easily add your own using
+KDialogBase::addVBoxPage() (for example). 
+
+5.1.1 Debug KGame
+-----------------
+The first page, "Debug KGame" shows on the left most or even all status values of
+KGame. That contains e.g.  minPlayers(), isAdmin(), gameStatus(), ...
+The right side is probably the more important one. It lists *all* KGameProperties
+which have been inserted to this KGame object (only to this KGame object - not
+the ones that have been added to the players!). Most of the status variables of
+the left side are here again as they are implemented as KGameProperty. You can
+see the name of the property (together with its ID), its value and the policy
+this property uses. Note that "unknwon" will be displayed as name of the
+property if you haven't supplied one. See KGamePropertyBase::registerData() for
+info. You probably always want to supply a name for the property to debug it
+easily. In the future there will be something like
+KGamePropertyHandler::setDebug() so that you can switch off debugging and save
+the memory of the names in a release version. 
+For as long as you use standard types for your properties (int, long, bool,
+...) you should always be able to see the value of the property. If you just see
+"unknown" then this type has not been implemented. You can connect to the signal
+KGamePropertyHandler::signalRequestValue() and supply a QString with the value
+yourself. If you do so for a standard type please also submit a bug report!
+
+Currently the dialog does *not* update automatically! So you alway have to click
+the "update" button when you want a current value. There are several reasons for
+this (and one of them is that i'm too lazy to implement the update ;)). E.g.
+often (very often) a property is just in the background - stores e.g. the
+available money in a game. But you don't want it to update whenever the value
+changes (a player receives/pays money) but only when the value on the screen
+changes.
+
+5.1.2 Debug Players
+-------------------
+This page consists of three widgets. On the very left there is a list of all
+players in the game. Only the IDs are displayed to save space. If you click one
+the other widgets are filled with content. These widgets are quite much the same
+as the ones in "Debug KGame" - the left shows the value of the functions and the
+right one displays all KProperties of a player. Not much to say here - except:
+See "Debug KGame".
+
+If you change to another player the value are also updated.
+
+5.1.3 Debug Messages
+--------------------
+This page is probably not as important as the other ones. It displays *every*
+message that is sent through the KGame object. As a KGameProperry also send
+messages you probably get a lot of them...
+You can exclude message IDs from being displayed (e.g. all game properties). 
+You can also change the sorting of the list to see all messages of a certain ID.
+The default is to sort by time (which is displayed on the left side).
+