This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
function [2014/03/05 07:07] l [parameter(number)] |
function [2015/05/21 15:15] kussmaul added prev/next havigation links at top & bottom |
||
---|---|---|---|
Line 1: | Line 1: | ||
+ | <- [[expression|About Expressions]] --------- [[print|Printing Variables and Functions]] -> | ||
+ | |||
===== 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. | 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 expressions separated by commas, followed by a '')'' right bracket. | + | 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(), history.replaceState() 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: | + | 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, ...)==== | ====either(value, value, ...)==== | ||
Line 11: | Line 17: | ||
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. | 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: | + | You can use either() with [[<<print>>]] to print a random message or phrase... |
<code> | <code> | ||
"I sentence you to be buried alive in <<print either("rhinoceros","buffalo","triceratops")>> | "I sentence you to be buried alive in <<print either("rhinoceros","buffalo","triceratops")>> | ||
<<print either("vomit", "sweat", "snot")>>!" the JudgeBot crackles noisily. | <<print either("vomit", "sweat", "snot")>>!" the JudgeBot crackles noisily. | ||
</code> | </code> | ||
+ | ...or with [[<<display>>]] to display one of a set of passages. | ||
You can also use either() with [[<<set>>]] to set variables to random values: | You can also use either() with [[<<set>>]] to set variables to random values: | ||
Line 25: | Line 32: | ||
</code> | </code> | ||
- | You can also use either() with the [[link]] syntax to make a link that goes to a random passage: | + | And, in addition to macros, you can use either() with the [[link]] syntax to make a link that goes to a random passage: |
<code> | <code> | ||
You plunge into the [[glowing vortex|either("12000 BC","The Future","2AM Yesterday")]]. | You plunge into the [[glowing vortex|either("12000 BC","The Future","2AM Yesterday")]]. | ||
</code> | </code> | ||
+ | ====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. | ||
+ | |||
+ | <code> | ||
+ | You have a <<print random(1,99)>> percent chance of complete and utter defeat! | ||
+ | </code> | ||
+ | |||
+ | ====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()==== | ====previous()==== | ||
Line 47: | Line 65: | ||
You've visited the Pond <<print visited("Pond")>> 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")>>\ | <<if visited("Armoury", "Haberdasher")>>\ | ||
With your sword and hat, nothing can stop you! | With your sword and hat, nothing can stop you! | ||
<<endif>>\</code> | <<endif>>\</code> | ||
+ | |||
+ | **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: | ||
+ | <code><<if visited() % 3 is 0>>\ | ||
+ | "Every 3 visits to this passage, I walk the Earth again," croons Count Dracula. | ||
+ | <<endif>>\</code> | ||
+ | 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...)==== | ====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(). | 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(). | ||
Line 65: | Line 92: | ||
====turns()==== | ====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. | 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()==== | ====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. | 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()==== | ====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: | 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: | ||
Line 91: | Line 115: | ||
<code> | <code> | ||
::CaramelCanoe | ::CaramelCanoe | ||
- | You're canoeing down the caramel river, rowing with your <<parameter(0)>>, your <<parameter(1)>> by your side. | + | You're canoeing down the caramel river, rowing with <<print parameter(0)>>, your <<print parameter(1)>> by your side. |
</code> | </code> | ||
- | Running the aforementioned <<display>> will show "You're canoeing down the caramel river, rowing with your oars, your satchel 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>>. | 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>>. | ||
Line 107: | Line 131: | ||
As an alternative to a browser dialog box, you can instead use the [[<<textinput>>]] macro. | As an alternative to a browser dialog box, you can instead use the [[<<textinput>>]] macro. | ||
+ | |||
====alert(string)==== | ====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")>>. | 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")>>. | ||
+ | ====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 <<set open("url")>>. | ||
+ | |||
+ | |||
+ | <- [[expression|About Expressions]] --------- [[print|Printing Variables and Functions]] -> | ||