User Tools

Site Tools


function

This is an old revision of the document!


Functions

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: 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 expressions separated by commas, followed by a ) right bracket.

Technically speaking, any Javascript built-in function is available to the Twine author: parseInt(), JSON.stringify(), history.replaceState() 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:

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 <<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.

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.

You can also 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")]].

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 <<print visited()>> times.

You've visited the Pond <<print visited("Pond")>> times.

<<if visited("Armoury", "Haberdasher")>>\
With your sword and hat, nothing can stop you!
<<endif>>\

visitedTag(string, string...)

New in version 1.4.1

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>>\

turns()

New in version 1.4.1

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()

New in version 1.4.1

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.

tags()

New in version 1.4.1

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:

<<if tags().indexOf("thunder") > -1>>\
Thunder is crackling above!
<<endif>>\

parameter(number)

FIXME

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.

<<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.

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 «set alert(“message”)».

function.1389773816.txt.gz · Last modified: 2017/10/10 00:37 (external edit)