Changeset 8107

Timestamp:

Mar 23, 2011, 9:41:21 PM (13 years ago)

Author:

dafrick

Message:

Done documenting Pong.
Also resolved some doxygen warnings.

Location:

code/branches/tetris

Files:

• doc/api/groups/Triggers.dox (modified) (1 diff)
• src/libraries/core/Loader.cc (modified) (1 diff)
• src/libraries/network/Host.cc (modified) (1 diff)
• src/libraries/network/MasterServerComm.h (modified) (1 diff)
• src/modules/designtools/ScreenshotManager.cc (modified) (1 diff)
• src/modules/pong/PongAI.cc (modified) (12 diffs)
• src/modules/pong/PongAI.h (modified) (2 diffs)
• src/modules/pong/PongBat.cc (modified) (1 diff)
• src/modules/pong/PongBot.cc (modified) (2 diffs)
• src/modules/pong/PongBot.h (modified) (2 diffs)
• src/modules/pong/PongScore.cc (modified) (8 diffs)
• src/modules/pong/PongScore.h (modified) (3 diffs)

code/branches/tetris/doc/api/groups/Triggers.dox

@@ -66 +66 @@
     A @ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger" is the MultiTrigger equivalent of the @ref orxonox::DistanceTrigger "DistanceTrigger" and works just the same way. It triggers (now separately for each object triggering it, since it's a @ref orxonox::MultiTrigger "MultiTrigger") whenever an object that is a target of the @ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger" is in the specified range.
 
-    Two additional parameters can be specified for the @ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger" are the <em>distance</em>, which defines the maximum distance at which an object still triggers the @ref orxonox:: "DistanceMultiTrigger", and the <em>targetname</em>. Setting the <em>targename</em> puts the @ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger" in <em>single-target mode</em>. In this mode the @ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger"  can only be triggered by objects that have a @ref orxonox::DistanceTriggerBeacon "DistanceTriggerBeacon" with the name specified by <em>targetname</em> directly attached. For the <em>single-target mode</em> to work the target of the @ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger" has to be set to <code>DistanceTriggerBeacon</code>.
+    Two additional parameters can be specified for the @ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger" are the <em>distance</em>, which defines the maximum distance at which an object still triggers the @ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger", and the <em>targetname</em>. Setting the <em>targename</em> puts the @ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger" in <em>single-target mode</em>. In this mode the @ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger"  can only be triggered by objects that have a @ref orxonox::DistanceTriggerBeacon "DistanceTriggerBeacon" with the name specified by <em>targetname</em> directly attached. For the <em>single-target mode</em> to work the target of the @ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger" has to be set to <code>DistanceTriggerBeacon</code>.
 
     A common usage (without @ref orxonox::DistanceTriggerBeacon "DistanceTriggerBeacon") would look like this:

code/branches/tetris/src/libraries/core/Loader.cc

@@ -144 +144 @@
     @param verbose
         Whether the loader is verbose (prints its progress in a low output level) or not.
+    @param bRemoveLuaTags
+        If true lua tags are just ignored and removed. The default is false.
     @return
         Returns true if successful.

code/branches/tetris/src/libraries/network/Host.cc

@@ -75 +75 @@
   * @param packet Packet to be added
   * @param clientID ID of the client the packet should be sent to
+  * @param channelID ID of the channel.
   * @return success?
   */

code/branches/tetris/src/libraries/network/MasterServerComm.h

@@ -89 +89 @@
 
       /** \param callback The callback function to call with data received.
+       *  \param delayms Delay in milliseconds.
        * \return 0 for success, other for error
        * 

code/branches/tetris/src/modules/designtools/ScreenshotManager.cc

@@ -61 +61 @@
     @brief
         Creates a screenshot with the given camera.
-    @param camera
-        Pointer to the camera "looking at" the scene of interest
-    @param fileName
-        the filename of the screenshot file.
     */
     void ScreenshotManager::makeScreenshot() const

code/branches/tetris/src/modules/pong/PongAI.cc

@@ -27 +27 @@
  */
 
+/**
+    @file PongAI.cc
+    @brief Implementation of the PongAI class.
+*/
+
 #include "PongAI.h"
 
@@ -32 +37 @@
 #include "core/ConfigValueIncludes.h"
 #include "tools/Timer.h"
+
 #include "worldentities/ControllableEntity.h"
+
 #include "PongBall.h"
 
@@ -41 +48 @@
     const static float MAX_REACTION_TIME = 0.4f;
 
+    /**
+    @brief
+        Constructor. Registers and initializes the object.
+    */
     PongAI::PongAI(BaseObject* creator) : Controller(creator)
     {
@@ -59 +70 @@
     }
 
+    /**
+    @brief
+        Destructor. Cleans up the list fo reaction timers.
+    */
     PongAI::~PongAI()
     {
@@ -65 +80 @@
     }
 
+    /**
+    @brief
+        Sets config values.
+    */
     void PongAI::setConfigValues()
     {
+        // Sets the strength of the PongAi as a config value.
         SetConfigValue(strength_, 0.5).description("A value from 0 to 1 where 0 is weak and 1 is strong.");
     }
 
+    /**
+    @brief
+        Is called each tick.
+        Implements the behavior of the PongAI (i.e. its intelligence).
+    @param dt
+        The time that has elapsed since the last tick.
+    */
     void PongAI::tick(float dt)
     {
-        if (!this->ball_ || !this->getControllableEntity())
+        // If either the ball, or the controllable entity (i.e. the bat) don't exist (or aren't set).
+        if (this->ball_  == NULL || this->getControllableEntity() == NULL)
             return;
 
@@ -109 +137 @@
             if (this->ballDirection_.x != 1)
             {
-                // The ball just startet to approach, initialize all values
+                // The ball just started to approach, initialize all values
                 this->ballDirection_.x = 1;
                 this->ballDirection_.y = sgn(ballvel.z);
@@ -158 +186 @@
             {
                 // We had to correct our position because we moved too far
-                // (and delay ist false, so we're not in the wrong place because of a new end-position prediction)
+                // (and delay is false, so we're not in the wrong place because of a new end-position prediction)
                 if (fabs(mypos.z - this->ballEndPosition_) < 0.5 * this->ball_->getBatLength() * this->ball_->getFieldDimension().y)
                 {
@@ -173 +201 @@
     }
 
+    /**
+    @brief
+        Calculates the random offset, that accounts for random errors the AI makes in order to be beatable.
+        The higher the strength of the AI, the smaller the (expected value of the) error.
+        The result of this method is stored in this->randomOffset_.
+    */
     void PongAI::calculateRandomOffset()
     {
@@ -184 +218 @@
                                           // exp < 1 -> position is more likely a large number
 
-        // The position shouln't be larger than 0.5 (50% of the bat-length from the middle is the end)
+        // The position shouldn't be larger than 0.5 (50% of the bat-length from the middle is the end)
         position *= 0.48f;
 
@@ -194 +228 @@
     }
 
+    /**
+    @brief
+        Calculate the end position the ball will be in.
+        The result of this calculation is stored in this->ballEndPosition_.
+    */
     void PongAI::calculateBallEndPosition()
     {
@@ -295 +334 @@
     }
 
+    /**
+    @brief
+        Determine the movement the AI will undertake. (Either -1, 0 or 1)
+        The result of this calculation is stored in this->movement_;
+    @param direction
+        The current direction of movement.
+    @param bUseDelay
+        The time by which this move is delayed. (Again, to make the AI less efficient)
+    */
     void PongAI::move(char direction, bool bUseDelay)
     {
@@ -321 +369 @@
     }
 
+    /**
+    @brief
+        Is called, when a delayed move takes effect.
+    */
     void PongAI::delayedMove()
     {

code/branches/tetris/src/modules/pong/PongAI.h

@@ -27 +27 @@
  */
 
+/**
+    @file PongAI.h
+    @brief Declaration of the PongAI class.
+    @ingroup Pong
+*/
+
 #ifndef _PongAI_H__
 #define _PongAI_H__
@@ -33 +39 @@
 
 #include <list>
+
 #include "util/Math.h"
 #include "tools/interfaces/Tickable.h"
+
 #include "controllers/Controller.h"
 
 namespace orxonox
 {
+
+    /**
+    @brief
+        The PongAI is an artificial intelligence for the @ref orxonox::Pong "Pong" gametype.
+
+    @author
+        Fabian 'x3n' Landau
+
+    @ingroup Pong
+    */
     class _PongExport PongAI : public Controller, public Tickable
     {
         public:
-            PongAI(BaseObject* creator);
+            PongAI(BaseObject* creator); //!< Constructor. Registers and initializes the object.
             virtual ~PongAI();
 
             void setConfigValues();
 
-            virtual void tick(float dt);
+            virtual void tick(float dt); //!< Implements the behavior of the PongAI (i.e. its intelligence).
 
+            /**
+            @brief Set the ball for the AI.
+            @param ball A pointer to the ball.
+            */
             void setPongBall(PongBall* ball)
                 { this->ball_ = ball; }
 
         protected:
-            void calculateRandomOffset();
-            void calculateBallEndPosition();
-            void move(char direction, bool bUseDelay);
-            void delayedMove();
+            void calculateRandomOffset(); //!< Calculates the random offset, that accounts for random errors the AI makes in order to be beatable.
+            void calculateBallEndPosition(); //!< Calculate the end position the ball will be in.
+            void move(char direction, bool bUseDelay); //!< Determine the movement the AI will undertake.
+            void delayedMove(); //!< Is called, when a delayed move takes effect.
 
-            PongBall* ball_;
-            Vector2 ballDirection_;
-            float ballEndPosition_;
-            float randomOffset_;
-            bool bChangedRandomOffset_;
-            float relHysteresisOffset_;
-            float strength_;
+            PongBall* ball_; //!< A pointer to the ball.
+            Vector2 ballDirection_; //!< Vector to store the (x,z) direction in which the ball is flying.
+            float ballEndPosition_; //!< The calculated end position of the ball.
+            float randomOffset_; //!< A random offset to introduce random errors (weighted by the strength of the AI) into the AI's behavior.
+            bool bChangedRandomOffset_; //!< Helper boolean, to change the random offset more often.
+            float relHysteresisOffset_; //!< A hysteresis offset.
+            float strength_; //!< The strength of the AI. Ranging from 0 to 1.
 
-            std::list<std::pair<Timer*, char> > reactionTimers_;
-            char movement_;
-            char oldMove_;
-            bool bOscillationAvoidanceActive_;
+            std::list<std::pair<Timer*, char> > reactionTimers_; //!< A list of reaction timers and the directions that take effect when their timer expires.
+            char movement_; //!< The planned movement.
+            char oldMove_; //!< The previous movement.
+            bool bOscillationAvoidanceActive_; //!< Boolean, to avoid oscillations.
     };
 }

code/branches/tetris/src/modules/pong/PongBat.cc

@@ -87 +87 @@
                 this->movement_ = clamp(this->movement_, -1.0f, 1.0f) * this->speed_;
 
-                //TODO: Why needed?
+                // If moveRightLeft() is used the movement is dependento on wehther it is the right or the left bat, so, it is i.e. dependent on the orientation of the bat.
                 if (this->bMoveLocal_)
                     this->setVelocity(this->getOrientation() * Vector3(this->movement_, 0, 0));

code/branches/tetris/src/modules/pong/PongBot.cc

@@ -27 +27 @@
  */
 
+/**
+    @file PongBot.cc
+    @brief Implementation of the PongBot class.
+*/
+
 #include "PongBot.h"
 
@@ -36 +41 @@
     CreateFactory(PongBot);
 
+    /**
+    @brief
+        Constructor. Registers the object and creates a PongAI controller.
+    */
     PongBot::PongBot(BaseObject* creator) : Bot(creator)
     {

code/branches/tetris/src/modules/pong/PongBot.h

@@ -27 +27 @@
  */
 
+/**
+    @file PongBot.h
+    @brief Declaration of the PongBot class.
+    @ingroup Pong
+*/
+
 #ifndef _PongBot_H__
 #define _PongBot_H__
@@ -35 +41 @@
 namespace orxonox
 {
+
+    /**
+    @brief
+        A bot especially for @ref orxonox::Pong "Pong".
+
+        Uses the @ref orxonox::PongAI "PongAI".
+
+    @author
+        Fabian 'x3n' Landau
+
+    @ingroup Pong
+    */
     class _PongExport PongBot : public Bot
     {

code/branches/tetris/src/modules/pong/PongScore.cc

@@ -27 +27 @@
  */
 
+/**
+    @file PongScore.cc
+    @brief Implementation of the PongScore class.
+*/
+
 #include "PongScore.h"
 
-#include "util/Convert.h"
 #include "core/CoreIncludes.h"
 #include "core/XMLPort.h"
+#include "util/Convert.h"
+
+#include "infos/PlayerInfo.h"
+
 #include "Pong.h"
-#include "infos/PlayerInfo.h"
 
 namespace orxonox
@@ -39 +46 @@
     CreateFactory(PongScore);
 
+    /**
+    @brief
+        Constructor. Registers and initializes the object.
+    */
     PongScore::PongScore(BaseObject* creator) : OverlayText(creator)
     {
@@ -51 +62 @@
     }
 
+    /**
+    @brief
+        Destructor.
+    */
     PongScore::~PongScore()
     {
     }
 
+    /**
+    @brief
+        Method to create a PongScore through XML.
+    */
     void PongScore::XMLPort(Element& xmlelement, XMLPort::Mode mode)
     {
@@ -65 +84 @@
     }
 
+    /**
+    @brief
+        Is called each tick.
+        Creates and sets the caption to be displayed by the PongScore.
+    @param dt
+        The time that has elapsed since the last tick.
+    */
     void PongScore::tick(float dt)
     {
         SUPER(PongScore, tick, dt);
 
-        if (this->owner_)
+        // If the owner is set. The owner being a Pong game.
+        if (this->owner_ != NULL)
         {
+            // Get the two players.
             PlayerInfo* player1 = this->owner_->getLeftPlayer();
             PlayerInfo* player2 = this->owner_->getRightPlayer();
@@ -80 +108 @@
             std::string score2("0");
 
-            if (player1)
+            // Save the name and score of each player as a string.
+            if (player1 != NULL)
             {
                 name1 = player1->getName();
                 score1 = multi_cast<std::string>(this->owner_->getScore(player1));
             }
-
-            if (player2)
+            if (player2 != NULL)
             {
                 name2 = player2->getName();
@@ -92 +120 @@
             }
 
+            // Assemble the strings, depending on what should all be displayed.
             std::string output1;
             if (this->bShowLeftPlayer_)
             {
-                if (this->bShowName_ && this->bShowScore_ && player1)
+                if (this->bShowName_ && this->bShowScore_ && player1 != NULL)
                     output1 = name1 + " - " + score1;
                 else if (this->bShowScore_)
@@ -106 +135 @@
             if (this->bShowRightPlayer_)
             {
-                if (this->bShowName_ && this->bShowScore_ && player2)
+                if (this->bShowName_ && this->bShowScore_ && player2 != NULL)
                     output2 = score2 + " - " + name2;
                 else if (this->bShowScore_)
@@ -127 +156 @@
     }
 
-
+    /**
+    @brief
+        Is called when the owner changes.
+        Sets the owner to NULL, if it is not a pointer to a Pong game.
+    */
     void PongScore::changedOwner()
     {
         SUPER(PongScore, changedOwner);
 
-        if (this->getOwner() && this->getOwner()->getGametype())
+        if (this->getOwner() != NULL && this->getOwner()->getGametype())
             this->owner_ = orxonox_cast<Pong*>(this->getOwner()->getGametype().get());
         else

code/branches/tetris/src/modules/pong/PongScore.h

@@ -39 +39 @@
 
 #include "tools/interfaces/Tickable.h"
+
 #include "overlays/OverlayText.h"
 
@@ -45 +46 @@
 
     /**
-    
+    @brief
+        The PongScore class displays the score for a game of @ref orxonox::Pong "Pong".
+
+    @author
+        Fabian 'x3n' Landau
+
+    @ingroup Pong
     */
     class _PongExport PongScore : public OverlayText, public Tickable
@@ -53 +60 @@
             virtual ~PongScore();
 
-            virtual void tick(float dt);
+            virtual void tick(float dt); //!< Creates and sets the caption to be displayed by the PongScore.
             virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode);
-            virtual void changedOwner();
+            virtual void changedOwner(); //!< Is called when the owner changes.
 
+            /**
+            @brief Set whether the PongScore displays the players' names.
+            @param value If true the players' names are displayed.
+            */
             inline void setShowName(bool value)
                 { this->bShowName_ = value; }
+            /**
+            @brief Get whether the PongScore displays the players' names.
+            @return Returns true if the players' names are displayed, false otherwise.
+            */
             inline bool getShowName() const
                 { return this->bShowName_; }
 
+            /**
+            @brief Set whether the PongScore displays the players' scores.
+            @param value If true the players' scores are displayed.
+            */
             inline void setShowScore(bool value)
                 { this->bShowScore_ = value; }
+            /**
+            @brief Get whether the PongScore displays the players' scores.
+            @return Returns true if the players' scores are displayed, false otherwise.
+            */
             inline bool getShowScore() const
                 { return this->bShowScore_; }
 
+            /**
+            @brief Set whether the PongScore displays the left player.
+            @param value If true the left player is displayed.
+            */
             inline void setShowLeftPlayer(bool value)
                 { this->bShowLeftPlayer_ = value; }
+            /**
+            @brief Get whether the PongScore displays the left player.
+            @return Returns true if the left player is displayed, false otherwise.
+            */
             inline bool getShowLeftPlayer() const
                 { return this->bShowLeftPlayer_; }
 
+            /**
+            @brief Set whether the PongScore displays the right player.
+            @param value If true the right player is displayed.
+            */
             inline void setShowRightPlayer(bool value)
                 { this->bShowRightPlayer_ = value; }
+            /**
+            @brief Get whether the PongScore displays the right player.
+            @return Returns true if the right player is displayed, false otherwise.
+            */
             inline bool getShowRightPlayer() const
                 { return this->bShowRightPlayer_; }
 
         private:
-            Pong* owner_;
-            bool bShowName_;
-            bool bShowScore_;
-            bool bShowLeftPlayer_;
-            bool bShowRightPlayer_;
+            Pong* owner_; //!< The Pong game that owns this PongScore.
+            bool bShowName_; //!< Whether the names of the players are shown.
+            bool bShowScore_; //!< Whether the score of the players is shown.
+            bool bShowLeftPlayer_; //!< Whether the left player is shown.
+            bool bShowRightPlayer_; //!< Whether the right player is shown.
     };
 }