Changeset 7540 for code/trunk/src

Timestamp:

Oct 14, 2010, 11:20:16 AM (14 years ago)

Author:

dafrick

Message:

Some more documenting.

Location:

code/trunk/src/modules/pickup

Files:

• PickupManager.h (modified) (1 diff)
• PickupRepresentation.cc (modified) (7 diffs)
• PickupRepresentation.h (modified) (4 diffs)
• PickupSpawner.cc (modified) (1 diff)
• PickupSpawner.h (modified) (4 diffs)

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

@@ -164 +164 @@
             PickupRepresentation* defaultRepresentation_; //!< The default PickupRepresentation.
 
-            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<const PickupIdentifier*, PickupRepresentation*, PickupIdentifierCompare> representations_; //!< Map linking PickupIdentifiers (representing types of Pickupables) and PickupRepresentations.
+            std::map<uint32_t, PickupRepresentation*> representationsNetworked_; //!< Map linking the PickupRepresentation's objectId to the PickupRepresentation itself. It is used for networking purposes.
 
-            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*> pickupInventoryContainers_; //!< Map linking a number identifying a Pickupable to a PickupInventoryContainer, which contains all necessary information about that Pickupable.
             std::map<uint32_t, PickupInventoryContainer*>::iterator pickupsIterator_; //!< An iterator pointing to the current Pickupable in pickupsList_.
 
-            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.
+            std::map<uint32_t, WeakPtr<Pickupable>*> pickups_; //!< Map linking a number identifying a Pickupable to a weak pointer of a Pickupable.
+            std::map<Pickupable*, uint32_t> indexes_;//!< Map linking Pickupable to the number identifying it.
 
             void updateGUI(void); //!< Updates the PickupInventory GUI.

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

@@ -36 +36 @@
 #include "core/CoreIncludes.h"
 #include "core/GameMode.h"
+#include "util/StringUtils.h"
+
 #include "graphics/Billboard.h"
-#include "util/StringUtils.h"
+
 #include "PickupManager.h"
 
@@ -55 +57 @@
 
         this->initialize();
-        this->setSyncMode(0x0);
+        this->setSyncMode(0x0); // The default PickupRperesentation created by each PickupManager is not synchronised, since it only exists locally.
     }
 
@@ -69 +71 @@
         this->registerVariables();
 
-        PickupManager::getInstance().registerRepresentation(this); //!< Registers the PickupRepresentation with the PickupManager.
+        PickupManager::getInstance().registerRepresentation(this); // Registers the PickupRepresentation with the PickupManager.
     }
 
@@ -107 +109 @@
     }
 
+    /**
+    @brief
+        Registers the variables that need to be synchornised.
+    */
     void PickupRepresentation::registerVariables(void)
     {
@@ -131 +137 @@
         if(GameMode::isMaster())
         {
-            PickupManager::getInstance().registerRepresentation(this->pickup_->getPickupIdentifier(), this); //!< Registers the PickupRepresentation with the PickupManager through the PickupIdentifier of the Pickupable it represents.
+            // Registers the PickupRepresentation with the PickupManager through the PickupIdentifier of the Pickupable it represents.
+            PickupManager::getInstance().registerRepresentation(this->pickup_->getPickupIdentifier(), this);
         }
 
@@ -156 +163 @@
             {
                 COUT(4) << "PickupRepresentation: Spawner template is empty." << std::endl;
-                //!< If neither spawnerRepresentation nor spawnerTemplate was specified
+                // If neither spawnerRepresentation nor spawnerTemplate was specified
                 return this->getDefaultSpawnerRepresentation(spawner);
             }
@@ -180 +187 @@
         Returns a pointer to the StaticEntity.
     */
-    //TODO: Possibility to define default representation through XML.
+    //TODO: Possibility to define default representation through XML?
     StaticEntity* PickupRepresentation::getDefaultSpawnerRepresentation(PickupSpawner* spawner)
     {

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

@@ -42 +42 @@
 #include "pickup/PickupIdentifier.h"
 #include "worldentities/StaticEntity.h"
+
 #include "PickupSpawner.h"
 
@@ -52 +53 @@
     /**
     @brief
-        The PickupRepresentation class represents a specific pickup type (identified by its PickupIdentifier). It defines the information displayed in the GUI and how PickupSpawners that spawn the pickup type look like.
-        They are created through XML and are registered with the PickupManager.
+        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.
+        They are created through XML and are registered with the @ref orxonox::PickupManager "PickupManager".
+
+        Creating a PickupRepresentation in XML could look as follows:
+        @code
+        <PickupRepresentation
+            name = "My awesome Pickup"
+            description = "This is the most awesome Pickup ever to exist."
+            spawnerTemplate = "awesomePickupRepresentation"
+            inventoryRepresentation = "AwesomePickup"
+        >
+            <pickup>
+                <SomePickup />
+            </pickup>
+        </PickupRepresentation>
+        @endcode
+        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).
+        @code
+        <Template name="awesomePickupRepresentation">
+            <PickupRepresentation>
+                <spawner-representation>
+                    <StaticEntity>
+                        <attached>
+                            <!-- Here you can put all the objects which define the look of the spawner. -->
+                        </attached>
+                    </StaticEntity>
+                </spawner-representation>
+            </PickupRepresentation>
+        </Template>
+        @endcode
+
+        For the purpose of them working over the network, they are synchronised.
 
     @author
@@ -69 +102 @@
             virtual ~PickupRepresentation(); //!< Destructor.
 
-            virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode);
+            virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode); //!< Method for creating a PickupRepresentation object through XML.
 
             /**
@@ -152 +185 @@
             StaticEntity* getDefaultSpawnerRepresentation(PickupSpawner* spawner); //!< Get the default spawnerRepresentation for a specific PickupSpawner.
 
-            void registerVariables(void); //!< Register some variables for synchronisation.
+            void registerVariables(void); //!< Registers the variables that need to be synchronised.
 
             std::string name_; //!< The name of the Pickupable represented by this PickupRepresentation.

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

@@ -106 +106 @@
     {
         this->triggerDistance_ = 10;
-        this->respawnTime_ = 0;
+        this->respawnTime_ = 0; //TODO: Smart? Shouldn't we have a better mechanism to prevent unwanted multiple pickups?
         this->maxSpawnedItems_ = INF;
         this->spawnsRemaining_ = INF;

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

@@ -39 +39 @@
 
 #include <string>
+
+#include "tools/Timer.h"
+
 #include "interfaces/Pickupable.h"
-#include "tools/Timer.h"
 
 #include "tools/interfaces/Tickable.h"
@@ -49 +51 @@
     /**
         @brief
-            The PickupSpawner class is responsible for spawning pickups of a specific type.
-            Forthermore it can be specified how long the time interval between spawning two items is and how many pickups are spawned at maximum, amongst other things.
+            The PickupSpawner class is responsible for spawning @ref orxonox::Pickupable "Pickupables" of a specific type.
+            Furthermore it can be specified how long the time interval between spawning two items is and how many @ref orxonox::Pickupable "Pickupables" are spawned at maximum, amongst other things. The parameters that can be used to further specify the behaviour of the PickupSpawner are:
+            - The <b>triggerDistance</b> can be used to specify how far away an entity has to be to still trigger the PickupSPawner (and thus receive a @ref orxonox::Pickupable "Pickupable" form it). The default is 10.
+            - The <b>respawnTime</b> is the time in seconds that passes until the PickupSpawner is enabled again, after having spawned a @ref orxonox::Pickupable "Pickupable". The default is 0.
+            - The <b>maxSpawnedItems</b> is the number of @ref orxonox::Pickupable "Pickupables" that are spawned by this PickupSpawner at the most. The default is -1, which denotes infinity.
+
+            A PickupSpawner is created in XML, which can be done in the following fashion:
+            @code
+            <PickupSpawner position="-100,0,-100" respawnTime="30" maxSpawnedItems="10">
+                <pickup>
+                    <SomePickup >
+                </pickup>
+            </PickupSpawner>
+            @endcode
+            As we can see, since the PickupSpawner is a StaticEntity, it also has spatial coordinates. We can also see, that the type of @ref orxonox::Pickupable "Pickupable" which is spawned hast to be specified as well.
 
         @author
@@ -56 +71 @@
         @author
             Damian 'Mozork' Frick
+
+        @ingroup Pickup
     */
     class _PickupExport PickupSpawner : public StaticEntity, public Tickable
@@ -66 +83 @@
             virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode);  //!< Method for creating a PickupSpawner through XML.
             virtual void changedActivity(); //!< Invoked when activity has changed (set visibilty).
-            virtual void tick(float dt);
+            virtual void tick(float dt); //!< Tick, checks if any Pawn is close enough to trigger.
 
             /**