The PaperDoll functions rely largely on the writer just making up what is needed as and when necessary.  There are no set lists of locations or items or item uses (except 3, view, equip and unequip).  So let’s start with what you will need.

1) Call &initialise_paper_doll(); as soon as possible.  Preferably in Reference 0 of your book.  This can be done with an event tag or a script tag or pretty much anything that calls SEL but those 2 are most appropriate.

2) Place &display_items_enumerated(); in your character sheet reference using a script tag.  It’s not essential to use this function to display and run the doll but there are no other properly formatted predefined functions to do so at this time, and without displaying the list most of the effective functionality of the library is lost.

That’s all the set up needed.  From here on in it’s simply a case of defining our items and multiple locations as and when they are needed.  Obviously for coherences sake and ease of editing it’s probably best if you make a list of all the items a reader may gain throughout the adventure and define the whole lot at one go say at the start of the adventure on reference 0 like the initialise function.  Naturally we do not actually call to gain these items until the relevant points in the adventure.  So how do we define an item?

 

3) Call &define_item($item_name,$equip_location,$usage_reference); for each item you want to create at some point later on, using an event tag or script tag.  For example to define a ‘Magic Sword Fangthane’ (you can call your item whatever you want), I would simply say &define_item(‘Fangthane’,’combat hand’,’use_Fangthane’);

If you’re wondering where ‘combat hand’ came from, I just made it up.  This will be the location defined as Fangthanes location when it is equipped.  If anything else occupies a location called ‘combat hand’ when I equip Fangthane (see later for equipping) that item will be automatically unequipped, and vice versa if I equip anything else that has ‘combat hand’ as its equip location when Fangthane is already equipped, Fangthane will be automatically unequipped.  It’s up to you to keep track of what your ‘Paper Doll’ is looking like as you write the adventure and define your items.  If the item has no equip location just leave this parameter as a null string ”.  It is possible to create a location that actually occupies multiple locations if necessary, which I will discuss later.

The usage reference ‘use_Fangthane’ (the last parameter of this call to &define_item) means we need to create a reference in the book called ‘use_Fangthane’.  You can call  it anything you like whatsoever as long as you can create a book reference for it.  If the item you are making has no ‘uses’ (i.e. it does nothing at all even when equipped or unequipped), and you don’t want to supply some kind of description for this item, just leave this as a null string ”.  I will discuss creating the usage references later.

So that’s our item defined.  Now we just need to know how to add them to our characters inventory.

 

4) Call &gain_item($item_name); in an event or script tag wherever the character finds one in the book.  For example to gain an item of type Fangthane simply say &gain_item(‘Fangthane’);  That’s it.  You have created your Paper Doll and added your first item to it, with automatic equip/unequip functionality accessible from the Character Sheet.

All that’s really left now is to explain the two other aspects of the PaperDoll library essential for making really useful items.

 

5) Defining the ‘usage reference’.  In the Book editor create a reference called ‘use_Fangthane’.  There are 2 predefined uses for any item that has an equip location defined, ‘equip’ and ‘unequip’.  All items that have a usage reference also get the use ‘view’.  Simply put, think of the usage reference as a normal reference that is dedicated purely to working the item.  At this time it generally ends up being displayed in the ‘Actions’ part of the screen next to the main page, but it could go anywhere depending on how the PaperDoll functions are used, and appears when a reader clicks on the item in the character sheet.

When a reader clicks on an item displayed from the character sheet (Fangthane in this case) not only does our usage reference get displayed but 2 global SEL variables are set for us, $item_ID and $item_action.  It’s $item_action we are mostly interested in.  This will hold the action the reader is trying to perform, which can be ‘view’ ‘equip’ ‘unequip’ or anything we define in the usage reference.  If you simply make a usage reference that holds some text describing the item, that text will always be displayed when performing an action on our item (like ‘view’).

Now since ‘use_Fangthane’ is an ABML document, we can use the value in our $item_action variable to do some neat stuff, like do different things depending on what action is happening.  So we can set up a simple if tag test like:

<if condition=”$item_action eq ‘view’;”>This is a kick ass sword called Fangthane</if>.

Which means we only get a description if the reader is actually ‘viewing’ the item.  Huh, so what.  Ok, it’s a magic sword and like all good magic swords should give us bonuses when it’s equipped, so:

<if condition=”$item_action eq ‘equip’;”><event event=”$skill=$skill+2;”>You grip Fangthane</event> and feel more skillful</if>.

<if condition=”$item_action eq ‘unequip’;”><event event=”$skill=$skill-2;”>You sheathe Fangthane</event> and feel less skillful</if>.

Hope that’s self explanatory.

OK, that’s good for the predefined stuff but what about other uses since I said we could have any uses we like.  Perhaps Fangthane can boost our luck if we do something like talk to it (let’s call this use ‘invoke’).  Easy.  In the usage reference description, maybe as part of our IF ‘view’ or outside IF ‘view’ if we want this option to come up every time the usage reference is displayed, we add a usage option like so:

You may invoke Fangthane to boost your Luck: <script script=”&display_use_option($item_ID,’invoke’);” />

Then add another action clause to handle what happens when we ‘invoke’ Fangthane:

<if condition=”$item_action eq ‘invoke’;”><event event=”$luck=$luck+1;”>You speak to Fangthane</event> and feel more lucky</if>.

Don’t worry about $item_ID, that’s supplied to us when the usage reference is displayed so we just need to add that as it is for the &display_use_option function to work.

So that’s about that for uses.

 

6) Multiple Locations.  Lastly, we sometimes have an item that occupies multiple locations when equipped the best example I can think of is a two handed sword, which naturally precludes the use of a shield or anything in the off-hand.  To tackle this situation we have &define_multiple_location.  Simply with an event or script tag call this function like so: &define_multiple_location(‘Hands’,’Primary Hand’,’Off Hand’);

This defines the location ‘Hands’ to occupy two other locations, ‘Primary Hand’ and ‘Off Hand’.  You can define it to occupy as many locations as you want, even other multiple locations (like’Fingers’).  Equip an item that has its equip location defined as ‘Hands’ and it will also be occupying the locations ‘Primary Hand’ and ‘Off Hand’.

 

So that’s about it for an introduction to the PaperDoll library.  There’s a lot of other functionality available, and a lot of stuff that still needs adding by me (I have yet to implement another common facility ‘charges’ for items like potions and wands etc., container items, encumberance, item type descriptions and item quantifiers), but I hope you can find your way round using these basic facilities easily enough using the current development for a satisfactory Gamebook writing experience.