A general usage guide for this library is forthcoming, in the meantime suffice to say for now if you’re confused about what and where (non-multiple) locations are defined, they aren’t you just make them up as you need them when defining items, likewise usage references (which you need to create an ABML reference in your adventure for with the same name as the usage reference)

Synopsis:
A set of functions to provide a virtual ‘paper doll’ inventory management system for Adventures.

Description:
Most RPG computer games provide a screen depicting a ‘paper doll’ figure of the adventurer with slots for placing/storing items gathered during an adventure.  Most typically an item is in a storage location or defined as ‘equipped’ to a location on the body, e.g. a sword is equipped to a hand, a cloak is equipped to the back and so on.  This definition is important as usually items that provide bonuses to the statistics system will not provide those bonuses when merely possessed and must be equipped to give those bonuses.

The difficulty that arises is that you obviously cannot wear (equip) two suits of armour, or wear two cloaks and so on.  The Paper Doll library attempts to provide an infinitely extensible method of assigning items to writer defined locations, as well as provide a method system to allow user defined functions to change the statistics system (or do pretty much anything) according to events such as equipping, storing or dropping an item.

This library is still under development and as such to use it reliably ought to be copied completely to your books associated SEL file to avoid updates altering expected behaviour.

Usage:
Not all functions in this library are intended for general usage, many simply support the usable functions.  The library is intended as a package, i.e. none of the functions are useful in a stand-alone context.  When copying functions of this library the entire library must be copied for the functions to work.

Note that many functions require a parameter $item_ID which uniquely identifies the item in question.  This ID number for an item is created on using the &gain_item function, which creates an instance of the new item in the @items array (consider the @items array to be a list of all the actual existing items).  Understanding the data arrangement and use of the 4 arrays is essential if you wish to do more than use the existing intereface functions.

Requirements:
Reserves the permanent variables: @multiple_locations, @item_definition, @item_locations, @items, $items_ID_index, $item_action, $item_ID
These variables should not be used or defined in any context other than using this library, altering them inappropriately is likely to cause errors.
(Note: Ought to put all these variables into one single array variable to reduce the reserved variable list?).
There are no required libraries to be included for this library to function at this time.

Note to self for further development:
Many functions output data/tags etc. themselves and have no return value.  Ought to redifine these to return what is currently being output so that coders may choose how to handle functions output.
Need a get_locations function that recursively gets all multiple locations (equipping and unequipping does this but need a general function since &is_location_multiple merely returns the immediately defined locations.

Functions:

• &initialise_paper_doll()

Simply declares all the required permanent variables so that the other paper doll functions can be used subsequently.  Best used at the very start of an adventure (e.g. reference 0).
Example:
&initialise_paper_doll();

• &item_equip($item_ID)

Equips the item referenced by $item_ID to its defined equip location, unequips any item(s) that are already equipped in its equip location(s).  If the item definition for the item includes a usage reference a dynamic ABML ‘event’ tag will be generated setting the global variable $item_action to ‘equip’ , and a subsequent ABML ‘include’ tag will be generated that outputs the reference defined in the usage definition.
Example:
&item_equip(&gain_item(&define_item(‘Shield’,’offhand’,’shield’)));
Firstly an item is defined by &define_item (see later), then &gain_item (again, see later) creates an actual instance of the item name returned by &define_item, finally &item_equip takes the instance ID returned by &gain_item and equips the ‘Shield’ to the location ‘offhand’, unequipping anything already equipped there first.  &item_equip also then includes the reference ‘shield’ at the point in the document where &item_equip was called, with the $item_action variable set to ‘equip’ and the $item_ID global variable set to the passed $item_ID via an ‘event’ tag.  This means that in the adventure reference ‘shield’ a test for the status of $item_action can be tested e.g. using an ABML ‘if’ tag and any action that should happen on equipping a shield can be defined there (e.g. plus 2 Skill or whatever). Note that if the function is called through an ‘option’ tag the included reference will be displayed in the Actions area like all other ‘option’ output.
Returns:1 if item succesfully equipped, 0 if item does not have an equip location.

• &item_location_equip($item_ID, $location)

Intended to support &item_equip, generally you should use that if you wish to equip items.  Performs the task of updating the various arrays and unequipping items already at equip location.

• &item_unequip($item_ID)

Unequips the item indicated by $item_ID.  If the item has a usage reference an event tag will be output setting $item_action to ‘unequip’, and a subsequent include tag will be output which will include the items usage reference at the point in the document where &item_unequip was called, as with &item_equip this will allow a test in the usage reference for the variable $item_action being set to ‘unequip’ (as well as global variable $item_ID being set to the passed $item_ID) so that behaviour for unequipping that item may be defined there.

• &item_location_unequip($location)

Intended to support &item_unequip.  Do not use this function directly as it will not execute the usage reference output clause.
note: this would be a generally useful function as writer may wish to force reader to unequip whatever is in their hands, must write a function to do this and call &item_unequip for equipped item at the location specified.

• &item_location_is_multiple($location)

Checks if the passed $location is defined as a multiple location (e.g. hands can be defined as comprising ‘left hand’ and ‘right hand’), and returns the list of the locations defined if so, nulll string otherwise. Does not recursively check listed locations for being multiple.

• &item_get_equip_location($item_ID)

Returns the equip location defined for the item_ID’s item definition, or a null string if it has no defined equip location.

• &item_existing_at_location($location)

Returns the item_ID of the item that is equipped to the location passed as $location, or a null string if no item is equipped to that location.

• &equip_status($item_ID)

Returns 0 for not equippable, 1 for equipped, 2 for unequipped, for the item_ID passed.

• &get_item_name($item_ID)

As it says on the tin (or null string if item_ID not found in @items)

• &display_equipped_locations()

Displays all locations that have something equipped to them, with the item name that is equipped to it

• &define_multiple_location($master_location, @locations)

Defines locations that include other locations, e.g. the location for a 2-handed-weapon could simply be called ‘hands’ (master location), which is defined as a multiple location consisting of ‘primary hand’ and ‘off hand’ (locations).
Example:
&define_multiple_location(‘Full Armour’,’head’,’arms’,’legs’,’torso’);
This will define a location called ‘Full Armour’ that occupies the locations head arms legs and torso.  When equipping an item to the Full Armour location (like some Armour) anything in any of the defined locations e.g. if a hat was equipped to the head and some leggings on the legs, all these items will be unequipped.  Likewise equipping a hat to the head when Full Armour is equipped will cause the Full Armour to Unequip itself.  Also note that Multiple Locations may include other Multiple Locations.

• &define_item($item_name,$equip_location,$usage_reference)

Redefines, or creates a new definition, of an item keyed by $item_name in the @item_definition array.  Returns the item name.

• &gain_item($item_name,$quantity)

Adds (quantity) new instance(s) of an item defined by $item_name to the @items array and returns the last new item ID.  Since @items is generally used as a characters inventory, this means the character has gained an item.  If quantity is omitted, 1 is assumed.

• &lose_items(@item_ID)

Removes all items in the list of @item_ID’s  from the array @items.  @item_ID must be a list of item instance ID’s not names.  If those items are equipped, the items are unequipped first.  This generally means the character has lost the items.

• &display_items()

This is a developmental tool, displays all item names in @items as an option tag with a call to &view_items, and also displays the item ID and the items usage ref definition field.  Not intended for general use.

• &display_items_enumerated()

Displays all items in @items by name in 2 parts, the first part of the list is the equipped items with their current location in brackets afterwards, the second part of the list is non-equipped items with an enumeration indicator where there are multiple unequipped items with the same definition (e.g. Torches*5).  The names are displayed as an option tag link that calls &item_view for the item_ID in question (when displaying an enumerated item the item_ID of the first item is passed to &item_view).  This is intended for general use, and is ideal for character sheet inventories.

• &item_view($item_ID)

Displays standard options for an item:
Drop item (lost for good)
Equip/Unequip options (according to current equip status and whether item has an equip location)
Also displays the items usage ref through output of an include tag and the global variables $item_action set to ‘view’ and $item_ID to the ID of the viewed item, by an event tag.

• &get_item_usage_reference($item_name)

Returns the usage reference for the item defined in @item_definition.

• &item_uses($item_ID,$item_use)

Deprecated, use &display_use_option

• &include_item_file($ref)

Do not use.

• &display_use_option($item_ID, $item_use)

Intended for use within an items usage reference.  The parameter $item_use is user defined and can be anything the writer wishes e.g. ‘drink’ for a potion.  The function displays an option tag that effectively re-calls the usage refeence (through the function &use_item) with the $item_action variable set to whatever was passed as the $item_use parameter, allowing conditional behaviour to be defined within the usage reference for that action.

• &use_item($item_ID, $item_use)

Outputs an include tag that calls the items usage reference and sets the $item_action variable to whatever was passed as the $item_use parameter via an event tag, allowing conditional behaviour to be performed in the usage reference.

• &lose_items_by_name($lose_item,$quantity)

Removes items with the name supplied in the $lose_item parameter from the @items array, the number of which is defined by the $quantity parammeter – pass the string ‘all’ to lose all the named items.  Unequips any equipped items that are set to be lost first.  Returns the number of items succesfully ‘lost’.

• &has_item($item_name)

Returns the item_ID of the first item in the @items array that has the name passed in $item_name parameter, or integer 0 if the item name is not in the @items array.  A good way to either perform a simple ‘has a character got this item’ check, or to get an item_ID of a particular item for use with other functions in this library.

• &count_items($item_name)

Returns the number of items in the @items array whos name matches that of the passed parameter $item_name.  So if you want to know if the character has 3 wands of doom….

• &has_item_equipped($item_name)

Boolean function returns 1 if an $item_name is defined as equipped in the @items array or 0 if the item name isn’t found or isn’t equipped.

• &display_item_definitions()

Displays all the entries in the @item_definitions array (item name, item equip location, item usage reference).  Note this displays item definitions and has nothing to do with the actual instances of items in the @items array.