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