Home › Development Diaries › L's blog

How to use JavaScript arrays in Twine

Fri, 02/01/2013 - 05:57 — L

An array is essentially an ordered list of data values, such as strings or number expressions. You can declare a Twine variable to be an array using just the set macro.

*To create an empty array called $inv: <<set $inv = [] >>
*To create an array called $inv containing the string "Dagger": <<set $inv = ["Dagger"] >>
*To create an array called $inv containing "Dagger", "Shield" and "Potion" in that order: <<set $inv = ["Dagger", "Shield", "Potion"] >>

To examine or change the values inside an array, a number of methods are available that can be used in the set, if and print macros. Here are some examples.

Examining arrays and their contents

*To print the entire contents of an array in order (usually for debug purposes): <<print $inv >>
*To see if the value "Magic Knife" is inside an array: <<if $inv.indexOf("Magic Knife") gte 0>>
*To get the number of values inside an array: <<set $size = $inv.length >>
*To get the first value inside an array: <<set $first = $inv[0] >>
*To get the last value inside an array: <<set $first = $inv[$inv.length - 1] >>

Changing values in arrays

*To add the value "Magic Knife" to the end of an array: <<set $inv.push("Magic Knife")>>
*To add the values "Blunt Axe", "Key" and $item to the end of an array: <<set $inv.push("Blunt Axe", "Key", $item)>> (push() can insert many values at once.)
*To add the value "Weird Pear" to the start of an array: <<set $inv.unshift("Weird Pear")>>
*To add the values "Blunt Axe", $item, 2, and $weapon to the start of an array: <<set $inv.unshift("Blunt Axe", $item, 2, $weapon)>> (unshift() can also insert many values at once.)
*To remove the value "Weird Pear" from an array: <<set $inv.splice($inv.indexOf("Weird Pear"),1)>>
*To sort an array alphabetically: <<set $inv.sort()>>
*To reverse an array: <<set $inv.reverse()>>
*To remove the first value from an array: <<set $inv.shift()>>
*To remove the last value from an array: <<set $inv.pop()>>
*To remove the first value from an array and set $item to it: <<set $item = $inv.shift()>>
*To remove the last value from an array and set $item to it: <<set $item = $inv.pop()>>

Comments

Tue, 11/05/2013 - 21:04 — novalin

Hi - I'm brand new to Twine

Hi - I'm brand new to Twine and got all the basics working already, and I want to explore using an inventory system in my adventure. Curious if you have an example of what you are explaining above so I can understand better. Thank you.

Fri, 12/19/2014 - 21:59 — loopernow

Easier way to remove items from array

Thank you to L for this extremely useful article. For those who don't know Javascript and want to know what some of the slightly more arcane syntax above means:

Why greater than or equal to zero ("gte 0") and not greater than or equal to one ("gte 1")? Because array "cubbyholes" are numbered starting with zero.

Why the ", 1" when removing an item? Because you're indicating to only remove one item.

If you do a little bit of Googling/reading about "Javascript arrays" and then about "splice" and "indexOf", things will start to make more sense.

Nonetheless, the syntax for removing an item from an array is pretty nonintuitive, compared to the rest of the array manipulation syntax, not to mention Twine syntax.

So I found an article (http://www.simonewebdesign.it/how-to-remove-element-from-array/) that showed me how to simplify that syntax.

Simply copy the function the author gives in the "Extending the Array object" section of his article and paste it into a Twine passage. Tag the Twine passage with "[script]".

Specifically, the function to copy and paste is:

// Removes an element from an array.
// String value: the value to search and remove.
// return: an array with the removed element; false otherwise.
Array.prototype.remove = function(value) {
var idx = this.indexOf(value);
if (idx != -1) {
return this.splice(idx, 1); // The second parameter is the number of elements to remove.
}
return false;
}

(You need to put double-<>s around the two following examples; the comment software for this website won't let me include them myself)

Now you can remove an item from your array/inventory anywhere in your Twine file with this syntax:

set $inv.remove('bar of soap')

instead of this syntax:

set $inv.splice($inv.indexOf("bar of soap"),1)

Cool!

pensive-mosquitoes