KDEGames

kplayer.h
1 /*
2  This file is part of the KDE games library
3  SPDX-FileCopyrightText: 2001 Martin Heni <kde at heni-online.de>
4  SPDX-FileCopyrightText: 2001 Andreas Beckermann <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-only
7 */
8 
9 #ifndef __KPLAYER_H_
10 #define __KPLAYER_H_
11 
12 // own
13 #include "libkdegamesprivate_export.h"
14 // Qt
15 #include <QObject>
16 #include <QList>
17 // Std
18 #include <memory>
19 
20 class KGame;
21 class KGameIO;
22 class KGamePropertyBase;
24 
25 class KPlayerPrivate;
26 
27 /**
28  * \class KPlayer kplayer.h <KPlayer>
29  *
30  * @short Base class for a game player
31  *
32  * The KPlayer class is the central player object. It holds
33  * information about the player and is responsible for any
34  * input the player does. For this arbitrary many KGameIO
35  * modules can be plugged into it. Main features are:
36  * - Handling of IO devices
37  * - load/save (mostly handled by KGamePropertyHandler)
38  * - Turn handling (turn based, asynchronous)
39  *
40  * A KPlayer depends on a KGame object. Call KGame::addPlayer() to plug
41  * a KPlayer into a KGame object. Note that you cannot do much with a
42  * KPlayer object before it has been plugged into a KGame. This is because
43  * most properties of KPlayer are KGameProperty which need to send messages
44  * through a KGame object to be changed.
45  *
46  * A KGameIO represents the input methods of a player and you should make all
47  * player inputs through it. So call something like playerInput->move(4);
48  * instead which should call KGameIO::sendInput() to actually move. This way
49  * you gain a *very* big advantage: you can exchange a KGameIO whenever you
50  * want! You can e.g. remove the KGameIO of a local (human) player and just
51  * replace it by a computerIO on the fly! So from that point on all playerInputs
52  * are done by the computerIO instead of the human player. You also can replace
53  * all network players by computer players when the network connection is broken
54  * or a player wants to quit.
55  * So remember: use KGameIO whenever possible! A KPlayer should just
56  * contain all data of the player (KGameIO must not!) and several common
57  * functions which are shared by all of your KGameIOs.
58  *
59  */
60 class KDEGAMESPRIVATE_EXPORT KPlayer : public QObject
61 {
62  Q_OBJECT
63 
64 public:
66 
67  // explicit KPlayer(KGame *,KGameIO * input=0);
68  /**
69  * Create a new player object. It will be automatically
70  * deleted if the game it belongs to is deleted.
71  */
72  explicit KPlayer();
73 
74  ~KPlayer() override;
75 
76  /**
77  * The identification of the player. Overwrite this in
78  * classes inheriting KPlayer to run time identify them.
79  *
80  * @return 0 for default KPlayer.
81  */
82  virtual int rtti() const;
83 
84  /**
85  * Gives debug output of the game status
86  */
87  void Debug();
88 
89  // properties
90  /**
91  * Returns a list of input devices
92  *
93  * @return list of devices
94  */
95  KGameIOList *ioList();
96 
97  /**
98  * sets the game the player belongs to. This
99  * is usually automatically done when adding a
100  * player
101  *
102  * @param game the game
103  */
104  void setGame(KGame *game);
105 
106  /**
107  * Query to which game the player belongs to
108  *
109  * @return the game
110  */
111  KGame *game() const;
112 
113  /**
114  * Set whether this player can make turns/input
115  * all the time (true) or only when it is its
116  * turn (false) as it is used in turn based games
117  *
118  * @param a async=true turn based=false
119  */
120  void setAsyncInput(bool a);
121 
122  /**
123  * Query whether this player does asynchronous
124  * input
125  *
126  * @return true/false
127  */
128  bool asyncInput() const;
129 
130  /**
131  * Is this player a virtual player, i.e. is it
132  * created by mirroring a real player from another
133  * network game. This mirroring is done automatically
134  * as soon as a network connection is build and it affects
135  * all players regardless what type
136  *
137  * @return true/false
138  */
139  bool isVirtual() const;
140 
141  /**
142  * @internal
143  * Sets whether this player is virtual. This is internally
144  * called
145  *
146  * @param v virtual true/false
147  */
148  void setVirtual(bool v);
149 
150  /**
151  * Is this player an active player. An player is usually
152  * inactivated if it is replaced by a network connection.
153  * But this could also be called manually
154  *
155  * @return true/false
156  */
157  bool isActive() const;
158 
159  /**
160  * Set an player as active (true) or inactive (false)
161  *
162  * @param v true=active, false=inactive
163  */
164  void setActive(bool v);
165 
166  /**
167  * Returns the id of the player
168  *
169  * @return the player id
170  */
171  quint32 id() const;
172 
173  /* Set the players id. This is done automatically by
174  * the game object when adding a new player!
175  *
176  * @param i the player id
177  */
178  void setId(quint32 i);
179 
180  /**
181  * Returns the user defined id of the player
182  * This value can be used arbitrary by you to
183  * have some user identification for your player,
184  * e.g. 0 for a white chess player, 1 for a black
185  * one. This value is more reliable than the player
186  * id which can even change when you make a network
187  * connection.
188  *
189  * @return the user defined player id
190  */
191  int userId() const;
192 
193  /* Set the user defined players id.
194  *
195  * @param i the user defined player id
196  */
197  void setUserId(int i);
198 
199  /**
200  * Returns whether this player can be replaced by a network
201  * connection player. The name of this function can be
202  * improved ;-) If you do not overwrite the function to
203  * select what players shall play in a network the KGame
204  * does an automatic selection based on the networkPriority
205  * This is not a terrible important function at the moment.
206  *
207  * @return true/false
208  */
209  int networkPriority() const;
210 
211  /**
212  * Set whether this player can be replaced by a network
213  * player. There are to possible games. The first type
214  * of game has arbitrary many players. As soon as a network
215  * players connects the game runs with more players (not tagged
216  * situation). The other type is e.g. games like chess which
217  * require a constant player number. In a network game situation
218  * you would tag one or both players of all participants. As
219  * soon as the connect the tagged player will then be replaced
220  * by the network partner and it is then controlled over the network.
221  * On connection loss the old situation is automatically restored.
222  *
223  * The name of this function can be improved;-)
224  *
225  * @param b should this player be tagged
226  */
227  void setNetworkPriority(int b);
228 
229  /**
230  * Returns the player which got inactivated to allow
231  * this player to be set up via network. Mostly internal
232  * function
233  */
234  KPlayer *networkPlayer() const;
235 
236  /**
237  * Sets this network player replacement. Internal stuff
238  */
239  void setNetworkPlayer(KPlayer *p);
240 
241  // A name and group the player belongs to
242  /**
243  * A group the player belongs to. This
244  * Can be set arbitrary by you.
245  */
246  void setGroup(const QString& group);
247 
248  /**
249  * Query the group the player belongs to.
250  */
251  virtual const QString& group() const;
252 
253  /**
254  * Sets the name of the player.
255  * This can be chosen arbitrary.
256  * @param name The player's name
257  */
258  void setName(const QString& name);
259 
260  /**
261  * @return The name of the player.
262  */
263  virtual const QString& name() const;
264 
265 
266  // set devices
267  /**
268  * Adds an IO device for the player. Possible KGameIO devices
269  * can either be taken from the existing ones or be self written.
270  * Existing are e.g. Keyboard, Mouse, Computerplayer
271  *
272  * @param input the inut device
273  * @return true if ok
274  */
275  bool addGameIO(KGameIO *input);
276 
277  /**
278  * remove (and delete) a game IO device
279  *
280  * The remove IO(s) is/are deleted by default. If
281  * you do not want this set the parameter deleteit to false
282  *
283  * @param input the device to be removed or 0 for all devices
284  * @param deleteit true (default) to delete the device otherwise just remove it
285  * @return true on ok
286  */
287  bool removeGameIO(KGameIO *input=nullptr,bool deleteit=true);
288 
289  /**
290  * Finds the KGameIO devies with the given rtti code.
291  * E.g. find the mouse or network device
292  *
293  * @param rtti the rtti code to be searched for
294  * @return the KGameIO device
295  */
296  KGameIO *findRttiIO(int rtti) const;
297 
298  /**
299  * Checks whether this player has a IO device of the
300  * given rtti type
301  *
302  * @param rtti the rtti typed to be checked for
303  * @return true if it exists
304  */
305  bool hasRtti(int rtti) const;
306 
307  // Message exchange
308  /**
309  * Forwards input to the game object..internal use only
310  *
311  * This method is used by KGameIO::sendInput(). Use that function
312  * instead to send player inputs!
313  *
314  * This function forwards a player input (see KGameIO classes) to the
315  * game object, see KGame, either to KGame::sendPlayerInput() (if
316  * transmit=true, ie the message has just been created) or to
317  * KGame::playerInput() (if player=false, ie the message *was* sent through
318  * KGame::sendPlayerInput).
319  */
320  virtual bool forwardInput(QDataStream &msg,bool transmit=true, quint32 sender=0);
321 
322  /**
323  * Forwards Message to the game object..internal use only
324  */
325  virtual bool forwardMessage(QDataStream &msg,int msgid,quint32 receiver=0,quint32 sender=0);
326 
327  // Game logic
328  /**
329  * is it my turn to go
330  *
331  * @return true/false
332  */
333  bool myTurn() const;
334 
335  /**
336  * Sets whether this player is the next to turn.
337  * If exclusive is given all other players are set
338  * to setTurn(false) and only this player can move
339  *
340  * @param b true/false
341  * @param exclusive true (default)/ false
342  * @return should be void
343  */
344  bool setTurn(bool b,bool exclusive=true);
345 
346 
347  // load/save
348  /**
349  * Load a saved player, from file OR network. By default all
350  * KGameProperty objects in the dataHandler of this player are loaded
351  * and saved when using load or save. If you need to save/load more
352  * you have to replace this function (and save). You will probably
353  * still want to call the default implementation additionally!
354  *
355  * @param stream a data stream where you can stream the player from
356  *
357  * @return true?
358  */
359  virtual bool load(QDataStream &stream);
360 
361  /**
362  * Save a player to a file OR to network. See also load
363  *
364  * @param stream a data stream to load the player from
365  *
366  * @return true?
367  */
368  virtual bool save(QDataStream &stream);
369 
370  /**
371  * Receives a message
372  * @param msgid The kind of the message. See messages.txt for further
373  * information
374  * @param stream The message itself
375  * @param sender
376  **/
377  void networkTransmission(QDataStream &stream,int msgid,quint32 sender);
378 
379  /**
380  * Searches for a property of the player given its id.
381  * @param id The id of the property
382  * @return The property with the specified id
383  **/
384  KGamePropertyBase* findProperty(int id) const;
385 
386  /**
387  * Adds a property to a player. You would add all
388  * your player specific game data as KGameProperty and
389  * they are automatically saved and exchanged over network.
390  *
391  * @param data The property to be added. Must have an unique id!
392  * @return false if the given id is not valid (ie another property owns
393  * the id) or true if the property could be added successfully
394  **/
395  bool addProperty(KGamePropertyBase* data);
396 
397  /**
398  * Calculates a checksum over the IO devices. Can be used to
399  * restore the IO handlers. The value returned is the 'or'ed
400  * value of the KGameIO rtti's.
401  * this is internally used for saving and restoring a player.
402  */
403  int calcIOValue();
404 
405  /**
406  * @return the property handler
407  */
408  KGamePropertyHandler* dataHandler();
409 
410 Q_SIGNALS:
411  /**
412  * The player object got a message which was targeted
413  * at it but has no default method to process it. This
414  * means probably a user message. Connecting to this signal
415  * allowed to process it.
416  */
417  void signalNetworkData(int msgid, const QByteArray& buffer, quint32 sender, KPlayer *me);
418 
419  /**
420  * This signal is emitted if a player property changes its value and
421  * the property is set to notify this change. This is an
422  * important signal as you should base the actions on a reaction
423  * to this property changes.
424  */
425  void signalPropertyChanged(KGamePropertyBase *property,KPlayer *me);
426 
427 protected Q_SLOTS:
428  /**
429  * Called by KGameProperty only! Internal function!
430  **/
431  void sendProperty(int msgid, QDataStream& stream, bool* sent);
432  /**
433  * Called by KGameProperty only! Internal function!
434  **/
435  void emitSignal(KGamePropertyBase *me);
436 
437 
438 private:
439  void init();
440 
441 private:
442  friend class KPlayerPrivate;
443  std::unique_ptr<KPlayerPrivate> const d;
444 
446 };
447 
448 #endif
A collection class for KGameProperty objects.
const QLatin1String name
Base class for a game player.
Definition: kplayer.h:60
Base class of KGameProperty.
Definition: kgameproperty.h:35
QCA_EXPORT void init()
Q_DISABLE_COPY(Class)
The main KDE game object.
Definition: kgame.h:57
Base class for IO devices for games.
Definition: kgameio.h:56
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Mon Dec 6 2021 22:33:53 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.