Changeset 7533 for code/trunk/src/modules

Timestamp:

Oct 13, 2010, 11:35:18 AM (14 years ago)

Author:

dafrick

Message:

Documenting in pickups module.
Cleaning up in PickupManager.
Removed some obsolete functions in HumanController and ControllableEntity, which were remenants of the old pickups module.
Fixed a bug.

Location:

code/trunk/src/modules/pickup

Files:

• CollectiblePickup.h (modified) (1 diff)
• DroppedPickup.h (modified) (1 diff)
• Pickup.cc (modified) (1 diff)
• Pickup.h (modified) (3 diffs)
• PickupCollection.cc (modified) (2 diffs)
• PickupCollection.h (modified) (1 diff)
• PickupCollectionIdentifier.cc (modified) (2 diffs)
• PickupCollectionIdentifier.h (modified) (1 diff)
• PickupManager.cc (modified) (21 diffs)
• PickupManager.h (modified) (3 diffs)
• PickupRepresentation.cc (modified) (1 diff)
• items/MetaPickup.cc (modified) (1 diff)
• items/MetaPickup.h (modified) (1 diff)

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

@@ -50 +50 @@
     @author
         Damian 'Mozork' Frick
+
+    @ingroup Pickup
     */
     class _PickupExport CollectiblePickup : public Pickupable

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

@@ -51 +51 @@
     @author
         Damian 'Mozork' Frick
+
+    @ingroup Pickup
     */
     class _PickupExport DroppedPickup : public PickupSpawner
     {
         public:
-            DroppedPickup(BaseObject* creator); //!< Default constructor.
+            DroppedPickup(BaseObject* creator);
             DroppedPickup(BaseObject* creator, Pickupable* pickup, PickupCarrier* carrier, float triggerDistance = 10.0); //!< Constructor.
-            virtual ~DroppedPickup(); //!< Destructor.
+            virtual ~DroppedPickup();
 
         protected:

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

@@ -44 +44 @@
 {
 
+    //! Initializing the static strings.
     /*static*/ const std::string Pickup::activationTypeImmediate_s = "immediate";
     /*static*/ const std::string Pickup::activationTypeOnUse_s = "onUse";

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

@@ -48 +48 @@
 {
 
-    //! Enum for the @ref orxonox::Pickup "Pickup" activation type.
+    /**
+    @brief
+        Enum for the @ref orxonox::Pickup "Pickup" activation type.
+
+    @ingroup Pickup
+    */
     namespace pickupActivationType
     {
@@ -58 +63 @@
     }
 
-    //! Enum for the @ref orxonox::Pickup "Pickup" duration type.
+    /**
+    @brief
+        Enum for the @ref orxonox::Pickup "Pickup" duration type.
+
+    @ingroup Pickup
+    */
     namespace pickupDurationType
     {
@@ -84 +94 @@
     @author
         Damian 'Mozork' Frick
+
+    @ingroup Pickup
     */
     class _PickupExport Pickup : public CollectiblePickup, public BaseObject

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

@@ -118 +118 @@
         // Change used for all Pickupables this PickupCollection consists of.
         for(std::vector<CollectiblePickup*>::iterator it = this->pickups_.begin(); it != this->pickups_.end(); it++)
-        {
             (*it)->setUsed(this->isUsed());
-        }
+
         this->processingUsed_ = false;
 
@@ -176 +175 @@
         // Change the pickedUp status for all Pickupables this PickupCollection consists of.
         for(std::vector<CollectiblePickup*>::iterator it = this->pickups_.begin(); it != this->pickups_.end(); it++)
-        {
             (*it)->setPickedUp(this->isPickedUp());
-        }
+
         this->processingPickedUp_ = false;
 

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

@@ -65 +65 @@
     @author
         Damian 'Mozork' Frick
+
+    @ingroup Pickup
     */
     class _PickupExport PickupCollection : public CollectiblePickup, public BaseObject

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

@@ -69 +69 @@
         assert(identifier);
 
-        // Slight un-niceity to cast the PickupIdentifier to a PickupCollectionIdentifier.
+        // Slight un-niceity to cast the const PickupIdentifier to a const PickupCollectionIdentifier, but since we cast to a const, there is no harm done.
         PickupIdentifier* temp = const_cast<PickupIdentifier*>(identifier);
         const PickupCollectionIdentifier* collectionIdentifier = orxonox_cast<PickupCollectionIdentifier*>(temp);
@@ -94 +94 @@
         }
 
-        // Means they are equal.
+        // This means they are equal.
         return 0;
     }

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

@@ -51 +51 @@
 
         @ref orxonox::Pickupable "Pickupables" (resp. @ref orxonox::CollectiblePickup "CollectiblePickups") can be added to the PickupCollectionIdentifier via the addPickup method.
+
     @author
         Damian 'Mozork' Frick
+
+    @ingroup Pickup
     */
     class _PickupExport PickupCollectionIdentifier : public PickupIdentifier

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

@@ -42 +42 @@
 #include "network/Host.h"
 #include "network/NetworkFunction.h"
+
 #include "interfaces/PickupCarrier.h"
 #include "infos/PlayerInfo.h"
 #include "worldentities/pawns/Pawn.h"
+
 #include "CollectiblePickup.h"
 #include "PickupRepresentation.h"
@@ -57 +59 @@
     ManageScopedSingleton(PickupManager, ScopeID::Root, false);
 
+    // Initialization of the name of the PickupInventory GUI.
     /*static*/ const std::string PickupManager::guiName_s = "PickupInventory";
 
+    // Register static newtork functions that are used to communicate changes to pickups over the network, such that the PickupInventory can display the information about the pickups properly.
     registerStaticNetworkFunction(PickupManager::pickupChangedUsedNetwork);
     registerStaticNetworkFunction(PickupManager::pickupChangedPickedUpNetwork);
@@ -68 +72 @@
         Constructor. Registers the PickupManager and creates the default PickupRepresentation.
     */
-    PickupManager::PickupManager() : guiLoaded_(false), pickupIndex_(0), defaultRepresentation_(NULL)
+    PickupManager::PickupManager() : guiLoaded_(false), pickupHighestIndex_(0), defaultRepresentation_(NULL)
     {
         RegisterObject(PickupManager);
 
+        //TODO: Only create if isMaster().
         this->defaultRepresentation_ = new PickupRepresentation();
 
@@ -80 +85 @@
     @brief
         Destructor.
-        Destroys the default PickupRepresentation.
+        Destroys the default PickupRepresentation and does some cleanup.
     */
     PickupManager::~PickupManager()
     {
+        // Destroying the default representation.
         if(this->defaultRepresentation_ != NULL)
             this->defaultRepresentation_->destroy();
 
         this->representations_.clear();
-
-        //TODO: Destroy properly...
+        this->representationsNetworked_.clear();
+
+        //TODO: Destroying properly?
+        //TODO: Shouldnt these list be empty, to avoid problems when switching levels?
+        // Destroying all the PickupInventoryContainers that are still there.
+        for(std::map<uint32_t, PickupInventoryContainer*>::iterator it = this->pickupInventoryContainers_.begin(); it != this->pickupInventoryContainers_.end(); it++)
+            delete it->second;
+        this->pickupInventoryContainers_.clear();
+
+        // Destroying all the WeakPointers that are still there.
+        for(std::map<uint32_t, WeakPtr<Pickupable>*>::iterator it = this->pickups_.begin(); it != this->pickups_.end(); it++)
+            delete it->second;
+        this->pickups_.clear();
+
+        this->indexes_.clear();
 
         COUT(3) << "PickupManager destroyed." << std::endl;
@@ -96 +115 @@
     /**
     @brief
-        Registers a PickupRepresentation together with the PickupIdentifier of the Pickupable the PickupRepresentation represents.
-        For every type of Pickupable (uniquely idnetified by a PickupIdentifier) there can be one (and just one) PickupRepresentation registered.
+        Registers a PickupRepresentation together with the PickupIdentifier of the Pickupable the PickupRepresentation represents, on the server (or in standalone mode).
+        For every type of Pickupable (uniquely identified by a PickupIdentifier) there can be one (and just one) PickupRepresentation registered.
     @param identifier
         The PickupIdentifier identifying the Pickupable.
@@ -110 +129 @@
         assert(representation);
 
-        if(!this->representations_.empty() && this->representations_.find(identifier) != this->representations_.end()) // If the Pickupable already has a Representation registered.
+        // If the list is not empty and Pickupable already has a Representation registered.
+        if(!this->representations_.empty() && this->representations_.find(identifier) != this->representations_.end())
             return false;
 
@@ -119 +139 @@
     }
 
-    bool PickupManager::registerRepresentation(PickupRepresentation* representation)
-    {
-        assert(representation);
-
-        if(!this->representationsNetworked_.empty() && this->representationsNetworked_.find(representation->getObjectID()) != this->representationsNetworked_.end()) // If the PickupRepresentation is already registered.
-            return false;
-
-        this->representationsNetworked_[representation->getObjectID()] = representation;
-        return true;
-    }
-
-    /**
-    @brief
-        Unegisters a PickupRepresentation together with the PickupIdentifier of the Pickupable the PickupRepresentation represents.
+    /**
+    @brief
+        Unegisters a PickupRepresentation together with the PickupIdentifier of the Pickupable the PickupRepresentation represents, on the server (or in standalone mode).
     @param identifier
         The PickupIdentifier identifying the Pickupable.
@@ -146 +155 @@
 
         std::map<const PickupIdentifier*, PickupRepresentation*, PickupIdentifierCompare>::iterator it = this->representations_.find(identifier);
-        if(it == this->representations_.end()) //!< If the Pickupable is not registered in the first place.
+        if(it == this->representations_.end()) // If the Pickupable is not registered in the first place.
             return false;
 
@@ -155 +164 @@
     }
 
+    /**
+    @brief
+        Registers a PickupRepresentation on the host it was created.
+    @param representation
+        A pointer to the PickupRepresentation.
+    @return
+        Returns true if successful, false if not.
+    */
+    bool PickupManager::registerRepresentation(PickupRepresentation* representation)
+    {
+        assert(representation);
+
+        // If the list is not empty and PickupRepresentation is already registered.
+        if(!this->representationsNetworked_.empty() && this->representationsNetworked_.find(representation->getObjectID()) != this->representationsNetworked_.end())
+            return false;
+
+        this->representationsNetworked_[representation->getObjectID()] = representation;
+        return true;
+    }
+
+    /**
+    @brief
+        Unregisters a PickupRepresentation on the host it is being destroyed (which is the same host on which it was created).
+    @param representation
+        A pointer to the Pickuprepresentation.
+    @return
+        Returns true if successful, false if not.
+    */
     bool PickupManager::unregisterRepresentation(PickupRepresentation* representation)
     {
@@ -160 +197 @@
 
         std::map<uint32_t, PickupRepresentation*>::iterator it = this->representationsNetworked_.find(representation->getObjectID());
-        if(it == this->representationsNetworked_.end()) //!< If the Pickupable is not registered in the first place.
+        if(it == this->representationsNetworked_.end()) // If the Pickupable is not registered in the first place.
             return false;
 
@@ -175 +212 @@
         Returns a pointer to the PickupRepresentation.
     */
+    //TODO: Why not return a const?
     PickupRepresentation* PickupManager::getRepresentation(const PickupIdentifier* identifier)
     {
         std::map<const PickupIdentifier*, PickupRepresentation*, PickupIdentifierCompare>::iterator it = this->representations_.find(identifier);
-        if(it == this->representations_.end())
+        if(it == this->representations_.end()) // If there is no PickupRepresentation associated with the input PickupIdentifier.
         {
             COUT(4) << "PickupManager::getRepresentation() returned default representation." << std::endl;
@@ -189 +227 @@
     /**
     @brief
-        Get the PickupRepresentation of an input Pickupable.
-        This method spares us the hassle to export the PickupIdentifier class to lua.
-    @param pickup
-        The Pickupable whose PickupRepresentation should be returned.
-    @return
-        Returns the PickupRepresentation of the input Pickupable or NULL if an error occurred.
-    */
-    orxonox::PickupRepresentation* PickupManager::getPickupRepresentation(uint64_t pickup)
-    {
-        this->representationsNetworked_.clear();
-        for(ObjectList<PickupRepresentation>::iterator it = ObjectList<PickupRepresentation>::begin(); it != ObjectList<PickupRepresentation>::end(); ++it)
-            this->representationsNetworked_[it->getObjectID()] = *it;
-
-        std::map<uint64_t, PickupInventoryContainer*>::iterator it = this->pickupInventoryContainers_.find(pickup);
-        if(it == this->pickupInventoryContainers_.end())
-            return this->defaultRepresentation_;
-
-        std::map<uint32_t, PickupRepresentation*>::iterator it2 = this->representationsNetworked_.find(it->second->representationObjectId);
-        if(it2 == this->representationsNetworked_.end())
-            return this->defaultRepresentation_;
-
-        return it2->second;
-    }
-
-    /**
-    @brief
-        Update the list of picked up Pickupables and get the number of Pickupables in the list.
-        This method is used in lua to populate the PickupInventory. The intended usage is to call this method to update the list of Pickupables and then use popPickup() to get the individual Pickupables.
-    @return
-        Returns the number of the players picked up Pickupables.
-    */
-    int PickupManager::getNumPickups(void)
-    {
-        this->pickupsIterator_ = this->pickupInventoryContainers_.begin();
-        return this->pickupInventoryContainers_.size();
-    }
-
-    /**
-    @brief
-        Drop the input Pickupable.
-        This method checks whether the inout Pickupable still exists and drops it, if so.
-    @param pickup
-        The Pickupable to be dropped.
-    */
-    void PickupManager::dropPickup(uint64_t pickup)
-    {
-        if(GameMode::isMaster() && !this->pickups_.empty())
-        {
-            Pickupable* pickupable = this->pickups_.find(pickup)->second->get();
-            if(pickupable != NULL)
-                pickupable->drop();
-        }
-        else
-        {
-            callStaticNetworkFunction(PickupManager::dropPickupNetworked, 0, pickup);
-        }
-    }
-
-    /*static*/ void PickupManager::dropPickupNetworked(uint64_t pickup)
-    {
-        if(GameMode::isServer())
-        {
-            PickupManager& manager = PickupManager::getInstance();
-            if(manager.pickups_.empty())
-                return;
-            Pickupable* pickupable = manager.pickups_.find(pickup)->second->get();
-            if(pickupable != NULL)
-                pickupable->drop();
-        }
-    }
-
-    /**
-    @brief
-        Use (or unuse) the input Pickupable.
-        This method checks whether the input Pickupable still exists and uses (or unuses) it, if so,
-    @param pickup
-        The Pickupable to be used (or unused).
-    @param use
-        If true the input Pickupable is used, if false it is unused.
-    */
-    void PickupManager::usePickup(uint64_t pickup, bool use)
-    {
-        if(GameMode::isMaster() && !this->pickups_.empty())
-        {
-            Pickupable* pickupable = this->pickups_.find(pickup)->second->get();
-            if(pickupable != NULL)
-                pickupable->setUsed(use);
-        }
-        else
-        {
-            callStaticNetworkFunction(PickupManager::usePickupNetworked, 0, pickup, use);
-        }
-    }
-
-    /*static*/ void PickupManager::usePickupNetworked(uint64_t pickup, bool use)
-    {
-        if(GameMode::isServer())
-        {
-            PickupManager& manager = PickupManager::getInstance();
-            if(manager.pickups_.empty())
-                return;
-            Pickupable* pickupable = manager.pickups_.find(pickup)->second->get();
-            if(pickupable != NULL)
-                pickupable->setUsed(use);
-        }
-    }
-
-    /**
-    @brief
-        Check whether the input Pickupable is valid, meaning that it is in the PickupManager's list and still exists.
-    @param pickup
-        The Pickupable.
-    @return
-        Returns true if the input Pickupable is still valid, false if not.
-    */
-    bool PickupManager::isValidPickup(uint64_t pickup)
-    {
-        return this->pickups_.find(pickup) != this->pickups_.end();
-    }
-
+        Is called by the PickupListener to notify the PickupManager, that the input Pickupable has transited to the input used state.
+    @param pickup
+        The Pickupable whose used status changed.
+    @param used
+        The used status the Pickupable changed to.
+    */
     void PickupManager::pickupChangedUsed(Pickupable* pickup, bool used)
     {
@@ -317 +241 @@
 
         CollectiblePickup* collectible = orxonox_cast<CollectiblePickup*>(pickup);
-        // If the Picupable is part of a PickupCollection it isn't displayed in the PickupInventory, just the PickupCollection is.
+        // If the Pickupable is part of a PickupCollection it isn't displayed in the PickupInventory, just the PickupCollection is.
         if(collectible != NULL && collectible->isInCollection())
             return;
 
+        // Getting clientId of the host this change of the pickup's used status concerns.
         PickupCarrier* carrier = pickup->getCarrier();
         while(carrier->getCarrierParent() != NULL)
@@ -332 +257 @@
         unsigned int clientId = info->getClientID();
 
-        std::map<Pickupable*, uint64_t>::iterator it = this->indexes_.find(pickup);
+        // Get the number identifying the pickup.
+        std::map<Pickupable*, uint32_t>::iterator it = this->indexes_.find(pickup);
         assert(it != this->indexes_.end());
-
-        uint64_t index = it->second;
+        uint32_t index = it->second;
+
+        // If we're either in standalone mode or this is the host whom the change of the pickup's status concerns.
         if(GameMode::isStandalone() || Host::getPlayerID() == clientId)
         {
             PickupManager::pickupChangedUsedNetwork(index, used, pickup->isUsable(), pickup->isUnusable());
         }
+        // If the concerned host is somewhere in the network, we call pickupChangedUsedNetwork() on its PickupManager.
         else
         {
@@ -346 +274 @@
     }
 
-    /*static*/ void PickupManager::pickupChangedUsedNetwork(uint64_t pickup, bool inUse, bool usable, bool unusable)
-    {
-        PickupManager& manager = PickupManager::getInstance();
+    /**
+    @brief
+        Helper method to react to the change in the used status of a Pickupable.
+        Static method that is used by the server to inform the client it concerns about the status change.
+        The parameters that are given are used to update the information (i.e. the PickupInventoryContainer) the concerning PickupManager has about the Pickupable that changed.
+    @param pickup
+        A number identifying the Pickupable that changed its used status.
+    @param inUse
+        The used status the Pickupable changed to. (i.e. whether the Pickupable is in use or not).
+    @param usable
+        Whether the Pickupable's used status can be changed used in the PickupInventory.
+    @param unusable
+        Whether the Pickupable's used status can be changed to unused in the PickupInventory.
+    */
+    /*static*/ void PickupManager::pickupChangedUsedNetwork(uint32_t pickup, bool inUse, bool usable, bool unusable)
+    {
+        PickupManager& manager = PickupManager::getInstance(); // Get the PickupManager singleton on this host.
+        // If the input Pickupable (i.e its identifier) is not present in the list the PickupManager has.
         if(manager.pickupInventoryContainers_.find(pickup) == manager.pickupInventoryContainers_.end())
         {
@@ -355 +298 @@
         }
 
+        // Update the Pickupable's container with the information transferred.
         manager.pickupInventoryContainers_[pickup]->inUse = inUse;
         manager.pickupInventoryContainers_[pickup]->usable = usable;
         manager.pickupInventoryContainers_[pickup]->unusable = unusable;
 
-        manager.updateGUI();
-    }
-
+        manager.updateGUI(); // Tell the PickupInventory that something has changed.
+    }
+
+    /**
+    @brief
+        Is called by the PickupListener to notify the PickupManager, that the input Pickupable has transited to the input pickedUp state.
+    @param pickup
+        The Pickupable whose pickedUp status changed.
+    @param pickedUp
+        The pickedUp status the Pickupable changed to.
+    */
     void PickupManager::pickupChangedPickedUp(Pickupable* pickup, bool pickedUp)
     {
         assert(pickup);
 
-        if(!GameMode::isMaster())
+        if(!GameMode::isMaster()) // If this is neither standalone nor the server.
             return;
 
         CollectiblePickup* collectible = orxonox_cast<CollectiblePickup*>(pickup);
-        // If the Picupable is part of a PickupCollection it isn't displayed in the PickupInventory, just the PickupCollection is.
+        // If the Pickupable is part of a PickupCollection it isn't displayed in the PickupInventory, just the PickupCollection is.
         if(collectible != NULL && collectible->isInCollection())
             return;
 
+        // Getting clientId of the host this change of the pickup's pickedUp status concerns.
         PickupCarrier* carrier = pickup->getCarrier();
         while(carrier->getCarrierParent() != NULL)
@@ -380 +333 @@
         if(pawn == NULL)
             return;
-        PlayerInfo* info = pawn->getPlayer();
+        PlayerInfo* info = pawn->getFormerPlayer();
         if(info == NULL)
             return;
         unsigned int clientId = info->getClientID();
 
-        uint64_t index = 0;
-        if(pickedUp)
-        {
-            index = this->getPickupIndex();
+        uint32_t index = 0;
+        if(pickedUp) // If the Pickupable has changed to picked up, it is added to the required lists.
+        {
+            index = this->getPickupIndex(); // Ge a new identifier (index) for the Pickupable.
+            // Add the Pickupable to the indexes_ and pickups_ lists.
             this->indexes_[pickup] = index;
             this->pickups_[index] = new WeakPtr<Pickupable>(pickup);
         }
-        else
-        {
-            std::map<Pickupable*, uint64_t>::iterator it = this->indexes_.find(pickup);
+        else // If it was dropped, it is removed from the required lists.
+        {
+            // Get the indentifier (index) that identifies the input Pickupable.
+            std::map<Pickupable*, uint32_t>::iterator it = this->indexes_.find(pickup);
             index = it->second;
+
+            // Remove the Pickupable form the indexes_ and pickups_ list.
             WeakPtr<Pickupable>* ptr = this->pickups_[index];
             this->indexes_.erase(it);
@@ -402 +359 @@
         }
 
+        // If we're either in standalone mode or this is the host whom the change of the pickup's status concerns.
+        //TODO: Needs to be added to server even if is was not picked up by it?
         if(GameMode::isStandalone() || Host::getPlayerID() == clientId)
         {
+            // If there is no PickupRepresentation registered the default representation is used.
             if(this->representations_.find(pickup->getPickupIdentifier()) == this->representations_.end())
                 PickupManager::pickupChangedPickedUpNetwork(index, pickup->isUsable(), this->defaultRepresentation_->getObjectID(), pickedUp);
@@ -409 +369 @@
                 PickupManager::pickupChangedPickedUpNetwork(index, pickup->isUsable(), this->representations_[pickup->getPickupIdentifier()]->getObjectID(), pickedUp);
         }
+        // If the concerned host is somewhere in the network, we call pickupChangedPickedUpNetwork() on its PickupManager.
         else
         {
+            // If there is no PickupRepresentation registered the default representation is used.
             if(this->representations_.find(pickup->getPickupIdentifier()) == this->representations_.end())
             {
@@ -423 +385 @@
     }
 
-    /*static*/ void PickupManager::pickupChangedPickedUpNetwork(uint64_t pickup, bool usable, uint32_t representationObjectId, bool pickedUp)
-    {
-        PickupManager& manager = PickupManager::getInstance();
+    /**
+    @brief
+        Helper method to react to the change in the pickedUp status of a Pickupable.
+        Static method that is used by the server to inform the client it concerns about the status change.
+        The parameters that are given are used to update the information (i.e. the PickupInventoryContainer) the concerning PickupManager has about the Pickupable that changed.
+    @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 representationObjectId
+        The objectId identifying (over the network) the PickupRepresentation that represents this Pickupable.
+    @param pickedUp
+        The pickedUp status the Pickupable changed to.
+    */
+    /*static*/ void PickupManager::pickupChangedPickedUpNetwork(uint32_t pickup, bool usable, uint32_t representationObjectId, bool pickedUp)
+    {
+        PickupManager& manager = PickupManager::getInstance(); // Get the PickupManager singleton on this host.
+        // If the Pickupable has been picked up, we create a new PickupInventoryContainer for it.
         if(pickedUp)
         {
+            // Create a new PickupInventoryContainer for the Pickupable and set all the necessary information.
             PickupInventoryContainer* container = new PickupInventoryContainer;
             container->pickup = pickup;
@@ -435 +413 @@
             container->unusable = false;
             container->representationObjectId = representationObjectId;
-            manager.pickupInventoryContainers_.insert(std::pair<uint64_t, PickupInventoryContainer*>(pickup, container));
-
-            if(GameMode::showsGraphics())
-            {
-                if(!manager.guiLoaded_)
-                {
-                    GUIManager::getInstance().loadGUI(PickupManager::guiName_s);
-                    manager.guiLoaded_ = true;
-                }
-                GUIManager::getInstance().getLuaState()->doString(PickupManager::guiName_s + ".update()");
-            }
-        }
+            // Insert the container into the pickupInventoryContainers_ list.
+            manager.pickupInventoryContainers_.insert(std::pair<uint32_t, PickupInventoryContainer*>(pickup, container));
+
+            manager.updateGUI(); // Tell the PickupInventory that something has changed.
+        }
+        // If the Pickupable has been dropped, we remove it from the pickupInventoryContainers_ list.
         else
         {
-            std::map<uint64_t, PickupInventoryContainer*>::iterator it = manager.pickupInventoryContainers_.find(pickup);
+            std::map<uint32_t, PickupInventoryContainer*>::iterator it = manager.pickupInventoryContainers_.find(pickup);
             if(it != manager.pickupInventoryContainers_.end())
                 delete it->second;
             manager.pickupInventoryContainers_.erase(pickup);
 
-            manager.updateGUI();
-        }
-    }
-
+            manager.updateGUI(); // Tell the PickupInventory that something has changed.
+        }
+    }
+
+    /**
+    @brief
+        Get the PickupRepresentation of an input Pickupable.
+        This method spares us the hassle to export the PickupIdentifier class to lua.
+    @param pickup
+        The number identifying the Pickupable whose PickupRepresentation should be returned.
+    @return
+        Returns the PickupRepresentation of the input Pickupable or NULL if an error occurred.
+    */
+    orxonox::PickupRepresentation* PickupManager::getPickupRepresentation(uint32_t pickup)
+    {
+        // Clear and rebuild the representationsNetworked_ list.
+        //TODO: Better solution?
+        this->representationsNetworked_.clear();
+        for(ObjectList<PickupRepresentation>::iterator it = ObjectList<PickupRepresentation>::begin(); it != ObjectList<PickupRepresentation>::end(); ++it)
+            this->representationsNetworked_[it->getObjectID()] = *it;
+
+        // Get the container belonging to the input pickup, if not found return the default representation.
+        std::map<uint32_t, PickupInventoryContainer*>::iterator it = this->pickupInventoryContainers_.find(pickup);
+        if(it == this->pickupInventoryContainers_.end())
+            return this->defaultRepresentation_;
+
+        // Get the PickupRepresentation of the input pickup (through the objecId of the representation stored in the PickupInventoryContainer belonging to the pickup), if not found return the default representation.
+        std::map<uint32_t, PickupRepresentation*>::iterator it2 = this->representationsNetworked_.find(it->second->representationObjectId);
+        if(it2 == this->representationsNetworked_.end())
+            return this->defaultRepresentation_;
+
+        return it2->second;
+    }
+
+    /**
+    @brief
+        Get the number of pickups currently picked up by the player.
+        This method is used in lua to populate the PickupInventory. The intended usage is to call this method to reset the iterator of the list of PickupInventoryContainers and then use popPickup() to get the individual PickupInventoryContainers.
+    @return
+        Returns the number of the players picked up Pickupables.
+    */
+    int PickupManager::getNumPickups(void)
+    {
+        this->pickupsIterator_ = this->pickupInventoryContainers_.begin(); // Reset iterator.
+
+        return this->pickupInventoryContainers_.size();
+    }
+
+    /**
+    @brief
+        Drop the input Pickupable.
+        This method checks whether the input Pickupable still exists and drops it, if so.
+    @param pickup
+        The identifier of the Pickupable to be dropped.
+    */
+    void PickupManager::dropPickup(uint32_t pickup)
+    {
+        // If we're either server or standalone and the list of pickups is not empty, we find and drop the input pickup.
+        if(GameMode::isMaster() && !this->pickups_.empty())
+        {
+            Pickupable* pickupable = this->pickups_.find(pickup)->second->get();
+            if(pickupable != NULL)
+                pickupable->drop();
+        }
+        // If we're neither server nor standalone we drop the pickup by calling dropPickupNetworked() of the PickupManager on the server.
+        else
+        {
+            callStaticNetworkFunction(PickupManager::dropPickupNetworked, 0, pickup);
+        }
+    }
+
+    /**
+    @brief
+        Helper method to drop the input pickup on the server.
+        Static method that is used by clients to instruct the server to drop the input pickup.
+    @param pickup
+        The identifier of the Pickupable to be dropped.
+    */
+    /*static*/ void PickupManager::dropPickupNetworked(uint32_t pickup)
+    {
+        if(GameMode::isServer()) // Obviously we only want to do this on the server.
+        {
+            PickupManager& manager = PickupManager::getInstance();
+            //TODO: Just call dropPickup() on manager?
+            if(manager.pickups_.empty())
+                return;
+            Pickupable* pickupable = manager.pickups_.find(pickup)->second->get();
+            if(pickupable != NULL)
+                pickupable->drop();
+        }
+    }
+
+    /**
+    @brief
+        Use (or unuse) the input Pickupable.
+        This method checks whether the input Pickupable still exists and uses (or unuses) it, if so,
+    @param pickup
+        The identifier of the Pickupable to be used (or unused).
+    @param use
+        If true the input Pickupable is used, if false it is unused.
+    */
+    void PickupManager::usePickup(uint32_t pickup, bool use)
+    {
+        // If we're either server or standalone and the list of pickups is not empty, we find and change the used status of the input pickup.
+        if(GameMode::isMaster() && !this->pickups_.empty())
+        {
+            Pickupable* pickupable = this->pickups_.find(pickup)->second->get();
+            if(pickupable != NULL)
+                pickupable->setUsed(use);
+        }
+        // If we're neither server nor standalone we change the used status of the pickup by calling usePickupNetworked() of the PickupManager on the server.
+        else
+        {
+            callStaticNetworkFunction(PickupManager::usePickupNetworked, 0, pickup, use);
+        }
+    }
+
+    /**
+    @brief
+        Helper method to use (or unuse) the input Pickupable on the server.
+        Static method that is used by clients to instruct the server to use (or unuse) the input pickup.
+    @param pickup
+        The identifier of the Pickupable to be used (or unused).
+    @param use
+        If true the input Pickupable is used, if false it is unused.
+    */
+    /*static*/ void PickupManager::usePickupNetworked(uint32_t pickup, bool use)
+    {
+        if(GameMode::isServer())
+        {
+            PickupManager& manager = PickupManager::getInstance();
+            //TODO: Just call usePickup() on manager?
+            if(manager.pickups_.empty())
+                return;
+            Pickupable* pickupable = manager.pickups_.find(pickup)->second->get();
+            if(pickupable != NULL)
+                pickupable->setUsed(use);
+        }
+    }
+
+    /**
+    @brief
+        Updates the PickupInventory GUI.
+        Also loads the PickupInventory GUI if is hasn't been done already.
+    */
     inline void PickupManager::updateGUI(void)
     {
+        // We only need to update (and load) the GUI if this host shows graphics.
         if(GameMode::showsGraphics())
         {
-            if(!this->guiLoaded_)
+            if(!this->guiLoaded_) // If the GUI hasn't been loaded, yet, we load it.
             {
                 GUIManager::getInstance().loadGUI(PickupManager::guiName_s);
                 this->guiLoaded_ = true;
             }
+
+            // Update the GUI.
             GUIManager::getInstance().getLuaState()->doString(PickupManager::guiName_s + ".update()");
         }
     }
 
-    uint64_t PickupManager::getPickupIndex(void)
-    {
-        if(this->pickupIndex_ == uint64_t(~0x0)-1)
-            this->pickupIndex_ = 0;
-        return this->pickupIndex_++;
+    /**
+    @brief
+        Get a new index for a Pickupable.
+        This will work as long as the number of Pickupables that are picked up is sufficiently small and as long as they don't exist forever.
+    @return
+        Returns the new index.
+    */
+    uint32_t PickupManager::getPickupIndex(void)
+    {
+        if(this->pickupHighestIndex_ == uint32_t(~0x0)-1) // If we've reached the highest possible number, we wrap around.
+            this->pickupHighestIndex_ = 0;
+        return this->pickupHighestIndex_++;
     }
 

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

@@ -53 +53 @@
 
     // tolua_begin
+    /**
+    @brief
+        Data structure to store collected data for one specific @ref orxonox::Pickupable "Pickupable".
+        This is used to not have to synchronise @ref orxonox::Pickupable "Pickupable" just to have the needed information for the PickupInventory available on all clients. Instead the information is sent over the network and stored in a PickupInventoryContainer.
+
+    @ingroup Pickup
+    */
     struct PickupInventoryContainer
     {
-        uint64_t pickup;
-        bool inUse;
-        bool pickedUp;
-        bool usable;
-        bool unusable;
-        uint32_t representationObjectId;
+        uint32_t pickup; //!< An indentifier for the @ref orxonox::Pickupable "Pickupable" that is associated with the information stored here.
+        bool inUse; //!< Whether the @ref orxonox::Pickupable "Pickupable" is currently in use.
+        bool pickedUp; //!< Whether the @ref orxonox::Pickupable "Pickupable" is currently picked up.
+        bool usable; //!< Whether the @ref orxonox::Pickupable "Pickupable" is usable.
+        bool unusable; //!< Whether the @ref orxonox::Pickupable "Pickupable" is droppable.
+        uint32_t representationObjectId; //!< The objectId of the @ref orxonox::PickupRepresentation "PickupRepresentation" that represents the @ref orxonox::Pickupable "Pickupable".
     };
     // tolua_end
@@ -66 +73 @@
     /**
     @brief
-        Manages Pickupables.
-        In essence has two tasks to fulfill. Firstly it must link Pickupables (through their PickupIdentifiers) and their PickupRepresentations. Secondly it manages the PickupInventory.
+        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.)
+
+        @section PickupManagerTechnicalDetails Technical details
+        Unfortunately <em>under the hood</em> it isn't just as easy. At least the PickupInventory part isn't. To grasp why this is we need to have a brief look at how the pickups module works over the network:
+
+        The pickups module essentially just exists on the @ref orxonox::Server "Server", since it's all game logic. That means, a @ref orxonox::PickupSpawner "PickupSpawner" is always triggered on the server, the @ref orxonox::Pickupable "Pickupable" is then picked up (and maybe used already) on the server. The effects the pickup has are synchronised over the network, if they have to be, but this is the responsibility of the entities that are affected, not the pickups module, and normally this is already implemented. The only two things that need to be communicated over the network are the graphical component of the @ref orxonox::PickupSpawner "PickupSpawner", since it needs to be displayed on the @ref orxonox::Client "Clients" as well, and anything that is needed for the PickupInventory, since it exists for each @ref orxonox::Host "Host" seperatly.
+
+        Fortunately synchronising the @ref orxonox::PickupSpawner "PickupSpawner" is already being taken care of by the synchronisation of the @ref orxonox::StaticEntity "StaticEntity" (or parents thereof).
+
+        This leaves us with the PickupInventory component (and this is really the source of all the complexity).
+
+        Firstly there are a number of lists (where by list I really mean any kind of ordered data structure) kept.
+        - 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::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.
+
+        There is communication in both directions. From server to client, when the server informs the client that the state of some @ref orxonox::Pickupable "Pickupable" has changed, during which all necessary information to create or update the PickupInventoryContainer for that pickup on the client is sent as well. Or from client to server, when the client wants the server to change the state of some @ref orxonox::Pickupable "Pickupable".
+
     @author
         Damian 'Mozork' Frick
+
+    @ingroup Pickup
     */
     class _PickupExport PickupManager // tolua_export
@@ -77 +106 @@
 
         public:
-            PickupManager();
-            virtual ~PickupManager();
+            PickupManager(); //!< Constructor.
+            virtual ~PickupManager(); //!< Destructor.
 
+            /**
+            @brief Get the instance of the PickupManager singleton.
+            @return Returns the instance of the PickupManager singleton.
+            */
             static PickupManager& getInstance() { return Singleton<PickupManager>::getInstance(); } // tolua_export
 
             bool registerRepresentation(const PickupIdentifier* identifier, PickupRepresentation* representation); //!< Registers a PickupRepresentation together with the PickupIdentifier of the Pickupable the PickupRepresentation represents.
-            bool registerRepresentation(PickupRepresentation* representation);
             bool unregisterRepresentation(const PickupIdentifier* identifier, PickupRepresentation* representation); //!< Unegisters a PickupRepresentation together with the PickupIdentifier of the Pickupable the PickupRepresentation represents.
-            bool unregisterRepresentation(PickupRepresentation* representation);
+
+            bool registerRepresentation(PickupRepresentation* representation); //!< Registers a PickupRepresentation on the host it was created.
+            bool unregisterRepresentation(PickupRepresentation* representation); //!< Unregisters a PickupRepresentation on the host it is being destroyed.
+
             PickupRepresentation* getRepresentation(const PickupIdentifier* identifier); //!< Get the PickupRepresentation representing the Pickupable with the input PickupIdentifier.
 
+            virtual void pickupChangedUsed(Pickupable* pickup, bool used); //!< Is called by the PickupListener to notify the PickupManager, that the input Pickupable has transited to the input used state.
+            static void pickupChangedUsedNetwork(uint32_t pickup, bool inUse, bool usable, bool unusable); //!< Helper method to react to the change in the used status of a Pickupable.
+            virtual void pickupChangedPickedUp(Pickupable* pickup, bool pickedUp); //!< Is called by the PickupListener to notify the PickupManager, that the input Pickupable has transited to the input pickedUp state.
+            static void pickupChangedPickedUpNetwork(uint32_t pickup, bool usable, uint32_t representationObjectId, bool pickedUp); //!< Helper method to react to the change in the pickedUp status of a Pickupable.
+
+        // Methods to be used by the PickupInventory.
+        public:
             // tolua_begin
-            orxonox::PickupRepresentation* getPickupRepresentation(uint64_t pickup); //!< Get the PickupRepresentation of an input Pickupable.
+            orxonox::PickupRepresentation* getPickupRepresentation(uint32_t pickup); //!< Get the PickupRepresentation of an input indentifier for Pickupable.
 
-            int getNumPickups(void); //!< Update the list of picked up Pickupables and get the number of Pickupables in the list.
+            int getNumPickups(void); //!< Get the number of pickups currently picked up by the player.
             /**
-            @brief Get the next Pickupable in the list.
-                   Use this, after having called getNumPickups() to access all the Pickupables individually and in succession.
-            @return Returns the next Pickupable in the list.
+            @brief Get the next PickupInventoryContainer in the list.
+                   Use this, after having called getNumPickups() to access all the PickupInventoryContainers individually and in succession.
+            @return Returns the next PickupInventoryContainer in the list.
             */
-            orxonox::PickupInventoryContainer* popPickup(void) { return (this->pickupsIterator_++)->second; }
+            orxonox::PickupInventoryContainer* popPickup(void)
+                { return (this->pickupsIterator_++)->second; }
 
-            void dropPickup(uint64_t pickup); //!< Drop the input Pickupable.
-            void usePickup(uint64_t pickup, bool use); //!< Use (or unuse) the input Pickupable.
-            bool isValidPickup(uint64_t pickup); //!< Check whether the input Pickupable is valid, meaning that it is in the PickupManager's list and still exists.
+            void dropPickup(uint32_t pickup); //!< Drop the input Pickupable.
+            void usePickup(uint32_t pickup, bool use); //!< Use (or unuse) the input Pickupable.
+             /**
+            @brief Check whether the input Pickupable is valid, meaning that it is in the PickupManager's list and still exists.
+            @param pickup The Pickupable.
+            @return Returns true if the input Pickupable is still valid, false if not.
+            */
+            bool isValidPickup(uint32_t pickup)
+                { return this->pickups_.find(pickup) != this->pickups_.end(); }
             // tolua_end
 
-            static void dropPickupNetworked(uint64_t pickup);
-            static void usePickupNetworked(uint64_t pickup, bool use);
-
-            virtual void pickupChangedUsed(Pickupable* pickup, bool used);
-            static void pickupChangedUsedNetwork(uint64_t pickup, bool inUse, bool usable, bool unusable);
-            virtual void pickupChangedPickedUp(Pickupable* pickup, bool pickedUp);
-            static void pickupChangedPickedUpNetwork(uint64_t pickup, bool usable, uint32_t representationObjectId, bool pickedUp);
+            static void dropPickupNetworked(uint32_t pickup); //!< Helper method to drop the input pickup on the server.
+            static void usePickupNetworked(uint32_t pickup, bool use); //!< Helper method to use (or unuse) the input Pickupable on the server.
 
         private:
             static PickupManager* singletonPtr_s;
             static const std::string guiName_s; //!< The name of the PickupInventory
-            bool guiLoaded_;
-            uint64_t pickupIndex_;
+            bool guiLoaded_; //!< Whether the PickupInventory GUI has been loaded, yet.
+            uint32_t pickupHighestIndex_; //!< The highest pickup index currently in use. (not taking wrap-around into account)
 
             PickupRepresentation* defaultRepresentation_; //!< The default PickupRepresentation.
-            std::map<const PickupIdentifier*, PickupRepresentation*, PickupIdentifierCompare> representations_; //!< Map linking PickupIdentifiers (representing types if Pickupables) and PickupRepresentations.
-            std::map<uint32_t, PickupRepresentation*> representationsNetworked_;
 
-            std::map<uint64_t, PickupInventoryContainer*> pickupInventoryContainers_;
-            std::map<uint64_t, PickupInventoryContainer*>::iterator pickupsIterator_; //!< An iterator pointing to the current Pickupable in pickupsList_.
+            std::map<const PickupIdentifier*, PickupRepresentation*, PickupIdentifierCompare> representations_; //!< Map linking @ref oroxnox::PickupIdentifier "PickupIdentifiers" (representing types of @ref orxonox::Pickupable "Pickupables") and @ref orxonox::PickupRepresentation "PickupRepresentations".
+            std::map<uint32_t, PickupRepresentation*> representationsNetworked_; //!< Map linking the @ref orxonox::PickupRepresentation "PickupRepresentation's" objectId to the @ref orxonox::PickupRepresentation "PickupRepresentation" itself. It is used for networking purposes.
 
-            std::map<uint64_t, WeakPtr<Pickupable>*> pickups_;
-            std::map<Pickupable*, uint64_t> indexes_;
+            std::map<uint32_t, PickupInventoryContainer*> pickupInventoryContainers_; //!< Map linking a number identifying a @ref orxonox::Pickupable "Pickupable" to a @ref orxonox::PickupInventoryContainer "PickupInventoryContainer", which contains all necessary information about that @ref orxonox::Pickupable "Pickupable".
+            std::map<uint32_t, PickupInventoryContainer*>::iterator pickupsIterator_; //!< An iterator pointing to the current Pickupable in pickupsList_.
 
-            void updateGUI(void);
-            uint64_t getPickupIndex(void);
+            std::map<uint32_t, WeakPtr<Pickupable>*> pickups_; //!< Map linking a number identifying a @ref orxonox::Pickupable "Pickupable" to a weak pointer of a @ref orxonox::Pickupable "Pickupable".
+            std::map<Pickupable*, uint32_t> indexes_;//!< Map linking @ref orxonox::Pickupable "Pickupable" to the number identifying it.
+
+            void updateGUI(void); //!< Updates the PickupInventory GUI.
+            uint32_t getPickupIndex(void); //!< Get a new index for a Pickupable.
 
     }; // tolua_export

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

@@ -83 +83 @@
         if(this->isInitialized())
         {
+            //TODO: Also (network) unregister for master.
             if(GameMode::isMaster() && this->pickup_ != NULL)
             {

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

@@ -125 +125 @@
                 if(this->getMetaTypeDirect() == pickupMetaType::destroyCarrier)
                 {
+                    this->Pickupable::destroy(); //TODO: Needed?
                     Pawn* pawn = orxonox_cast<Pawn*>(carrier);
                     pawn->kill();

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

@@ -108 +108 @@
             static const std::string metaTypeDestroyCarrier_s;
 
-
     };