Orxonox  0.0.5 Codename: Arcturus
Modules | Files | Classes | Enumerations
Pickup

The Pickup module adds a special type of object to Orxonox, the so-called Pickupables. More...

Modules

 Items
 The actual pickups can be found here.
 

Files

file  CollectiblePickup.h
 Definition of the CollectiblePickup class.
 
file  Pickup.h
 Declaration of the Pickup class.
 
file  Pickupable.h
 Definition of the Pickupable class.
 
file  PickupCarrier.h
 Definition of the PickupCarrier class.
 
file  PickupCollection.h
 Declaration of PickupCollection.
 
file  PickupListener.h
 Definition of the PickupListener class.
 
file  PickupManager.h
 Definition of the PickupManager class.
 
file  PickupRepresentation.h
 Definition of the PickupRepresentation class.
 
file  PickupSpawner.h
 Definition of the PickupSpawner class.
 

Classes

class  orxonox::CollectiblePickup
 The CollectiblePickup class encompasses all Pickupables that can be added to a PickupCollection and thus be part of such. More...
 
class  orxonox::Pickup
 The Pickup class offers (useful) base functionality for a wide range of pickups. More...
 
class  orxonox::Pickupable
 An Interface (or more precisely an abstract class) to model and represent different (all kinds of) pickups. More...
 
class  orxonox::PickupCarrier
 The PickupCarrier interface provides the means, for any class implementing it, to possess Pickupables. More...
 
class  orxonox::PickupCollection
 The PickupCollection combines different Pickupables (more precisely CollectiblePickups) to a coherent, single pickup and makes them seem (from the outside looking in) just as if they were just one Pickupable. More...
 
struct  orxonox::PickupInventoryContainer
 Data structure to store collected data for one specific Pickupable. More...
 
class  orxonox::PickupListener
 The PickupListener class facilitates the flow of information regarding the picking up, dropping, using and unusing of Pickupables to interested parties (such as the PickupManager). More...
 
class  orxonox::PickupManager
 The PickupManager class manages Pickupables. More...
 
class  orxonox::PickupRepresentation
 The PickupRepresentation class represents a specific pickup type. More...
 
class  orxonox::PickupSpawner
 
The PickupSpawner class is responsible for spawning @ref orxonox::Pickupable "Pickupables" of a specific type.
More...
 

Enumerations

enum  orxonox::PickupActivationType { orxonox::PickupActivationType::immediate, orxonox::PickupActivationType::onUse }
 Enum for the Pickup activation type. More...
 
enum  orxonox::PickupDurationType { orxonox::PickupDurationType::once, orxonox::PickupDurationType::continuous }
 Enum for the Pickup duration type. More...
 

Detailed Description

The Pickup module adds a special type of object to Orxonox, the so-called Pickupables.

Pickupables are objects that can be picked up (by virtually any entity, but commonly by the Pawn) and have some kind of effect on the entity that picked the Pickupable up.

Including pickups in a level

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 Pickupables) or in the game) are neatly seperated. To be able to use Pickupables in a level one must understand some basic concepts.

Using predefined pickups

There is a file called pickupRepresentationTemplates.oxt in levels/templates, which holds the templates for the PickupRepresentations and also templates for Pickupables. The templates for the PickupRepresentations define the StaticEntities that are attached to the PickupSpawners to make them look like the Pickupable they are spawning. The templates for the Pickupables can be added just for ease of use. If you want to use pickups you will have to include this file in your level file, somewhere above the Level-tag.

<?lua
include("templates/pickupRepresentationTemplates.oxt")
?>
...
<Level>
...

There is another file called pickups.oxi in level/includes which creates all PickupRepresentations needed for the Pickupable supplied by the pickupRepresentationTemplates.oxt 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.

<Scene>
...
<?lua
include("includes/pickups.oxi")
?>

After that all the predefined pickups specified in those two files can be used just by creating a PickupSpawner for them in the respective level. For example:

<PickupSpawner position="-100,0,-100" respawnTime="30" maxSpawnedItems="10">
<pickup>
<HealthPickup
health = 10
healthType = "limited"
activationType = "immediate"
durationType = "once"
/>
</pickup>
</PickupSpawner>

Please be aware, that the Pickupable specified for the PickupSpawner, has to be exactly the same (including all parameters) to the one specified in the pickups.oxi file. To make things simpler, one could just use the templates specified in the pickupRepresentationTemplates.oxt file. Which, following the previous example, would look like this:

<PickupSpawner position="-100,0,-100" respawnTime="30" maxSpawnedItems="10">
<pickup>
<HealthPickup template="smallhealthpickup" />
</pickup>
</PickupSpawner>

Using non-predefined pickups

To include a type of pickup (which, as we remember, is the class of the Pickupable with specific values for all the relevant parameters) in a level file, you can just create a new PickupSpawner and specify the Pickupable.

<PickupSpawner position="-100,0,-100" respawnTime="30" maxSpawnedItems="10">
<pickup>
<HealthPickup
health = 33
healthType = "limited"
activationType = "immediate"
durationType = "once"
/>
</pickup>
</PickupSpawner>

As can be seen in the pickupRepresentationTemplates.oxt file and the pickups.oxi file there is no PickupRepresentation defined for this type of pickup. Thus the default representation will be used.

To create an appropriate PickupRepresentation for the inserted pickup above, you can just create a PickupRepresentation within the scene (Within the Scene-tags).

<PickupRepresentation
name = "My new health pickup"
description = "This is an awesome new health pickup."
spawnerTemplate = "mediumhealthpickupRepresentation"
inventoryRepresentation = "MediumHealth"
>
<pickup>
<HealthPickup
health = 33
healthType = "limited"
activationType = "immediate"
durationType = "once"
/>
</pickup>
</PickupRepresentation>

Notice, that the type of pickup specified for the PickupRepresentation, naturally, needs to be the same (this is the way they can be connected). Also, we just used an existing spawnerTemplate, to make things simpler.

The next step is to create a spawnerRepresentation uniquely for our new type of pickup. Lets call it newhealthpickupRepresentation. Thus the parameter spawnerTemplate of the PickupRepresentation has to be changed to that value.

spawnerTemplate = "newhealthpickupRepresentation"

The spawnerTemplate defines how the PickupSpawner is displayed in a level. In our example case it could look like this:

<Template name=newhealthpickupRepresentation>
<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>

Please refer to the pickupRepresentationTemplates.oxt for more examples.

The PickupRepresentation also needs another parameter the inventoryRepresentation. This parameter defined how the Pickupable is displayed in the PickupInventory (a menu to browse the currently equipped pickups).

inventoryRepresentation = "MediumHealth"

This is the name of an image defined in the PickupInventory imageset (PickupInventory.imageset), which can be found in data_extern/gui/imagesets.

This is all that has to be done. Now you have a new pickup type with an appropriate 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 pickupRepresentationTemplates.oxt file and the pickups.oxi file, so that anyone who wants to use it can do so quite easily.

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 Pickupable called the PickupCollection, which is just a collection (hence the name) of Pickupables (more precisely of CollectiblePickups), behaving as if it was just one Pickupable. A PickupCollection can be created as follows:

<PickupCollection>
<pickupables>
-- some pickups you want to have in your collection, e.g. --
<HealthPickup template=smallhealthpickup />
<HealthPickup health=50 healthRate=5 durationType=continuous activationType=immediate healthType=limited />
</pickupables>
</PickupCollection>

Of which types of pickups a collection is made up is entirely up to the one creating the PickupCollection, they can be mixed freely.

Creating a new pickup

Things have been fairly straightforward so far. Creating a 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.

Creating the class

For a new Pickupable you need to create a new class in >modules/pickup/items. Your class needs to be derived from another pickup class, normally this would either be Pickupable, CollectiblePickup or Pickup. Pickupable is (as mentioned earlier) the base class of all things that can be picked up, thus of all pickups. CollectiblePickup is a (directly) derived class of Pickupable and provides the additional functionality of enabling your pickup to be used in a PickupCollection. However you are probably going to want to derive your class form Pickup, because it is a CollectiblePickup and provides some useful methods. So have a look at Pickup. Once you have created your new pickup class you have to insert it in the PickupPrereqs.h file in the modules/pickup folder and in the CMakeList.txt file in the modules/pickup/items folder. Also have a look at other pickups to make sure you include all the necessary files in your class.

Coosing the carriers

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.

Creating the inner workings of your pickup

Todo:
This is completely outdated. Someone who knows how pickups work should update this.

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 Pickupable, for our pickup to work properly. But first I will introduce some more concepts to make the need for these methods more obvious.

Let's have a look at the important methods.

Please be aware, that these three methods are methods registered with Super, meaning, that whenever overloading them, don't forget to call SUPER(MyClass, myMethod);. 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. Additionally you should use the destroy() method of Pickupable instead of the method provided by OrxonoxClass, meaning Pickupable::destroy() instead of plain destroy().

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 PickupCollection with a derived class of the PickupIdentifier, the PickupCollectionIdentifier) or in the DronePickup class by using a Template.

Technical details

pickupmodule.png

Enumeration Type Documentation

Enum for the Pickup activation type.

Enumerator
immediate 

Means that the Pickup will be used immediately after pickup.

onUse 

Means that the Pickup will be used at a later point trough some external influence.

Enum for the Pickup duration type.

Enumerator
once 

Means that the Pickup will be used only once at a singular time instant.

continuous 

Means that the Pickup will be used over a continuous timespan.