Part 2: Items

The details of this procedure is largely outlined in the PaperDoll Library SEL guide article, however I will run through it here.  Since most adventures involve gaining items and in some cases using them you will need to know how to do this.  Note this section might actually be pretty complex for the novice, so unless you need more than just the most basic of an item list (one that you can pick up/drop, and test for possession later on) just read the first section for now.

Creating and using a Basic Item:

Let’s say we want to create a very simple item, and add it to our inventory, say a ‘Copper Key’.  It has no uses, does nothing to our statistics, and is simply required at some point in the adventure.

1) Define the item

Place this in a reference when you want the item to be defined (I suggest defining all items right at the start of the adventure):

<event event="&define_item('Copper Key');" />

Though a script tag could be used I recommend not doing so.

 

2) Gain the item

Place this in a reference where you want a copper key to be gained, for example:

You open the cupboard.  Inside is what looks like a shoe box, which you cautiously open to reveal a Copper Key, which <event event="&gain_item('Copper Key');">you decide to put in your backpack</event>

Option tags may also be used if you want to let the reader choose to gain an item or not:

If you wish you may <option option=”&gain_item(‘Copper Key’);”>take the key</option>

Defining an item and gaining an item can be done at the same time like so:

<event event="&gain_item(&define_item('Copper Key'));">you decide to put in your backpack</event>

 

3) Test for the item

Let’s say our Hero encounters a locked door that looks suspiciously like it would suit our key.

You reach the end of the corridor, where there is a large door with a copper lock on it.  <if condition="&has_item('Copper Key');">If you have a Copper Key, <tt ref="123">turn to 123</tt></if><else>Otherwise you must retreat back down the corridor <tt ref="456">turn to 456</tt></else>

 

Refining an item – defining a Usage Reference:

You may have noticed that while the Key has no use until you get to the point where the adventure demands it, the entry in the items list is a clickable link that displays a ‘no description’ message and an option to drop it.  Well, this is pretty unfriendly so let’s add a description to our item.  This is not essential for the Key really but it helps explain the process needed for more complex items.  We firstly do this by creating a ‘usage reference’.  This is basically just another normal reference named something we will remember, I simply use the same name as the item, so create a reference called ‘Copper Key’ and add some text that describes it/where it was found etc. then hit Save.

Now change the definition of the Copper Key to this:

<event event="&define_item('Copper Key','','Copper Key');" />

(note the double quote in the middle is in fact two single quotes – this should change in the future to not being needed).

Now when you click on the link for the Key in the Items list, the description will appear in the Actions area.

 

Making Provisions/Potions etc.

Defining an item may be nice but doesn’t actually do anything all that useful so far.  But what I didn’t explain is that the Usage Reference is actually checked for ABML itself, so we can put more than just a bit of text in our description!  Most typically this is great for items like potions or provisions, because we can really get tricky with our usage reference, so lets define and gain an item, say provisions, like so:

<event event="&define_item('Provisions','','Provisions')" />

<event event="&gain_item('Provisions');" />

… and make a Usage Reference called ‘Provisions’, but this time do NOT add text to it, yet.

This time, we need to know whether we are just looking at the Provisions, or whether we are doing something else like eating them.  So firstly we add some text to the Usage Reference (‘Provisions’ in this case) for just looking at the Provisions like so:

<if condition="$item_action eq 'view';" falsecolor="hidden">These are provisions.  If you eat them you will gain 4 Stamina <script script="&display_use_option($item_ID,'Eat Provisions');" /></if>

If you look at the Provisions in your items list now, you will see the description along with the option to ‘Eat Provisions’.  So we had better add something to deal with what happens when that is clicked on to our Usage Reference (‘Provisions’) like so:

<if condition="$item_action eq 'Eat Provisions';" falsecolor="hidden">You eat your  provisions and <event event="&gain_stat('stamina',4);&lose_items($item_ID);">gain 4 Stamina </event></if>

Now we have our Provisions, and the reader may instruct the hero to eat them at any time to gain 4 stamina (and lose one portion of provisions).

 

Equipping/Unequipping items

Defining an item that is ‘equippable’, the most typical example would be a Sword, is straightforward.  An equippable item is something that has a specific place it has to be placed in/on (typically somewhere on the body) to be of use.  The PaperDoll library has some functionality built in to facilitate this.  Every equippable item may have one location defined for it, such that no other item can be equipped in that location at the same time – for example you cannot ‘equip’ 2 Swords to your ‘combat hand’ location (or a ‘sword’ and a ‘lamp’), only one item may exist in the ‘combat hand’ location at any given time (this is handled automatically for you by PaperDoll).  We simply make up what location names we want for our items to be equipped in, and allow PaperDoll to sort the rest out.  So lets define a Sword, we’ll call it a Magic Sword, in any reference you like:

<event event="&define_item('Magic Sword','Combat Hand','Magic Sword');" />

That has defined an item called ‘Magic Sword’ which is equippable in the ‘Combat Hand’ and its Usage Reference is ‘Magic Sword’.  Now let’s gain it, in whatever reference you want the hero to gain it:

<event event="&gain_item('Magic Sword')" />

Assuming you have followed the steps from the first Guide, this will appear in your Items list now, and if we click on it we have a new option in our Actions pane, ‘This item is equippable, you may Equip it’.  Clicking on the link will place the Sword in to the heros Combat Hand in our list.  Which is all very well, but so far it’s just pretty.  We need to make something happen every time it is equipped/unequipped for any of this to have any use.

Remember the ‘Eat Provisions’ test we made for $item_action earlier?  Well, ‘equip’ and ‘unequip’ are predefined actions that we may test for in our Usage Reference when we are talking about an item with an equip location defined.  So let’s say this Sword gives the hero an extra skill point, place this in the reference ‘Magic Sword’:

<if condition="$item_action eq 'equip';" falsecolor="hidden">You grip the Magic Sword, it's magical energy <event event="$skill=$skill+1">gives you 1 Skill </event></if>

<if condition="$item_action eq 'unequip';" falsecolor="hidden">You sheathe the Magic Sword, it's magical energy <event event="$skill=$skill-1">fades from you </event></if>

… and don’t forget to define an event for simply viewing the Sword in the reference too:

<if condition="$item_action eq 'view';" falsecolor="hidden">This is a magical sword, when equipped it gives you an extra Skill point </if>

And that’s it.  You have now created a Magical Sword for use by the Hero wherever in the adventure.  There are lots of other functions available to you in PaperDoll, please see the references for more information, or just ask on the forum.

Now we have our character, we know how to make kit for the Hero, we need to find out how to do stuff like Test Luck and Combat, which will be covered in section 3