Castle Game Engine: CastleItems: Class TInventoryItem

# Class TInventoryItem
Description | Hierarchy | Fields | Methods | Properties
## Unit CastleItems ## Declaration `type TInventoryItem = class(TComponent)` ## Description An item that can be used, kept in the inventory, or (using PutOnWorld that wraps it in TItemOnWorld) dropped on 3D world. Thanks to the Quantity property, this may actually represent many "stacked" items, all having the same properties. ## Hierarchy TComponent TInventoryItem ## Overview ### Methods
| `procedure Stack(var Item: TInventoryItem); virtual;`
| `procedure Picked(const NewOwner: T3DAliveWithInventory); virtual;`
| `procedure Use; virtual;`
| `function Split(QuantitySplit: Cardinal): TInventoryItem;`
| `function PutOnWorld(const AWorld: T3DWorld; const APosition: TVector3Single): TItemOnWorld;`
| `function World: T3DWorld;`
### Properties
| `property Resource: TItemResource read FResource;`
| `property Quantity: Cardinal read FQuantity write FQuantity;`
| `property Owner3D: T3D read FOwner3D;`
## Description ### Methods
| `procedure Stack(var Item: TInventoryItem); virtual;`
Try to sum (`stack`) the given Item with current TInventoryItem. The idea is that if player has 5 arrows, and picks an item representing another 5 arrows, then we sum then into one TInventoryItem instance representing 10 arrows. Various games, and various items, may require various approaches: for example, maybe you don't want some items to `stack` at all (e.g. you want to only allow stacking for items naturally appearing in vast quantities, like arrows and bolts and bullets (if you represent them as TInventoryItem at all)). Maybe you want to allow stacking only to centain number, e.g. arrows are summed into groups of maximum 20 items, anything above creates new `stack`? Overriding this procedure allows you to do all this. You can here increase the Quantity of current item, decrease the Quantity of parameter Item. In case the parameter Item no longer exists (it's Quantity reaches 0) you have to free it and set to `Nil` the Item parameter, in practice you usually want to call then `FreeAndNil(Item)`. The default implementation of this in TInventoryItem class allows stacking always, as long as the Resource matches. This means that, by default, every TItemResource is existing at most once in T3DAliveWithInventory.Inventory.
| `procedure Picked(const NewOwner: T3DAliveWithInventory); virtual;`
Item is `picked` by an alive player/creature. The default implementation in this class adds the item to the Inventory by calling T3DAliveWithInventory.PickItem. You can override this to cause different behavior (for example, to consume some items right at pickup). Remember that this method must take care of memory management of this item.
| `procedure Use; virtual;`
`Use` this item. In this class, this just prints a message "this item cannot be used". Implementation of this method can assume for now that this is one of player's owned Items. Implementation of this method can change our properties, including Quantity. As a very special exception, implementation of this method is allowed to set Quantity of Item to 0. Never call this method when Player.Dead. Implementation of this method may assume that Player is not Dead. Caller of this method should always be prepared to immediately handle the "Quantity = 0" situation by freeing given item, removing it from any list etc.
| `function Split(QuantitySplit: Cardinal): TInventoryItem;`
Splits item (with Quantity >= 2) into two items. It returns newly created object with the same properties as this object, and with Quantity set to QuantitySplit. And it lowers our Quantity by QuantitySplit. Always QuantitySplit must be >= 1 and < Quantity.
| `function PutOnWorld(const AWorld: T3DWorld; const APosition: TVector3Single): TItemOnWorld;`
Create TItemOnWorld instance referencing this item, and add this to the given 3D AWorld. Although normal item knows (through Owner3D) the world it lives in, but this method may be used for items that don't have an owner yet, so we take AWorld parameter explicitly. This is how you should create new TItemOnWorld instances. It is analogous to TCreatureResource.CreateCreature, but now for items.
| `function World: T3DWorld;`
3D world of this item, if any. Although the TInventoryItem, by itself, is not a 3D thing (only pickable TItemOnWorld is a 3D thing). But it exists inside a 3D world: either as pickable (TItemOnWorld), or as being owned by a 3D object (like player or creature) that are part of 3D world. In other words, our Owner3D.World is the 3D world this item lives in.
### Properties
| `property Resource: TItemResource read FResource;`
| `property Quantity: Cardinal read FQuantity write FQuantity;`
Quantity of this item. This must always be >= 1.
| `property Owner3D: T3D read FOwner3D;`
3D owner of the item, like a player or creature (if the item is in the backpack) or the TItemOnWorld instance (if the item is lying on the world, pickable). May be `Nil` only in special situations (when item is moved from one 3D to another, and technically it's safer to `Nil` this property). The owner is always responsible for freeing this TInventoryItem instance (in case of TItemOnWorld, it does it directly; in case of player or creature, it does it by TInventory).
Generated by PasDoc 0.13.0 on 2015-06-15 04:43:10