This is an old revision of the document!
When writing code in your stories, functions are special devices that can be used in expressions in place of variables or values.
Syntactically, they consist of:
document.createElement() and all the rest are accessible, as are any functions that have been added by scripts. However, you should find the most commonly useful functions are among these Twine exclusives and basic browser functions:
Give the either() function several string or number values, separated by commas, and it will pick one of them randomly. This allows a good degree of randomness to be inserted into the story, while still being fairly readable.
You can use either() with <<print>> to print a random message or phrase…
"I sentence you to be buried alive in <<print either("rhinoceros","buffalo","triceratops")>> <<print either("vomit", "sweat", "snot")>>!" the JudgeBot crackles noisily.
…or with <<display>> to display one of a set of passages.
You can also use either() with <<set>> to set variables to random values:
<<set $playerMoxie to either(2, 4, 6)>> <<set $playerAttire to either("green", "black", "rainbow")>> You have <<print $playerMoxie>> moxie points, and <<print $playerAttire>> armour.
And, in addition to macros, you can use either() with the link syntax to make a link that goes to a random passage:
You plunge into the [[glowing vortex|either("12000 BC","The Future","2AM Yesterday")]].
When given two positive numbers, this produces a positive whole number randomly selected between the two, inclusive. This function can (and should only) be used to generate random numbers within a wide range - such as 1 to 100. Prior to version 1.4.2, you had to use the cumbersome
Math.random(value)*value idiom to do this, which wasn't that memorable or succinct.
You have a <<print random(1,99)>> percent chance of complete and utter defeat!
When given a string, it performs the ROT13 transformation on it, which simultaneously encodes normal text and decodes ROT13 text. (This is not expected to be a widely used function, but is available anyway.)
Has a value equal to the name of the last passage the player visited.
You can use this with the link syntax to make a link that goes back to the previous passage:
The snowballs are useless against this lava beast! Undo! [[Undo!|previous()]]
Has a value equal to the number of times you've visited the named passage. It's fairly useful - this can eliminate or greatly reduce the need to use “counter variables” to keep track of the player's actions. If the passage name is omitted, as in visited(), then its value is for the current passage.
If multiple strings are supplied to it, then it will return the value for the passage that was visited the least.
You've visited this passage <<print visited()>> times. You've visited the Pond <<print visited("Pond")>> times. /% Since visited() returns the value for the passage visited the least, then if the below result is greater than 0 (i.e. not false), then both passages must have been visited at least once. %/ <<if visited("Armoury", "Haberdasher")>>\ With your sword and hat, nothing can stop you! <<endif>>\
Advanced use: if you want to display something on every third time you visit a passage (no matter if you visit it 3 times, 10 times, or 100 times), then you can use the modulo operator
% to transform the number:
<<if visited() % 3 is 0>>\ "Every 3 visits to this passage, I walk the Earth again," croons Count Dracula. <<endif>>\
Feel free to modify the “3” to any number you wish, to make something happen on every four visits, every ten visits, etc.
Has a value equal to the number of times you've visited passages with the given tags. If you use tags to delineate parts of your story, this can be a useful variant of visited().
Hard to believe you spent <<print visitedTag("Swamp")>> turns inside the swamp! <<if visitedTag("church","death")>>\ You died in the church, for some reason. <<endif>>\
Has a value equal to the number of moves the player has made - that is, the number of times a link to another passage has been followed by the player.
Has a value equal to the current passage's name. If used inside a <<display>>ed passage, then it will be the name of the “top” passage - the one that is causing it to be displayed.
<<if tags().indexOf("thunder") > -1>>\ Thunder is crackling above! <<endif>>\
This is an interesting one. Suppose you're <<display>>ing a passage using the shorthand, and you include some extra values at the end of the tag:
<<CaramelCanoe "oars" "satchel">>
With parameter(), you can access these extra values and use them inside the displayed passage:
::CaramelCanoe You're canoeing down the caramel river, rowing with <<print parameter(0)>>, your <<print parameter(1)>> by your side.
Running the aforementioned «display» will show “You're canoeing down the caramel river, rowing with oars, your satchel by your side.”
This allows you to subtly alter a passage depending on where and how it's «display»ed, without using variables. You can, for instance, make a passage that describes the character's clothes, and you can supply different adjectives to the passage, just by including them in the shorthand «display».
Displays a yes/no dialog box. If you click Yes, the function's value is true. Otherwise, it is false. The provided string is the question shown to the player. This is a browser built-in.
Displays a text input dialog box. The text entered here will be the value of the function. The first string you give it is the message to display to the player. The second is the default value for the text input. This is a browser built-in.
<<set $name to prompt("What's your name?","Alyssa P. Hacker")>>
As an alternative to a browser dialog box, you can instead use the <<textinput>> macro.
Displays an alert box, with the given text string displayed. This is a browser built-in. It has no value - feel free to use it by simply writing «set alert(“message”)».
When given a URL in string form, it opens a new browser tab containing that web page. This is a browser built-in. It has no value - feel free to use it by simply writing «set open(“url”)».