Scripting:Items

Items are an area where lots of customization can be done, as they live mostly on Python side. However, this makes them a complex topic, where errors will often result in weird behaviour. Therefore, it is vital to get at least a basic understanding of the item implementation.

Inside the Engine

On the outside, all items are treated alike, but internally there is a huge difference between mutable and immutable items.

• Mutable items are all those items that can change their state throughout the game, like a torch that burns down, or a container that can be filled or emptied. Because of that, the engine has to keep track of each individual mutable item, which can become quite costly if there are a large number of them.
• Immutable items on the other hand – that is, items that don’t change, like a coin or an arrow – are not treated that way. Instead, exactly one copy of each immutable item type exists throughout the game. All instances of such an item are mere references to that single copy. This means, if an immutable item gets changed, all items of the same type will change as well!

That may sound very restrictive, but it isn’t. Immutable items can still be transformed into completely different items.

Basic Interface

Although items live mostly on Python side, that doesn’t mean that they are totally independent from the engine. Item management and persistance are part of the engine and it relies upon a specific interface. Fortunately, the item base class, defined in item.py, provides most of this interface already. As long as all items inherit (directly or indirectly) from the item class, little further work needs to be done. Only three things have to be taken care of:

• Constructor If an item requires an init method, it must not forget to call the constructor of its base class. Otherwise, some attributes of the item might remain unitialized, and errors will surely follow.
• Saving Each item must be able to save its current state. For that purpose, it has to provide the put_state method. Apart from saving its own attributes, it must not forget to save its base class.
• Loading Finally, an item must be able to restore its state. This is done via the get_state method. Again, items must also take care of loading the state of their base class.

The following script can serve as template for new items:

 import base_class 
 
 # 
 # Item description goes here 
 # 
 class new_item (base_class.base_class): 
     def __init__ (self): 
         # -- init parent class 
         base_class.base_class.__init__(self) 
         # -- init attributes ... 
 
     def [void] put_state (self, [base.flat] file): 
         # -- save state of parent class 
         base_class.base_class.put_state (self, file) 
         # -- save attributes ... 
 
     def [void] get_state (self, [base.flat] file): 
         # -- load state of parent class 
         base_class.base_class.get_state (self, file) 
         # -- load attributes ...

Advanced Interface

While the methods described above are essential for item management, they do little in terms of defining an item’s properties and abilities. For that purpose, six more methods – the so called item actions – have been defined: pick up, drop, equip, unequip, combine and use. However, not every item needs to implement every action. Those that are not essential to an item’s functionality can be omitted. Purpose and constraints of each action are described in detail below.

• The equip method serves two purposes. For one, it is used to test whether an item is equippable (by a certain character). If the equip method of an item returns 1, the item can be equipped. If it returns 0, or if the item has no equip method, the item cannot be equipped. Further, the equip method can also be used to apply any effects the item might have on the character.
• The combine method is used to implement actions involving exactly two items: an agent that is “applied” to a target. If the combination is possible, the target will be transformed, as the following examples demonstrate: