Changeset 7547 for code/trunk/src/modules/pickup/items

Timestamp:

Oct 16, 2010, 12:37:09 PM (14 years ago)

Author:

dafrick

Message:

Documenting and cleanup.

Location:

code/trunk/src/modules/pickup/items

Files:

• DronePickup.cc (modified) (1 diff)
• DronePickup.h (modified) (2 diffs)
• HealthPickup.cc (modified) (2 diffs)
• HealthPickup.h (modified) (5 diffs)
• InvisiblePickup.cc (modified) (7 diffs)
• InvisiblePickup.h (modified) (4 diffs)
• MetaPickup.cc (modified) (5 diffs)
• MetaPickup.h (modified) (3 diffs)
• ShieldPickup.cc (modified) (8 diffs)
• ShieldPickup.h (modified) (4 diffs)
• SpeedPickup.cc (modified) (5 diffs)
• SpeedPickup.h (modified) (4 diffs)

code/trunk/src/modules/pickup/items/DronePickup.cc

@@ -35 +35 @@
 
 #include <sstream>
-
 #include "core/CoreIncludes.h"
 #include "core/XMLPort.h"
-#include "util/StringUtils.h"
 
 #include "controllers/DroneController.h"
 #include "pickup/PickupIdentifier.h"
+#include "worldentities/Drone.h"
 #include "worldentities/pawns/Pawn.h"
-#include "worldentities/Drone.h"
-#include "worldentities/StaticEntity.h"
 
 namespace orxonox

code/trunk/src/modules/pickup/items/DronePickup.h

@@ -48 +48 @@
     @brief
         The DronePickup adds a Drone to the Pawn upon being picked up.
+
         It can be used in XML as follows:
         @code
@@ -71 +72 @@
             virtual void clone(OrxonoxClass*& item); //!< Creates a duplicate of the input OrxonoxClass.
 
-            void setDroneTemplate(std::string templatename); //!< Set the droneTemplate.
             const std::string& getDroneTemplate() const; //!< Get the name of the droneTemplate.
 
         protected:
             void initializeIdentifier(void); //!< Initializes the PickupIdentifier of this pickup.
+
+            void setDroneTemplate(std::string templatename); //!< Set the droneTemplate.
 
         private:

code/trunk/src/modules/pickup/items/HealthPickup.cc

@@ -34 +34 @@
 #include "HealthPickup.h"
 
+#include <sstream>
 #include "core/CoreIncludes.h"
 #include "core/XMLPort.h"
-#include "util/StringUtils.h"
-
+
+#include "pickup/PickupIdentifier.h"
 #include "worldentities/pawns/Pawn.h"
-#include "pickup/PickupIdentifier.h"
-
-#include <sstream>
 
 namespace orxonox
@@ -307 +305 @@
         Returns the health type as a string.
     */
-    const std::string& HealthPickup::getHealthType(void)
+    const std::string& HealthPickup::getHealthType(void) const
     {
         switch(this->getHealthTypeDirect())

code/trunk/src/modules/pickup/items/HealthPickup.h

@@ -39 +39 @@
 
 #include <string>
-#include <worldentities/pawns/Pawn.h>
-#include "worldentities/StaticEntity.h"
 
 #include "pickup/Pickup.h"
@@ -65 +63 @@
     /**
     @brief
-        The Health Pickup is a Pickupable that can do (dependent upon the parameters) lots of different things to the health of a Pawn.
-        There are 4 parameters that can be chosen:
-        - The <b>health</b> The amount of health that (in a way dependent on the other parameters) is transferred to the Pawn.
-        - The <b>activation type</b> It can be chosen to be either <em>immediate</em> or <em>onUse</em>. The activation type essentially (as indicated by the name) defines when the health is transferred, either immediately after being picked up or only after the player uses it.
-        - The <b>duration type</b> It can be chosen to be either <em>once</em> or <em>continuous</em>. For <em>once</em> the specified health is transferred once to the Pawn, for <em>continuous</em> the set health is transferred over a span of time at a rate defined by the health rate parameter.
-        - The <b>health type</b> The health type can be chosen to be <em>limited</em>, <em>temporary</em> or <em>permanent</em>. <em>limited</em> means that the health is increased only to the maximum health of the Pawn. 'temporary' means that the maximum health is temporarily elevated but will be set back as soon as the pickup is no longer in use. <em>permanent</em> means that the maximum health of the Pawn is increased such that the health provided by the pickup will fit in and the maximum health stays that way.
+        The HealthPickup is a Pickupable that can do (dependent upon the parameters) lots of different things to the health of a Pawn.
+        There are 5 parameters that can be chosen:
+        - The @b activationType It can be chosen to be either <em>immediate</em> or <em>onUse</em>. The activation type essentially (as indicated by the name) defines when the health is transferred, either immediately after being picked up or only after the player uses it. The default is <em>immediate</em>.
+        - The @b durationType It can be chosen to be either <em>once</em> or <em>continuous</em>. For <em>once</em> the specified health is transferred once to the Pawn, for <em>continuous</em> the set health is transferred over a span of time at a rate defined by the health rate parameter. The default is <em>once</em>.
+        - The @b health The amount of health that (in a way dependent on the other parameters) is transferred to the Pawn. Default is 0.
+        - The @b healthType The health type can be chosen to be <em>limited</em>, <em>temporary</em> or <em>permanent</em>. <em>limited</em> means that the health is increased only to the maximum health of the Pawn. 'temporary' means that the maximum health is temporarily elevated but will be set back as soon as the pickup is no longer in use. <em>permanent</em> means that the maximum health of the Pawn is increased such that the health provided by the pickup will fit in and the maximum health stays that way. The default is <em>limited</em>.
+        - The @b healthRate If set to continuous, the health that is transferred per second is the <em>healthRate</em>. There is health transferred until the health set by <em>health</em> is depleted. The default is 0.
 
-        An examle of a XML implementation of a HealthPickup would be:
+        An example of a XML implementation of a HealthPickup would be:
         @code
         <HealthPickup
@@ -104 +103 @@
             @return Returns the health.
             */
-            inline float getHealth(void)
+            inline float getHealth(void) const
                 { return this->health_; }
             /**
@@ -110 +109 @@
             @return Returns the rate.
             */
-            inline float getHealthRate(void)
+            inline float getHealthRate(void) const
                 { return this->healthRate_; }
 
@@ -117 +116 @@
             @return Returns the health type as an enum.
             */
-            inline pickupHealthType::Value getHealthTypeDirect(void)
+            inline pickupHealthType::Value getHealthTypeDirect(void) const
                 { return this->healthType_; }
-            const std::string& getHealthType(void); //!< Get the health type of this pickup.
+            const std::string& getHealthType(void) const; //!< Get the health type of this pickup.
 
         protected:

code/trunk/src/modules/pickup/items/InvisiblePickup.cc

@@ -35 +35 @@
 
 #include <sstream>
-#include <OgreEntity.h>
-#include <OgreAnimationState.h>
-
-#include "util/StringUtils.h"
+//#include <OgreEntity.h>
+//#include <OgreAnimationState.h>
 #include "core/CoreIncludes.h"
 #include "core/XMLPort.h"
 
+#include "pickup/PickupIdentifier.h"
 #include "worldentities/pawns/Pawn.h"
-#include "pickup/PickupIdentifier.h"
 
 namespace orxonox
@@ -68 +66 @@
     }
 
-
+    /**
+    @brief
+    Initializes the member variables.
+    */
+    void InvisiblePickup::initialize(void)
+    {
+        this->duration_ = 0.0f;
+        // Defines who is allowed to pick up the pickup.
+        this->addTarget(ClassIdentifier<Pawn>::getIdentifier());
+    }
+
+    /**
+    @brief
+        Initializes the PickupIdentifier of this pickup.
+    */
     void InvisiblePickup::initializeIdentifier(void)
     {
@@ -80 +92 @@
     /**
     @brief
-    Initializes the member variables.
-    */
-    void InvisiblePickup::initialize(void)
-    {
-        this->duration_ = 0.0f;
-        // Defines who is allowed to pick up the pickup.
-        this->addTarget(ClassIdentifier<Pawn>::getIdentifier());
-    }
-
-    /**
-    @brief
         Method for creating a HealthPickup object through XML.
     */
@@ -113 +114 @@
             return;
 
+        // If the pickup has transited to used.
         if (this->isUsed())
         {
+            // If its durationType is continuous, we set a Timer to be reminded, when the time has run out.
             if(this->isContinuous())
             {
@@ -134 +137 @@
             this->setInvisible(false);
 
+            // We destroy the pickup if either, the pickup has activationType immediate and durationType once or it has durationType continuous and the duration was exceeded.
             if((!this->isContinuous() && this->isImmediate()) || (this->isContinuous() && !this->durationTimer_.isActive() && this->durationTimer_.getRemainingTime() == this->getDuration()))
             {
                 this->Pickupable::destroy();
             }
+            // We pause the Timer if the pickup is continuous and the duration is not yet exceeded,
             else if(this->isContinuous() && this->durationTimer_.isActive())
             {
@@ -143 +148 @@
             }
         }
-
-    }
-
-    /**
-    @brief
-        Helper to transform the PickupCarrier to a Pawn, and throw an error message if the conversion fails.
-    @return
-        A pointer to the Pawn, or NULL if the conversion failed.
-    */
-    Pawn* InvisiblePickup::carrierToPawnHelper(void)
-    {
-        PickupCarrier* carrier = this->getCarrier();
-        Pawn* pawn = dynamic_cast<Pawn*>(carrier);
-
-        if(pawn == NULL)
-        {
-            COUT(1) << "Invalid PickupCarrier in InvisiblePickup." << std::endl;
-        }
-        return pawn;
     }
 
@@ -212 +198 @@
     /**
     @brief
+        Helper to transform the PickupCarrier to a Pawn, and throw an error message if the conversion fails.
+    @return
+        A pointer to the Pawn, or NULL if the conversion failed.
+    */
+    Pawn* InvisiblePickup::carrierToPawnHelper(void)
+    {
+        PickupCarrier* carrier = this->getCarrier();
+        Pawn* pawn = dynamic_cast<Pawn*>(carrier);
+
+        if(pawn == NULL)
+        {
+            COUT(1) << "Invalid PickupCarrier in InvisiblePickup." << std::endl;
+        }
+        return pawn;
+    }
+
+    /**
+    @brief
         Sets the time the InvisibilityPickup will last.
     @param duration

code/trunk/src/modules/pickup/items/InvisiblePickup.h

@@ -40 +40 @@
 #include <string>
 
-#include <worldentities/pawns/Pawn.h>
-#include "worldentities/StaticEntity.h"
 #include "pickup/Pickup.h"
 
@@ -49 +47 @@
     @brief
         A pickup that makes the Pawn invisible.
-        There are 2 parameters that can be chosen:
-        - The <b>activation type</b> It can be chosen to be either <em>immediate</em> or <em>onUse</em>. The activation type essentially (as indicated by the name) defines when the Pawn will be invisible, either immediately after being picked up or only after the player uses it.
-        - The <b>duration type</b> It can be chosen to be either <em>once</em> or <em>continuous</em>. For <em>once</em> the InvisiblePickup just makes the Pawn invisible for as long as it is used, for <em>continuous</em> the Pawn is invisible for the specified duration.
-        - The <b>duration</b> Specifies how long (in seconds) the invisibility lasts.
+        There are 3 parameters that can be chosen:
+        - The @b activationType It can be chosen to be either <em>immediate</em> or <em>onUse</em>. The activation type essentially (as indicated by the name) defines when the Pawn will be invisible, either immediately after being picked up or only after the player uses it. The default is <em>immediate</em>.
+        - The @b durationType< It can be chosen to be either <em>once</em> or <em>continuous</em>. For <em>once</em> the InvisiblePickup just makes the Pawn invisible for as long as it is used, for <em>continuous</em> the Pawn is invisible for the specified duration. The default is <em>once</em>.
+        - The @b duration Specifies how long (in seconds) the invisibility lasts. The default is 0.
 
-        An examle of a XML implementation of a InvisiblePickup would be:
+        An example of a XML implementation of a InvisiblePickup would be:
         @code
-        <HealthPickup
+        <InvisiblePickup
             activationType = "immediate"
             durationType = "continuous"
@@ -83 +81 @@
             @return Returns if the Pawn is invisible.
             */
-            inline bool getInvisibility(bool)
+            inline bool getInvisibility(bool) const
                 { return this->invisible_; }
             /**
@@ -89 +87 @@
             @return Returns the time in seconds the InvisibiltyPickup lasts.
             */
-            inline float getDuration(void)
+            inline float getDuration(void) const
                 { return this->duration_; }
 
         protected:
-            void initializeIdentifier(void);
+            void initializeIdentifier(void); //!< Initializes the PickupIdentifier of this pickup.
 
             bool setInvisible(bool invisibility); //!< Set the Pawn to be invisible or visible again.

code/trunk/src/modules/pickup/items/MetaPickup.cc

@@ -34 +34 @@
 #include "core/CoreIncludes.h"
 #include "core/XMLPort.h"
-#include "worldentities/pawns/Pawn.h"
+
 #include "interfaces/PickupCarrier.h"
 #include "pickup/PickupIdentifier.h"
+#include "worldentities/pawns/Pawn.h"
 
 #include "MetaPickup.h"
@@ -79 +80 @@
         this->addTarget(ClassIdentifier<PickupCarrier>::getIdentifier());
 
-        this->setActivationTypeDirect(pickupActivationType::immediate);
         this->setDurationTypeDirect(pickupDurationType::once);
         this->metaType_ = pickupMetaType::none;
@@ -117 +117 @@
         SUPER(MetaPickup, changedUsed);
 
-        //! If the MetaPickup transited to used.
-        if(this->isUsed())
+        // If the MetaPickup transited to used, and the metaType is not none.
+        if(this->isUsed() && this->metaType_ != pickupMetaType::none)
         {
             PickupCarrier* carrier = this->getCarrier();
             if(this->getMetaTypeDirect() != pickupMetaType::none && carrier != NULL)
             {
+                // If the metaType is destroyCarrier, then the PickupCarrier is destroyed.
                 if(this->getMetaTypeDirect() == pickupMetaType::destroyCarrier)
                 {
@@ -131 +132 @@
                 }
                 std::set<Pickupable*> pickups = carrier->getPickups();
-                //! Set all Pickupables carried by the PickupCarrier either to used or drop them, depending on the meta type.
+                // Iterate over all Pickupables of the PickupCarrier.
                 for(std::set<Pickupable*>::iterator it = pickups.begin(); it != pickups.end(); it++)
                 {
-                    Pickup* pickup = dynamic_cast<Pickup*>(*it);
-                    if(this->getMetaTypeDirect() == pickupMetaType::use)
+                    Pickupable* pickup = (*it);
+                    if(pickup == NULL || pickup == this)
+                        continue;
+
+                    // If the metaType is use, then the Pickupable is set to used.
+                    if(this->getMetaTypeDirect() == pickupMetaType::use && !pickup->isUsed())
                     {
-                        if(pickup != NULL && pickup != this && pickup->isOnUse() && !pickup->isUsed())
-                        {
-                            pickup->setUsed(true);
-                        }
+                        pickup->setUsed(true);
                     }
-                    if(this->getMetaTypeDirect() == pickupMetaType::drop)
+                    // If the metaType is drop, then the Pickupable is dropped.
+                    else if(this->getMetaTypeDirect() == pickupMetaType::drop)
                     {
-                        if(pickup != NULL && pickup != this)
-                        {
-                            pickup->drop();
-                        }
+                        pickup->drop();
                     }
-                    if(this->getMetaTypeDirect() == pickupMetaType::destroy)
+                    // If the metaType is destroy, then the Pickupable is destroyed.
+                    else if(this->getMetaTypeDirect() == pickupMetaType::destroy)
                     {
-                        if(pickup != NULL && pickup != this)
-                        {
-                            pickup->Pickupable::destroy();
-                        }
+                        pickup->Pickupable::destroy();
                     }
                 }
@@ -187 +185 @@
         Returns a string with the meta type of the MetaPickup.
     */
-    const std::string& MetaPickup::getMetaType(void)
+    const std::string& MetaPickup::getMetaType(void) const
     {
         switch(this->getMetaTypeDirect())

code/trunk/src/modules/pickup/items/MetaPickup.h

@@ -42 +42 @@
 namespace orxonox {
 
-    //! The meta type, deciding what the pickup does exactly.
+    /**
+    @brief
+        The meta type, specifying what the @ref orxonox::MetaPickup "MetaPickup" does exactly.
+
+    @ingroup PickupItems
+    */
     namespace pickupMetaType
     {
         enum Value
         {
-            none,
-            use,
-            drop,
-            destroy,
-            destroyCarrier
+            none, //!< The @ref orxonox::MetaPickup "MetaPickup" does nothing.
+            use, //!< The @ref orxonox::MetaPickup "MetaPickup" uses all the @ref orxonox::PickupCarrier "PickupCarriers'" @ref orxonox::Pickupable "Pickupables".
+            drop, //!< The @ref orxonox::MetaPickup "MetaPickup" drops all the @ref orxonox::PickupCarrier "PickupCarriers'" @ref orxonox::Pickupable "Pickupables".
+            destroy, //!< The @ref orxonox::MetaPickup "MetaPickup" destroys all the @ref orxonox::PickupCarrier "PickupCarriers'" @ref orxonox::Pickupable "Pickupables".
+            destroyCarrier //!< The @ref orxonox::MetaPickup "MetaPickup" destroys the @ref orxonox::PickupCarrier "PickupCarrier".
         };
     }
@@ -57 +62 @@
     /**
     @brief
-        The MetaPickup is a pickup that can, depending on the parameter 'metaType', do different things. If the 'metaType' is set to
-        - @b use All the pickups, the PickupCarrier has, are immediately set to used upon pickup of the MetaPickup.
-        - @b drop All the pickups, the PickupCarrier has, are immediately dropped upon pickup of the MetaPickup.
-        - @b destroy All the pickups, the PickupCarrier has, are immediately destroyed upon pickup of the MetaPickup.
-        - @b destroyCarrier The PickupCarrier is immediately destroyed upon pickup of the MetaPickup.
+        The MetaPickup is a Pickupable that can, depending on the parameter <em>metaTye</em>, do different things. If the <em>metaTye</em> is set to
+        - @b use All the @ref orxonox::Pickupable "Pickupables", the PickupCarrier has, are immediately set to used upon using the MetaPickup.
+        - @b drop All the @ref orxonox::Pickupable "Pickupables", the PickupCarrier has, are immediately dropped upon using the MetaPickup.
+        - @b destroy All the @ref orxonox::Pickupable "Pickupables", the PickupCarrier has, are immediately destroyed upon using the MetaPickup.
+        - @b destroyCarrier The PickupCarrier is immediately destroyed upon using the MetaPickup.
+
+        The default value is <em>none</em>, which basically does nothing.
+        
+        The parameter <b>activation type</b> can be used to specify, whether the MetaPickup is used upon pickup (<em>immediate</em>) or not (<em>onUse</em>). With <em>immediate</em> being the default.
+
+        An example of a XML implementation of a MetaPickup would be:
+        @code
+        <MetaPickup
+            activationType = "immediate"
+            metaType = "use"
+        />
+        @endcode
+
     @author
         Damian 'Mozork' Frick
+
+    @ingroup PickupItems
     */
     class _PickupExport MetaPickup : public Pickup
@@ -81 +101 @@
             @return Returns an enum with the meta type of the MetaPickup.
             */
-            inline pickupMetaType::Value getMetaTypeDirect(void)
+            inline pickupMetaType::Value getMetaTypeDirect(void) const
                 { return this->metaType_; }
-            const std::string& getMetaType(void); //!< Get the meta type of this MetaPickup.
+            const std::string& getMetaType(void) const; //!< Get the meta type of this MetaPickup.
 
         protected:

code/trunk/src/modules/pickup/items/ShieldPickup.cc

@@ -34 +34 @@
 #include "ShieldPickup.h"
 
+#include <sstream>
 #include "core/CoreIncludes.h"
 #include "core/XMLPort.h"
-#include "util/StringUtils.h"
-
-#include "worldentities/pawns/SpaceShip.h"
-#include "items/Engine.h"
+
 #include "pickup/PickupIdentifier.h"
-
-#include <sstream>
-
+#include "worldentities/pawns/Pawn.h"
 
 namespace orxonox
@@ -67 +63 @@
     {
 
-    }
-
-    /**
-    @brief
-    Helper to transform the PickupCarrier to a Pawn, and throw an error message if the conversion fails.
-    @return
-    A pointer to the Pawn, or NULL if the conversion failed.
-    */
-    Pawn* ShieldPickup::carrierToPawnHelper(void)
-    {
-        PickupCarrier* carrier = this->getCarrier();
-        Pawn* pawn = dynamic_cast<Pawn*>(carrier);
-
-        if(pawn == NULL)
-        {
-            COUT(1) << "Invalid PickupCarrier in ShieldPickup." << std::endl;
-        }
-        return pawn;
     }
 
@@ -134 +112 @@
         SUPER(ShieldPickup, XMLPort, xmlelement, mode);
 
-        XMLPortParam(ShieldPickup, "duration", setDuration, getDuration, xmlelement, mode);
         XMLPortParam(ShieldPickup, "shieldhealth", setShieldHealth, getShieldHealth, xmlelement, mode);
         XMLPortParam(ShieldPickup, "shieldabsorption", setShieldAbsorption, getShieldAbsorption, xmlelement, mode);
+        XMLPortParam(ShieldPickup, "duration", setDuration, getDuration, xmlelement, mode);
 
         this->initializeIdentifier();
@@ -149 +127 @@
         SUPER(ShieldPickup, changedUsed);
 
-        //! If the pickup is not picked up nothing must be done.
+        // If the pickup is not picked up nothing must be done.
         if(!this->isPickedUp())
             return;
@@ -157 +135 @@
             this->Pickupable::destroy();
 
-        //! If the pickup has transited to used.
+        // If the pickup has transited to used.
         if(this->isUsed())
         {
-            if(!this->durationTimer_.isActive() && this->durationTimer_.getRemainingTime() > 0.0f)
+            // If its durationType is continuous, we set a Timer to be reminded, when the time has run out.
+            if(this->isContinuous())
             {
-                this->durationTimer_.unpauseTimer();
-            }
-            else
-            {
-                this->durationTimer_.setTimer(this->getDuration(), false, createExecutor(createFunctor(&ShieldPickup::pickupTimerCallback, this)));
+                if(!this->durationTimer_.isActive() && this->durationTimer_.getRemainingTime() > 0.0f)
+                {
+                    this->durationTimer_.unpauseTimer();
+                }
+                else
+                {
+                    this->durationTimer_.setTimer(this->getDuration(), false, createExecutor(createFunctor(&ShieldPickup::pickupTimerCallback, this)));
+                }
             }
             pawn->setShieldAbsorption(this->getShieldAbsorption());
@@ -177 +159 @@
             pawn->setShieldHealth(0.0f);
 
-            if(this->isOnce())
+            // We destroy the pickup if either, the pickup has activationType immediate and durationType once or it has durationType continuous and the duration was exceeded.
+            if((!this->isContinuous() && this->isImmediate()) || (this->isContinuous() && !this->durationTimer_.isActive() && this->durationTimer_.getRemainingTime() == this->getDuration()))
             {
-                if(!this->durationTimer_.isActive() && this->durationTimer_.getRemainingTime() == this->getDuration())
-                {
-                    this->Pickupable::destroy();
-                }
-                else
-                {
-                    this->durationTimer_.pauseTimer();
-                }
+                this->Pickupable::destroy();
             }
-        }
+            // We pause the Timer if the pickup is continuous and the duration is not yet exceeded,
+            else if(this->isContinuous() && this->durationTimer_.isActive())
+            {
+                this->durationTimer_.pauseTimer();
+            }
+        }
+    }
+
+    /**
+    @brief
+    Helper to transform the PickupCarrier to a Pawn, and throw an error message if the conversion fails.
+    @return
+    A pointer to the Pawn, or NULL if the conversion failed.
+    */
+    Pawn* ShieldPickup::carrierToPawnHelper(void)
+    {
+        PickupCarrier* carrier = this->getCarrier();
+        Pawn* pawn = dynamic_cast<Pawn*>(carrier);
+
+        if(pawn == NULL)
+        {
+            COUT(1) << "Invalid PickupCarrier in ShieldPickup." << std::endl;
+        }
+        return pawn;
     }
 
@@ -213 +212 @@
     /**
     @brief
-    Sets the percentage the shield absorbs of the dealt damage.
+        Sets the duration.
+    @param duration
+        The duration in seconds.
+    */
+    void ShieldPickup::setDuration(float duration)
+    {
+        if(duration >= 0.0f)
+        {
+            this->duration_ = duration;
+        }
+        else
+        {
+            COUT(1) << "Invalid duration in ShieldPickup." << std::endl;
+            this->duration_ = 0.0f;
+        }
+    }
+
+    /**
+    @brief
+        Sets the health of the shield.
+    @param shieldHealth
+        The shieldHealth.
+    */
+    void ShieldPickup::setShieldHealth(float shieldHealth)
+    {
+        if (shieldHealth>=0)
+        {
+            this->shieldHealth_=shieldHealth;
+        }
+        else
+        {
+            COUT(1) << "Invalid Shieldhealth in ShieldPickup." << std::endl;
+            this->shieldHealth_=0;
+        }
+    }
+
+    /**
+    @brief
+        Sets the percentage the shield absorbs of the dealt damage.
     @param shieldAbsorption
-    The shieldAbsorption. Has to be between 0 and 1
+        The shieldAbsorption. Has to be between 0 and 1.
     */
     void ShieldPickup::setShieldAbsorption(float shieldAbsorption)
@@ -232 +269 @@
     /**
     @brief
-    Sets the health of the shield.
-    @param shieldHealth
-    The shieldHealth
-    */
-    void ShieldPickup::setShieldHealth(float shieldHealth)
-    {
-        if (shieldHealth>=0)
-        {
-            this->shieldHealth_=shieldHealth;
-        }
-        else
-        {
-            COUT(1) << "Invalid Shieldhealth in ShieldPickup." << std::endl;
-            this->shieldHealth_=0;
-        }
-    }
-
-    /**
-    @brief
-        Sets the duration.
-    @param duration
-        The duration
-    */
-    void ShieldPickup::setDuration(float duration)
-    {
-        if(duration >= 0.0f)
-        {
-            this->duration_ = duration;
-        }
-        else
-        {
-            COUT(1) << "Invalid duration in ShieldPickup." << std::endl;
-            this->duration_ = 0.0f;
-        }
-    }
-
+        Helper method. Is called by the Timer as soon as it expires.
+    */
     void ShieldPickup::pickupTimerCallback(void)
     {

code/trunk/src/modules/pickup/items/ShieldPickup.h

@@ -40 +40 @@
 
 #include <string>
-#include "worldentities/pawns/Pawn.h"
-#include "worldentities/StaticEntity.h"
 
 #include "pickup/Pickup.h"
@@ -51 +49 @@
         A Pickup which can add a Shield to the Pawn.
 
-        There are 4 parameters that can be cosen.
-        - The @b percentage The percentage the shield takes from the damage dealt to a Pawn
-        - The @b hit @b points The amount of damage points a shield can teake before collapsing
-        - The @b activation @b type 'immediate' or 'onUse'. defines if the item is used when it's picked up or only after the player chooses to use it.
-        - The @b duration the activation time of the pickup.
+        There are 5 parameters that can be cosen.
+        - The @b shieldhealth< The amount of damage points a shield can take before collapsing. The default is 0.
+        - The @b shieldabsorption The percentage the shield takes from the damage dealt to a Pawn. The default is 0.
+        - The @b activationType, <em>immediate</em> or <em>onUse</em>. defines if the ShiedlPickup is used when it's picked up or only after the player chooses to use it. The default is <em>immediate</em>.
+        - The @b durationType, <em>once</em> means, that the shield will stay until it collapses, <em>continuous</em> means, that the shield only stays for a limited amount of time, specifiey by the duration. The default is <em>once</em>.
+        - The @b duration the time in seconds the shield is active at the most. The default is 0.
+
+        An example of a XML implementation of a ShieldPickup would be:
+        @code
+        <ShieldPickup
+            shieldhealth = 30
+            shieldabsorption = 0.8
+            activationType = "immediate"
+            durationtype = "continuous"
+            duration = 20.0
+        />
+        @endcode
 
     @author
         Eric Beier
+
+    @ingroup PickupItems
     */
     class _PickupExport ShieldPickup : public Pickup
@@ -72 +84 @@
             virtual void clone(OrxonoxClass*& item); //!< Creates a duplicate of the input OrxonoxClass.
 
-            inline float getDuration(void)
+            /**
+            @brief Get the duration, the time the shield is actvie at the most.
+            @return Returns the duration in seconds.
+            */
+            inline float getDuration(void) const
                 { return this->duration_; }
-            inline float getShieldHealth()
+            /**
+            @brief Get the shield health, the amount of damage the shield can sustain.
+            @return Returns the shield health.
+            */
+            inline float getShieldHealth() const
                 { return this->shieldHealth_; }
-            inline float getShieldAbsorption()
+            /**
+            @brief Get the shield absorption, the percentage of damage that is absorbed by the shield.
+            @return Returns the shield absorption.
+            */
+            inline float getShieldAbsorption() const
                 { return this->shieldAbsorption_; }
 
         protected:
             void initializeIdentifier(void); //!< Initializes the PickupIdentifier of this pickup.
+            void pickupTimerCallback(void); //!< Helper method. Is called by the Timer as soon as it expires.
 
-            void pickupTimerCallback(void); //!< Function that gets called when timer ends.
-
-            void setDuration(float duration);
-            void setShieldHealth(float shieldHealth);
-            void setShieldAbsorption(float shieldAbsorption);
+            void setDuration(float duration); //!< Sets the duration.
+            void setShieldHealth(float shieldHealth); //!< Sets the health of the shield.
+            void setShieldAbsorption(float shieldAbsorption); //!< Sets the percentage the shield absorbs of the dealt damage.
 
         private:
@@ -95 +118 @@
 
             float duration_; //!< The health that is transferred to the Pawn.
-            float shieldHealth_;
-            float shieldAbsorption_; // Has to be between 0 and 1
+            float shieldHealth_; //!< The amount of damage the shield can sustain.
+            float shieldAbsorption_; //!< The percentage of damage that is absorbed by the shield.
 
     };

code/trunk/src/modules/pickup/items/SpeedPickup.cc

@@ -34 +34 @@
 #include "SpeedPickup.h"
 
+#include <sstream>
 #include "core/CoreIncludes.h"
 #include "core/XMLPort.h"
-#include "util/StringUtils.h"
-
-#include "worldentities/pawns/SpaceShip.h"
+
 #include "items/Engine.h"
 #include "pickup/PickupIdentifier.h"
-
-#include <sstream>
-
+#include "worldentities/pawns/SpaceShip.h"
 
 namespace orxonox
@@ -130 +127 @@
         SUPER(SpeedPickup, changedUsed);
 
-        //! If the pickup is not picked up nothing must be done.
+        // If the pickup is not picked up nothing must be done.
         if(!this->isPickedUp())
             return;
 
         Engine* engine = this->carrierToEngineHelper();
-        if(engine == NULL) //!< If the PickupCarrier is no Engine, then this pickup is useless and therefore is destroyed.
+        if(engine == NULL) // If the PickupCarrier is no Engine, then this pickup is useless and therefore is destroyed.
             this->Pickupable::destroy();
 
-        //! If the pickup has transited to used.
+        // If the pickup has transited to used.
         if(this->isUsed())
         {
-            if(!this->durationTimer_.isActive() && this->durationTimer_.getRemainingTime() > 0.0f)
+            // If its durationType is continuous, we set a Timer to be reminded, when the time has run out.
+            if(this->isContinuous())
             {
-                this->durationTimer_.unpauseTimer();
-            }
-            else
-            {
-                this->durationTimer_.setTimer(this->getDuration(), false, createExecutor(createFunctor(&SpeedPickup::pickupTimerCallback, this)));
-            }
-            engine->setSpeedAdd(this->getSpeedAdd());
-            engine->setSpeedMultiply(this->getSpeedMultiply());
-        }
-        else
-        {
-            engine->setSpeedAdd(0.0f);
-            engine->setSpeedMultiply(1.0f);
-
-            if(this->isOnce())
-            {
-                if(!this->durationTimer_.isActive() && this->durationTimer_.getRemainingTime() == this->getDuration())
+                if(!this->durationTimer_.isActive() && this->durationTimer_.getRemainingTime() > 0.0f)
                 {
-                    this->Pickupable::destroy();
+                    this->durationTimer_.unpauseTimer();
                 }
                 else
                 {
-                    this->durationTimer_.pauseTimer();
+                    this->durationTimer_.setTimer(this->getDuration(), false, createExecutor(createFunctor(&SpeedPickup::pickupTimerCallback, this)));
                 }
+            }
+
+            engine->setSpeedAdd(this->getSpeedAdd());
+            engine->setSpeedMultiply(this->getSpeedMultiply());
+        }
+        else
+        {
+            engine->setSpeedAdd(0.0f);
+            engine->setSpeedMultiply(1.0f);
+
+            // We destroy the pickup if either, the pickup has activationType immediate and durationType once or it has durationType continuous and the duration was exceeded.
+            if((!this->isContinuous() && this->isImmediate()) || (this->isContinuous() && !this->durationTimer_.isActive() && this->durationTimer_.getRemainingTime() == this->getDuration()))
+            {
+                this->Pickupable::destroy();
+            }
+            // We pause the Timer if the pickup is continuous and the duration is not yet exceeded,
+            else if(this->isContinuous() && this->durationTimer_.isActive())
+            {
+                this->durationTimer_.pauseTimer();
             }
         }
@@ -213 +214 @@
     /**
     @brief
-        Sets the duration.
+        Sets the duration for which the SpeedPickup stays active.
     @param duration
-        The duration
+        The duration in seconds.
     */
     void SpeedPickup::setDuration(float duration)
@@ -232 +233 @@
     /**
     @brief
-        Sets the SpeedAdd
+        Sets the speedAdd, the value that is added to the speed of the Pawn.
     @param speedAdd
-        The added Speed
+        The added speed.
     */
     void SpeedPickup::setSpeedAdd(float speedAdd)
@@ -251 +252 @@
     /**
     @brief
-        Sets the SpeedMultiply
+        Sets the speedMultiply, the factor by which the speed of the Pawn is multiplied.
     @param speedMultiply
-        The multiplied Speed
+        The factor by which the speed is mutiplied.
     */
     void SpeedPickup::setSpeedMultiply(float speedMultiply)

code/trunk/src/modules/pickup/items/SpeedPickup.h

@@ -39 +39 @@
 
 #include <string>
-#include "worldentities/pawns/Pawn.h"
-#include "worldentities/StaticEntity.h"
 
 #include "pickup/Pickup.h"
@@ -50 +48 @@
         A Pickup which can manipulate the Speed of a Pawn.
 
-        There are 4 parameters that can be cosen:
-        - The @b speed @b multiplier
-        - The @b additional (forward) @b speed
-        - The @b activation @b type 'immediate' or 'onUse'. defines if the item is used when it's picked up or only after the player chooses to use it.
-        - The @b duration The activation time of the pickup.
+        There are 5 parameters that can be cosen:
+        - The @b speedMultiply, specifies a factor by which the Spaceships speed is multiplied. The default is 1.
+        - The @b speedAdd, specifies a value that is added to the speed of the Spaceship. The default is 0.
+        - The @b activationType <em>immediate</em> or <em>onUse</em>, defines if the SpeedPickup is used when it's picked up or only after the player chooses to use it. The default is <em>immediate</em>.
+        - The @b durationType Can be either <em>once</em> or <em>continuous</em>. For <em>once</em> the SpeedPickup is just active for as long as it is used, for <em>continuous</em> the SpeedPickup is active only for the specified duration. The default is <em>once</em>.
+        - The @b duration The time in seconds the SpeedPickup is active at the most. The default is 0.
+
+        An example, how a SpeedPickup could be defined in XML could be:
+        @code
+        <SpeedPickup
+            speedMultiply = 2.0
+            speedAdd = 10.0
+            activationType = "immediate"
+            durationType = "continuous"
+            duration = 30.0
+        />
+        @endcode
 
     @author
         Eric Beier
+
+    @ingroup PickupItems
     */
     class _PickupExport SpeedPickup : public Pickup
@@ -71 +83 @@
             virtual void clone(OrxonoxClass*& item); //!< Creates a duplicate of the input OrxonoxClass.
 
-            inline float getDuration(void)
+            /**
+            @brief Get the duration, the time the SpeedPickup is active.
+            @return Returns the duration in seconds.
+            */
+            inline float getDuration(void) const
                 { return this->duration_; }
-            inline float getSpeedAdd(void)
+            /**
+            @brief Get the value that is added to the speed of the Pawn.
+            @return Returns the speedAdd.
+            */
+            inline float getSpeedAdd(void) const
                 { return this->speedAdd_; }
-            inline float getSpeedMultiply(void)
+            /**
+            @brief Get the factor by wich the speed of the Pawn is multplied.
+            @return Returns the speedMultiply.
+            */
+            inline float getSpeedMultiply(void) const
                 { return this->speedMultiply_; }
 
         protected:
             void initializeIdentifier(void); //!< Initializes the PickupIdentifier of this pickup.
-
             void pickupTimerCallback(void); //!< Function that gets called when timer ends.
 
-            void setDuration(float duration);
-            void setSpeedAdd(float speedAdd);
-            void setSpeedMultiply(float speedMultiply);
+            void setDuration(float duration); //!< Sets the duration.
+            void setSpeedAdd(float speedAdd); //!< Sets the SpeedAdd, the value that is added to the speed of the Pawn.
+            void setSpeedMultiply(float speedMultiply); //!< Sets the speedMultiply, the factor by which the speed of the Pawn is multiplied.
 
         private:
@@ -93 +116 @@
             Timer durationTimer_; //!< Timer.
 
-            float duration_; //!< The health that is transferred to the Pawn.
-            float speedAdd_;
-            float speedMultiply_;
+            float duration_; //!< The time in seconds for which the SpeedPickup stays active.
+            float speedAdd_; //!< The value that is added to the speed of the Pawn.
+            float speedMultiply_; //!< The factor by which the speed of the Pawn is multiplied.
     };
 }