Converting Lone Wolf to Twine and SugarCube - Part 7 - Finishing Equipment

Finally, An Inventory System That Actually Works

     Okay, more time as passed (you should be glad you can read this all at once instead of watching me working on it :) and I think I finally have it, one widget that will handle all my inventory needs - and cut down the hundreds of lines of code to just a few dozen!
Here it is...

:: Initialize [Widget]

<<set $gold = 0>>
<<set $weapons = [ "-empty-", "-empty-" ]>>
<<set $backpack = [ "-empty-", "-empty-", "-empty-", "-empty-", "-empty-", "-empty-", "-empty-", "-empty-" ]>>
<<set $specialitems = []>>

<<widget "ManageInventory">> <<nobr>>
/*
*    Usage: this widget handles the display, removal and addition of all inventory items.
// WARNING : This widget requires several arguments to be passed.
*    <<ManageInventory  action container item quantity random_min random_max>>
* $args[0] - action: 1 - display, 2 - add item(s), 3 - remove item(s)
* $args[1] - container: 1 - Gold, 2 - Weapons, 3 - Backpack Items, 4 - Special Items, 5 - [if args[0] = 1 (display)] displays all items
* $args[2] - item:
* if adding items- the item name (no quotes needed unless the name has a space; ie, Sword and "Short Sword")
* if removing items- weapon (for a random weapon), backpack (for a random backpack item), or the item name (no quotes) if
a specific item should be searched for and removed
* $args[3] - quantity:
* # - the number of items to change
* random  - for a random number (for items this is only 1 at the moment)
* all - to remove all backpack items
* $args[4] - if a random number, the minimum
* $args[5] - if a random number, the maximum
*/
  <<switch $args[0]>>

    <<case 1>>

<<switch $args[1]>>
<<case 1>> <br> Belt Pouch: $gold Gold Crowns
<<case 2>> <br> Weapons: <<for _wi = 0; _wi < $weapons.length; _wi++>> <<print "<br>&nbsp;&nbsp;" + $weapons[_wi]>> <</for>>
<<case 3>> <br> Backpack Items: <<for _bi = 0; _bi < $backpack.length; _bi++>> <<print "<br>&nbsp;&nbsp;" + $backpack[_bi]>> <</for>>
<<case 4>> <br> Special Items: <<for _si = 0; _si < $specialitems.length; _si++>> <<print "<br>&nbsp;&nbsp;" + $specialitems[_si]>> <</for>>
<<case 5>>
<br> Belt Pouch: $gold Gold Crowns
<br> Weapons: <<for _wi = 0; _wi < $weapons.length; _wi++>> <<print "<br>&nbsp;&nbsp;" + $weapons[_wi]>> <</for>>
<br> Backpack Items: <<for _bi = 0; _bi < $backpack.length; _bi++>> <<print "<br>&nbsp;&nbsp;" + $backpack[_bi]>> <</for>>
<br> Special Items: <<for _si = 0; _si < $specialitems.length; _si++>> <<print "<br>&nbsp;&nbsp;" + $specialitems[_si]>> <</for>>
<</switch>>

<<case 2>>

  <<switch $args[1]>>

    <<case 1>>
  <<if $args[3] != "random">>You pick up $args[3] Gold Crowns, <<set $gold += $args[3]>> <<if $gold > 50>> <<set $gold = 50>> but your Belt Pouch only holds 50 Gold Crowns, <</if>> you now have $gold Gold Crowns.
  <<elseif $args[3] == "random">> <<set _goldfound = random ( $args[4], $args[5] )>> You found _goldfound Gold Crowns, <<set $gold += _goldfound>> <<if $gold > 50>> <<set $gold = 50>> but your Belt Pouch only holds 50 Gold Crowns, <</if>> you now have $gold Gold Crowns.
  <<else>> Error: Gold amount has not been defined !
  <</if>>

<<case 2>>
<span class="wpnreplace">What weapon slot do you want to replace?
<<link " <br> Replace the $weapons[0] with $args[2]">> <<set $weapons[0] = $args[2]>> <<replace .wpnreplace>> You now have a $weapons[0] and a $weapons[1] <</replace>> <</link>>
<<link " <br> Replace the $weapons[1] with $args[2]">> <<set $weapons[1] = $args[2]>> <<replace .wpnreplace>> You now have a $weapons[0] and a $weapons[1] <</replace>> <</link>>
<<link " <br> Do not pick up the items">> <<replace .wpnreplace>> You leave your items unchanged <</replace>> <</link>>
</span>

<<case 3>>
<span class="backreplace">What backpack item do you want to replace?
<<link " <br> Replace the $backpack[0] with $args[2]">> <<set $backpack[0] = $args[2]>> <<replace .backreplace>> You have gained a $args[2] <</replace>> <</link>>
<<link " <br> Replace the $backpack[1] with $args[2]">> <<set $backpack[1] = $args[2]>> <<replace .backreplace>> You have gained a $args[2] <</replace>> <</link>>
<<link " <br> Replace the $backpack[2] with $args[2]">> <<set $backpack[2] = $args[2]>> <<replace .backreplace>> You have gained a $args[2] <</replace>> <</link>>
<<link " <br> Replace the $backpack[3] with $args[2]">> <<set $backpack[3] = $args[2]>> <<replace .backreplace>> You have gained a $args[2] <</replace>> <</link>>
<<link " <br> Replace the $backpack[4] with $args[2]">> <<set $backpack[4] = $args[2]>> <<replace .backreplace>> You have gained a $args[2] <</replace>> <</link>>
<<link " <br> Replace the $backpack[5] with $args[2]">> <<set $backpack[5] = $args[2]>> <<replace .backreplace>> You have gained a $args[2] <</replace>> <</link>>
<<link " <br> Replace the $backpack[6] with $args[2]">> <<set $backpack[6] = $args[2]>> <<replace .backreplace>> You have gained a $args[2] <</replace>> <</link>>
<<link " <br> Replace the $backpack[7] with $args[2]">> <<set $backpack[7] = $args[2]>> <<replace .backreplace>> You have gained a $args[2] <</replace>> <</link>>
<<link " <br> Do not pick up the items">> <<replace .backreplace>> You leave your items unchanged <</replace>> <</link>>
</span>

<<case 4>>
<<if $specialitems.contains ($args[2])>> You already have a $args[2]!
<<else>>
<<run $specialitems.push ($args[2])>> You now have a $args[2].
<</if>>

  <</switch>>

<<case 3>>

  <<switch $args[1]>>

    <<case 1>>
<<if $args[3] != "random">> You have lost $args[3] Gold Crowns, <<set $gold = $gold - $args[3]>> <<if $gold < 0>> <<set $gold = 0>> <</if>> you now have $gold Gold Crowns.
<<elseif $args[3] == "random">> <<set _goldlost = random ( $args[4], $args[5] )>> You have lost _goldlost Gold Crowns, <<set $gold = $gold - _goldlost>> <<if $gold < 0>> <<set $gold = 0>> <</if>> you now have $gold Gold Crowns.
<<else>> Error: Gold amount has not been defined !
<</if>>

<<case 2>>
<<if $args[3] == "random">>
<<set _randomslot = random (1, 2)>>
<<if _randomslot == 1>> <<set $weapons[0] = "-empty-">>You lose your first weapon!
<<elseif _randomslot == 2>> <<set $weapons[1] = "-empty-">>You lose your second weapon!
<</if>>
<<elseif $args[3] == 2>>
<<set $weapons = [ "-empty-", "-empty-" ]>> You have lost all your weapons!
<</if>>

<<case 3>>
<<if $args[3] == "random">>
<<set _randomslot = random (0, 7)>> You lost a backpack item!
<<if _randomslot == 0>> <<set $backpack[0] = "-empty-">>
<<elseif _randomslot == 1>> <<set $backpack[1] = "-empty-">>
<<elseif _randomslot == 2>> <<set $backpack[2] = "-empty-">>
<<elseif _randomslot == 3>> <<set $backpack[3] = "-empty-">>
<<elseif _randomslot == 4>> <<set $backpack[4] = "-empty-">>
<<elseif _randomslot == 5>> <<set $backpack[5] = "-empty-">>
<<elseif _randomslot == 6>> <<set $backpack[6] = "-empty-">>
<<elseif _randomslot == 7>> <<set $backpack[7] = "-empty-">>
<</if>>
<</if>>
<<if $args[3] == "all">>
<<set $backpack = [ "-empty-", "-empty-", "-empty-", "-empty-", "-empty-", "-empty-", "-empty-", "-empty-" ]>> You have lost all backpack items!
<</if>>

<<case 4>>  // remove a special item - not actually used in LW !!

<<else>> Error: Argument for items to remove was not properly defined !

  <</switch>>

    <<default>>
      Error: No state was passed as the first argument to this widget!

  <</switch>>

<</nobr>> <</widget>>

Let me walk through it with you...

<<widget "ManageInventory">> <<nobr>>
/*
* Usage: this widget handles the display, removal and addition of all inventory items.
// WARNING : This widget requires several arguments to be passed.
* <<ManageInventory action container item quantity random_min random_max>>
* $args[0] - action: 1 - display, 2 - add item(s), 3 - remove item(s)
* $args[1] - container: 1 - Gold, 2 - Weapons, 3 - Backpack Items, 4 - Special Items, 5 - [if args[0] = 1 (display)] displays all items
* $args[2] - item:
* if adding items- the item name (no quotes needed unless the name has a space; ie, Sword and "Short Sword")
* if removing items- weapon (for a random weapon), backpack (for a random backpack item), or the item name (no quotes) if
a specific item should be searched for and removed
* $args[3] - quantity:
* # - the number of items to change
* random - for a random number (for items this is only 1 at the moment)
* all - to remove all backpack items
* $args[4] - if a random number, the minimum
* $args[5] - if a random number, the maximum
*/

     I'm calling this widget <<ManageInventory>>, and putting the <<nobr>> to keep my output pretty. This is in my first Passage, with the “Widget” tag to prevent any problems (per the SugarCube documentation). At the start of it I've got some HTML comments to make notes to myself (and anyone else) about how to use this widget. Taz says documentation is good - and this widget is kind of complicated, it's going to take up to 6 arguments.
     First argument will be what to do: display the inventory, add to it or remove from it. There could be another kind, to “use an item” but I'm going to put that in another section [the Lone Wolf items can only be used at certain times].
     After what we're doing, the next argument is what container/ type of items are we working on: gold, weapons, backpack items, or special items.
     Argument after that is the specific item, or a generic placeholder (the order matters, if you skip this the index of arguments moves - which would be bad).
     Final arguments are the specific number of items to work on, or “random” and then the following arguments as the minimum and maximum number.
     Takes a bit of getting used to, but isn't too bad. Not everything in this list is done right now, my Lone Wolf book only does limited inventory management - I will fill in the blanks after I get done with this conversion and move on to making my own story.

So let's look at the variables we'll be working with:

<<set $gold = 0>>
<<set $weapons = [ "-empty-", "-empty-" ]>>
<<set $backpack = [ "-empty-", "-empty-", "-empty-", "-empty-", "-empty-", "-empty-", "-empty-", "-empty-" ]>>
<<set $specialitems = []>>

     I'm defining arrays for each container (except gold, since it's just a number). I've put that “-empty-” in each available slot so that when I print the contents each empty slot will show up as something. I could have just used “--” or “_” for something shorter (and I may change it to that later). It just needs to print something the player can see and not be totally empty. Except for the Special Items, since they do not get checked or moved like the weapons and backpack items (they mostly just sit quietly in the background).

     Okay, so what happens when we want to display the inventory?

<<switch $args[0]>>

<<case 1>>

<<switch $args[1]>>

<<case 1>> <br> Belt Pouch: $gold Gold Crowns

<<case 2>> <br> Weapons: <<for _wi = 0; _wi < $weapons.length; _wi++>> <<print "<br>&nbsp;&nbsp;" + $weapons[_wi]>> <</for>>

<<case 3>> <br> Backpack Items: <<for _bi = 0; _bi < $backpack.length; _bi++>> <<print "<br>&nbsp;&nbsp;" + $backpack[_bi]>> <</for>>

<<case 4>> <br> Special Items: <<for _si = 0; _si < $specialitems.length; _si++>> <<print "<br>&nbsp;&nbsp;" + $specialitems[_si]>> <</for>>

<<case 5>>
<br> Belt Pouch: $gold Gold Crowns
<br> Weapons: <<for _wi = 0; _wi < $weapons.length; _wi++>> <<print "<br>&nbsp;&nbsp;" + $weapons[_wi]>> <</for>>
<br> Backpack Items: <<for _bi = 0; _bi < $backpack.length; _bi++>> <<print "<br>&nbsp;&nbsp;" + $backpack[_bi]>> <</for>>
<br> Special Items: <<for _si = 0; _si < $specialitems.length; _si++>> <<print "<br>&nbsp;&nbsp;" + $specialitems[_si]>> <</for>>
<</switch>>

     Our first <<switch>> looks at $args[0], the first argument that says what we're doing. A “1” means we're displaying the inventory (not actually changing it). The next <<switch>> looks at $args[1], the second argument of what containers to display. 1 is Gold, 2 is Weapons, 3 the Backpack, 4 Special Items and 5 the whole inventory. For each container we just use a <<for>> loop to read each slot and print it's contents (with the default -empty- if it's empty). Easy.

Adding Items To Inventory

     Looking at the stuff you have is bound to make you want more. So how do you pick up stuff?

<<case 2>>

<<switch $args[1]>>

<<case 1>>

<<if $args[3] != "random">>You pick up $args[3] Gold Crowns,
<<set $gold += $args[3]>>
<<if $gold > 50>> <<set $gold = 50>> but your Belt Pouch only holds 50 Gold Crowns,
<</if>> you now have $gold Gold Crowns.

<<elseif $args[3] == "random">>
<<set _goldfound = random ( $args[4], $args[5] )>> You found _goldfound Gold Crowns,
<<set $gold += _goldfound>>
<<if $gold > 50>> <<set $gold = 50>> but your Belt Pouch only holds 50 Gold Crowns,
<</if>> you now have $gold Gold Crowns.

<<else>> Error: Gold amount has not been defined !

<</if>>

     Back to the first <<switch>>, here if $args[0] == 2 then we are adding an item to the inventory. A second <<switch>> and $args[1] == 1 says that we are adding to the gold. Then we check $args[3], the argument for the quantity, and if it is a number we add it, if it is the word “random” we read $arg[4] and $arg[5] for the minimum and maximum to randomly pick from.
     Now, in here we're not looking at $arg[2], the specific item, since there is only one item, gold. That argument should still be “gold” or some word, just to keep the arguments index in the right order. Also, there is an <<else>> that will print an error. It isn't a very useful error right now (if you think about the conditions when it would trigger), but it's good to anticipate where things could go wrong and how you could tell yourself what happened (a lesson I keep trying to remember :). You could remove this after finishing your code, I'd leave it in so that even your reader could see where a mistake was. And if you make it say something useful it'll help your reader to report that mistake to you to be fixed.
     This is actually just the code I was using in the “Change Gold” Passage from before, if it ain't broke don't fix it.

<<case 2>>

<span class="wpnreplace">What weapon slot do you want to replace?

<<link " <br> Replace the $weapons[0] with $args[2]">>
<<set $weapons[0] = $args[2]>>
<<replace .wpnreplace>> You now have a $weapons[0] and a $weapons[1]
<</replace>>
<</link>>

<<link " <br> Replace the $weapons[1] with $args[2]">>
<<set $weapons[1] = $args[2]>>
<<replace .wpnreplace>> You now have a $weapons[0] and a $weapons[1]
<</replace>>
<</link>>

<<link " <br> Do not pick up the items">>
<<replace .wpnreplace>> You leave your items unchanged <</replace>> <</link>>
</span>

     Okay, we're still adding items $args[0] == 1, now we're moving on to adding a weapon $args[1] == 2. This gets a little tricky, in an unexpected way. So, we print out 2 lines, one for each weapon slot, showing what the player has in that slot, asking if they want to replace it with the item to be picked up. If they do (by clicking on the <<link>>) we trigger a <<replace>> that replaces the whole block of text. It looks like this...

     There's the list of items you can pick up (a sword, dagger or axe), so you click on the one you want...

     So, what slot do I want to replace with the Sword? Both are empty. Or, I could choose not to pick up the item (though, that will get rid of the original link, so I won't be able to pick it up again - I'm not sure how to fix that, not too worried about it at the moment). But I want it, so I pick whichever slot..

     Great, now I have a Sword. But I have another empty slot, so why not pick up one of the other weapons?

     Okay, now I can get the Dagger. I can put it in the empty slot, or replace the Sword, whatever I want (and which took a whole ton of code the last way I did this).

     So now I have a Dagger, um... twice? That looks a little confusing...
     Let's talk about something in CSS...

CSS IDs and Classes

     When we do a <<replace>> we need some kind of target, something to be replaced. Before this I had been using IDs (like <span id="replace_this">). An ID is supposed to be unique on the page, in Twine I'm trying to make it unique to the whole story. One Id to one element. But there is another selector, a “Class.” A Class is meant to belong to several items, so <span class="warning_message"> could be used for every place there needs to be some kind of warning (like we did way back at the beginning).
     So why do I bring this up now? Well, that funny thing above where each line had the same text, that's because the <<ManageInventory>> widget is using a class: <span class="wpnreplace"> and <<replace .wpnreplace>> (for the <<replace>> when you target an Id you use #name and a class is targeted with .name).
     Well, that's silly - why not use an Id instead then?
     Um... that looks even weirder...

     Because the Id is unique, each link to pick up an item keeps overwriting the one before it, and doesn't get rid of the links for what slot to put the item in (so you could keep picking up the same item forever). That really didn't work right. So I changed it to using a class and while it looks funny, there is no "infinite item glitch" that way. I really do need to revisit this and see how to clean it up some more, which will be one of the long list of things to fix down the road (I have a feeling it will be an easy fix, I'm just a little overwhelmed with this inventory stuff right now).


Okay, where was I again?

     Oh yeah, now we can add a weapon, we just let the player choose where.

     Adding a Backpack Item is pretty much exactly the same thing, we just have 8 Backpack slots compared to only 2 Weapons.

<<case 3>>
<span class="backreplace">What backpack item do you want to replace?
<<link " <br> Replace the $backpack[0] with $args[2]">> <<set $backpack[0] = $args[2]>> <<replace .backreplace>> You have gained a $args[2] <</replace>> <</link>>
<<link " <br> Replace the $backpack[1] with $args[2]">> <<set $backpack[1] = $args[2]>> <<replace .backreplace>> You have gained a $args[2] <</replace>> <</link>>
<<link " <br> Replace the $backpack[2] with $args[2]">> <<set $backpack[2] = $args[2]>> <<replace .backreplace>> You have gained a $args[2] <</replace>> <</link>>
<<link " <br> Replace the $backpack[3] with $args[2]">> <<set $backpack[3] = $args[2]>> <<replace .backreplace>> You have gained a $args[2] <</replace>> <</link>>
<<link " <br> Replace the $backpack[4] with $args[2]">> <<set $backpack[4] = $args[2]>> <<replace .backreplace>> You have gained a $args[2] <</replace>> <</link>>
<<link " <br> Replace the $backpack[5] with $args[2]">> <<set $backpack[5] = $args[2]>> <<replace .backreplace>> You have gained a $args[2] <</replace>> <</link>>
<<link " <br> Replace the $backpack[6] with $args[2]">> <<set $backpack[6] = $args[2]>> <<replace .backreplace>> You have gained a $args[2] <</replace>> <</link>>
<<link " <br> Replace the $backpack[7] with $args[2]">> <<set $backpack[7] = $args[2]>> <<replace .backreplace>> You have gained a $args[2] <</replace>> <</link>>
<<link " <br> Do not pick up the items">> <<replace .backreplace>> You leave your items unchanged <</replace>> <</link>>
</span>

     Again, the presentation is not the greatest - I'm going to need to work on making everything look neat and easy to read. But it does work, and after the last several days of banging my head against the wall on this, I'm okay with ugly-but-works for now.

     Adding a Special Item is stupidly easy.

<<case 4>>
<<if $specialitems.contains ($args[2])>> You already have a $args[2]!
<<else>>
<<run $specialitems.push ($args[2])>> You now have a $args[2].
<</if>>

     The system tells you if you already have one, or adds it to the array if you don't. Thankfully Special Items do not get moved around, either you have them or you don't.

     And that's it - now we have an inventory system that will let you view your items and add items, including letting you replace existing items with new ones. All at a fraction of the code I was working on before, and all from one central source.

Taking Out The Trash

     So we can add items in our new inventory system, what about getting rid of them?

     Well, that's not a problem either. All the removals are $args[0] == 3, so our first <<switch>> looks for that, and again a second <<switch>> looks at $args[1] for what container we're removing an item from.

<<if $args[3] != "random">> You have lost $args[3] Gold Crowns,
<<set $gold = $gold - $args[3]>>
<<if $gold < 0>> <<set $gold = 0>> <</if>> you now have $gold Gold Crowns.
<<elseif $args[3] == "random">>
<<set _goldlost = random ( $args[4], $args[5] )>> You have lost _goldlost Gold Crowns,
<<set $gold = $gold - _goldlost>> <<if $gold < 0>> <<set $gold = 0>> <</if>> you now have $gold Gold Crowns.
<<else>> Error: Gold amount has not been defined !
<</if>>

     Again, using the old code, removing gold is easy, and checks for a specific number or a random number. Just like the code to add, but in reverse.

<<if $args[3] == "random">>
<<set _randomslot = random (1, 2)>>
<<if _randomslot == 1>> <<set $weapons[0] = "-empty-">>You lose your first weapon!
<<elseif _randomslot == 2>> <<set $weapons[1] = "-empty-">>You lose your second weapon!
<</if>>
<<elseif $args[3] == 2>>
<<set $weapons = [ "-empty-", "-empty-" ]>> You have lost all your weapons!
<</if>>

     The code to remove a Weapon is a little funny right now. All I'm testing for is 2 things - weather to remove 1 random weapon or weather to remove all of them. Because, in the Lone Wolf books that's all that ever happens. I can and should set up a way to remove a specific item (like just a Sword, if you had one) and will, later. Again, I just want to get my basic code working, breathe, and then expand on and refine it.

<<if $args[3] == "random">>
<<set _randomslot = random (0, 7)>> You lost a backpack item!
<<if _randomslot == 0>> <<set $backpack[0] = "-empty-">>
<<elseif _randomslot == 1>> <<set $backpack[1] = "-empty-">>
<<elseif _randomslot == 2>> <<set $backpack[2] = "-empty-">>
<<elseif _randomslot == 3>> <<set $backpack[3] = "-empty-">>
<<elseif _randomslot == 4>> <<set $backpack[4] = "-empty-">>
<<elseif _randomslot == 5>> <<set $backpack[5] = "-empty-">>
<<elseif _randomslot == 6>> <<set $backpack[6] = "-empty-">>
<<elseif _randomslot == 7>> <<set $backpack[7] = "-empty-">>
<</if>>
<</if>>
<<if $args[3] == "all">>
<<set $backpack = [ "-empty-", "-empty-", "-empty-", "-empty-", "-empty-", "-empty-", "-empty-", "-empty-" ]>> You have lost all backpack items!
<</if>>

     Backpack Items are the same way, we either clear one random slot or all of them - again, all that ever happens in the game. Again, needs to be fleshed out down the road.

     Thankfully, you never lose Special Items - so I'm totally ignoring that section :)

     And that's it - view, add and remove items ; what else do you really need an inventory system to do?
     One last comment before we finally move on from Inventory (thankfully)...

Test, Test, Test

     Writing code is complicated, you need to think it through, write it a piece at a time, and then test it a lot. While working on this system I made a few Passages just to play with adding and removing items...

     This is a vital step. I made a ton of errors, both large and small, I had the whole unexpected display difference between Ids and Classes, there was a lot of work to refine this (and it's not even finished, so there's still more work to do!). Trying to write everything out and then wade through the errors would be a disaster. It would be so frustrating, so overwhelming, so hard to track exactly where an error came from - no fun. So write a bit, make a Passage and test it, write some more, update the test Passage and test, rinse, wash, repeat. That will make your coding into a series of small, manageable disasters - and give you some small, regular success to see that you really are getting somewhere. Coding is work, make it as easy on yourself as possible.

     Okay, that's it. The inventory system will still need some work, but it's close enough to done that I want to move on and get the last chunk of the game rules out of the way... Combat.