|
|
|
This document tries to describe the design of KGame - the KDE multiplayer
|
|
|
|
library.
|
|
|
|
This document has been written by:
|
|
|
|
Andreas Beckermann <b_mann@gmx.de>
|
|
|
|
M. Heni <martin@heni-online.de>
|
|
|
|
Burkhard Lehner <Burkhard.Lehner@gmx.de>
|
|
|
|
|
|
|
|
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;
|
|
|
|
TQString 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, TQ_SIGNAL(finished()), dialog, TQ_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 TQString 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).
|
|
|
|
|