= Pickups =

== Description ==
Pickups, or more precisely Pickupables (in the following refereed to as pickups), are items that can be picked up by other entities (which are derived from the PickupCarrier class and I will in the following simply refer to as carriers) and have some effect on the carrier.

== HowTo's ==
I want to start with explaining, how pickups can be included in levels and how new pickups can be created (coded).

=== Including pickups in a level ===
I wanted to make including pickups in level as simple as possible, while also ensuring a division between the pickup itself and how it looks. For you to be able to use pickups in your level you need to understand a few concepts.
-  Pickups (Pickupables) are entities which have no physical (or graphical) dimension. The simply represent the effect they will have on a carrier, when used.
- The physical (or graphical) dimension of a pickup is called a PickupRepresentation (or in the following refereed to as representation). 
- The representation of a pickup and the pickup itself are linked to each other, meaning a representation can only represent one type of pickup.
- The entity that actually gives a pickup to a carrier is called a PickupSpawner (in the following called spawner). A spawner creates (based on some parameters) pickups which can be picked up and how the spawner looks in the game is defined by the representation of the pickup it spawns.

==== Using predefined pickups ====

There is a file called pickup_representation_templates.oxt, which holds the templates for the representations and also templates for pickups. 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/pickup_representation_templates.oxt")
?>
}}}

There is another file called pickups.oxi which creates all representations needed for the pickups supplied by the pickup_representation_templates.oxt file. You will have to include it as well. It has to be some where after the opening Scene-tag and your first use of a pickup.

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

After that you can use all the predefined pickups specified in those two files just by creating a spawner for them in your level. e.g.

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

Or even simpler, you can use the templates for pickups specified in the pickup_representation_templates.oxt file, e.g.

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

work in progress...