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

KDE's Doxygen guidelines are available online.