libkdegames/kgame

KGame Class Reference

#include <kgame.h>

Inheritance diagram for KGame:

[legend]

List of all members.

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:

 KGame *game=new KGame;

Definition at line 58 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	signalReplacePlayerIO (KPlayer player, bool remove)
void	signalLoadPrePlayers (QDataStream &stream)
void	signalLoad (QDataStream &stream)
void	signalSavePrePlayers (QDataStream &stream)
void	signalSave (QDataStream &stream)
void	signalLoadError (QDataStream &stream, bool network, int cookie, bool &result)
void	signalNetworkData (int msgid, const QByteArray &buffer, quint32 receiver, quint32 sender)
void	signalMessageUpdate (int msgid, quint32 receiver, quint32 sender)
void	signalPlayerLeftGame (KPlayer *player)
void	signalPlayerJoinedGame (KPlayer *player)
void	signalPropertyChanged (KGamePropertyBase property, KGame me)
void	signalGameOver (int status, KPlayer current, KGame me)
void	signalClientJoinedGame (quint32 clientid, KGame *me)
void	signalClientLeftGame (int clientID, int oldgamestatus, KGame *me)
Public Member Functions
	KGame (int cookie=42, QObject *parent=0)
virtual	~KGame ()
virtual void	Debug ()
KGamePlayerList *	playerList ()
const KGamePlayerList *	playerList () const
KGamePlayerList *	inactivePlayerList ()
const KGamePlayerList *	inactivePlayerList () const
KRandomSequence *	random () const
KGameSequence *	gameSequence () const
bool	isRunning () const
KPlayer *	findPlayer (quint32 id) const
void	setGameSequence (KGameSequence *sequence)
bool	addPlayer (KPlayer *newplayer)
bool	removePlayer (KPlayer *player)
void	playerDeleted (KPlayer *player)
bool	activatePlayer (KPlayer *player)
bool	inactivatePlayer (KPlayer *player)
void	setMaxPlayers (uint maxnumber)
int	maxPlayers () const
void	setMinPlayers (uint minnumber)
uint	minPlayers () const
uint	playerCount () const
virtual KPlayer *	nextPlayer (KPlayer *last, bool exclusive=true)
virtual bool	sendPlayerInput (QDataStream &msg, KPlayer *player, quint32 sender=0)
virtual bool	systemPlayerInput (QDataStream &msg, KPlayer *player, quint32 sender=0)
virtual KPlayer *	createPlayer (int rtti, int io, bool isvirtual)
virtual bool	load (QDataStream &stream, bool reset=true)
virtual bool	load (const QString &filename, bool reset=true)
virtual bool	save (QDataStream &stream, bool saveplayers=true)
virtual bool	save (const QString &filename, bool saveplayers=true)
virtual bool	reset ()
int	gameStatus () const
void	setGameStatus (int status)
bool	addProperty (KGamePropertyBase *data)
bool	sendPlayerProperty (int msgid, QDataStream &s, quint32 playerId)
KGamePropertyBase *	findProperty (int id) const
void	setPolicy (GamePolicy p, bool recursive=true)
GamePolicy	policy () const
bool	sendGroupMessage (const QByteArray &msg, int msgid, quint32 sender, const QString &group)
bool	sendGroupMessage (const QDataStream &msg, int msgid, quint32 sender, const QString &group)
bool	sendGroupMessage (int msg, int msgid, quint32 sender, const QString &group)
bool	sendGroupMessage (const QString &msg, int msgid, quint32 sender, const QString &group)
virtual void	networkTransmission (QDataStream &stream, int msgid, quint32 receiver, quint32 sender, quint32 clientID)
KGamePropertyHandler *	dataHandler () const
Protected Slots
void	sendProperty (int msgid, QDataStream &stream, bool *sent)
void	emitSignal (KGamePropertyBase *me)
virtual void	prepareNext ()
void	slotClientConnected (quint32 clientId)
void	slotClientDisconnected (quint32 clientId, bool broken)
void	slotServerDisconnected ()
Protected Member Functions
virtual bool	playerInput (QDataStream &msg, KPlayer *player)=0
KPlayer *	playerInputFinished (KPlayer *player)
virtual void	newPlayersJoin (KGamePlayerList oldplayer, KGamePlayerList newplayer, QList< int > &inactivate)
void	savePlayers (QDataStream &stream, KGamePlayerList *list=0)
void	savePlayer (QDataStream &stream, KPlayer *player)
KPlayer *	loadPlayer (QDataStream &stream, bool isvirtual=false)
bool	systemInactivatePlayer (KPlayer *player)
bool	systemActivatePlayer (KPlayer *player)
bool	systemAddPlayer (KPlayer *newplayer)
void	systemRemovePlayer (KPlayer *player, bool deleteit)
virtual void	negotiateNetworkGame (quint32 clientID)
void	syncRandom ()
void	deletePlayers ()
void	deleteInactivePlayers ()
virtual int	checkGameOver (KPlayer *player)
virtual bool	loadgame (QDataStream &stream, bool network, bool reset)
virtual bool	savegame (QDataStream &stream, bool network, bool saveplayers)

Member Typedef Documentation

typedef QList<KPlayer*> KGame::KGamePlayerList

Definition at line 63 of file kgame.h.

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.

Enumerator:

PolicyUndefined
PolicyClean
PolicyDirty
PolicyLocal

Definition at line 86 of file kgame.h.

enum KGame::GameStatus

Game status - Use this to Control the game flow.

The KGame e.g. sets the status to Pause when you have less player than the minimum amount

Enumerator:

Init
Run
Pause
End
Abort
SystemPause
Intro
UserStatus

Definition at line 116 of file kgame.h.

Constructor & Destructor Documentation

KGame::KGame	(	int	cookie = `42`,
		QObject *	parent = `0`
	)			`[explicit]`

Create a KGame object.

The cookie is used to identify your game in load/save and network operations. Change this between games.

Definition at line 82 of file kgame.cpp.

KGame::~KGame ( ) [virtual]

Destructs the game.

Definition at line 119 of file kgame.cpp.

Member Function Documentation

void KGame::Debug ( ) [virtual]

Gives debug output of the game status.

Reimplemented from KGameNetwork.

Definition at line 1251 of file kgame.cpp.

KGame::KGamePlayerList * KGame::playerList ( )

Returns a list of all active players.

Returns:: the list of players

Definition at line 702 of file kgame.cpp.

const KGame::KGamePlayerList * KGame::playerList ( ) const

The same as playerList but returns a const pointer.

Definition at line 705 of file kgame.cpp.

KGame::KGamePlayerList * KGame::inactivePlayerList ( )

Returns a list of all inactive players.

Returns:: the list of players

Definition at line 696 of file kgame.cpp.

const KGame::KGamePlayerList * KGame::inactivePlayerList ( ) const

The same as inactivePlayerList but returns a const pointer.

Definition at line 699 of file kgame.cpp.

KRandomSequence * KGame::random ( ) const

Returns a pointer to the game's KRandomSequence.

This sequence is identical for all network players!

Returns:: KRandomSequence pointer

Definition at line 708 of file kgame.cpp.

KGameSequence * KGame::gameSequence ( ) const

Returns:: The KGameSequence object that is currently in use.

See also:: setGameSequence

Definition at line 812 of file kgame.cpp.

bool KGame::isRunning ( ) const

Is the game running.

Returns:: true/false

Definition at line 689 of file kgame.cpp.

KPlayer * KGame::findPlayer ( quint32 id ) const

Returns the player object for a given player id.

Parameters:

Player id

Returns:: player object

Definition at line 382 of file kgame.cpp.

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!

Definition at line 802 of file kgame.cpp.

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

Definition at line 408 of file kgame.cpp.

bool KGame::removePlayer ( KPlayer * player ) [inline]

Sends a message over the network, msgid=IdRemovePlayer.

As soon as this message is received by networkTransmission systemRemovePlayer is called and the player is removed.

Definition at line 218 of file kgame.h.

void KGame::playerDeleted ( KPlayer * player )

Called by the destructor of KPlayer to remove itself from the game.

Definition at line 491 of file kgame.cpp.

bool KGame::activatePlayer ( KPlayer * player )

sends activate player: internal use only?

Definition at line 630 of file kgame.cpp.

bool KGame::inactivatePlayer ( KPlayer * player )

sends inactivate player: internal use only?

Definition at line 580 of file kgame.cpp.

void KGame::setMaxPlayers ( uint maxnumber )

Set the maximal number of players.

After this is reached no more players can be added. You must be ADMIN to call this (

See also:: isAdmin).

Parameters:

maxnumber

maximal number of players

Definition at line 671 of file kgame.cpp.

int KGame::maxPlayers ( ) const

What is the maximal number of players?

Returns:: maximal number of players

Definition at line 680 of file kgame.cpp.

void KGame::setMinPlayers ( uint minnumber )

Set the minimal number of players.

A game can not be started with less player resp. is paused when already running. You must be ADMIN to call this (see isAdmin)!

Parameters:

minnumber

minimal number of players

Definition at line 674 of file kgame.cpp.

uint KGame::minPlayers ( ) const

What is the minimal number of players?

Returns:: minimal number of players

Definition at line 677 of file kgame.cpp.

uint KGame::playerCount ( ) const

Returns how many players are plugged into the game.

Returns:: number of players

Definition at line 683 of file kgame.cpp.

KPlayer * KGame::nextPlayer	(	KPlayer *	last,
		bool	exclusive = `true`
	)			`[virtual]`

Deprecated:: Use KGameSequence::nextPlayer instead

Definition at line 826 of file kgame.cpp.

bool KGame::sendPlayerInput	(	QDataStream &	msg,
		KPlayer *	player,
		quint32	sender = `0`
	)			`[virtual]`

Called by KPlayer to send a player input to the KMessageServer.

Definition at line 712 of file kgame.cpp.

bool KGame::systemPlayerInput	(	QDataStream &	msg,
		KPlayer *	player,
		quint32	sender = `0`
	)			`[virtual]`

Called when a player input arrives from KMessageServer.

Calls prepareNext (using QTimer::singleShot) if gameOver() returns 0. This function should normally not be used outside KGame. It could be made non-virtual,protected in a later version. At the moment it is a virtual function to give you more control over KGame.

For documentation see playerInput.

Definition at line 730 of file kgame.cpp.

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

Definition at line 345 of file kgame.cpp.

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?

Definition at line 169 of file kgame.cpp.

bool KGame::load	(	const QString &	filename,
		bool	reset = `true`
	)			`[virtual]`

Same as above function but with different parameters.

Parameters:

	filename	- the filename of the file to be opened
	reset	- shall the game be reset before loading

Returns:: true?

Definition at line 152 of file kgame.cpp.

bool KGame::save	(	QDataStream &	stream,
		bool	saveplayers = `true`
	)			`[virtual]`

Save a game to a file OR to network.

Otherwise the same as the load function

Parameters:

	stream	a data stream to load the game from
	saveplayers	If true then all players wil be saved too

Returns:: true?

Definition at line 280 of file kgame.cpp.

bool KGame::save	(	const QString &	filename,
		bool	saveplayers = `true`
	)			`[virtual]`

Same as above function but with different parameters.

Parameters:

	filename	the filename of the file to be saved
	saveplayers	If true then all players wil be saved too

Returns:: true?

Definition at line 263 of file kgame.cpp.

bool KGame::reset ( ) [virtual]

Resets the game, i.e.

puts it into a state where everything can be started from, e.g. a load game Right now it does only need to delete all players

Returns:: true on success

Definition at line 130 of file kgame.cpp.

int KGame::gameStatus ( ) const

returns the game status, ie running,pause,ended,.

Returns:: game status

Definition at line 686 of file kgame.cpp.

void KGame::setGameStatus ( int status )

sets the game status

Parameters:

status

the new status

Definition at line 835 of file kgame.cpp.

bool KGame::addProperty ( KGamePropertyBase * data )

docu: see KPlayer

Definition at line 1443 of file kgame.cpp.

bool KGame::sendPlayerProperty	(	int	msgid,
		QDataStream &	s,
		quint32	playerId
	)

This is called by KPlayer::sendProperty only! Internal function!

Definition at line 1446 of file kgame.cpp.

KGamePropertyBase * KGame::findProperty ( int id ) const

This function allows to find the pointer to a player property when you know it's id.

Definition at line 1463 of file kgame.cpp.

void KGame::setPolicy	(	GamePolicy	p,
		bool	recursive = `true`
	)

Changes the consistency policy of a property.

The GamePolicy is one of PolicyClean (default), PolicyDirty or PolicyLocal.

It is up to you to decide how you want to work.

Definition at line 1470 of file kgame.cpp.

KGame::GamePolicy KGame::policy ( ) const

Returns:: The default policy of the property

Definition at line 1466 of file kgame.cpp.

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

Definition at line 1416 of file kgame.cpp.

bool KGame::sendGroupMessage	(	const QDataStream &	msg,
		int	msgid,
		quint32	sender,
		const QString &	group
	)

Definition at line 1432 of file kgame.cpp.

bool KGame::sendGroupMessage	(	int	msg,
		int	msgid,
		quint32	sender,
		const QString &	group
	)

bool KGame::sendGroupMessage	(	const QString &	msg,
		int	msgid,
		quint32	sender,
		const QString &	group
	)

Definition at line 1435 of file kgame.cpp.

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.

Definition at line 846 of file kgame.cpp.

KGamePropertyHandler * KGame::dataHandler ( ) const

Returns a pointer to the KGame property handler.

Definition at line 692 of file kgame.cpp.

void KGame::sendProperty	(	int	msgid,
		QDataStream &	stream,
		bool *	sent
	)			`[protected, slot]`

Called by KGamePropertyHandler only! Internal function!

Definition at line 1449 of file kgame.cpp.

void KGame::emitSignal ( KGamePropertyBase * me ) [protected, slot]

Called by KGamePropertyHandler only! Internal function!

Definition at line 1458 of file kgame.cpp.

void KGame::prepareNext ( ) [protected, virtual, slot]

Deprecated:: Use KGameSequence::prepareNext() instead

Definition at line 817 of file kgame.cpp.

void KGame::slotClientConnected ( quint32 clientId ) [protected, slot]

Calls negotiateNetworkGame() See KGameNetwork::signalClientConnected.

Definition at line 1264 of file kgame.cpp.

void KGame::slotClientDisconnected	(	quint32	clientId,
		bool	broken
	)			`[protected, slot]`

This slot is called whenever the connection to a client is lost (ie the signal KGameNetwork::signalClientDisconnected is emitted) and will remove the players from that client.

Parameters:

	clientId	The client the connection has been lost to
	broken	(ignore this - not used)

Definition at line 1340 of file kgame.cpp.

void KGame::slotServerDisconnected ( ) [protected, slot]

This slot is called whenever the connection to the server is lost (ie the signal KGameNetwork::signalConnectionBroken is emitted) and will switch to local game mode.

Definition at line 1272 of file kgame.cpp.

void KGame::signalReplacePlayerIO	(	KPlayer *	player,
		bool *	remove
	)			`[signal]`

When a client disconnects from the game usually all players from that client are removed.

But if you use completely the KGame structure you probably don't want this. You just want to replace the KGameIO of the (human) player by a computer KGameIO. So this player continues game but is from this point on controlled by the computer.

You achieve this by connecting to this signal. It is emitted as soon as a client disconnects on all other clients. Make sure to add a new KGameIO only once! you might want to use isAdmin for this. If you added a new KGameIO set *remove=false otherwise the player is completely removed.

Parameters:

	player	The player that is about to be removed. Add your new KGameIO here - but only on one client!
	remove	Set this to FALSE if you don't want this player to be removed completely.

void KGame::signalLoadPrePlayers ( QDataStream & stream ) [signal]

The game will be loaded from the given stream.

Load from here the data which is NOT a game or player property. It is not necessary to use this signal for a full property game.

This signal is emitted before the players are loaded by KGame. See also signalLoad

You must load exactly the same data from the stream that you have saved in signalSavePrePlayers. Otherwise player loading will not work anymore.

Parameters:

stream

the load stream

void KGame::signalLoad ( QDataStream & stream ) [signal]

The game will be loaded from the given stream.

Load from here the data which is NOT a game or player property. It is not necessary to use this signal for a full property game.

Parameters:

stream

the load stream

void KGame::signalSavePrePlayers ( QDataStream & stream ) [signal]

The game will be saved to the given stream.

Fill this with data which is NOT a game or player property. It is not necessary to use this signal for a full property game.

This signal is emitted before the players are saved by KGame. See also signalSave

If you can choose between signalSavePrePlayers and signalSave then better use signalSave

Parameters:

stream

the save stream

void KGame::signalSave ( QDataStream & stream ) [signal]

The game will be saved to the given stream.

Fill this with data which is NOT a game or player property. It is not necessary to use this signal for a full property game.

Parameters:

stream

the save stream

void KGame::signalLoadError	(	QDataStream &	stream,
		bool	network,
		int	cookie,
		bool &	result
	)			`[signal]`

Is emmited if a game with a different version cookie is loaded.

Normally this should result in an error. But maybe you do support loading of older game versions. Here would be a good place to do a conversion.

Parameters:

	stream	- the load stream
	network	- true if this is a network connect. False for load game
	cookie	- the saved cookie. It differs from KGame::cookie()
	result	- set this to true if you managed to load the game

void KGame::signalNetworkData	(	int	msgid,
		const QByteArray &	buffer,
		quint32	receiver,
		quint32	sender
	)			`[signal]`

We got an user defined update message.

This is usually done by a sendData in a inherited KGame Object which defines its own methods and has to syncronise them over the network. Reaction to this is usually a call to a KGame function.

void KGame::signalMessageUpdate	(	int	msgid,
		quint32	receiver,
		quint32	sender
	)			`[signal]`

We got an network message.

this can be used to notify us that something changed. What changed can be seen in the message id. Whether this is the best possible method to do this is unclear...

void KGame::signalPlayerLeftGame ( KPlayer * player ) [signal]

a player left the game because of a broken connection or so!

Note that when this signal is emitted the player is not part of playerList anymore but the pointer is still valid. You should do some final cleanups here since the player is usually deleted after the signal is emitted.

Parameters:

player

the player who left the game

void KGame::signalPlayerJoinedGame ( KPlayer * player ) [signal]

a player joined the game

Parameters:

player

the player who joined the game

void KGame::signalPropertyChanged	(	KGamePropertyBase *	property,
		KGame *	me
	)			`[signal]`

This signal is emmited if a player property changes its value and the property is set to notify this change.

void KGame::signalGameOver	(	int	status,
		KPlayer *	current,
		KGame *	me
	)			`[signal]`

Is emitted after a call to gameOver() returns a non zero return code.

This code is forwarded to this signal as 'status'.

Parameters:

	status	the return code of gameOver()
	current	the player who did the last move
	me	a pointer to the KGame object

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,

libkdegames/kgame

KGame Class Reference

Detailed Description

Public Types

Signals

Public Member Functions

Protected Slots

Protected Member Functions

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation