KDE 4.2 API Reference libkdegames/kgame
KGame Class Reference
#include <KGame/KGame>
Detailed Description
The main KDE game object.The KGame class is the central game object. A game basically consists of following features:
- Player handling (add, remove,...)
- Game status (end,start,pause,...)
- load/save
- Move (and message) handling
- nextPlayer and gameOver()
- Network connection (for KGameNetwork)
Example:
Definition at line 60 of file kgame.h.
Public Types | |
| enum | GamePolicy { PolicyUndefined = 0, PolicyClean = 1, PolicyDirty = 2, PolicyLocal = 3 } |
| enum | GameStatus { Init = 0, Run = 1, Pause = 2, End = 3, Abort = 4, SystemPause = 5, Intro = 6, UserStatus = 7 } |
| typedef QList< KPlayer * > | KGamePlayerList |
Signals | |
| void | signalClientJoinedGame (quint32 clientid, KGame *me) |
| void | signalClientLeftGame (int clientID, int oldgamestatus, KGame *me) |
| void | signalGameOver (int status, KPlayer *current, KGame *me) |
| void | signalLoad (QDataStream &stream) |
| void | signalLoadError (QDataStream &stream, bool network, int cookie, bool &result) |
| void | signalLoadPrePlayers (QDataStream &stream) |
| void | signalMessageUpdate (int msgid, quint32 receiver, quint32 sender) |
| void | signalNetworkData (int msgid, const QByteArray &buffer, quint32 receiver, quint32 sender) |
| void | signalPlayerJoinedGame (KPlayer *player) |
| void | signalPlayerLeftGame (KPlayer *player) |
| void | signalPropertyChanged (KGamePropertyBase *property, KGame *me) |
| void | signalReplacePlayerIO (KPlayer *player, bool *remove) |
| void | signalSave (QDataStream &stream) |
| void | signalSavePrePlayers (QDataStream &stream) |
Public Member Functions | |
| bool | activatePlayer (KPlayer *player) |
| bool | addPlayer (KPlayer *newplayer) |
| bool | addProperty (KGamePropertyBase *data) |
| virtual KPlayer * | createPlayer (int rtti, int io, bool isvirtual) |
| KGamePropertyHandler * | dataHandler () const |
| virtual void | Debug () |
| KPlayer * | findPlayer (quint32 id) const |
| KGamePropertyBase * | findProperty (int id) const |
| KGameSequence * | gameSequence () const |
| int | gameStatus () const |
| bool | inactivatePlayer (KPlayer *player) |
| const KGamePlayerList * | inactivePlayerList () const |
| KGamePlayerList * | inactivePlayerList () |
| bool | isRunning () const |
| KGame (int cookie=42, QObject *parent=0) | |
| virtual bool | load (const QString &filename, bool reset=true) |
| virtual bool | load (QDataStream &stream, bool reset=true) |
| int | maxPlayers () const |
| uint | minPlayers () const |
| virtual void | networkTransmission (QDataStream &stream, int msgid, quint32 receiver, quint32 sender, quint32 clientID) |
| virtual KPlayer * | nextPlayer (KPlayer *last, bool exclusive=true) |
| uint | playerCount () const |
| void | playerDeleted (KPlayer *player) |
| const KGamePlayerList * | playerList () const |
| KGamePlayerList * | playerList () |
| GamePolicy | policy () const |
| KRandomSequence * | random () const |
| bool | removePlayer (KPlayer *player) |
| virtual bool | reset () |
| virtual bool | save (const QString &filename, bool saveplayers=true) |
| virtual bool | save (QDataStream &stream, bool saveplayers=true) |
| bool | sendGroupMessage (const QString &msg, int msgid, quint32 sender, const QString &group) |
| bool | sendGroupMessage (int msg, int msgid, quint32 sender, const QString &group) |
| bool | sendGroupMessage (const QDataStream &msg, int msgid, quint32 sender, const QString &group) |
| bool | sendGroupMessage (const QByteArray &msg, int msgid, quint32 sender, const QString &group) |
| virtual bool | sendPlayerInput (QDataStream &msg, KPlayer *player, quint32 sender=0) |
| bool | sendPlayerProperty (int msgid, QDataStream &s, quint32 playerId) |
| void | setGameSequence (KGameSequence *sequence) |
| void | setGameStatus (int status) |
| void | setMaxPlayers (uint maxnumber) |
| void | setMinPlayers (uint minnumber) |
| void | setPolicy (GamePolicy p, bool recursive=true) |
| virtual bool | systemPlayerInput (QDataStream &msg, KPlayer *player, quint32 sender=0) |
| virtual | ~KGame () |
Protected Slots | |
| void | emitSignal (KGamePropertyBase *me) |
| virtual void | prepareNext () |
| void | sendProperty (int msgid, QDataStream &stream, bool *sent) |
| void | slotClientConnected (quint32 clientId) |
| void | slotClientDisconnected (quint32 clientId, bool broken) |
| void | slotServerDisconnected () |
Protected Member Functions | |
| virtual int | checkGameOver (KPlayer *player) |
| void | deleteInactivePlayers () |
| void | deletePlayers () |
| virtual bool | loadgame (QDataStream &stream, bool network, bool reset) |
| KPlayer * | loadPlayer (QDataStream &stream, bool isvirtual=false) |
| virtual void | negotiateNetworkGame (quint32 clientID) |
| virtual void | newPlayersJoin (KGamePlayerList *oldplayer, KGamePlayerList *newplayer, QList< int > &inactivate) |
| virtual bool | playerInput (QDataStream &msg, KPlayer *player)=0 |
| KPlayer * | playerInputFinished (KPlayer *player) |
| virtual bool | savegame (QDataStream &stream, bool network, bool saveplayers) |
| void | savePlayer (QDataStream &stream, KPlayer *player) |
| void | savePlayers (QDataStream &stream, KGamePlayerList *list=0) |
| void | syncRandom () |
| bool | systemActivatePlayer (KPlayer *player) |
| bool | systemAddPlayer (KPlayer *newplayer) |
| bool | systemInactivatePlayer (KPlayer *player) |
| void | systemRemovePlayer (KPlayer *player, bool deleteit) |
Member Typedef Documentation
| typedef QList<KPlayer*> KGame::KGamePlayerList |
Member Enumeration Documentation
| enum KGame::GamePolicy |
The policy of the property.
This can be PolicyClean (setVale uses send), PolicyDirty (setValue uses changeValue) or PolicyLocal (setValue uses setLocal).
A "clean" policy means that the property is always the same on every client. This is achieved by calling send which actually changes the value only when the message from the MessageServer is received.
A "dirty" policy means that as soon as setValue is called the property is changed immediately. And additionally sent over network. This can sometimes lead to bugs as the other clients do not immediately have the same value. For more information see changeValue.
PolicyLocal means that a KGameProperty behaves like ever "normal" variable. Whenever setValue is called (e.g. using "=") the value of the property is changes immediately without sending it over network. You might want to use this if you are sure that all clients set the property at the same time.
| enum KGame::GameStatus |
Constructor & Destructor Documentation
| KGame::KGame | ( | int | cookie = 42, |
|
| QObject * | parent = 0 | |||
| ) | [explicit] |
Member Function Documentation
| bool KGame::activatePlayer | ( | KPlayer * | player | ) |
| bool KGame::addPlayer | ( | KPlayer * | newplayer | ) |
Note that KPlayer::save must be implemented properly, as well as KPlayer::rtti This will only send a message to all clients.
The player is _not_ added directly! See also playerInput which will be called as soon as the player really has been added.
Note that an added player will first get into a "queue" and won't be in the game. It will be added to the game as soon as systemAddPlayer is called what will happen as soon as IdAddPlayer is received.
Note: you probably want to connect to signalPlayerJoinedGame for further initialization!
- Parameters:
-
newplayer The player you want to add. KGame will send a message to all clients and add the player using systemAddPlayer
| bool KGame::addProperty | ( | KGamePropertyBase * | data | ) |
| int KGame::checkGameOver | ( | KPlayer * | player | ) | [protected, virtual] |
- Deprecated:
- Use KGameSequence instead.
- Parameters:
-
player the player who made the last move
- Returns:
- anything else but 0 is considered as game over
| KPlayer * KGame::createPlayer | ( | int | rtti, | |
| int | io, | |||
| bool | isvirtual | |||
| ) | [virtual] |
This virtual function is called if the KGame needs to create a new player.
This happens only over a network and with load/save. Doing nothing will create a default KPlayer. If you want to have your own player you have to create one with the given rtti here. Note: If your game uses a player class derived from KPlayer you MUST override this function and create your player here. Otherwise the game will crash. Example:
KPlayer *MyGame::createPlayer(int rtti,int io,bool isvirtual) { KPlayer *player=new MyPlayer; if (!isvirtual) // network player ? { // Define something like this to add the IO modules createIO(player,(KGameIO::IOMode)io); } return player; }
- Parameters:
-
rtti is the type of the player (0 means default KPlayer) io is the 'or'ed rtti of the KGameIO's isvirtual true if player is virtual
| KGamePropertyHandler * KGame::dataHandler | ( | ) | const |
| void KGame::Debug | ( | ) | [virtual] |
| void KGame::emitSignal | ( | KGamePropertyBase * | me | ) | [protected, slot] |
| KPlayer * KGame::findPlayer | ( | quint32 | id | ) | const |
| KGamePropertyBase * KGame::findProperty | ( | int | id | ) | const |
| KGameSequence * KGame::gameSequence | ( | ) | const |
| int KGame::gameStatus | ( | ) | const |
| bool KGame::inactivatePlayer | ( | KPlayer * | player | ) |
| const KGame::KGamePlayerList * KGame::inactivePlayerList | ( | ) | const |
The same as inactivePlayerList but returns a const pointer.
| KGame::KGamePlayerList * KGame::inactivePlayerList | ( | ) |
| bool KGame::isRunning | ( | ) | const |
| bool KGame::load | ( | const QString & | filename, | |
| bool | reset = true | |||
| ) | [virtual] |
| bool KGame::load | ( | QDataStream & | stream, | |
| bool | reset = true | |||
| ) | [virtual] |
Load a saved game, from file OR network.
This function has to be overwritten or you need to connect to the load signal if you have game data other than KGameProperty. For file load you should reset() the game before any load attempt to make sure you load into an clear state.
- Parameters:
-
stream a data stream where you can stream the game from reset - shall the game be reset before loading
- Returns:
- true?
| bool KGame::loadgame | ( | QDataStream & | stream, | |
| bool | network, | |||
| bool | reset | |||
| ) | [protected, virtual] |
Load a saved game, from file OR network.
Internal. Warning: loadgame must not rely that all players all already activated. Actually the network will activate a player AFTER the loadgame only. This is not true anymore. But be careful anyway.
- Parameters:
-
stream a data stream where you can stream the game from network is it a network call -> make players virtual reset shall the game be reset before loading
- Returns:
- true?
| KPlayer * KGame::loadPlayer | ( | QDataStream & | stream, | |
| bool | isvirtual = false | |||
| ) | [protected] |
| int KGame::maxPlayers | ( | ) | const |
| uint KGame::minPlayers | ( | ) | const |
| void KGame::negotiateNetworkGame | ( | quint32 | clientID | ) | [protected, virtual] |
This member function will transmit e.g.
all players to that client, as well as all properties of these players (at least if they have been added by KPlayer::addProperty) so that the client will finally have the same status as the master. You want to overwrite this function if you expand KGame by any properties which have to be known by all clients.
Only the ADMIN is allowed to call this.
- Parameters:
-
clientID The ID of the message client which has connected
| void KGame::networkTransmission | ( | QDataStream & | stream, | |
| int | msgid, | |||
| quint32 | receiver, | |||
| quint32 | sender, | |||
| quint32 | clientID | |||
| ) | [virtual] |
This will either forward an incoming message to a specified player (see KPlayer::networkTransmission) or handle the message directly (e.g.
if msgif==IdRemovePlayer it will remove the (in the stream) specified player). If both is not possible (i.e. the message is user specified data) the signal signalNetworkData is emitted.
This emits signalMessageUpdate before doing anything with the message. You can use this signal when you want to be notified about an update/change.
- Parameters:
-
msgid Specifies the kind of the message. See messages.txt for further information stream The message that is being sent receiver The is of the player this message is for. 0 For broadcast. sender clientID the client from which we received the transmission - hardly used
Implements KGameNetwork.
| virtual void KGame::newPlayersJoin | ( | KGamePlayerList * | oldplayer, | |
| KGamePlayerList * | newplayer, | |||
| QList< int > & | inactivate | |||
| ) | [inline, protected, virtual] |
This virtual function can be overwritten for your own player management.
It is called when a new game connects to an existing network game or to the network master. In case you do not want all players of both games to be present in the new network game, you can deactivate players here. This is of particular importance if you have a game with fixed number of player like e.g. chess. A network connect needs to disable one player of each game to make sense.
Not overwriting this function will activate a default behaviour which will deactivate players until the maxPlayers() numebr is reached according to the KPlayer::networkPriority() value. Players with a low value will be kicked out first. With equal priority players of the new client will leave first. This means, not setting this value and not overwriting this function will never allow a chess game to add client players!!! On the other hand setting one player of each game to a networkPriorty of say 10, already does most of the work for you.
The parameters of this function are the playerlist of the network game, which is playerList(). The second argument is the player list of the new client who wants to join and the third argument serves as return parameter. All player ID's which are written into this list will be removed from the created game. You do this by an
inactivate.append(player->id());
- Parameters:
-
oldplayer - the list of the network players newplayer - the list of the client players inactivate - the value list of ids to be deactivated
| uint KGame::playerCount | ( | ) | const |
| void KGame::playerDeleted | ( | KPlayer * | player | ) |
| virtual bool KGame::playerInput | ( | QDataStream & | msg, | |
| KPlayer * | player | |||
| ) | [protected, pure virtual] |
A player input occurred.
This is the most important function as the given message will contain the current move made by the given player. Note that you HAVE to overwrite this function. Otherwise your game makes no sense at all. Generally you have to return TRUE in this function. Only then the game sequence is proceeded by calling playerInputFinished which in turn will check for game over or the next player However, if you have a delayed move, because you e.g. move a card or a piece you want to return FALSE to pause the game sequence and then manually call playerInputFinished to resume it. Example:
bool MyClass::playerInput(QDataStream &msg,KPlayer *player) { qint32 move; msg >> move; kDebug() << " Player" << player->id() << "moved to" << move; return true; }
- Parameters:
-
msg the move message player the player who did the move
- Returns:
- true - input ready, false: input manual
Called after the player input is processed by the game.
Here the checks for game over and nextPlayer (in the case of turn base games) are processed. Call this manually if you have a delayed move, i.e. your playerInput function returns FALSE. If it returns true you need not do anything here.
- Returns:
- the current player
| const KGame::KGamePlayerList * KGame::playerList | ( | ) | const |
| KGame::KGamePlayerList * KGame::playerList | ( | ) |
| KGame::GamePolicy KGame::policy | ( | ) | const |
| void KGame::prepareNext | ( | ) | [protected, virtual, slot] |
| KRandomSequence * KGame::random | ( | ) | const |
| bool KGame::removePlayer | ( | KPlayer * | player | ) | [inline] |
| bool KGame::reset | ( | ) | [virtual] |
| bool KGame::save | ( | const QString & | filename, | |
| bool | saveplayers = true | |||
| ) | [virtual] |
| bool KGame::save | ( | QDataStream & | stream, | |
| bool | saveplayers = true | |||
| ) | [virtual] |
| bool KGame::savegame | ( | QDataStream & | stream, | |
| bool | network, | |||
| bool | saveplayers | |||
| ) | [protected, virtual] |
Save a game, to file OR network.
Internal.
- Parameters:
-
stream a data stream where you can stream the game from network is it a call from the network or from a file (unused but informative) saveplayers shall the players be saved too (should be TRUE)
- Returns:
- true?
| void KGame::savePlayer | ( | QDataStream & | stream, | |
| KPlayer * | player | |||
| ) | [protected] |
Prepare a player for being added.
Put all data about a player into the stream so that it can be sent to the KGameCommunicationServer using addPlayer (e.g.)
This function ensures that the code for adding a player is the same in addPlayer as well as in negotiateNetworkGame
- Parameters:
-
stream is the stream to add the player player The player to add
| void KGame::savePlayers | ( | QDataStream & | stream, | |
| KGamePlayerList * | list = 0 | |||
| ) | [protected] |
Save the player list to a stream.
Used for network game and load/save. Can be overwritten if you know what you are doing
- Parameters:
-
stream is the stream to save the player ot list the optional list is the player list to be saved, default is playerList()
| bool KGame::sendGroupMessage | ( | int | msg, | |
| int | msgid, | |||
| quint32 | sender, | |||
| const QString & | group | |||
| ) |
| bool KGame::sendGroupMessage | ( | const QDataStream & | msg, | |
| int | msgid, | |||
| quint32 | sender, | |||
| const QString & | group | |||
| ) |
| bool KGame::sendGroupMessage | ( | const QByteArray & | msg, | |
| int | msgid, | |||
| quint32 | sender, | |||
| const QString & | group | |||
| ) |
See KGameNetwork::sendMessage.
Send a network message msg with a given message ID msgid to all players of a given group (see KPlayer::group)
- Parameters:
-
msg the message which will be send. See messages.txt for contents msgid an id for this message sender the id of the sender group the group of the receivers
- Returns:
- true if worked
| bool KGame::sendPlayerInput | ( | QDataStream & | msg, | |
| KPlayer * | player, | |||
| quint32 | sender = 0 | |||
| ) | [virtual] |
Called by KPlayer to send a player input to the KMessageServer.
| bool KGame::sendPlayerProperty | ( | int | msgid, | |
| QDataStream & | s, | |||
| quint32 | playerId | |||
| ) |
This is called by KPlayer::sendProperty only! Internal function!
| void KGame::sendProperty | ( | int | msgid, | |
| QDataStream & | stream, | |||
| bool * | sent | |||
| ) | [protected, slot] |
| void KGame::setGameSequence | ( | KGameSequence * | sequence | ) |
Set a new KGameSequence to control player management.
By default KGame uses a normal KGameSequence object. You might want to subclass that and provide your own object.
The previous sequence will get deleted.
- Parameters:
-
sequence The new game sequence object. KGame takes ownership and will delete it on destruction!
| void KGame::setGameStatus | ( | int | status | ) |
| void KGame::setMaxPlayers | ( | uint | maxnumber | ) |
| void KGame::setMinPlayers | ( | uint | minnumber | ) |
| void KGame::setPolicy | ( | GamePolicy | p, | |
| bool | recursive = true | |||
| ) |
| void KGame::signalClientJoinedGame | ( | quint32 | clientid, | |
| KGame * | me | |||
| ) | [signal] |
Is emmited after a client is successfully connected to the game.
The client id is the id of the new game client. An easy way to check whether that's us is
if (clientid==gameid()) .. // we joined else ... // someone joined the game
- Parameters:
-
clientid - The id of the new client me - our game pointer
| void KGame::signalClientLeftGame | ( | int | clientID, | |
| int | oldgamestatus, | |||
| KGame * | me | |||
| ) | [signal] |
This signal is emitted after a network partner left the game (either by a broken connection or voluntarily).
All changes to the network players have already be done. If there are not enough players left, the game might have been paused. To check this you get the old gamestatus before the disconnection as argument here. The id of the client who left the game allows to distinguish who left the game. If it is 0, the server disconnected and you were a client which has been switched back to local play. You can use this signal to, e.g. set some menus back to local player when they were network before.
- Parameters:
-
clientID - 0:server left, otherwise the client who left oldgamestatus - the gamestatus before the loss me - our game pointer
| void KGame::signalGameOver | ( | int | status, |
| KPlayer * | current, | ||