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 <b_mann@gmx.de>
5
6 SPDX-License-Identifier: LGPL-2.0-only
7*/
8
9#ifndef __KPLAYER_H_
10#define __KPLAYER_H_
11
12// own
13#include "kdegamesprivate_export.h"
14// Qt
15#include <QList>
16#include <QObject>
17// Std
18#include <memory>
19
20class KGame;
21class KGameIO;
24
25class 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 */
59class KDEGAMESPRIVATE_EXPORT KPlayer : public QObject
60{
61 Q_OBJECT
62
63public:
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
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 */
423
424protected 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
434private:
435 void init();
436
437private:
438 friend class KPlayerPrivate;
439 std::unique_ptr<KPlayerPrivate> const d;
440
442};
443
444#endif
Base class for IO devices for games.
Definition kgameio.h:57
Base class of KGameProperty.
A collection class for KGameProperty objects.
The main KDE game object.
Definition kgame.h:47
Base class for a game player.
Definition kplayer.h:60
void signalPropertyChanged(KGamePropertyBase *property, KPlayer *me)
This signal is emitted if a player property changes its value and the property is set to notify this ...
void signalNetworkData(int msgid, const QByteArray &buffer, quint32 sender, KPlayer *me)
The player object got a message which was targeted at it but has no default method to process it.
Q_SIGNALSQ_SIGNALS
Q_SLOTSQ_SLOTS
T qobject_cast(QObject *object)
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jun 14 2024 11:52:26 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.