Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Changeset 7551


Ignore:
Timestamp:
Oct 17, 2010, 9:40:53 PM (14 years ago)
Author:
dafrick
Message:

Moved documentation for pickup module from wiki to doxygen.

Location:
code/trunk
Files:
1 added
3 edited

Legend:

Unmodified
Added
Removed

  • code/trunk/doc/api/Groups.dox

    r7489 r7551  
    195195    @ingroup Modules
    196196
     197    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.
     198
     199    @section IncludingPickups Including pickups in a level
     200    @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.
     201    To be able to use @ref orxonox::Pickupable "Pickupables" in a level one must understand some basic concepts.
     202    - @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.
     203    - The physical (or graphical) dimension of a pickup is called a @ref orxonox::PickupRepresentation "PickupRepresentation".
     204    - 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".
     205    - 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.
     206    - 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.
     207
     208    @subsection UsingPredifinedPickups Using predefined pickups
     209    There is a file called <code>pickup_representation_templates.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.
     210    If you want to use pickups you will have to include this file in your level file, somewhere above the Level-tag.
     211    @code
     212    <?lua
     213        include("templates/pickup_representation_templates.oxt")
     214    ?>
     215    ...
     216    <Level>
     217    ...
     218    @endcode
     219    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>pickup_representation_templates.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.
     220    @code
     221    <Scene>
     222    ...
     223    <?lua
     224        include("includes/pickups.oxi")
     225    ?>
     226    @endcode
     227    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.
     228    For example:
     229    @code
     230    <PickupSpawner position="-100,0,-100" respawnTime="30" maxSpawnedItems="10">
     231        <pickup>
     232            <HealthPickup
     233                health = 10
     234                healthType = "limited"
     235                activationType = "immediate"
     236                durationType = "once"
     237            />
     238        </pickup>
     239    </PickupSpawner>
     240    @endcode
     241    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.
     242    To make things simpler, one could just use the templates specified in the <code>pickup_representation_templates.oxt</code> file. Which, following the previous example, would look like this:
     243    @code
     244    <PickupSpawner position="-100,0,-100" respawnTime="30" maxSpawnedItems="10">
     245        <pickup>
     246            <HealthPickup template="smallhealthpickup" />
     247        </pickup>
     248    </PickupSpawner>
     249    @endcode
     250
     251    @subsection UnsingNon-PredefinedPickups Using non-predefined pickups
     252    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".
     253    @code
     254    <PickupSpawner position="-100,0,-100" respawnTime="30" maxSpawnedItems="10">
     255    <pickup>
     256        <HealthPickup
     257            health = 33
     258            healthType = "limited"
     259            activationType = "immediate"
     260            durationType = "once"
     261        />
     262    </pickup>
     263    </PickupSpawner>
     264    @endcode
     265    As can be seen in the <code>pickup_representation_templates.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.
     266
     267    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).
     268    @code
     269    <PickupRepresentation
     270        name = "My new health pickup"
     271        description = "This is an awesome new health pickup."
     272        spawnerTemplate = "mediumhealthpickupRepresentation"
     273        inventoryRepresentation = "MediumHealth"
     274    >
     275        <pickup>
     276            <HealthPickup
     277            health = 33
     278            healthType = "limited"
     279            activationType = "immediate"
     280            durationType = "once"
     281        />
     282        </pickup>
     283    </PickupRepresentation>
     284    @endcode
     285    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.
     286
     287    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.
     288    @code
     289    spawnerTemplate = "newhealthpickupRepresentation"
     290    @endcode
     291    The <em>spawnerTemplate</em> defines how the @ref orxonox::PickupSpawner "PickupSpawner" is displayed in a level.
     292    In our example case it could look like this:
     293    @code
     294    <Template name=newhealthpickupRepresentation>
     295        <PickupRepresentation>
     296            <spawner-representation>
     297                <StaticEntity>
     298                    <attached>
     299                        -- Here you can put all the objects which define the look of the spawner. --
     300                    </attached>
     301                </StaticEntity>
     302            </spawner-representation>
     303        </PickupRepresentation>
     304    </Template>
     305    @endcode
     306    Please refer to the <code>pickup_representation_templates.oxt</code> for more examples.
     307
     308    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).
     309    @code
     310    inventoryRepresentation = "MediumHealth"
     311    @endcode
     312    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>.
     313
     314    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>pickup_representation_templates.oxt</code> file and the <code>pickups.oxi</code> file, so that anyone who wants to use it can do so quite easily.
     315
     316    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".
     317    A @ref orxonox::PickupCollection "PickupCollection" can be created as follows:
     318    @code
     319    <PickupCollection>
     320        <pickupables>
     321            -- some pickups you want to have in your collection, e.g. --
     322            <HealthPickup template=smallhealthpickup />
     323            <HealthPickup health=50 healthRate=5 durationType=continuous activationType=immediate healthType=limited />
     324        </pickupables>
     325    </PickupCollection>
     326    @endcode
     327    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.
     328
     329    @section CreatingAPickup Creating a new pickup
     330    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.
     331
     332    @subsection CreatingAPickupClass Creating the class
     333    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".
     334    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.
     335    Additionally you have to add your pickup as a friend of the @ref orxonox::PickupCarrier "PickupCarrier" class. To that end open <code>PickupCarrier.h</code> in the <code>orxonox/interfaces</code> folder and add your class under
     336    @code
     337    // Forward-declarations.
     338    @endcode
     339    and under
     340    @code
     341    // Friends
     342    @endcode
     343
     344    @subsection ChoosingTheCarriers Coosing the carriers
     345    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.
     346    - 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.
     347    - 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.
     348    @code
     349    this->addTarget(ClassIdentifier<MyCarrierClass>::getIdentifier());
     350    @endcode
     351
     352    @subsection CreatingTheInnerWorkings Creating the inner workings of your pickup
     353    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.
     354    - 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.)
     355    - 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.
     356
     357    Let's have a look at the important methods.
     358    - <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.
     359    - <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.
     360    - <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.
     361
     362    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>.
     363    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.
     364    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>.
     365
     366    - <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:
     367    @code
     368    void MyPickup::clone(OrxonoxClass*& item)
     369    {
     370        if(item == NULL)
     371            item = new MyPickup(this);
     372
     373        SUPER(MyPickup, clone, item);
     374
     375        MyPickup* pickup = dynamic_cast<MyPickup*>(item);
     376        // Here you should set all the important parameters (that distinguish the different types of this pickup), e.g.
     377        pickup->setSomeParameter(this->getSomeParameter());
     378        // You must also initialize the identifier of the new pickup, this is normally done in a member function called in
     379        pickup->initializeIdentifier();
     380    }
     381    @endcode
     382    - <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:
     383    @code
     384    void Pickup::initializeIdentifier(void)
     385    {
     386        // If the get method returns a string.
     387        std::string val1 = this->getSomeParameter();
     388        std::string type1 = "someParameter";
     389        this->pickupIdentifier_->addParameter(type1, val1);
     390        // If the get method doesn't return a string
     391        std::stringstream stream;
     392        stream << this->getSomeOtherParameter();
     393        std::string type2 = "someOtherParameter";
     394        std::string val2 = stream.str();
     395        this->pickupIdentifier_->addParameter(type2, val2);
     396    }
     397    @endcode
     398
     399    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".
     400    - <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.
     401    @code
     402    bool MyPickup::createSpawner(void)
     403    {
     404        new DroppedPickup(this, this, this->getCarrier());
     405        return true;
     406    }
     407    @endcode
     408
     409    @section PickupTechnicalDetails Technical details
     410
     411    @image html pickupmodule.png
     412
    197413    @defgroup PickupItems Items
    198414    @ingroup Pickup

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

    r7547 r7551  
    7474        @code
    7575        <HealthPickup
    76             health = 33
     76            health = 50
    7777            healthType = "limited"
    7878            activationType = "immediate"

  • code/trunk/src/orxonox/pickup/PickupIdentifier.h

    r7547 r7551  
    8383    @brief
    8484        Struct that overloads the compare operation between two @ref orxonox::PickupIdentifier "PickupIdentifier" pointers.
     85
     86    @ingroup Pickup
    8587    */
    8688    struct PickupIdentifierCompare
Note: See TracChangeset for help on using the changeset viewer.