KGameProperty< type > Class Template Reference
#include <kgameproperty.h>
Inheritance diagram for KGameProperty< type >:

Detailed Description
template<class type>
class KGameProperty< type >
A class for network transparent games.
Note: The entire API documentation is obsolete!
The class KGameProperty can store any form of data and will transmit it via network whenver you call send. This makes network transparent games very easy. You first have to register the data to a KGamePropertyHandler using KGamePropertyBase::registerData (which is called by the constructor). For the KGamePropertyHandler you can use KGame::dataHandler or KPlayer::dataHandler but you can also create your own data handler.
There are several concepts you can follow when writing network games. These concepts differ completely from the way how data is transferred so you should decide which one to use. You can also mix these concepts for a single property but we do not recommend this. The concepts:
- Always Consistent (clean)
- Not Always Consistent (dirty)
- A Mixture (very dirty)
consistent (clean):
This "policy" is default. Whenever you create a KGameProperty it is always consistent. This means that consistency is the most important thing for the property. This is achieved by using send to change the value of the property. send needs a running KMessageServer and therefore MUST be plugged into a KGamePropertyHandler using either registerData or the constructor. The parent of the dataHandler must be able to send messages (see above: the message server must be running). If you use send to change the value of a property you won't see the effect immediately: The new value is first transferred to the message server which queues the message. As soon as all messages in the message server which are before the changed property have been transferred the message server delivers the new value of the KGameProperty to all clients. A QTimer::singleShot is used to queue the messages inside the KMessageServer.This means that if you do the following:
KGamePropertyInt myProperty(id, dataHandler()); myProperty.initData(0); myProperty = 10; int value = myProperty.value();
This may look quite confusing but it has a big advantage: all KGameProperty objects are ensured to have the same value on all clients in the game at every time. This way you will save you a lot of trouble as debugging can be very difficult if the value of a property changes immediately on client A but only after one or two additianal messages (function calls, status changes, ...) on client B.
The only disadvantage of this (clean) concept is that you cannot use a changed variable immediately but have to wait for the KMessageServer to change it. You probably want to use KGamePropertyHandler::signalPropertyChanged for this.
Always Consistent (dirty):
There are a lot of people who don't want to use the (sometimes quite complex) "clean" way. You can use setAlwaysConsistent to change the default behaviour of the KGameProperty. If a property is not always consistent it will use changeValue to send the property. changeValue also uses send to send the new value over network but it also uses setLocal to create a local copy of the property. This copy is created dynamically and is deleted again as soon as the next message from the network is received. To use the example above again:KGamePropertyInt myProperty(id, dataHandler()); myProperty.setAlwaysConsistent(false); myProperty.initData(0); myProperty = 10; int value = myProperty.value();
The advantage of this concept is clear: you can use a KGameProperty as every other variable as the changes value takes immediate effect. Additionally you can be sure that the value is transferred to all clients. You will usually not experience serious bugs just because you use the "dirty" way. Several events have to happen at once to get these "strange errors" which result in inconsistent properties (like "game running" on client A but "game ended/paused" on client B). But note that there is a very good reason for the existence of these different concepts of KGameProperty. I have myself experienced such a "strange error" and it took me several days to find the reason until I could fix it. So I personally recommend the "clean" way. On the other hand if you want to port a non-network game to a network game you will probably start with "dirty" properties as it is you will not have to change that much code...
Mixture (very dirty):
You can also mix the concepts above. Note that we really don't recommend this. With a mixture I mean something like this:KGamePropertyInt myProperty(id, dataHandler()); myProperty.setAlwaysConsistent(false); myProperty.initData(0); myProperty = 10; myProperty.setAlwaysConsistent(true); myProperty = 20;
KGamePropertyInt myProperty1(id1, dataHandler()); KGamePropertyInt myProperty2(id2, dataHandler()); myProperty1.initData(0); myProperty2.initData(0); myProperty1.setAlwaysConsistent(false); myProperty2.setAlwaysConsistent(true); myProperty1 = 10; myProperty2 = 20;
So the right thing to do(tm) is to decide in the constructor whether you want a "clean" or "dirty" property.
Even if you have decided for one of the concepts you still can manually follow another concept than the "policy" of your property. So if you use an always consistent KGameProperty you still can manually call changeValue as if it was not always consistent. Note that although this is also kind of a "mixture" as described above this is very useful sometimes. In contrast to the "mixture" above you don't have the problem that you don't exactly know which concept you are currently following because you used the function of the other concept only once.
classes:
If you want to use a custum class with KGameProperty you have to implement the operators << and >> for QDataStream:class Card { public: int type; int suite; }; QDataStream& operator<<(QDataStream& stream, Card& card) { Q_INT16 type = card.type; Q_INT16 suite = card.suite; s << type; s << suite; return s; } QDataStream& operator>>(QDataStream& stream, Card& card) { Q_INT16 type; Q_INT16 suite; s >> type; s >> suite; card.type = (int)type; card.suite = (int)suite; return s; } class Player : KPlayer { [...] KGameProperty<Card> mCards; };
Note: unlike most QT classes KGameProperty objects are *not* deleted automatically! So if you create an object using e.g. KGameProperty<int>* data = new KGameProperty(id, dataHandler()) you have to put a delete data into your destructor!
Definition at line 581 of file kgameproperty.h.
Public Member Functions | |
KGameProperty (int id, KGamePropertyHandler *owner) | |
KGameProperty () | |
virtual | ~KGameProperty () |
void | setValue (type v) |
bool | send (type v) |
bool | setLocal (type v) |
void | changeValue (type v) |
virtual void | save (QDataStream &stream) |
const type & | value () const |
virtual void | load (QDataStream &s) |
const type & | operator= (const type &t) |
const type & | operator= (const KGameProperty &property) |
operator type () const | |
virtual const type_info * | typeinfo () |
Constructor & Destructor Documentation
KGameProperty< type >::KGameProperty | ( | int | id, | |
KGamePropertyHandler * | owner | |||
) | [inline] |
Constructs a KGameProperty object.
A KGameProperty object will transmit any changes to the KMessageServer and then to all clients in the game (including the one that has sent the new value)
- Parameters:
-
id The id of this property. MUST be UNIQUE! Used to send and receive changes in the property of the playere automatically via network. owner The parent of the object. Must be a KGame which manages the changes made to this object, i.e. which will send the new data. Note that in contrast to most KDE/QT classes KGameProperty objects are not deleted automatically!
Definition at line 597 of file kgameproperty.h.
KGameProperty< type >::KGameProperty | ( | ) | [inline] |
This constructor does nothing.
You have to call KGamePropertyBase::registerData yourself before using the KGameProperty object.
Definition at line 604 of file kgameproperty.h.
Member Function Documentation
void KGameProperty< type >::setValue | ( | type | v | ) | [inline] |
Set the value depending on the current policy (see setConsistent).
By default KGameProperty just uses send to set the value of a property. This behaviour can be changed by using setConsistent.
- Parameters:
-
v The new value of the property
Definition at line 615 of file kgameproperty.h.
bool KGameProperty< type >::send | ( | type | v | ) | [inline] |
This function sends a new value over network.
Note that the value DOES NOT change when you call this function. This function saves the value into a QDataStream and calls sendProperty where it gets forwarded to the owner and finally the value is sent over network. The KMessageServer now sends the value to ALL clients - even the one who called this function. As soon as the value from the message server is received load is called and _then_ the value of the KGameProperty has been set.
This ensures that a KGameProperty has _always_ the same value on _every_ client in the network. Note that this means you can NOT do something like
myProperty.send(1); doSomething(myProperty);
You are informed about a value change by a singal from the parent of the property which can be deactivated by setEmittingSignal because of performance (you probably don't have to deactivate it - except you want to write a real-time game like Command&Conquer with a lot of acitvity). See emitSignal
Note that if there is no KMessageServer accessible - before the property has been registered to the KGamePropertyHandler (as it is the case e.g. before a KPlayer has been plugged into the KGame object) the property is *not* sent but set *locally* (see setLocal)!
- Parameters:
-
v The new value of the property
- Returns:
- whether the property could be sent successfully
- See also:
- setValue setLocal changeValue value
Definition at line 670 of file kgameproperty.h.
bool KGameProperty< type >::setLocal | ( | type | v | ) | [inline] |
This function sets the value of the property directly, i.e.
it doesn't send it to the network.
Int contrast to
- See also:
- you change _only_ the local value when using this function. You do _not_ change the value of any other client. You probably don't want to use this if you are using a dedicated server (which is the only "client" which is allowed to change a value) but rather want to use send().
myProperty.setLocal(1); doSomething(myProperty);
If you want to set the value locally AND send it over network you want to call changeValue!
You can also use setPolicy to set the default policy to PolicyLocal.
- See also:
- setValue send changeValue value
Definition at line 715 of file kgameproperty.h.
void KGameProperty< type >::changeValue | ( | type | v | ) | [inline] |
This function does both, change the local value and change the network value.
The value is sent over network first, then changed locally.
This function is a convenience function and just calls send followed by setLocal
Note that emitSignal is also called twice: once after setLocal and once when the value from send is received
Definition at line 744 of file kgameproperty.h.
virtual void KGameProperty< type >::save | ( | QDataStream & | stream | ) | [inline, virtual] |
Saves the object to a stream.
- Parameters:
-
stream The stream to save to
Implements KGamePropertyBase.
Definition at line 754 of file kgameproperty.h.
const type& KGameProperty< type >::value | ( | ) | const [inline] |
- Returns:
- The local value (see setLocal) if it is existing, otherwise the network value which is always consistent on every client.
Definition at line 764 of file kgameproperty.h.
virtual void KGameProperty< type >::load | ( | QDataStream & | s | ) | [inline, virtual] |
Reads from a stream and assigns the read value to this object.
This function is called automatically when a new value is received over network (i.e. it has been sent using send on this or any other client) or when a game is loaded (and maybe on some other events).
Also calls emitSignal if isEmittingSignal is TRUE.
- Parameters:
-
s The stream to read from
Implements KGamePropertyBase.
Definition at line 780 of file kgameproperty.h.
const type& KGameProperty< type >::operator= | ( | const type & | t | ) | [inline] |
This calls setValue to change the value of the property.
Note that depending on the policy (see setAlwaysConsistent) the returned value might be different from the assigned value!!
So if you use setPolicy(PolicyClean):
int a, b = 10;
myProperty = b;
a = myProperty.value();
If you use a clean policy (see setPolicy) then the returned value is the assigned value
Definition at line 807 of file kgameproperty.h.
const type& KGameProperty< type >::operator= | ( | const KGameProperty< type > & | property | ) | [inline] |
This copies the data of property to the KGameProperty object.
Equivalent to setValue(property.value());
Definition at line 818 of file kgameproperty.h.
KGameProperty< type >::operator type | ( | ) | const [inline] |
Yeah, you can do it!
int a = myGamePropertyInt;
Definition at line 831 of file kgameproperty.h.
virtual const type_info* KGameProperty< type >::typeinfo | ( | ) | [inline, virtual] |
- Returns:
- a type_info of the data this property contains.
This is used e.g. by KGameDebugDialog
Reimplemented from KGamePropertyBase.
Definition at line 833 of file kgameproperty.h.
The documentation for this class was generated from the following file: