Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Jan 27, 2016, 6:50:51 PM (9 years ago)
Author:
muemart
Message:

Fix loads of doxygen warnings and other documentation issues

Location:
code/trunk/doc/api/groups
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • code/trunk/doc/api/groups/Pickup.dox

    r8351 r11099  
    151151
    152152    @subsection CreatingTheInnerWorkings Creating the inner workings of your pickup
     153    @todo This is completely outdated. Someone who knows how pickups work should update this.
     154   
    153155    Now that we have the skeleton of a pickup and we have defined which carriers are allowed to pick our pickup up we are going to take a look at all the methods we can (or sometimes have to) overload from @ref orxonox::Pickupable "Pickupable", for our pickup to work properly. But first I will introduce some more concepts to make the need for these methods more obvious.
    154156    - Since one pickup class can by itself be many pickup types, we need a way to find out whether a particular instance of a pickup is of the same type as another instance of a pickup. To that end the @ref orxonox::PickupIdentifier "PickupIdentifier" was created. The @ref orxonox::PickupIdentifier "PickupIdentifier" accounts for the type of class your pickup is of and also for the parameters (and their values) that distinguish different types of pickups of the same class. Much of the functionality of the pickup module relies on this identifier being correct, thus it is very important to initialize it correctly. (We will see, how that is done in a short while.)

  • code/trunk/doc/api/groups/Portals.dox

    r9348 r11099  
    6060     - design: the name of the @ref orxonox::Template "design template"
    6161*/
    62 
    63 /**
    64     @addtogroup Pickup Pickup
    65     @ingroup Modules
    66 
    67     The Pickup module adds a special type of object to Orxonox, the so-called @ref orxonox::Pickupable "Pickupables". @ref orxonox::Pickupable "Pickupables" are objects that can be picked up (by virtually any entity, but commonly by the @ref orxonox::Pawn "Pawn") and have some kind of effect on the entity that picked the @ref orxonox::Pickupable "Pickupable" up.
    68 
    69     @section IncludingPickups Including pickups in a level
    70     @ref orxonox::Pickupable "Pickupables" are designed so that they can be included in levels fairly easily, while also ensuring, that the pickup itself (its game-logic component) and how it is represented (e.g. in the PickupInventory (the GUI that displays @ref orxonox::Pickupable "Pickupables") or in the game) are neatly seperated.
    71     To be able to use @ref orxonox::Pickupable "Pickupables" in a level one must understand some basic concepts.
    72     - @ref orxonox::Pickupable "Pickupables" are entities which (by itself) have no physical (or graphical) dimension. The simply represent the effect they will have on a @ref orxonox::PickupCarrier "PickupCarrier" (the entity that can pick up @ref orxonox::Pickupable "Pickupables", @ref orxonox::Pawn "Pawn" for example inherits from @ref orxonox::PickupSpawner "PickupSpawner" and thus is able to pick up and carry @ref orxonox::Pickupable "Pickupables"), when used and the mechanism that leads to that.
    73     - The physical (or graphical) dimension of a pickup is called a @ref orxonox::PickupRepresentation "PickupRepresentation".
    74     - The @ref orxonox::PickupRepresentation "PickupRepresentation" of a @ref orxonox::Pickupable "Pickupable" and the @ref orxonox::Pickupable "Pickupable" itself are linked to each other, in such a way that a @ref orxonox::PickupRepresentation "PickupRepresentation" can only represent one type of @ref orxonox::Pickupable "Pickupable".
    75     - A type of @ref orxonox::Pickupable "Pickupable" is a specific pickup class (inheriting from @ref orxonox::Pickupable "Pickupable") with specific values for all its relevant parameters. This means, that a pickup of the same class with the same values for all parameters except for one is a different type of pickup and will therefore have a different @ref orxonox::PickupRepresentation "PickupRepresentation". Which parameters are the ones relevant to destinguish between two types of pickups can be defined in the class description of the specific pickup.
    76     - The entity that actually gives a @ref orxonox::Pickupable "Pickupable" to a @ref orxonox::PickupCarrier "PickupCarrier" is called a @ref orxonox::PickupSpawner "PickupSpawner". A @ref orxonox::PickupSpawner "PickupSpawner" creates (based on some parameters) @ref orxonox::Pickupable "Pickupables" which then is picked up by the @ref orxonox::PickupCarrier "PickupCarrier", that caused the @ref orxonox::PickupSpawner "PickupSpawner" to spawn a new pickup. How the spawner looks in the game is defined by the @ref orxonox::PickupRepresentation "PickupRepresentation" of the @ref orxonox::Pickupable "Pickupable" it spawns.
    77 
    78     @subsection UsingPredifinedPickups Using predefined pickups
    79     There is a file called <code>pickupRepresentationTemplates.oxt</code> in <code>levels/templates</code>, which holds the templates for the @ref orxonox::PickupRepresentation "PickupRepresentations" and also templates for @ref orxonox::Pickupable "Pickupables". The templates for the @ref orxonox::PickupRepresentation "PickupRepresentations" define the @ref orxonox::StaticEntity "StaticEntities" that are attached to the @ref orxonox::PickupSpawner "PickupSpawners" to make them look like the @ref orxonox::Pickupable "Pickupable" they are spawning. The templates for the @ref orxonox::Pickupable "Pickupables" can be added just for ease of use.
    80     If you want to use pickups you will have to include this file in your level file, somewhere above the Level-tag.
    81     @code
    82     <?lua
    83         include("templates/pickupRepresentationTemplates.oxt")
    84     ?>
    85     ...
    86     <Level>
    87     ...
    88     @endcode
    89     There is another file called <code>pickups.oxi</code> in <code>level/includes</code> which creates all @ref orxonox::PickupRepresentation "PickupRepresentations" needed for the @ref orxonox::Pickupable "Pickupable" supplied by the <code>pickupRepresentationTemplates.oxt</code> file. This file will have to be included as well. It has to be somewhere after the opening Scene-tag and your first use of a pickup.
    90     @code
    91     <Scene>
    92     ...
    93     <?lua
    94         include("includes/pickups.oxi")
    95     ?>
    96     @endcode
    97     After that all the predefined pickups specified in those two files can be used just by creating a @ref orxonox::PickupSpawner "PickupSpawner" for them in the respective level.
    98     For example:
    99     @code
    100     <PickupSpawner position="-100,0,-100" respawnTime="30" maxSpawnedItems="10">
    101         <pickup>
    102             <HealthPickup
    103                 health = 10
    104                 healthType = "limited"
    105                 activationType = "immediate"
    106                 durationType = "once"
    107             />
    108         </pickup>
    109     </PickupSpawner>
    110     @endcode
    111     Please be aware, that the @ref orxonox::Pickupable "Pickupable" specified for the @ref orxonox::PickupSpawner "PickupSpawner", has to be exactly the same (including all parameters) to the one specified in the <code>pickups.oxi</code> file.
    112     To make things simpler, one could just use the templates specified in the <code>pickupRepresentationTemplates.oxt</code> file. Which, following the previous example, would look like this:
    113     @code
    114     <PickupSpawner position="-100,0,-100" respawnTime="30" maxSpawnedItems="10">
    115         <pickup>
    116             <HealthPickup template="smallhealthpickup" />
    117         </pickup>
    118     </PickupSpawner>
    119     @endcode
    120 
    121     @subsection UnsingNon-PredefinedPickups Using non-predefined pickups
    122     To include a type of pickup (which, as we remember, is the class of the @ref orxonox::Pickupable "Pickupable" with specific values for all the relevant parameters) in a level file, you can just create a new @ref orxonox::PickupSpawner "PickupSpawner" and specify the @ref orxonox::Pickupable "Pickupable".
    123     @code
    124     <PickupSpawner position="-100,0,-100" respawnTime="30" maxSpawnedItems="10">
    125     <pickup>
    126         <HealthPickup
    127             health = 33
    128             healthType = "limited"
    129             activationType = "immediate"
    130             durationType = "once"
    131         />
    132     </pickup>
    133     </PickupSpawner>
    134     @endcode
    135     As can be seen in the <code>pickupRepresentationTemplates.oxt</code> file and the <code>pickups.oxi</code> file there is no @ref orxonox::PickupRepresentation "PickupRepresentation" defined for this type of pickup. Thus the default representation will be used.
    136 
    137     To create an appropriate @ref orxonox::PickupRepresentation "PickupRepresentation" for the inserted pickup above, you can just create a @ref orxonox::PickupRepresentation "PickupRepresentation" within the scene (Within the Scene-tags).
    138     @code
    139     <PickupRepresentation
    140         name = "My new health pickup"
    141         description = "This is an awesome new health pickup."
    142         spawnerTemplate = "mediumhealthpickupRepresentation"
    143         inventoryRepresentation = "MediumHealth"
    144     >
    145         <pickup>
    146             <HealthPickup
    147             health = 33
    148             healthType = "limited"
    149             activationType = "immediate"
    150             durationType = "once"
    151         />
    152         </pickup>
    153     </PickupRepresentation>
    154     @endcode
    155     Notice, that the type of pickup specified for the @ref orxonox::PickupRepresentation "PickupRepresentation", naturally, needs to be the same (this is the way they can be connected). Also, we just used an existing <em>spawnerTemplate</em>, to make things simpler.
    156 
    157     The next step is to create a <em>spawnerRepresentation</em> uniquely for our new type of pickup. Lets call it <code>newhealthpickupRepresentation</code>. Thus the parameter <em>spawnerTemplate</em> of the @ref orxonox::PickupRepresentation "PickupRepresentation" has to be changed to that value.
    158     @code
    159     spawnerTemplate = "newhealthpickupRepresentation"
    160     @endcode
    161     The <em>spawnerTemplate</em> defines how the @ref orxonox::PickupSpawner "PickupSpawner" is displayed in a level.
    162     In our example case it could look like this:
    163     @code
    164     <Template name=newhealthpickupRepresentation>
    165         <PickupRepresentation>
    166             <spawner-representation>
    167                 <StaticEntity>
    168                     <attached>
    169                         -- Here you can put all the objects which define the look of the spawner. --
    170                     </attached>
    171                 </StaticEntity>
    172             </spawner-representation>
    173         </PickupRepresentation>
    174     </Template>
    175     @endcode
    176     Please refer to the <code>pickupRepresentationTemplates.oxt</code> for more examples.
    177 
    178     The @ref orxonox::PickupRepresentation "PickupRepresentation" also needs another parameter the <em>inventoryRepresentation</em>. This parameter defined how the @ref orxonox::Pickupable "Pickupable" is displayed in the PickupInventory (a menu to browse the currently equipped pickups).
    179     @code
    180     inventoryRepresentation = "MediumHealth"
    181     @endcode
    182     This is the name of an image defined in the PickupInventory imageset (<code>PickupInventory.imageset</code>), which can be found in <code>data_extern/gui/imagesets</code>.
    183 
    184     This is all that has to be done. Now you have a new pickup type with an appropriate @ref orxonox::PickupRepresentation "PickupRepresentation" for your use. If you feel that your pickup is useful in general, please don't hesitate to create a template for the pickup and add your pickup to the <code>pickupRepresentationTemplates.oxt</code> file and the <code>pickups.oxi</code> file, so that anyone who wants to use it can do so quite easily.
    185 
    186     There is also an additional way to create new types of pickups to be used in a level (without having to do any coding). There is a @ref orxonox::Pickupable "Pickupable" called the @ref orxonox::PickupCollection "PickupCollection", which is just a collection (hence the name) of @ref orxonox::Pickupable "Pickupables" (more precisely of @ref orxonox::CollectiblePickup "CollectiblePickups"), behaving as if it was just one @ref orxonox::Pickupable "Pickupable".
    187     A @ref orxonox::PickupCollection "PickupCollection" can be created as follows:
    188     @code
    189     <PickupCollection>
    190         <pickupables>
    191             -- some pickups you want to have in your collection, e.g. --
    192             <HealthPickup template=smallhealthpickup />
    193             <HealthPickup health=50 healthRate=5 durationType=continuous activationType=immediate healthType=limited />
    194         </pickupables>
    195     </PickupCollection>
    196     @endcode
    197     Of which types of pickups a collection is made up is entirely up to the one creating the @ref orxonox::PickupCollection "PickupCollection", they can be mixed freely.
    198 
    199     @section CreatingAPickup Creating a new pickup
    200     Things have been fairly straightforward so far. Creating a @ref orxonox::Pickupable "Pickupable" form scratch isn't as easy. Therefore I'm just going to supply you with a recipe, or a set of steps you have to take, without which your pickup won't work and point out some common pitfalls.
    201 
    202     @subsection CreatingAPickupClass Creating the class
    203     For a new @ref orxonox::Pickupable "Pickupable" you need to create a new class in <code>>modules/pickup/items</code>. Your class needs to be derived from another pickup class, normally this would either be @ref orxonox::Pickupable "Pickupable", @ref orxonox::CollectiblePickup "CollectiblePickup" or @ref orxonox::Pickup "Pickup". @ref orxonox::Pickupable "Pickupable" is (as mentioned earlier) the base class of all things that can be picked up, thus of all pickups. @ref orxonox::CollectiblePickup "CollectiblePickup" is a (directly) derived class of @ref orxonox::Pickupable  "Pickupable" and provides the additional functionality of enabling your pickup to be used in a @ref orxonox::PickupCollection "PickupCollection". However you are probably going to want to derive your class form @ref orxonox::Pickup "Pickup", because it is a @ref orxonox::CollectiblePickup "CollectiblePickup" and provides some useful methods. So have a look at @ref orxonox::Pickup "Pickup".
    204     Once you have created your new pickup class you have to insert it in the <code>PickupPrereqs.h</code> file in the <code>modules/pickup</code> folder and in the <code>CMakeList.txt</code> file in the <code>modules/pickup/items</code> folder. Also have a look at other pickups to make sure you include all the necessary files in your class.
    205 
    206     @subsection ChoosingTheCarriers Coosing the carriers
    207     You also have to choose the entities that are allowed to pick your pickup up. After you have chosen the entity that carries your pickup, you need to do the following.
    208     - The enity that carries your pickup needs to be derived from the @ref orxonox::PickupCarrier "PickupCarrier" interface. And you need to implement the @ref orxonox::PickupCarrier "PickupCarriers'" virtual functions <code>getCarrierChildren()</code> and <code>getCarrierParent()</code>. These tow methods are needed, because all pickups are initially picked up by a @ref orxonox::Pawn "Pawn" and then handed down to the entity that effectively carries them. With the above mentioned two function just that is accomplished. A hierarchical structure is established with one parent and a set of children, where the @ref orxonox::Pawn "Pawn" is the root node of this hierarchical structure, the only entity with no parent.
    209     - Once you have done that you will also want to specify in your pickup which carriers can pick it up, this is done via the <code>addTarget()</code> function. So you have to make sure the target is added whenever one of your pickups is created (so, most conveniently somewhere in the constructor), with the following command.
    210     @code
    211     this->addTarget(ClassIdentifier<MyCarrierClass>::getIdentifier());
    212     @endcode
    213 
    214     @subsection CreatingTheInnerWorkings Creating the inner workings of your pickup
    215     Now that we have the skeleton of a pickup and we have defined which carriers are allowed to pick our pickup up we are going to take a look at all the methods we can (or sometimes have to) overload from @ref orxonox::Pickupable "Pickupable", for our pickup to work properly. But first I will introduce some more concepts to make the need for these methods more obvious.
    216     - Since one pickup class can by itself be many pickup types, we need a way to find out whether a particular instance of a pickup is of the same type as another instance of a pickup. To that end the @ref orxonox::PickupIdentifier "PickupIdentifier" was created. The @ref orxonox::PickupIdentifier "PickupIdentifier" accounts for the type of class your pickup is of and also for the parameters (and their values) that distinguish different types of pickups of the same class. Much of the functionality of the pickup module relies on this identifier being correct, thus it is very important to initialize it correctly. (We will see, how that is done in a short while.)
    217     - Every @ref orxonox::Pickupable "Pickupable" has at least two states which are very important. The first is, whether the @ref orxonox::Pickupable "Pickupable" is currently in use or not and the second is whether the pickup is currently picked up or not.
    218 
    219     Let's have a look at the important methods.
    220     - <b>changedUsed()</b> The <code>changedUsed()</code> method is called whenever the state of the @ref orxonox::Pickupable "Pickupable" transits from being used to not being used or the other way around. Which means this method is probably the most important method you have at your fingertips, since it enables you to apply the effect of your pickup when it gets used and remove the effect as soon as it is no longer in use.
    221     - <b>changedPickedUp()</b> The <code>changedPickedUp()</code> method is called whenever the state of the @ref orxonox::Pickupable "Pickupable" changes from being picked up to not being picked up or the other way around. For example if you want your pickup to be used as soon as it is picked up, this is the method you have to overload to achieve that behavior (or just let your pickup be derived from @ref orxonox::Pickup "Pickup", which implements exactly that behavior, if the <em>activationType</em> is set to <em>immediate</em>). You don't have to concern yourself with destroying the pickup or creating a spawner when it changes to not picked up, since that is already implemented with the @ref orxonox::Pickupable "Pickupable" and @ref orxonox::PickupCarrier "PickupCarrier" classes. If you want a different behavior, however, once again, this is the method.
    222     - <b>changedCarrier()</b> The <code>changedCarrier()</code> method is called whenever the carrier of the @ref orxonox::Pickupable "Pickupable" changes. And by that I don't mean the class that is allowed to carry the pickup, but the object that actually carries (or carried) the pickup. Please do not overload this class to implement behavior for picked up -> not picked up transitions, use <code>changedPickedUp()</code> for that. For most pickup classes this method doesn't need to be overloaded. Where it is used, however is in the @ref orxonox::PickupCollection "PickupCollection" class, where the new carrier needed to be communicated to all pickups the collection consists of, whenever the carrier was changed.
    223 
    224     Please be aware, that these three methods are methods registered with @ref Super.h "Super", meaning, that whenever overloading them, don't forget to call <code>SUPER(MyClass, myMethod);</code>.
    225     Also when implementing the above methods you should think of what should happen in unexpected situations, e.g. when your pickup is unused manually and set to used again.
    226     Additionally you should use the <code>destroy()</code> method of Pickupable instead of the method provided by @ref orxonox::OrxonoxClass "OrxonoxClass", meaning <code>Pickupable::destroy()</code> instead of plain <code>destroy()</code>.
    227 
    228     - <b>clone()</b> The <code>clone()</code> method creates a new pickup of the same type as the pickup it is cloned from. So the cloned pickup is not exactly the same, as it doesn't necessarily completely reflect the status of the pickup it is cloned from, but it reflects all the parameters and their values, that distinguish different types of this pickup class. It needs to be implemented by every pickup class. And it is best if this is done in a very specific way. Below is shown how:
    229     @code
    230     void MyPickup::clone(OrxonoxClass*& item)
    231     {
    232         if(item == NULL)
    233             item = new MyPickup(this);
    234 
    235         SUPER(MyPickup, clone, item);
    236 
    237         MyPickup* pickup = dynamic_cast<MyPickup*>(item);
    238         // Here you should set all the important parameters (that distinguish the different types of this pickup), e.g.
    239         pickup->setSomeParameter(this->getSomeParameter());
    240         // You must also initialize the identifier of the new pickup, this is normally done in a member function called in
    241         pickup->initializeIdentifier();
    242     }
    243     @endcode
    244     - <b>initializeIdentifier()</b> The <code>initializeIdentifier()</code> method initializes (or more simply put, creates) the @ref orxonox::PickupIdentifier "PickupIdentifier" of the instance of your pickup. Since the important values of the parameters are not yet available in the constructor of your pickup this <code>initializeIdentifier()</code> method must be called as soon as they are available, which normally is in the <code>XMLPort()</code> method, and the <code>clone()</code> method, as seen above. In the <code>initializeIdentifier()</code> method you need to register each parameter that is important for the type of your pickup to its identifier, this is normally done as follows:
    245     @code
    246     void Pickup::initializeIdentifier(void)
    247     {
    248         // If the get method returns a string.
    249         std::string val1 = this->getSomeParameter();
    250         std::string type1 = "someParameter";
    251         this->pickupIdentifier_->addParameter(type1, val1);
    252         // If the get method doesn't return a string
    253         std::stringstream stream;
    254         stream << this->getSomeOtherParameter();
    255         std::string type2 = "someOtherParameter";
    256         std::string val2 = stream.str();
    257         this->pickupIdentifier_->addParameter(type2, val2);
    258     }
    259     @endcode
    260 
    261     Be aware, this only works for parameters that are simple enough, meaning with pointers for example it will, naturally, not work, and other ways must be found (this is for example done in @ref orxonox::PickupCollection "PickupCollection" with a derived class of the @ref orxonox::PickupIdentifier "PickupIdentifier", the @ref orxonox::PickupCollectionIdentifier "PickupCollectionIdentifier") or in the @ref orxonox::DronePickup "DronePickup" class by using a @ref orxonox::Template "Template".
    262     - <b>createSpawner()</b> The <code>createSpawner()</code> method needs to be implemented by any pickup directly inheriting from @ref orxonox::Pickupable "Pickupable" (or directly from @ref orxonox::CollectiblePickup "CollectiblePickup"), so if you inherit from @ref orxonox::Pickup "Pickup", you don't need to implement this. It is used to create a @ref orxonox::PickupSpawner "PickupSpawner", when the pickup is dropped. A standard implementation would look like this.
    263     @code
    264     bool MyPickup::createSpawner(void)
    265     {
    266         new DroppedPickup(this, this, this->getCarrier());
    267         return true;
    268     }
    269     @endcode
    270 
    271     @section PickupTechnicalDetails Technical details
    272 
    273     @image html pickupmodule.png
    274 */
    275 
    276 /**
    277     @defgroup PickupItems Items
    278     @ingroup Pickup
    279 
    280     The actual pickups can be found here.
    281 */
Note: See TracChangeset for help on using the changeset viewer.