Changeset 7547 for code/trunk/src/modules

Timestamp:

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

Author:

dafrick

Message:

Documenting and cleanup.

Location:

code/trunk/src/modules/pickup

Files:

• CollectiblePickup.h (modified) (1 diff)
• Pickup.cc (modified) (2 diffs)
• Pickup.h (modified) (8 diffs)
• PickupCollection.cc (modified) (3 diffs)
• PickupCollection.h (modified) (2 diffs)
• PickupManager.cc (modified) (1 diff)
• PickupManager.h (modified) (5 diffs)
• PickupRepresentation.h (modified) (5 diffs)
• PickupSpawner.cc (modified) (3 diffs)
• PickupSpawner.h (modified) (4 diffs)
• items/DronePickup.cc (modified) (1 diff)
• items/DronePickup.h (modified) (2 diffs)
• items/HealthPickup.cc (modified) (2 diffs)
• items/HealthPickup.h (modified) (5 diffs)
• items/InvisiblePickup.cc (modified) (7 diffs)
• items/InvisiblePickup.h (modified) (4 diffs)
• items/MetaPickup.cc (modified) (5 diffs)
• items/MetaPickup.h (modified) (3 diffs)
• items/ShieldPickup.cc (modified) (8 diffs)
• items/ShieldPickup.h (modified) (4 diffs)
• items/SpeedPickup.cc (modified) (5 diffs)
• items/SpeedPickup.h (modified) (4 diffs)

code/trunk/src/modules/pickup/CollectiblePickup.h

@@ -67 +67 @@
             @return Returns true if the CollectiblePickup is part of a PickupCollection.
             */
-            bool isInCollection(void)
+            bool isInCollection(void) const
                 { return this->isInCollection_; }
 

code/trunk/src/modules/pickup/Pickup.cc

@@ -119 +119 @@
         Returns a string containing the activation type.
     */
-    const std::string& Pickup::getActivationType(void)
+    const std::string& Pickup::getActivationType(void) const
     {
         switch(this->activationType_)
@@ -138 +138 @@
         Returns a string containing the duration type.
     */
-    const std::string& Pickup::getDurationType(void)
+    const std::string& Pickup::getDurationType(void) const
     {
         switch(this->durationType_)

code/trunk/src/modules/pickup/Pickup.h

@@ -40 +40 @@
 #include "core/BaseObject.h"
 #include "core/XMLPort.h"
+#include "tools/Timer.h"
 
 #include "CollectiblePickup.h"
-
-#include "tools/Timer.h"
 
 namespace orxonox
@@ -83 +82 @@
 
         Pickups ingeriting from this class can choose an activation type and a duration type.
-        - The <b>activation type</b> deals with what happens to the Pickup as soon as it is picked up. It can either be set to <em>immediate</em>, which means that the Pickup is activated/used immediately upon being picked up. Or to <em>onUse</em>, which means, that the Pickup will be activated/used if some outside entity (most commonly the player through the PickupInventory) decides to use it.
-        - The <b>duration type</b> deals with whether the Pickup has a continuous effect or whether its effect is focused on a singular instant. It can either be set to <em>once</em>, which means, that the Pickup just has an effect (at a singular instant in time) and is done once that effect has been applied. Or to <em>continuous</em>, which means that the effect of the Pickup unfolds over some timespan.
+        - The <b>activationType</b> deals with what happens to the Pickup as soon as it is picked up. It can either be set to <em>immediate</em>, which means that the Pickup is activated/used immediately upon being picked up. Or to <em>onUse</em>, which means, that the Pickup will be activated/used if some outside entity (most commonly the player through the PickupInventory) decides to use it. Default is <em>immediate</em>.
+        - The <b>durationType</b> deals with whether the Pickup has a continuous effect or whether its effect is focused on a singular instant. It can either be set to <em>once</em>, which means, that the Pickup just has an effect (at a singular instant in time) and is done once that effect has been applied. Or to <em>continuous</em>, which means that the effect of the Pickup unfolds over some timespan. Default is <em>once</em>.
 
         If it were not an abstract class it could for example be used as follows in XML.
@@ -110 +109 @@
             @return Returns the activation type of the Pickup.
             */
-            inline pickupActivationType::Value getActivationTypeDirect(void)
+            inline pickupActivationType::Value getActivationTypeDirect(void) const
                 { return this->activationType_; }
             /**
@@ -116 +115 @@
             @return Returns the duration type of the Pickup.
             */
-            inline pickupDurationType::Value getDurationTypeDirect(void)
+            inline pickupDurationType::Value getDurationTypeDirect(void) const
                 { return this->durationType_; }
 
-            const std::string& getActivationType(void); //!< Get the activation type of the Pickup.
-            const std::string& getDurationType(void); //!< Get the duration type of the Pickup.
+            const std::string& getActivationType(void) const; //!< Get the activation type of the Pickup.
+            const std::string& getDurationType(void) const; //!< Get the duration type of the Pickup.
 
             /**
@@ -126 +125 @@
             @return Returns true if the activation type is 'immediate'.
             */
-            inline bool isImmediate(void)
+            inline bool isImmediate(void) const
                 { return this->getActivationTypeDirect() == pickupActivationType::immediate; }
             /**
@@ -132 +131 @@
             @return Returns true if the activation type is 'onUse'.
             */
-            inline bool isOnUse(void)
+            inline bool isOnUse(void) const
                 { return this->getActivationTypeDirect() == pickupActivationType::onUse; }
             /**
@@ -138 +137 @@
             @return Returns true if the duration type is 'once'.
             */
-            inline bool isOnce(void)
+            inline bool isOnce(void) const
                 { return this->getDurationTypeDirect() == pickupDurationType::once; }
             /**
@@ -144 +143 @@
             @return Returns true if the duration type is 'continuous'.
             */
-            inline bool isContinuous(void)
+            inline bool isContinuous(void) const
                 { return this->getDurationTypeDirect() == pickupDurationType::continuous; }
 
             virtual void changedPickedUp(void); //!< Should be called when the pickup has transited from picked up to dropped or the other way around.
-
             virtual void clone(OrxonoxClass*& item); //!< Creates a duplicate of the OrxonoxClass.
 

code/trunk/src/modules/pickup/PickupCollection.cc

@@ -235 +235 @@
         Returns true if the PickupCarrier identified by the input PickupIdentififer it is a target of this PickupCollection, false if not.
     */
-    bool PickupCollection::isTarget(PickupCarrier* carrier) const
+    bool PickupCollection::isTarget(const PickupCarrier* carrier) const
     {
         for(std::vector<CollectiblePickup*>::const_iterator it = this->pickups_.begin(); it != this->pickups_.end(); it++)
@@ -253 +253 @@
         Returns a pointer to the PickupIdentifier of this PickupCollection.
     */
-    const PickupIdentifier* PickupCollection::getPickupIdentifier(void)
+    const PickupIdentifier* PickupCollection::getPickupIdentifier(void) const
     {
         return this->pickupCollectionIdentifier_;
@@ -284 +284 @@
         Returns a pointer to the Pickupable at the index given by index.
     */
-    const Pickupable* PickupCollection::getPickupable(unsigned int index)
+    const Pickupable* PickupCollection::getPickupable(unsigned int index) const
     {
         return this->pickups_[index];

code/trunk/src/modules/pickup/PickupCollection.h

@@ -38 +38 @@
 #include "PickupPrereqs.h"
 
+#include <list>
+
+#include "CollectiblePickup.h"
 #include "core/BaseObject.h"
-#include "CollectiblePickup.h"
-
-#include <list>
 
 namespace orxonox
@@ -83 +83 @@
             virtual void clone(OrxonoxClass*& item); //!< Creates a duplicate of the input pickup.
 
-            virtual bool isTarget(PickupCarrier* carrier) const; //!< Get whether a given class, represented by the input Identifier, is a target of this PickupCollection.
+            virtual bool isTarget(const PickupCarrier* carrier) const; //!< Get whether a given class, represented by the input Identifier, is a target of this PickupCollection.
 
-            virtual const PickupIdentifier* getPickupIdentifier(void); //!< Get the PickupIdentifier of this PickupCollection.
+            virtual const PickupIdentifier* getPickupIdentifier(void) const; //!< Get the PickupIdentifier of this PickupCollection.
 
             bool addPickupable(CollectiblePickup* pickup); //!< Add the input Pickupable to list of Pickupables combined by this PickupCollection.
-            const Pickupable* getPickupable(unsigned int index); //!< Get the Pickupable at the given index.
+            const Pickupable* getPickupable(unsigned int index) const; //!< Get the Pickupable at the given index.
 
             void pickupChangedUsed(bool changed); //!< Informs the PickupCollection, that one of its pickups has changed its used status to the input value.

code/trunk/src/modules/pickup/PickupManager.cc

@@ -389 +389 @@
     @param pickup
         A number identifying the Pickupable that changed its pickedUp status.
-    @param unusable
-        Whether the Pickupable's used status can be changed to unused in the PickupInventory.
+    @param usable
+        Whether the Pickupable's used status can be changed to used in the PickupInventory.
     @param representationObjectId
         The objectId identifying (over the network) the PickupRepresentation that represents this Pickupable.

code/trunk/src/modules/pickup/PickupManager.h

@@ -39 +39 @@
 
 #include <map>
-
 #include "core/WeakPtr.h"
 
@@ -75 +74 @@
         The PickupManager class manages @ref orxonox::Pickupable "Pickupables".
 
-        It has in essence two tasks to fulfill. Firstly it must link @ref orxonox::Pickupable "Pickupables" (through their @ref orxonox::PickupIdentifier "PickupIdentifiers") to their respective @ref orxonox:PickupRepresentation "PickupRepresentations". Secondly it manages the PickupInventory. (The PickupInventory is the GUI that displays @ref roxonox::Pickupable "Pickupables" for the covenience of the user.)
+        It has in essence two tasks to fulfill. Firstly it must link @ref orxonox::Pickupable "Pickupables" (through their @ref orxonox::PickupIdentifier "PickupIdentifiers") to their respective @ref orxonox::PickupRepresentation "PickupRepresentations". Secondly it manages the PickupInventory. (The PickupInventory is the GUI that displays @ref orxonox::Pickupable "Pickupables" for the covenience of the user.)
 
         @section PickupManagerTechnicalDetails Technical details
@@ -89 +88 @@
         - The @ref orxonox::PickupManager::representations_ "representations_" list links @ref orxonox::PickupRepresentation "PickupRepresentations" with @ref orxonox::PickupIdentifier "PickupIdentifiers" and can be used to get the @ref orxonox::PickupRepresentation "PickupRepresentation" for a given @ref orxonox::Pickupable "Pickupable". It is only populated on the server (or in standalone mode). Each @ref orxonox::PickupRepresentation "PickupRepresentation" that is generated through XML registers itself with the PickupManager and is thereby added to the list.
         - The @ref orxonox::PickupManager::representationsNetworked_ "representationsNetworked_" list is the networked (hence the name) equivalent to the @ref orxonox::PickupManager::representations_ "representations_" list. It links an objectId of a @ref orxonox::PickupRepresentation "PickupRepresentation" to a @ref orxonox::PickupRepresentation "PickupRepresentation". This list is maintained on all hosts, each representation registers itself (in its constructor) with the PickupManager. Since the representations are synchronised they are created on each host. The "same" instance on each host is identified by the same objectId and that is why we store the representations with the objectId as key. We can then use this list to get a @ref orxonox::PickupRepresentation "PickupRepresentation" for a specific @ref orxonox::Pickupable "Pickupable" (or more precisely a number identifiying that particular pickup, but we'll see that, when we look at the next list) on a client to be used in the PickupInventory.
-        - The @ref orxonox::PickupManager::pickupInventoryContainers_ "pickupInventoryContainers_" list links a number identifying a @ref orxonox::Pickupable "Pickupable" to a data structure (the @ref orxonox::PickupInventoryContainer "PickupInventoryContainer"), which contains all necessary information about that @ref orxonox::Pickupable "Pickupable". This list is maintained on all hosts, a new container is inserted when a @ref orxonox::Pickupable "Pickupable" is picked up, but only if it has been picked up by the repsective host. This list is then used by the PickupInventory to access the required information and to get the correct @ref orxonox:.PickupRepresentation "PickupRepresentation".
+        - The @ref orxonox::PickupManager::pickupInventoryContainers_ "pickupInventoryContainers_" list links a number identifying a @ref orxonox::Pickupable "Pickupable" to a data structure (the @ref orxonox::PickupInventoryContainer "PickupInventoryContainer"), which contains all necessary information about that @ref orxonox::Pickupable "Pickupable". This list is maintained on all hosts, a new container is inserted when a @ref orxonox::Pickupable "Pickupable" is picked up, but only if it has been picked up by the repsective host. This list is then used by the PickupInventory to access the required information and to get the correct @ref orxonox::PickupRepresentation "PickupRepresentation".
         - The @ref orxonox::PickupManager::pickups_ "pickups_" list links a number identifiying a @ref orxonox::Pickupable "Pickupable" to a (weak pointer to a) @ref orxonox::Pickupable "Pickupable". It is only maintained by the server (or in standalone mode), to be able to use, unuse and drop @ref orxonox::Pickupable "Pickupables" through the PickupInventory. Since @ref orxonox::Pickupable "Pickupables" only exist on the server a client that wants to change a pickups status has so send a request over the network (with the number identifying the pickup) to the server and then the server facilitates the change, using this list to map from the identifyer to the actual @ref orxonox::Pickupable "Pickupable".
         - The @ref orxonox::PickupManager::indexes_ "indexes_" list links a @ref orxonox::Pickupable "Pickupable" to the number identifying it. This is only maintained on the server (or in standalone mode), and is used for the inverse mapping of the previous list, which means the server uses it identify pickups on clients when it communicates changes in pickups to clients.
@@ -139 +138 @@
             @return Returns the next PickupInventoryContainer in the list.
             */
-            orxonox::PickupInventoryContainer* popPickup(void)
+            const orxonox::PickupInventoryContainer* popPickup(void)
                 { return (this->pickupsIterator_++)->second; }
 
@@ -149 +148 @@
             @return Returns true if the input Pickupable is still valid, false if not.
             */
-            bool isValidPickup(uint32_t pickup)
+            const bool isValidPickup(uint32_t pickup) const
                 { return this->pickups_.find(pickup) != this->pickups_.end(); }
             // tolua_end

code/trunk/src/modules/pickup/PickupRepresentation.h

@@ -39 +39 @@
 
 #include "core/XMLPort.h"
+
 #include "interfaces/Pickupable.h"
 #include "pickup/PickupIdentifier.h"
@@ -53 +54 @@
     /**
     @brief
-        The PickupRepresentation class represents a specific pickup type (identified by its @ref orxonox::PickupIdentififer "PickupIdentifier"). It defines the information displayed in the GUI (PickupInventory) and how @ref orxonox::PickupSpawner "PickupSpawners" that spawn the pickup type look like.
+        The PickupRepresentation class represents a specific pickup type (identified by its @ref orxonox::PickupIdentifier "PickupIdentifier"). It defines the information displayed in the GUI (PickupInventory) and how @ref orxonox::PickupSpawner "PickupSpawners" that spawn the pickup type look like.
         They are created through XML and are registered with the @ref orxonox::PickupManager "PickupManager".
 
@@ -71 +72 @@
         As you might have noticed, there is a parameter called <em>spawnerTemplate</em> and also another parameter called <em>inventoryRepresentation</em>. Let's first explain the second one, <em>inventoryRepresentation</em>.
         - The <b>inventoryRepresentation</b> specifies the image that is displayed in the PickupInventory for the specific type of @ref orxonox::Pickupable "Pickupable". More technically, it is the name of an image located in the <code>PickupInventory.imageset</code>, which in turn is located in <code>data_extern/gui/imagesets/</code>.
-        - The <b>spawnerTemplate</b> specifies how the type of @ref orxonox::Pickupable "Pickupable" (or more precisely the @ref orxonox::PickupSpawner "PickupSpawner", that spawns that type of @ref orxonox::Pickupable "Pickupable") is displayed ingame. It is a @ref orxnox::Template "Template" defined in XML. The <em>spawnerTemplate</em> can be specified as follows (keep in mind, that the template needs to have been specified before the definition of the PickupRepresentation that uses it).
+        - The <b>spawnerTemplate</b> specifies how the type of @ref orxonox::Pickupable "Pickupable" (or more precisely the @ref orxonox::PickupSpawner "PickupSpawner", that spawns that type of @ref orxonox::Pickupable "Pickupable") is displayed ingame. It is a @ref orxonox::Template "Template" defined in XML. The <em>spawnerTemplate</em> can be specified as follows (keep in mind, that the template needs to have been specified before the definition of the PickupRepresentation that uses it).
         @code
         <Template name="awesomePickupRepresentation">
@@ -105 +106 @@
 
             /**
+            @brief Get the name of the Pickupable represented by this PickupRepresentation.
+            @return Returns the name.
+            */
+            inline const std::string& getPickupName(void) const { return this->name_; } // tolua_export
+            /**
+            @brief Get the description of the Pickupable represented by this PickupRepresentation.
+            @return Returns the description.
+            */
+            inline const std::string& getPickupDescription(void) const { return this->description_; } // tolua_export
+            /**
+            @brief Get the name of spawnerTemplate the Pickupable represented by this PickupRepresentation.
+            @return Returns the name of the spawnerTemplate.
+            */
+            inline const std::string& getSpawnerTemplate(void) const
+                { return this->spawnerTemplate_; }
+            /**
+            @brief Get the StaticEntity that defines how the PickupSpawner of the Pickupable represented by this PickupRepresentation looks like.
+            @param index The index.
+            @return Returns (for index = 0) a pointer to the StaticEntity. For index > 0 it returns NULL.
+            */
+            inline const StaticEntity* getSpawnerRepresentationIndex(unsigned int index) const
+                { if(index == 0) return this->spawnerRepresentation_; return NULL; }
+            /**
+            @brief Get the name of the image representing the pickup in the PickupInventory.
+            @return Returns the name of the image as a string.
+            */
+            inline const std::string& getInventoryRepresentation(void) const { return this->inventoryRepresentation_; } // tolua_export
+            /**
+            @brief Get the Pickupable represented by this PickupRepresentation.
+            @param index The index.
+            @return Returns (for index = 0) a pointer to the Pickupable. For index > 0 it returns NULL.
+            */
+            inline const Pickupable* getPickup(unsigned int index) const
+                { if(index == 0) return this->pickup_; return NULL; }
+
+            StaticEntity* getSpawnerRepresentation(PickupSpawner* spawner); //!< Get a spawnerRepresentation for a specific PickupSpawner.
+
+        protected:
+            /**
             @brief Set the name of the Pickupable represented by this PickupRepresentation.
             @param name The name.
@@ -142 +182 @@
             inline void setPickup(Pickupable* pickup)
                 { this->pickup_ = pickup; }
-
-            /**
-            @brief Get the name of the Pickupable represented by this PickupRepresentation.
-            @return Returns the name.
-            */
-            inline const std::string& getPickupName(void) { return this->name_; } // tolua_export
-            /**
-            @brief Get the description of the Pickupable represented by this PickupRepresentation.
-            @return Returns the description.
-            */
-            inline const std::string& getPickupDescription(void) { return this->description_; } // tolua_export
-            /**
-            @brief Get the name of spawnerTemplate the Pickupable represented by this PickupRepresentation.
-            @return Returns the name of the spawnerTemplate.
-            */
-            inline const std::string& getSpawnerTemplate(void)
-                { return this->spawnerTemplate_; }
-            /**
-            @brief Get the StaticEntity that defines how the PickupSpawner of the Pickupable represented by this PickupRepresentation looks like.
-            @param index The index.
-            @return Returns (for index = 0) a pointer to the StaticEntity. For index > 0 it returns NULL.
-            */
-            inline const StaticEntity* getSpawnerRepresentationIndex(unsigned int index)
-                { if(index == 0) return this->spawnerRepresentation_; return NULL; }
-            /**
-            @brief Get the name of the image representing the pickup in the PickupInventory.
-            @return Returns the name of the image as a string.
-            */
-            inline const std::string& getInventoryRepresentation(void) { return this->inventoryRepresentation_; } // tolua_export
-            /**
-            @brief Get the Pickupable represented by this PickupRepresentation.
-            @param index The index.
-            @return Returns (for index = 0) a pointer to the Pickupable. For index > 0 it returns NULL.
-            */
-            inline const Pickupable* getPickup(unsigned int index)
-                { if(index == 0) return this->pickup_; return NULL; }
-
-            StaticEntity* getSpawnerRepresentation(PickupSpawner* spawner); //!< Get a spawnerRepresentation for a specific PickupSpawner.
 
         private:

code/trunk/src/modules/pickup/PickupSpawner.cc

@@ -38 +38 @@
 #include "core/Template.h"
 #include "core/XMLPort.h"
+
 #include "worldentities/pawns/Pawn.h"
+
 #include "PickupManager.h"
 #include "PickupRepresentation.h"
@@ -187 +189 @@
                 PickupCarrier* carrier = dynamic_cast<PickupCarrier*>(*it);
                 // If a Pawn, that fits the target-range of the item spawned by this Pickup, is in trigger-distance.
-                if (distance.length() < this->triggerDistance_ && carrier != NULL && carrier->isTarget(this->pickup_))
+                if (distance.length() < this->triggerDistance_ && carrier != NULL)
                 {
-                    this->trigger(*it);
+                    if(carrier->isTarget(this->pickup_))
+                        this->trigger(*it);
                 }
             }
@@ -270 +273 @@
         Returns the Pickupable that is spawned by this PickupSpawner.
     */
-    const Pickupable* PickupSpawner::getPickupable(void)
+    const Pickupable* PickupSpawner::getPickupable(void) const
     {
         return this->pickup_;

code/trunk/src/modules/pickup/PickupSpawner.h

@@ -39 +39 @@
 
 #include <string>
-
 #include "tools/Timer.h"
 
@@ -92 +91 @@
                 { return this->triggerDistance_; }
             /**
-            @brief Set the distance in which to trigger.
-            @param value The new distance in which to trigger.
-            */
-            inline void setTriggerDistance(float value)
-                { this->triggerDistance_ = value; }
-
-            /**
             @brief Get the time to respawn.
             @returns Returns the time after which this gets re-actived.
@@ -105 +97 @@
                 { return this->respawnTime_; }
             /**
+            @brief Get the maximum number of items that will be spawned by this PickupSpawner.
+            @return Returns the maximum number of items spawned by this PickupSpawner.
+            */
+            inline int getMaxSpawnedItems(void) const
+                { return this->maxSpawnedItems_; }
+            
+
+        protected:
+            void decrementSpawnsRemaining(void); //!< Decrements the number of remaining spawns.
+            void startRespawnTimer(void);
+
+            /**
+            @brief Set the distance in which to trigger.
+            @param value The new distance in which to trigger.
+            */
+            inline void setTriggerDistance(float value)
+                { this->triggerDistance_ = value; }
+            /**
             @brief Set the time to respawn.
             @param time New time after which this gets re-actived.
@@ -110 +120 @@
             inline void setRespawnTime(float time)
                 { this->respawnTime_ = time; }
-
-            /**
-            @brief Get the maximum number of items that will be spawned by this PickupSpawner.
-            @return Returns the maximum number of items spawned by this PickupSpawner.
-            */
-            inline int getMaxSpawnedItems(void)
-                { return this->maxSpawnedItems_; }
             void setMaxSpawnedItems(int items); //!< Sets the maximum number of spawned items.
-
-        protected:
-            void decrementSpawnsRemaining(void); //!< Decrements the number of remaining spawns.
-
-            void startRespawnTimer(void);
 
             virtual Pickupable* getPickup(void); //!< Creates a new Pickupable.
 
             void setPickupable(Pickupable* pickup); //!< Sets a Pickupable for the PickupSpawner to spawn.
-            const Pickupable* getPickupable(void); //!< Get the Pickupable that is spawned by this PickupSpawner.
+            const Pickupable* getPickupable(void) const; //!< Get the Pickupable that is spawned by this PickupSpawner.
 
             Pickupable* pickup_; //!< The pickup to be spawned.

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.
     };
 }