<- [[expression|About Expressions]] --------- [[print|Printing Variables and Functions]] -> ===== Functions ===== When writing code in your stories, functions are special devices that can be used in [[about_expressions|expressions]] in place of variables or values. Syntactically, they consist of: * a name, which is subject to the same rules that [[variable]] names are under, * followed by a ''('' left bracket, * followed by zero or more other [[expression]]s separated by commas, * followed by a '')'' right bracket. Technically speaking, any Javascript built-in function is available to the Twine author: ''parseInt()'', ''JSON.stringify()'', ''document.createElement()'' and all the rest are accessible, as are any functions that have been added by [[script]]s. However, you should find the most commonly useful functions are among these Twine exclusives and basic browser functions: ====either(value, value, ...)==== 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 [[<>]] to print a random message or phrase... "I sentence you to be buried alive in <> <>!" the JudgeBot crackles noisily. ...or with [[<>]] to display one of a set of passages. You can also use either() with [[<>]] to set variables to random values: <> <> You have <> moxie points, and <> 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")]]. ====random(value, value)==== 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 <> percent chance of complete and utter defeat! ====rot13(string)==== When given a string, it performs the [[http://en.wikipedia.org/wiki/ROT13|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.) ====previous()==== 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()]] ====visited(string, string...)==== 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 <> times. You've visited the 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. %/ <>\ With your sword and hat, nothing can stop you! <>\ **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 [[expression|modulo operator]] ''%'' to transform the number: <>\ "Every 3 visits to this passage, I walk the Earth again," croons Count Dracula. <>\ Feel free to modify the "3" to any number you wish, to make something happen on every four visits, every ten visits, etc. ====visitedTag(string, string...)==== 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 <> turns inside the swamp! <>\ You died in the church, for some reason. <>\ ====turns()==== 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. ====passage()==== Has a value equal to the current passage's name. If used inside a [[<>]]ed passage, then it will be the name of the "top" passage - the one that is causing it to be displayed. ====tags()==== Has a value equal to an array containing the current passage's tags. The meaning of "current passage" is the same as it is for passage(). Since this is a Javascript array, you will need to use built-in array functions to obtain values from it. Usually, you'd simply want to do something like this: < -1>>\ Thunder is crackling above! <>\ ====parameter(number)==== This is an interesting one. Suppose you're [[<>]]ing a passage using the shorthand, and you include some extra values at the end of the tag: <> 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 <>, your <> by your side. Running the aforementioned <> 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 <>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 <>. ====confirm(string)==== 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. ====prompt(string, string)==== 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. <> As an alternative to a browser dialog box, you can instead use the [[<>]] macro. ====alert(string)==== 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 <>. ====open(string)==== 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 <>. <- [[expression|About Expressions]] --------- [[print|Printing Variables and Functions]] ->