This documentation is a reference for SugarCube v2, a free (gratis and libre) story format for Twine/Twee.
Tip: This document is a single page, so you may use your browser's find-in-page functionality—+, +, —to search for specific terms. CTRLFCMDFF3
Note: If you believe that you've found a bug in SugarCube, or simply wish to make a suggestion, you may do so by creating a new issue at its source code repository.
Contributions to this documentation have been graciously made by:
Note:
Except where noted, all markup has been available since .
v2.0.0
In addition to using one of the print macros (<<print>>
, <<=>>
, <<->>
) to print the values of TwineScript variables, SugarCube's naked variable markup allows printing them simply by including them within your normal passage text—i.e., variables in passage text are interpolated into a string representation of their values.
The following forms are supported by the naked variable markup:
Type | Syntax | Example |
---|---|---|
Simple variable |
|
|
Property access, dot notation |
|
|
Index/property access, square bracket notation |
|
|
If you need to print anything more complex—e.g., using a calculation, , or a method call, —then you will still need to use one of the print macros.$variable[_i + 1]
$variable.someMethod()
For example:
/* Explicitly printing the value of $name via the <<print>> macro */
Well hello there, <<print $name>>.
/* Implicitly printing the value of $name via the naked variable markup */
Well hello there, $name.
/* Assuming $name is set to "Mr. Freeman", both should yield the following */
Well hello there, Mr. Freeman.
Because variables within your passage text are transformed into their values automatically, if you actually want to output a variable as-is—i.e., without interpolation; e.g., for a tutorial, debug output, or whatever—then you'll need to escape it in some fashion. For example:
/* Using the nowiki markup: """…""" (triple double-quotes) */
The variable """$name""" is set to: $name
/* Using the nowiki markup: <nowiki>…</nowiki> */
The variable <nowiki>$name</nowiki> is set to: $name
/* Using the double dollar-sign markup (which escapes the $-sigil): $$ */
The variable $$name is set to: $name
/* Assuming $name is set to "Mr. Freeman", all of the above should yield the following */
The variable $name is set to: Mr. Freeman
Additionally, you could use the inline code markup to escape the variable, though it will also wrap the escaped variable within a element, so it's probably best used for examples and tutorials. For example:<code>
/* Using the inline code markup: {{{…}}} (triple curly braces) */
The variable {{{$name}}} is set to: $name
/* Assuming $name is set to "Mr. Freeman", it should yield the following */
The variable <code>$name</code> is set to: Mr. Freeman
SugarCube's link markup consists of a required component and optional and components.Link
Text
Setter
The component may be either plain text or any valid TwineScript expression, which will be evaluated early—i.e., when the link is initially processed. Its value should be the title of a passage or any valid URL to a resource (local or remote).Link
The optional component may be either plain text or any valid TwineScript expression, which will be evaluated early—i.e., when the link is initially processed.Text
The optional component, which only works with passage links, must be a valid TwineScript expression, of the <<set>>
macro variety, which will be evaluated late—i.e., when the link is clicked on. If you need to specify multiple expressions, then they should be separated by semi-colons ()—e.g., .Setter
;
$a to 5; $b to true
In addition to the standard pipe separator () used to separate the and components (as seen below), SugarCube also supports the arrow separators ( & ). Particular to the arrow separators, the arrows' direction determines the order of the components, with the arrow always pointing at the component—i.e., the right arrow works like the pipe separator, , while the left arrow is reversed, .|
Link
Text
->
<-
Link
Text->Link
Link<-Text
Warning (Twine 2):
Due to how the Twine 2 automatic passage creation feature currently works, using any TwineScript expression for the component will cause a passage named after the expression to be created that will need to be deleted. To avoid this problem, it's suggested that you use the separate argument form of the <<link>>
macro in Twine 2 when you need to use an expression.
Link
Syntax | Example |
---|---|
|
|
|
|
|
|
|
|
SugarCube's image markup consists of a required component and optional , , and components.Image
Title
Link
Setter
The component may be either plain text or any valid TwineScript expression, which will be evaluated early—i.e., when the link is initially processed. Its value may be any valid URL to an image resource (local or remote) or the title of an media (image) passage.Image
The optional component may be either plain text or any valid TwineScript expression, which will be evaluated early—i.e., when the link is initially processed. Its value will be used as the alt text of the image.Title
The optional component may be either plain text or any valid TwineScript expression, which will be evaluated early—i.e., when the link is initially processed. Its value may be the title of a passage or any valid URL to a resource (local or remote).Link
The optional component, which only works with passage links, must be a valid TwineScript expression, of the <<set>>
macro variety, which will be evaluated late—i.e., when the link is clicked on. If you need to specify multiple expressions, then they should be separated by semi-colons ()—e.g., .Setter
;
$a to 5; $b to true
In addition to the standard pipe separator () used to separate the and components (as seen below), SugarCube also supports the arrow separators ( & ). Particular to the arrow separators, the arrows' direction determines the order of the components, with the arrow always pointing at the component—i.e., the right arrow works like the pipe separator, , while the left arrow is reversed, .|
Image
Title
->
<-
Image
Title->Image
Image<-Title
Warning (Twine 2):
Due to how the Twine 2 automatic passage creation feature currently works, using any TwineScript expression for the component will cause a passage named after the expression to be created that will need to be deleted. To avoid this problem, it's suggested that you use the separate argument form of the <<link>>
macro in Twine 2 when you need to use an expression.
Link
Syntax | Example |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
A restricted subset of the image markup, allowing only the component, may be used within stylesheets—primarily to allow the easy use of media (image) passages. For example:Image
/* Using the external image "forest.png" as the <body> background. */
body {
background-image: [img[forest.png]];
}
/* Using the image passage "lagoon" as the <body> background. */
body {
background-image: [img[lagoon]];
}
Warning: None of these features work within the verbatim HTML markup.
SugarCube provides a few special HTML & SVG attributes, which you may add to tags to enable special behaviors. There are attributes for passage links, media passages, and setters.
Type | Attribute | Example |
---|---|---|
Passage, Link |
|
|
Passage, Audio |
|
|
Passage, Image |
|
|
Passage, Source |
|
|
Passage, Video |
|
|
Setter |
|
|
v2.0.0
: Introduced.v2.24.0
: Added attribute support to , , and tags.data-passage
<audio>
<source>
<video>
HTML & SVG attributes may be prefixed with directives, special text, which trigger special processing of such attributes.
sc-eval:
@
The evaluation directive causes the attribute's value to be evaluated as TwineScript. Post-evaluation, the directive will be removed from the attribute's name and the result of the evaluation will be used as the actual value of the attribute.
Warning:
The evaluation directive is not allowed on the data-setter
attribute—as its function is to evaluate its contents upon activation of its own element—and any such attempt will cause an error.
Syntax | Example | Rendered As |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
v2.21.0
: Introduced.v2.23.5
: Fixed an issue with the evaluation directive where using multiple directives on a single HTML tag would result in some being unprocessed.See Also:
The various no-break features—<<nobr>>
macro, nobr
special tag, and Config.passages.nobr
setting—all perform a similar, though slightly different, function.
Warning: Line continuations, or any markup that relies on line positioning, are incompatible with the no-break features because of how the latter function.
A backslash () that begins or ends a line is the line continuation markup. Upon processing the backslash, associated line break, and all whitespace between them are removed—thus, joining the nearby lines together. This is mostly useful for controlling whitespace when you want to wrap lines for readability, but not generate extra whitespace upon display, and the <<silently>>
macro isn't an option because you need to generate output.\
For example, all of the following: (n.b., represents whitespace that will be removed, represents line breaks)·
¬
The rain in Spain falls \¬
mainly on the plain.
The rain in Spain falls \····¬
mainly on the plain.
The rain in Spain falls¬
\ mainly on the plain.
The rain in Spain falls¬
····\ mainly on the plain.
Yield the single line in the final output:
The rain in Spain falls mainly on the plain.
An exclamation point () that begins a line defines the heading markup. It consists of one to six exclamation points, each additional one beyond the first signifying a lesser heading.!
Type | Syntax & Example | Rendered As | Displays As (roughly) |
---|---|---|---|
Level 1 |
|
|
Level 1 Heading |
Level 2 |
|
|
Level 2 Heading |
Level 3 |
|
|
Level 3 Heading |
Level 4 |
|
|
Level 4 Heading |
Level 5 |
|
|
Level 5 Heading |
Level 6 |
|
|
Level 6 Heading |
Warning: Because the style markups use the same tokens to begin and end each markup, the same style cannot be nested within itself.
Type | Syntax & Example | Rendered As | Displays As (roughly) |
---|---|---|---|
Emphasis |
|
|
Emphasis |
Strong |
|
|
Strong |
Underline |
|
|
Underline |
Strikethrough |
|
|
|
Superscript |
|
|
Superscript |
Subscript |
|
|
Subscript |
An asterisk () or number sign () that begins a line defines a member of the unordered or ordered list markup, respectively.*
#
Type | Syntax & Example | Rendered As | Displays As (roughly) |
---|---|---|---|
Unordered |
|
|
|
Ordered |
|
|
|
A right angle bracket () that begins a line defines the blockquote markup. It consists of one or more right angle brackets, each additional one beyond the first signifying a level of nested blockquote.>
Syntax & Example | Rendered As | Displays As (roughly) |
---|---|---|
|
|
Line 1 |
Type | Syntax & Example | Rendered As | Displays As (roughly) |
---|---|---|---|
Inline |
|
|
|
Block |
|
|
|
A set of four hyphen/minus characters () that begins a line defines the horizontal rule markup.-
Type | Syntax & Example | Rendered As | Displays As (roughly) |
---|---|---|---|
Horizontal rule |
|
|
The verbatim text markup disables processing of all markup contained within—both SugarCube and HTML—passing its contents directly into the output as plain text.
Type | Syntax & Example | Rendered As | Displays As (roughly) |
---|---|---|---|
Triple double quotes |
|
|
No //format// |
<nowiki> tag |
|
|
No //format// |
A set of opening and closing <html> tags—i.e., —defines the verbatim HTML markup. The verbatim HTML markup disables processing of all markup contained within—both SugarCube and HTML—passing its contents directly into the output as HTML markup for the browser. Thus, you should only use plain HTML markup within the verbatim markup—meaning using none of SugarCube's special HTML attributes or directives.<html></html>
Note: You should virtually never need to use the verbatim HTML markup.
Warning: Because the custom style markup uses the same tokens to begin and end the markup, it cannot be nested within itself.
Type | Syntax | Example | Rendered As |
---|---|---|---|
Inline |
|
|
|
|
|
||
Block |
|
|
|
|
|
;
#alfa
.bravo
color:red
v2.31.0
#alfa;.bravo;.charlie;
#alfa.bravo.charlie;
A text replacement markup. The template markup begins with a question mark () followed by the template name—e.g., —and are set up as functions-that-return-strings, strings, or arrays of either—from which a random member is selected whenever the template is processed. They are defined via the Template
API.?
?yolo
For example, consider the following markup:
?He was always willing to lend ?his ear to anyone.
Assuming that resolves to and to , then that will produce the following output:?He
She
?his
her
She was always willing to lend her ear to anyone.
v2.29.0
: Introduced.Note: Comments used within passage markup are not rendered into the page output.
Type | Syntax & Example | Supported Within… |
---|---|---|
C-style, Block |
|
Passage markup, JavaScript, Stylesheets |
TiddlyWiki, Block |
|
Passage markup |
HTML, Block |
|
Passage markup |
TwineScript in SugarCube is, essentially, JavaScript with an extra spoonful of sugar on top to make it a bit nicer for the uninitiated.
Note:
Temporary variables were added in .
v2.3.0
A variable is a bit of storage where you may stash a value for later use. In SugarCube, they come in two types: story variables and temporary variables. Story variables are a part of the story history and exist for the lifetime of a playthrough session. Temporary variables do not become part of the story history and only exist for the lifetime of the moment/turn that they're created in. You'll likely use story variables most often throughout your project—though, temporary variables are perfect candidates for things like loop variables, if you're using the <<for>>
macro.
For example, you might use the story variable to store the main player character's name or the story variable to store how much money the player has on hand.$name
$cash
Values may be of most primitive types and some object types, see Supported Types for more information.
The names of both story and temporary variables have a certain format that they must follow—which signifies that they are variables and not some other kind of data.
The very first, and mandatory, character is their sigil, which denotes whether they are a story or temporary variable. The sigil must be a dollar sign () for story variables or an underscore () for temporary variables.$
_
The second, and also mandatory, character of the variable name may be one of the following: the letters A though Z (in upper or lower case), the dollar sign, and the underscore (i.e., )—after their initial use as the sigil, the dollar sign and underscore become regular variable characters.A-Za-z$_
Subsequent, optional, characters have the same set as the second with the addition of numerals (i.e., , so the full set is ). No other characters are allowed.0-9
A-Za-z0-9$_
A few examples of valid names:
有效名称的几个示例:
/* Story variables */
$cash
$hasKeyCard5
$met_alice
$TIMES_POKED_MR_BEAR
/* Temporary variables */
_i
_something2
_some_loop_value
_COUNT
Note:
This is not an exhaustive list. There are many ways to use and interact with variables.
注意:这并不是一个详尽的清单。有许多方法可以使用变量并与之交互。
To modify the values contained within variables, see the <<set>>
macro and setter links.
要修改变量中包含的值,请参阅 <<set>>
宏和 setter 链接。
To print the values contained within variables, see the naked variable markup and the <<print>>
, <<=>>
, and <<->>
macros.
要打印变量中包含的值,请参阅裸变量标记和 <<print>>
、<<=>>
和 <<->>
宏。
To control aspects of your project based on the values contained within variables, see the <<if>>
and <<switch>>
macros.
要根据变量中包含的值控制项目的各个方面,请参阅 <<if>>
和 <<switch>>
宏。
The following types of values are natively supported by SugarCube and may be safely used within story and temporary variables.
true
& false
42
3.14
-24
-17.76
Infinity
"I like pie"
& 'You like pie'
null
undefined
Array
Date
Map
Set
Any supported object type may itself contain any supported primitive or object type.
Unsupported object types, either native or custom, can be made compatible by implementing and methods for them—see the Non-generic object types (classes) guide for more information..clone()
.toJSON()
Due to how SugarCube stores the state history a few constructs are not supported within story variables.
Functions, including static—i.e., non-instance—methods, due to a few issues.
Instance methods of classes are not affected by either issue, as they're never actually stored within story variables, being referenced from their classes' prototypes instead.
Expressions are simply units of code that yield values when evaluated. For example:
// Yields: true
true
// Yields: 1 (assuming that it is the first turn)
turns()
// Yields: 4
2 + 2
// Yields: "22"
"2" + "2"
Basic expressions simply consist of identifiers and literals—e.g., , , and . Complex expressions consist of basic expressions joined together by operators—e.g., and .$a
69
"hello"
=
+
While every valid expression—even those you might not expect—yields a value, there are essentially two types of expressions: those with side effects and those without. A side effect simply means that the evaluation of the expression modifies some state. For example:
// Yields: 5; Side effect: assigns 5 to the story variable $a
$a = 5
// Yields: 25 (assuming $x is 15); No side effects
$x + 10
In general, you can group expressions into categories based on what kind of value they yield and/or what side effects they cause. For example: (not an exhaustive list)
42
3.14
"Lulamoon"
"5678"
true
false
$a = 5
You will, in all likelihood, use expressions most often within macros—e.g., <<set>>
, <<print>>
, <<if>>
, <<for>>
.
Operators join together operands, which are formed from either basic or complex expressions.
In both TwineScript and JavaScript there are binary and unary operators—n.b., Javascript also includes a ternary operator, the conditional operator. Binary operators require two operands, one before and one after the operator, while unary operators only require one operand, either before or after the operator.
Binary operator examples:
// operand1 OPERATOR operand2
2 + 2
$a = 5
Unary operator examples:
// operand OPERATOR
$i++
// OPERATOR operand
++$x
not $hasKey
Assignment operators assign a value to their left-hand operand based on the value of their right-hand operand.
Operator | Description | Example |
---|---|---|
to |
Assigns the value on the right-hand side of the operator to the left-hand side. |
|
Operator | Description | Example |
---|---|---|
= |
Assigns the value on the right-hand side of the operator to the left-hand side. |
|
+= |
Adds the value on the right-hand side of the operator to the current value on the left-hand side and assigns the result to the left-hand side. |
|
-= |
Subtracts the value on the right-hand side of the operator from the current value on the left-hand side and assigns the result to the left-hand side. |
|
*= |
Multiplies the current value on the left-hand side of the operator by the value on the right-hand side and assigns the result to the left-hand side. |
|
/= |
Divides the current value on the left-hand side of the operator by the value on the right-hand side and assigns the result to the left-hand side. |
|
%= |
Divides the current value on the left-hand side of the operator by the value on the right-hand side and assigns the remainder to the left-hand side. |
|
Comparison operators compare their operands and return a boolean value based on whether the comparison is true.
Operator | Description | Example |
---|---|---|
is |
Evaluates to if both sides are strictly equal.true |
|
isnot |
Evaluates to if both sides are strictly not equal.true |
|
eq |
Evaluates to if both sides are equivalent. Not recommended, use the operator.true is |
|
neq |
Evaluates to if both sides are not equivalent. Not recommended, use the operator.true isnot |
|
gt |
Evaluates to if the left side is greater than the right side.true |
|
gte |
Evaluates to if the left side is greater than or equal to the right side.true |
|
lt |
Evaluates to if the left side is less than the right side.true |
|
lte |
Evaluates to if the left side is less than or equal to the right side.true |
|
not |
Flips a evaluation to , and vice versa.true false |
|
and |
Evaluates to if all subexpressions evaluate to .true true |
|
or |
Evaluates to if any subexpressions evaluate to .true true |
|
def |
Evaluates to if the right side is defined. See the precedence warning below.true |
|
ndef |
Evaluates to if the right side is not defined. See the precedence warning below.true |
|
Warning:
The and operators have very low precedence, so it is strongly recommended that if you mix them with other operators, that you wrap them in parentheses—e.g., .
def
ndef
(def $style) and ($style is "girly")
Operator | Description | Example |
---|---|---|
=== |
Evaluates to if both sides are strictly equal.true |
|
!== |
Evaluates to if both sides are strictly not equal.true |
|
== |
Evaluates to if both sides are equivalent. Not recommended, use the operator.true === |
|
!= |
Evaluates to if both sides are not equivalent. Not recommended, use the operator.true !== |
|
> |
Evaluates to if the left side is greater than the right side.true |
|
>= |
Evaluates to if the left side is greater than or equal to the right side.true |
|
< |
Evaluates to if the left side is less than the right side.true |
|
<= |
Evaluates to if the left side is less than or equal to the right side.true |
|
! |
Flips a evaluation to , and vice versa.true false |
|
&& |
Evaluates to if all subexpressions evaluate to .true true |
|
|| |
Evaluates to if any subexpressions evaluate to .true true |
|
Macros fall into two broad categories based on the kind of arguments they accept: those that want an expression—e.g., and —and those that want discrete arguments separated by whitespace—e.g., and . The documentation for each macro will tell you what it expects.<<set>>
<<print>>
<<link>>
<<audio>>
Those that want an expression are fairly straightforward, as you simply supply an expression.
The discrete argument type of macros are also fairly straightforward, most of the time, as you simply supply the requisite arguments separated by whitespace, which may include variables—as SugarCube automatically yields their values to the macro. There are cases, however, where things get a bit more complicated, namely: instances where you need to pass the name of a variable as an argument, rather than its value, and those where you want to pass the result of an expression as argument.
Passing the name of a variable as an argument is problematic because variable substitution occurs automatically in SugarCube macros. Meaning that when you pass a variable as an argument, its value is passed to the macro rather than its name.
Normally, this is exactly what you want to happen. Occasionally, however, macros will need the name of a variable rather than its value—e.g., data input macros like —so that they may modify the variable. To resolve these instances, you will need to quote the name of the variable—i.e., instead of passing as normal, you'd pass . These, rare, instances are noted in the macros' documentation and shown in their examples.<<textbox>>
$pie
"$pie"
Passing the result of an expression as an argument is problematic for a couple of reasons: because the macro argument parser doesn't treat arguments as expressions by default and because it separates arguments with whitespace.
Normally, those aren't issues as you should not need to use the result of an expression as an argument terribly often. To resolve instances where you do, however, you'll want to use either a temporary variable or a backquote expression.
For example, the following will not work because the macro parser will think that you're passing five discrete arguments, rather than a single expression:
<<link "Wake " + $friend + ".">> … <</link>>
You could solve the problem by using a temporary variable to hold the result of the expression, then pass that to the macro. For example:
<<set _text to "Wake " + $friend + ".">>\
<<link _text>> … <</link>>
A better solution, however, would be to use a backquote1 () expression, which is really just a special form of quoting available in macro arguments that causes the contents of the backquotes to be evaluated and then yields the result as a singular argument. For example:`
<<link `"Wake " + $friend + "."`>> … <</link>>
~
<<capture variableList>> … <</capture>>
Captures story $variables and temporary _variables, creating localized versions of their values within the macro body.
Note:
Use of this macro is only necessary when you need to localize a variable's value for use with an asynchronous macro—i.e., a macro whose contents are executed at some later time, rather than when it's invoked; e.g., interactive macros, <<repeat>>
, <<timed>>
. Generally, this means only when the variable's value will change between the time the asynchronous macro is invoked and when it's activated—e.g., a loop variable.
v2.14.0
: Introduced.variableList
: A list of story $variables and/or temporary _variables.→ Using <<capture>> to localize a temporary loop variable for use within a <<linkappend>>
<<set _what to [
"a crab rangoon",
"a gaggle of geese",
"an aardvark",
"the world's smallest violin"
]>>
<<for _i to 0; _i lt _what.length; _i++>>
<<capture _i>>
I spy with my little <<linkappend "eye" t8n>>, _what[_i]<</linkappend>>.
<</capture>>
<</for>>
→ Capturing several variables at once
<<capture $aStoryVar, $anotherStoryVar, _aTempVar>> … <</capture>>
<<set expression>>
Sets story $variables and temporary _variables based on the given expression.
v2.0.0
: Introduced.expression
: A valid expression. See Variables, Expressions, Operators for more information.<<set $cheese to "a nice, sharp cheddar">> → Assigns "a nice, sharp cheddar" to story variable $cheese
<<set $chestEmpty to true>> → Assigns boolean true to story variable $chestEmpty
<<set $sum to $a + $b>> → Assigns the summation of story variables $a and $b to $sum
<<set $gold to $gold + 5>> → Adds 5 to the value of story variable $gold
<<set _counter to _counter + 1>> → Adds 1 to the value of temporary variable _counter
<<set $cheese = "a nice, sharp cheddar">> → Assigns "a nice, sharp cheddar" to story variable $cheese
<<set $chestEmpty = true>> → Assigns boolean true to story variable $chestEmpty
<<set $sum = $a + $b>> → Assigns the summation of story variables $a and $b to $sum
<<set $gold += 5>> → Adds 5 to the value of story variable $gold
<<set _counter += 1>> → Adds 1 to the value of temporary variable _counter
<<unset variableList>>
Unsets story $variables, temporary _variables, and properties of objects stored within either.
v2.0.0
: Introduced.v2.37.0
: Added ability to unset object properties.variableList
: A list of story $variables, temporary variables, or properties of objects stored within either.Basic usage, unsetting story and temporary variables.
<<unset $rumors>>
<<unset _npc>>
<<unset $rumors, _npc, _choices, $job>>
Unsetting object properties.
<<unset _choices.b>>
<<unset $towns['port ulster'].rumors>>
<<unset _choices.b, $towns['port ulster'].rumors, $pc.notes, _park.rides['wheel of death']>>
<<run expression>>
Functionally identical to <<set>>
. Intended to be mnemonically better for uses where the expression is arbitrary code, rather than variables to set—i.e., <<run>>
to run code, <<set>>
to set variables.
<<script [language]>> … <</script>>
Silently executes its contents as either JavaScript or TwineScript code (default: JavaScript).
Note:
The predefined variable , which is a reference to a local content buffer, is available for use within the macro's code contents. Once the code has been fully executed, the contents of the buffer, if any, will be output.
output
v2.0.0
: Introduced.v2.37.0
: Added optional argument.language
language
: (optional) The language to evaluate the given code as; case-insensitive options: , . If omitted, defaults to .JavaScript
TwineScript
JavaScript
<<script>>
/* JavaScript code */
<</script>>
<<script TwineScript>>
/* TwineScript code */
<</script>>
<<script>>
/*
When accessing managed variables in JavaScript, it's often a good idea
to cache references to whichever variable store you happen to be using.
*/
const svars = State.variables;
const tvars = State.temporary;
/* Access the `$items` story variable. */
if (svars.items.includes('bloody knife')) {
/* Has a bloody knife. */
}
/* Access the `_hit` temporary variable. */
tvars.hit += 1;
<</script>>
<<script TwineScript>>
/* Access the `$items` story variable. */
if ($items.includes('bloody knife')) {
/* Has a bloody knife. */
}
/* Access the `_hit` temporary variable. */
_hit += 1;
<</script>>
There's no difference between JavaScript and TwineScript here.
<<script>>
/* Parse some markup and append the result to the output buffer. */
$(output).wiki("Cry 'Havoc!', and let slip the //ponies// of ''friendship''.");
<</script>>
<<= expression>>
Outputs a string representation of the result of the given expression. This macro is an alias for <<print>>
.
Tip: If you only need to print the value of a TwineScript variable, then you may simply include it in your normal passage text and it will be printed automatically via the naked variable markup.
v2.0.0
: Introduced.expression
: A valid expression. See Expressions for more information.→ Assuming $gold is 5
You found <<= $gold>> gold. → Outputs: You found 5 gold.
→ Assuming $weight is 74.6466266
You weigh <<= $weight.toFixed(2)>> kg. → Outputs: You weigh 74.65 kg.
<<- expression>>
Outputs a string representation of the result of the given expression. This macro is functionally identical to <<print>>
, save that it also encodes HTML special characters in the output.
Tip: If you only need to print the value of a TwineScript variable, then you may simply include it in your normal passage text and it will be printed automatically via the naked variable markup.
v2.0.0
: Introduced.expression
: A valid expression. See Expressions for more information.→ Assuming $gold is 5
You found <<- $gold>> gold. → Outputs: You found 5 gold.
→ Assuming $weight is 74.6466266
You weigh <<- $weight.toFixed(2)>> kg. → Outputs: You weigh 74.65 kg.
<<do [tag tags] [element tag]>> … <</do>>
Displays its contents. Listens for <<redo>>
macro commands upon which it updates its contents.
v2.37.0
: Introduced.tag
tags
: (optional) The space separated list of tags used to filter commands.<<redo>>
element
tag
: (optional) The element to use as the content container—e.g., and . If omitted, defaults to .div
span
span
<<set $money to 10>>
''Money:'' <<do>>$money<</do>>
<<link "Update money display">>
<<set $money += 10>>
<<redo>>
<</link>>
<<set $key to "">> /* no key */
<<do>>
<<if $key>>
You have the $key key.
<<else>>
You do not have a key.
<</if>>
<</do>>
<<link "Update key display">>
<<set $key to ["", "red", "blue", "skull"].random()>>
<<redo>>
<</link>>
''Foo:'' <<do tag "foo foobar">><<= ["fee", "fie", "foe", "fum"].random()>><</do>>
''Bar:'' <<do tag "bar foobar">><<= ["alfa", "bravo", "charlie", "delta"].random()>><</do>>
<<link "Update foo">>
<<redo "foo">>
<</link>>
<<link "Update bar">>
<<redo "bar">>
<</link>>
<<link "Update foo & bar (1)">>
<<redo "foo bar">>
<</link>>
<<link "Update foo & bar (2)">>
<<redo "foobar">>
<</link>>
<<include passageName [elementName]>>
<<include linkMarkup [elementName]>>
Outputs the contents of the passage with the given name, optionally wrapping it within an HTML element. May be called either with the passage name or with a link markup.
v2.15.0
: Introduced.passageName
: The name of the passage to include.elementName
: (optional) The HTML element to wrap the included passage in. If used, the element will include the passage's name normalized into a class name. See CSS passage conversions for more information.linkMarkup
: The link markup to use (regular syntax only, no setters).elementName
: Identical to the passage name form.<<include "Go West">> → Include the passage "Go West"
<<include [[Go West]]>> → Include the passage "Go West"
<<include "Go West" "div">> → Include the passage "Go West", wrapping it within a <div>
<<include [[Go West]] "div">> → Include the passage "Go West", wrapping it within a <div>
<<nobr>> … <</nobr>>
Executes its contents and outputs the result, after removing leading/trailing newlines and replacing all remaining sequences of newlines with single spaces.
Note:
The nobr
special tag and Config.passages.nobr
setting applies the same processing to an entire passage or all passages, respectively. The line continuation markup performs a similar function, though in a slightly different way.
v2.0.0
: Introduced.→ Given: $feeling eq "blue", outputs: I'd like a blueberry pie.
I'd like a <<nobr>>
<<if $feeling eq "blue">>
blueberry
<<else>>
cherry
<</if>>
<</nobr>> pie.
<<print expression>>
Outputs a string representation of the result of the given expression.
Tip: If you only need to print the value of a TwineScript variable, then you may simply include it in your normal passage text and it will be printed automatically via the naked variable markup.
v2.0.0
: Introduced.expression
: A valid expression. See Expressions for more information.→ Assuming $gold is 5
You found <<print $gold>> gold. → Outputs: You found 5 gold.
→ Assuming $weight is 74.6466266
You weigh <<print $weight.toFixed(2)>> kg. → Outputs: You weigh 74.65 kg.
<<redo [tags]>>
Causes one or more <<do>>
macros to update their contents.
v2.37.0
: Introduced.tags
: (optional) The space separated list of tags corresponding to tagged macros to send update commands to. If omitted, sends update commands to all macros.<<do>>
<<do>>
See:
<<do>>
macro for examples.
<<silent>> … <</silent>>
Causes any output generated within its body to be discarded, except for errors (which will be displayed). Generally, only really useful for formatting blocks of macros for ease of use/readability, while ensuring that no output is generated, from spacing or whatnot.
v2.37.0
: Introduced.→ Basic
<<silent>>
You'll never see any of this!
<</silent>>
→ Hiding the guts of a countdown timer
<<set $seconds to 10>>\
Countdown: <span id="countdown">$seconds seconds remaining</span>!\
<<silent>>
<<repeat 1s>>
<<set $seconds to $seconds - 1>>
<<if $seconds gt 0>>
<<replace "#countdown">>$seconds seconds remaining<</replace>>
<<else>>
<<replace "#countdown">>Too Late<</replace>>
/* do something useful here */
<<stop>>
<</if>>
<</repeat>>
<</silent>>
<<type speed [start delay] [class classes] [element tag] [id ID] [keep|none] [skipkey key]>>
…
<</type>>
Outputs its contents a character—technically, a code point—at a time, mimicking a teletype/typewriter. Can type most content: links, markup, macros, etc.
Warning:
Interactions with macros or other code that inject content only after some external action or period—e.g., , , etc.—may or may not behave as you'd expect. Testing is strongly advised.
<<linkreplace>>
<<timed>>
See Also:
Config.macros.typeSkipKey
, Config.macros.typeVisitedPassages
, <<type>>
Events.
v2.32.0
: Introduced.v2.33.0
: Added , , and options and class.class
element
id
macro-type-done
v2.33.1
: Added option.skipkey
v2.37.0
: Updated argument so and skip.speed
0s
0ms
speed
: The rate at which characters are typed, as a valid CSS time value—e.g., and . Values in the range are a good starting point. Values of and cause typing to finish immediately.1s
40ms
20–60ms
0s
0ms
start
delay
: (optional) The amount of time to delay the start of typing, as a valid CSS time value—e.g., and . If omitted, defaults to .5s
500ms
400ms
class
classes
: (optional) The space separated list of classes to be added to the typing container.element
tag
: (optional) The element to use as the typing container—e.g., and . If omitted, defaults to .div
span
div
id
ID
: (optional) The unique ID to be assigned to the typing container.keep
: (optional) Keyword, used to signify that the cursor should be kept after typing is complete.none
: (optional) Keyword, used to signify that the cursor should not be used at all.skipkey
: (optional) The key used to cause typing to finish immediately. If omitted, defaults to the value of Config.macros.typeSkipKey
.<<type 40ms>>
Type characters from this content every 40 milliseconds. Including [[links]] and ''other markup''!
<</type>>
<<type 40ms start 2s>>
Type characters from this content every 40 milliseconds, starting after a 2 second delay.
<</type>>
<<type 40ms class "foo bar">>
Type characters from this content every 40 milliseconds, adding classes to the typing container.
<</type>>
<<type 40ms element "span">>
Type characters from this content every 40 milliseconds, using a <span> as the typing container.
<</type>>
<<type 40ms id "type01">>
Type characters from this content every 40 milliseconds, assigning an ID to the typing container.
<</type>>
<<type 40ms keep>>
Type characters from this content every 40 milliseconds, keeping the cursor after typing is complete.
<</type>>
<<type 40ms skipkey "Control">>
Type characters from this content every 40 milliseconds, using the Control (CTRL) key as the skip key.
<</type>>
The typed text has no default styling. If you want to change the font or color, then you'll need to change the styling of the class. For example:macro-type
.macro-type {
color: limegreen;
font-family: monospace, monospace;
}
There's also a class that is added to text that has finished typing, which may be used to style it differently from actively typing text.macro-type-done
The default cursor is the block element character Right Half Block (U+2590) and it has no default font or color styling. If you want to change the font, color, or character, then you'll need to change the styling of the pseudo-element of the class. For example::after
macro-type-cursor
.macro-type-cursor:after {
color: limegreen;
content: "\269C\FE0F"; /* Fleur-de-lis emoji */
font-family: monospace, monospace;
}
<<silently>> … <</silently>>
Deprecated:
This macro has been deprecated and should no longer be used. See the <<silent>>
macro for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of .<<silent>>
<<if conditional>> … [<<elseif conditional>> …] [<<else>> …] <</if>>
Executes its contents if the given conditional expression evaluates to . If the condition evaluates to and an or exists, then other contents can be executed.true
false
<<elseif>>
<<else>>
Note:
SugarCube does not trim whitespace from the contents of macros, so that authors don't have to resort to various kludges to get whitespace where they want it. This means, however, that extra care must be taken when writing them to ensure that unwanted whitespace is not created within the final output.
<<if>>
v2.0.0
: Introduced.conditional
: A valid conditional expression, evaluating to either or . See Expressions and Operators for more information.true
false
<<if $daysUntilLoanDue is 0>><<include "Panic">><</if>>
<<if $cash lt 5>>
I'm sorry, ma'am, but you don't have enough for the pie.
<<else>>
<<set $cash -= 5, $hasMeatPie = true>>
One meat pie, fresh out of the oven, coming up!
<</if>>
<<if $affection gte 75>>
I love you!
<<elseif $affection gte 50>>
I like you.
<<elseif $affection gte 25>>
I'm okay with you.
<<else>>
Get out of my face.
<</if>>
<<if $hullBreached>>
<<if $wearingHardSuit>>
<<include "That was close">>
<<elseif $wearingSoftSuit>>
<<include "Hole in suit">>
<<else>>
<<include "You die">>
<</if>>
<</if>>
<<for [conditional]>> … <</for>>
<<for [init] ; [conditional] ; [post]>> … <</for>>
<<for [[keyVariable ,] valueVariable] range collection>> … <</for>>
Repeatedly executes its contents. There are three forms: a conditional-only form, a 3-part conditional form, and a range form.
See Also:
<<break>>
and <<continue>>
.
v2.0.0
: Introduced.v2.20.0
: Added range form.v2.37.0
: Added range over integers and made range value variable optional._i
Executes its contents while the given conditional expression evaluates to . If no conditional expression is given, it is equivalent to specifying .true
true
Note:
The maximum number of loop iterations in the conditional forms is not unlimited by default, however, it is configurable. See Config.macros.maxLoopIterations
for more information.
init
: (optional) A valid expression, evaluated once at loop initialization. Typically used to initialize counter variable(s). See <<set>>
for more information.conditional
: (optional) A valid conditional expression, evaluated prior to each loop iteration. As long as the expression evaluates to , the loop is executed. See <<if>>
for more information.true
post
: (optional) A valid expression, evaluated after each loop iteration. Typically used to update counter variable(s). See <<set>>
for more information.→ Example setup
<<set $dwarves to ["Doc", "Dopey", "Bashful", "Grumpy", "Sneezy", "Sleepy", "Happy"]>>
→ Loop
<<for _i to 0; _i lt $dwarves.length; _i++>>
<<print _i + 1>>. $dwarves[_i]
<</for>>
→ Result
1. Doc
2. Dopey
3. Bashful
4. Grumpy
5. Sneezy
6. Sleepy
7. Happy
Iterates through all enumerable entries of the given collection. For each iteration, it assigns the key/value pair of the associated entry in the collection to the iteration variables and then executes its contents. Valid collection types are: arrays, generic objects, integers, maps, sets, and strings.
keyVariable
: (optional) A story or temporary variable that will be set to the iteration key.valueVariable
: (optional) A story or temporary variable that will be set to the iteration value.range
: Keyword, used to signify that the loop is using the range form syntax.collection
: An expression that yields a valid collection type, evaluated once at loop initialization.Collection type | Iteration: key, value |
---|---|
Arrays, Integers, & Sets | Member: index, value |
Generic objects | Property: name, value |
Maps | Entry: key, value |
Strings | Code point: start index, value |
Note: Strings are iterated by Unicode code point, however, due to historic reasons they are comprised of, and indexed by, individual UTF-16 code units. This means that some code points may span multiple code units—e.g., the character 💩 is one code point, but two code units.
→ Example setup
<<set $dwarves to ["Doc", "Dopey", "Bashful", "Grumpy", "Sneezy", "Sleepy", "Happy"]>>
→ Loop
<<for _i, _name range $dwarves>>
<<print _i + 1>>. _name
<</for>>
→ Result
1. Doc
2. Dopey
3. Bashful
4. Grumpy
5. Sneezy
6. Sleepy
7. Happy
→ Loop
<<for _value range 7>>
<<print _value + 1>>.
<</for>>
→ Result
1.
2.
3.
4.
5.
6.
7.
<<break>>
Used within <<for>>
macros. Terminates the execution of the current .<<for>>
v2.0.0
: Introduced.<<continue>>
Used within <<for>>
macros. Terminates the execution of the current iteration of the current and begins execution of the next iteration.<<for>>
Note: May eat line-breaks in certain situations.
v2.0.0
: Introduced.<<switch expression>>
[<<case valueList>> …]
[<<default>> …]
<</switch>>
Evaluates the given expression and compares it to the value(s) within its children. The value(s) within each case are compared to the result of the expression given to the parent . Upon a successful match, the matching case will have its contents executed. If no cases match and an optional case exists, which must be the final case, then its contents will be executed. At most one case will execute.<<case>>
<<switch>>
<<default>>
Note:
SugarCube does not trim whitespace from the contents of / macros, so that authors don't have to resort to various kludges to get whitespace where they want it. However, this means that extra care must be taken when writing them to ensure that unwanted whitespace is not created within the final output.
<<case>>
<<default>>
v2.7.2
: Introduced.<<switch>>
expression
: A valid expression. See Expressions for more information.<<case>>
valueList
: A space separated list of values to compare against the result of the switch expression.→ Without a default case
<<switch $hairColor>>
<<case "red" "auburn">>
You ginger.
<<case "black" "brown">>
Dark haired, eh?
<<case "blonde">>
You may have more fun.
<</switch>>
→ With a default case (assume the passage is about a waterfall)
<<switch visited()>>
<<case 1>>
You gaze in wonder at the magnificent waterfall for the first time, awestruck by its natural beauty.
<<case 2 3>>
You once again gaze upon the magnificent waterfall.
<<case 4 5>>
Yet again, you find yourself looking upon the waterfall.
<<default>>
Oh, look. It's that waterfall again. Meh.
<</switch>>
Interactive macros are both asynchronous and require interaction from the player. Thus, there are some potential pitfalls to consider:
<<capture>>
macro due to their asynchronous nature.<<button linkText [passageName]>> … <</button>>
<<button linkMarkup>> … <</button>>
<<button imageMarkup>> … <</button>>
Creates a button that silently executes its contents when clicked, optionally forwarding the player to another passage. May be called with either the link text and passage name as separate arguments, a link markup, or an image markup.
See: Interactive macro warning.
Note:
This macro is functionally identical to <<link>>, save that it uses a button element () rather than an anchor element ().
<button>
<a>
v2.8.0
: Introduced.linkText
: The text of the link. May contain markup.passageName
: (optional) The name of the passage to go to.linkMarkup
: The link markup to use (regular syntax only, no setters).imageMarkup
: The image markup to use (regular syntax only, no setters).→ Without forwarding: a very basic statistic setting example
Strength: <<set $pcStr to 10>><span id="stats-str"><<print $pcStr>></span> \
( <<button "[+]">><<set $pcStr++>><<replace "#stats-str">><<print $pcStr>><</replace>><</button>> \
| <<button "[-]">><<set $pcStr-->><<replace "#stats-str">><<print $pcStr>><</replace>><</button>> )
→ With forwarding: execute a script, then go to the specified passage
<<button "Onward, Reginald!" "On with the story">><<script>>/* (code) */<</script>><</button>>
<<button [[Onward, Reginald!|On with the story]]>><<script>>/* (code) */<</script>><</button>>
<<button [img[onward.jpg][On with the story]]>><<script>>/* (code) */<</script>><</button>>
<<checkbox receiverName uncheckedValue checkedValue [autocheck|checked]>>
Creates a checkbox, used to modify the value of the variable with the given name.
See: Interactive macro warning.
v2.0.0
: Introduced.v2.32.0
: Added keyword.autocheck
receiverName
: The name of the variable to modify, which must be quoted—e.g., . Object and array property references are also supported—e.g., , , & ."$foo"
"$foo.bar"
"$foo['bar']"
"$foo[0]"
uncheckedValue
: The value set by the checkbox when unchecked.checkedValue
: The value set by the checkbox when checked.autocheck
: (optional) Keyword, used to signify that the checkbox should be automatically set to the checked state based on the current value of the receiver variable. NOTE: Automatic checking may fail on non-primitive values—i.e., on arrays and objects.checked
: (optional) Keyword, used to signify that the checkbox should be in the checked state.What pies do you enjoy?
* <<checkbox "$pieBlueberry" false true autocheck>> Blueberry?
* <<checkbox "$pieCherry" false true autocheck>> Cherry?
* <<checkbox "$pieCoconutCream" false true autocheck>> Coconut cream?
What pies do you enjoy?
* <<checkbox "$pieBlueberry" false true checked>> Blueberry?
* <<checkbox "$pieCherry" false true>> Cherry?
* <<checkbox "$pieCoconutCream" false true checked>> Coconut cream?
<label>
Tip:
For accessibility reasons, it's recommended that you wrap each and its accompanying text within a element. Doing so allows interactions with the text to also trigger its .
<<checkbox>>
<label>
<<checkbox>>
What pies do you enjoy?
* <label><<checkbox "$pieBlueberry" false true autocheck>> Blueberry?</label>
* <label><<checkbox "$pieCherry" false true autocheck>> Cherry?</label>
* <label><<checkbox "$pieCoconutCream" false true autocheck>> Coconut cream?</label>
What pies do you enjoy?
* <label><<checkbox "$pieBlueberry" false true checked>> Blueberry?</label>
* <label><<checkbox "$pieCherry" false true>> Cherry?</label>
* <label><<checkbox "$pieCoconutCream" false true checked>> Coconut cream?</label>
<<cycle receiverName [once] [autoselect]>>
[<<option label [value [selected]]>> …]
[<<optionsfrom collection>> …]
<</cycle>>
Creates a cycling link, used to modify the value of the variable with the given name. The cycling options are populated via and/or .<<option>>
<<optionsfrom>>
See: Interactive macro warning.
v2.29.0
: Introduced.v2.36.0
: Fixed the keyword and added the keyword.selected
once
<<cycle>>
receiverName
: The name of the variable to modify, which must be quoted—e.g., . Object and array property references are also supported—e.g., , , & ."$foo"
"$foo.bar"
"$foo['bar']"
"$foo[0]"
once
: (optional) Keyword, used to signify that the cycle should stop upon reaching the last option and deactivate itself. NOTE: Since you likely want to start at the first option when using this keyword, you should either not select an option, so it defaults to the first, or, if you do, select the first option only.autoselect
: (optional) Keyword, used to signify that an option should be automatically selected as the cycle default based on the current value of the receiver variable. NOTE: Automatic option selection will fail on non-primitive values—i.e., on arrays and objects.<<option>>
label
: The label shown by the cycling link for the option.value
: (optional) The value set by the cycling link when the option is selected. If omitted, the label will be used as the value.selected
: (optional) Keyword, used to signify that the option should be the cycle default. Only one option may be so selected. If no options are selected as the default, the cycling link will default to the first option, unless the cycle keyword is specified. NOTE: If specified, the argument is not optional.autoselect
value
<<optionsfrom>>
collection
: An expression that yields a valid collection type.
Collection type | Option: label, value |
---|---|
Arrays & Sets | Member: value, value |
Generic objects | Property: name, value |
Maps | Entry: key, value |
<<option>>
The answer to the //Ultimate Question of Life, the Universe, and Everything// is?
<<cycle "$answer" autoselect>>
<<option "Towel">>
<<option "π" 3.14159>>
<<option 42>>
<<option 69>>
<<option "∞" Infinity>>
<</cycle>>
<<optionsfrom>>
→ Given: _pieOptions = ["blueberry", "cherry", "coconut cream"]
What's your favorite pie?
<<cycle "$pie" autoselect>>
<<optionsfrom _pieOptions>>
<</cycle>>
<<optionsfrom>>
→ Given: _pieOptions = { "Blueberry" : "blueberry", "Cherry" : "cherry", "Coconut cream" : "coconut cream" }
What's your favorite pie?
<<cycle "$pie" autoselect>>
<<optionsfrom _pieOptions>>
<</cycle>>
once
You see a large red, candy-like button.
<<cycle "$presses" once>>
<<option "Should you press it?" 0>>
<<option "Nothing happened. Press it again?" 1>>
<<option "Again?" 2>>
<<option "That time it locked into place with a loud click and began to glow ominously." 3>>
<</cycle>>
<<link linkText [passageName]>> … <</link>>
<<link linkMarkup>> … <</link>>
<<link imageMarkup>> … <</link>>
Creates a link that silently executes its contents when clicked, optionally forwarding the player to another passage. May be called with either the link text and passage name as separate arguments, a link markup, or an image markup.
See: Interactive macro warning.
Note: If you simply need a passage link that modifies variables, both the link markup and image markup offer setter variants.
v2.8.0
: Introduced.linkText
: The text of the link. May contain markup.passageName
: (optional) The name of the passage to go to.linkMarkup
: The link markup to use (regular syntax only, no setters).imageMarkup
: The image markup to use (regular syntax only, no setters).→ Without forwarding: a very basic statistic setting example
Strength: <<set $pcStr to 10>><span id="stats-str"><<print $pcStr>></span> \
( <<link "[+]">><<set $pcStr++>><<replace "#stats-str">><<print $pcStr>><</replace>><</link>> \
| <<link "[-]">><<set $pcStr-->><<replace "#stats-str">><<print $pcStr>><</replace>><</link>> )
→ With forwarding: execute a script, then go to the specified passage
<<link "Onward, Reginald!" "On with the story">><<script>>/* (code) */<</script>><</link>>
<<link [[Onward, Reginald!|On with the story]]>><<script>>/* (code) */<</script>><</link>>
<<link [img[onward.jpg][On with the story]]>><<script>>/* (code) */<</script>><</link>>
<<linkappend linkText [transition|t8n]>> … <</linkappend>>
Creates a single-use link that deactivates itself and appends its contents to its link text when clicked. Essentially, a combination of <<link>>
and <<append>>
.
See: Interactive macro warning.
v2.0.0
: Introduced.linkText
: The text of the link. May contain markup.transition
: (optional) Keyword, used to signify that a CSS transition should be applied to the incoming insertions.t8n
: (optional) Keyword, alias for transition
.→ Without a transition
We—We should <<linkappend "take">> away their METAL BAWKSES<</linkappend>>!
→ With a transition
I spy with my little <<linkappend "eye" t8n>>, a crab rangoon<</linkappend>>.
<<linkprepend linkText [transition|t8n]>> … <</linkprepend>>
Creates a single-use link that deactivates itself and prepends its contents to its link text when clicked. Essentially, a combination of <<link>>
and <<prepend>>
.
See: Interactive macro warning.
v2.0.0
: Introduced.linkText
: The text of the link. May contain markup.transition
: (optional) Keyword, used to signify that a CSS transition should be applied to the incoming insertions.t8n
: (optional) Keyword, alias for transition
.→ Without a transition
You see a <<linkprepend "robot">>GIANT <</linkprepend>>.
→ With a transition
I <<linkprepend "like" t8n>>do not <</linkprepend>> lemons.
<<linkreplace linkText [transition|t8n]>> … <</linkreplace>>
Creates a single-use link that deactivates itself and replaces its link text with its contents when clicked. Essentially, a combination of <<link>>
and <<replace>>
.
See: Interactive macro warning.
v2.0.0
: Introduced.linkText
: The text of the link. May contain markup.transition
: (optional) Keyword, used to signify that a CSS transition should be applied to the incoming insertions.t8n
: (optional) Keyword, alias for transition
.→ Without a transition
I'll have a <<linkreplace "cupcake">>slice of key lime pie<</linkreplace>>, please.
→ With a transition
<<linkreplace "You'll //never// take me alive!" t8n>>On second thought, don't hurt me.<</linkreplace>>
<<listbox receiverName [autoselect]>>
[<<option label [value [selected]]>> …]
[<<optionsfrom collection>> …]
<</listbox>>
Creates a listbox, used to modify the value of the variable with the given name. The list options are populated via and/or .<<option>>
<<optionsfrom>>
See: Interactive macro warning.
v2.26.0
: Introduced.v2.27.0
: Added keyword.autoselect
v2.28.0
: <<optionsFrom>>
child tag.v2.28.1
: Fixed name of child tag, which was erroneously added as in .<<optionsfrom>>
<<optionsFrom>>
v2.28.0
v2.29.0
: Made the child tag's argument optional.<<option>>
value
v2.36.0
: Fixed the keyword.selected
<<listbox>>
receiverName
: The name of the variable to modify, which must be quoted—e.g., . Object and array property references are also supported—e.g., , , & ."$foo"
"$foo.bar"
"$foo['bar']"
"$foo[0]"
autoselect
: (optional) Keyword, used to signify that an option should be automatically selected as the listbox default based on the current value of the receiver variable. NOTE: Automatic option selection will fail on non-primitive values—i.e., on arrays and objects.<<option>>
label
: The label shown by the listbox for the option.value
: (optional) The value set by the listbox when the option is selected. If omitted, the label will be used as the value.selected
: (optional) Keyword, used to signify that the option should be the listbox default. Only one option may be so selected. If no options are selected as the default, the listbox will default to the first option, unless the listbox keyword is specified. NOTE: If specified, the argument is not optional.autoselect
value
<<optionsfrom>>
collection
: An expression that yields a valid collection type.
Collection type | Option: label, value |
---|---|
Arrays & Sets | Member: value, value |
Generic objects | Property: name, value |
Maps | Entry: key, value |
<<option>>
The answer to the //Ultimate Question of Life, the Universe, and Everything// is?
<<listbox "$lbanswer" autoselect>>
<<option "Towel">>
<<option "π" 3.14159>>
<<option 42>>
<<option 69>>
<<option "∞" Infinity>>
<</listbox>>
<<optionsfrom>>
→ Given: _pieOptions = ["blueberry", "cherry", "coconut cream"]
What's your favorite pie?
<<listbox "$pie" autoselect>>
<<optionsfrom _pieOptions>>
<</listbox>>
<<optionsfrom>>
→ Given: _pieOptions = { "Blueberry" : "blueberry", "Cherry" : "cherry", "Coconut cream" : "coconut cream" }
What's your favorite pie?
<<listbox "$pie" autoselect>>
<<optionsfrom _pieOptions>>
<</listbox>>
<<numberbox receiverName defaultValue [passage] [autofocus]>>
Creates a number input box, used to modify the value of the variable with the given name, optionally forwarding the player to another passage.
See: Interactive macro warning.
v2.32.0
: Introduced.receiverName
: The name of the variable to modify, which must be quoted—e.g., . Object and array property references are also supported—e.g., , , & ."$foo"
"$foo.bar"
"$foo['bar']"
"$foo[0]"
defaultValue
: The default value of the number box.passage
: (optional) The name of the passage to go to if the return/enter key is pressed. May be called either with the passage name or with a link markup.autofocus
: (optional) Keyword, used to signify that the number box should automatically receive focus. Only use the keyword once per page; attempting to focus more than one element is undefined behavior.→ Creates a number box that modifies $wager
Wager how much on Buttstallion in the race? <<numberbox "$wager" 100>>
→ Creates an automatically focused number box that modifies $wager
Wager how much on Buttstallion in the race? <<numberbox "$wager" 100 autofocus>>
→ Creates a number box that modifies $wager and forwards to the "Result" passage
Wager how much on Buttstallion in the race? <<numberbox "$wager" 100 "Result">>
→ Creates an automatically focused number box that modifies $wager and forwards to the "Result" passage
Wager how much on Buttstallion in the race? <<numberbox "$wager" 100 "Result" autofocus>>
<<radiobutton receiverName checkedValue [autocheck|checked]>>
Creates a radio button, used to modify the value of the variable with the given name. Multiple macros may be set up to modify the same variable, which makes them part of a radio button group.<<radiobutton>>
See: Interactive macro warning.
v2.0.0
: Introduced.v2.32.0
: Added keyword.autocheck
receiverName
: The name of the variable to modify, which must be quoted—e.g., . Object and array property references are also supported—e.g., , , & ."$foo"
"$foo.bar"
"$foo['bar']"
"$foo[0]"
checkedValue
: The value set by the radio button when checked.autocheck
: (optional) Keyword, used to signify that the radio button should be automatically set to the checked state based on the current value of the receiver variable. NOTE: Automatic checking may fail on non-primitive values—i.e., on arrays and objects.checked
: (optional) Keyword, used to signify that the radio button should be in the checked state. NOTE: Only one radio button in a group—i.e., those using the same receiver variable—should be so checked.What's your favorite pie?
* <<radiobutton "$pie" "blueberry" autocheck>> Blueberry?
* <<radiobutton "$pie" "cherry" autocheck>> Cherry?
* <<radiobutton "$pie" "coconut cream" autocheck>> Coconut cream?
What's your favorite pie?
* <<radiobutton "$pie" "blueberry" checked>> Blueberry?
* <<radiobutton "$pie" "cherry">> Cherry?
* <<radiobutton "$pie" "coconut cream">> Coconut cream?
<label>
Tip:
For accessibility reasons, it's recommended that you wrap each and its accompanying text within a element. Doing so allows interactions with the text to also trigger its .
<<radiobutton>>
<label>
<<radiobutton>>
What's your favorite pie?
* <label><<radiobutton "$pie" "blueberry" autocheck>> Blueberry?</label>
* <label><<radiobutton "$pie" "cherry" autocheck>> Cherry?</label>
* <label><<radiobutton "$pie" "coconut cream" autocheck>> Coconut cream?</label>
What's your favorite pie?
* <label><<radiobutton "$pie" "blueberry" checked>> Blueberry?</label>
* <label><<radiobutton "$pie" "cherry">> Cherry?</label>
* <label><<radiobutton "$pie" "coconut cream">> Coconut cream?</label>
<<textarea receiverName defaultValue [autofocus]>>
Creates a multiline text input block, used to modify the value of the variable with the given name.
See: Interactive macro warning.
v2.0.0
: Introduced.receiverName
: The name of the variable to modify, which must be quoted—e.g., . Object and array property references are also supported—e.g., , , & ."$foo"
"$foo.bar"
"$foo['bar']"
"$foo[0]"
defaultValue
: The default value of the text block.autofocus
: (optional) Keyword, used to signify that the text block should automatically receive focus. Only use the keyword once per page; attempting to focus more than one element is undefined behavior.→ Creates a text block that modifies $pieEssay
Write a short essay about pies:
<<textarea "$pieEssay" "">>
→ Creates an automatically focused text block that modifies $pieEssay
Write a short essay about pies:
<<textarea "$pieEssay" "" autofocus>>
<<textbox receiverName defaultValue [passage] [autofocus]>>
Creates a text input box, used to modify the value of the variable with the given name, optionally forwarding the player to another passage.
See: Interactive macro warning.
v2.0.0
: Introduced.receiverName
: The name of the variable to modify, which must be quoted—e.g., . Object and array property references are also supported—e.g., , , & ."$foo"
"$foo.bar"
"$foo['bar']"
"$foo[0]"
defaultValue
: The default value of the text box.passage
: (optional) The name of the passage to go to if the return/enter key is pressed. May be called either with the passage name or with a link markup.autofocus
: (optional) Keyword, used to signify that the text box should automatically receive focus. Only use the keyword once per page; attempting to focus more than one element is undefined behavior.→ Creates a text box that modifies $pie
What's your favorite pie? <<textbox "$pie" "Blueberry">>
→ Creates an automatically focused text box that modifies $pie
What's your favorite pie? <<textbox "$pie" "Blueberry" autofocus>>
→ Creates a text box that modifies $pie and forwards to the "Cakes" passage
What's your favorite pie? <<textbox "$pie" "Blueberry" "Cakes">>
→ Creates an automatically focused text box that modifies $pie and forwards to the "Cakes" passage
What's your favorite pie? <<textbox "$pie" "Blueberry" "Cakes" autofocus>>
<<back [linkText [passageName]]>>
<<back linkMarkup>>
<<back imageMarkup>>
Creates a link that undoes past moments within the story history. May be called with, optional, the link text and passage name as separate arguments, a link markup, or an image markup.
Note:
If you want to return to a previously visited passage, rather than undo a moment within the history, see the <<return>>
macro or the previous()
function.
v2.0.0
: Introduced.v2.37.0
: Added optional passage name argument in separate argument form.linkText
: (optional if is not specified) The text of the link. May contain markup.passageName
passageName
: (optional) The name of the moment to undo to until it's reached.linkMarkup
: The link markup to use (regular syntax only, no setters).imageMarkup
: The image markup to use (regular syntax only, no setters).Assume your story history consists of three moments:
A, B, [C]
N.b., the square brackets there denote the active moment.
Using once upon that history will change it to be thus:<<back>>
A, [B], C
I.e., the history was rolled back to the previous moment.
→ Creates a link that undoes the most recent moment, with default text
<<back>>
→ Creates a link that undoes the most recent moment, with text "Home."
<<back "Home.">>
→ Creates a link that undoes past moments until the most recent "HQ" moment is reached, with text "Home."
<<back "Home." "HQ">>
→ Creates a link that undoes past moments until the most recent "HQ" moment is reached, with default text
<<back [[HQ]]>>
→ Creates a link that undoes past moments until the most recent "HQ" moment is reached, with text "Home."
<<back [[Home.|HQ]]>>
→ Creates a link that undoes the most recent moment, with image "home.png"
<<back [img[home.png]]>>
→ Creates a link that undoes past moments until the most recent "HQ" moment is reached, with image "home.png"
<<back [img[home.png][HQ]]>>
<<return [linkText [passageName]]>>
<<return linkMarkup>>
<<return imageMarkup>>
Creates a link that navigates forward to a previously visited passage. May be called with, optional, the link text and passage name as separate arguments, a link markup, or an image markup.
Note:
If you want to undo previous moments within the history, rather than return to a passage, see the <<back>>
macro.
v2.0.0
: Introduced.v2.37.0
: Added optional passage name argument in separate argument form.linkText
: (optional if is not specified) The text of the link. May contain markup.passageName
passageName
: (optional) The name of the passage to go to.linkMarkup
: The link markup to use (regular syntax only, no setters).imageMarkup
: The image markup to use (regular syntax only, no setters).Note:
The versions that forward to a specific passage are largely unnecessary, as you could simply use a normal link, and exist solely for compatibility with the <<back>>
macro.
Assume your story history consists of three moments:
A, B, [C]
N.b., the square brackets there denote the active moment.
Using once upon that history will change it to be thus:<<return>>
A, B, C, [B]
I.e., a new moment, to the same passage as the previous moment, was added to the history.
→ Creates a link that forwards to the previous passage, with default text
<<return>>
→ Creates a link that forwards to the previous passage, with text "Home."
<<return "Home.">>
→ Creates a link that forwards to the "HQ" passage, with text "Home."
<<return "Home." "HQ">>
→ Creates a link that forwards to the "HQ" passage, with default text
<<return [[HQ]]>>
→ Creates a link that forwards to the "HQ" passage, with text "Home."
<<return [[Home.|HQ]]>>
→ Creates a link that forwards to the previous passage, with image "home.png"
<<return [img[home.png]]>>
→ Creates a link that forwards to the "HQ" passage, with image "home.png"
<<return [img[home.png][HQ]]>>
<<actions passageList>>
<<actions linkMarkupList>>
<<actions imageMarkupList>>
Deprecated: This macro has been deprecated and should no longer be used.
v2.0.0
: Introduced.v2.37.0
: Deprecated.<<choice passageName [linkText]>>
<<choice linkMarkup>>
<<choice imageMarkup>>
Deprecated: This macro has been deprecated and should no longer be used.
v2.0.0
: Introduced.v2.37.0
: Deprecated.
Warning:
All DOM macros require the elements to be manipulated to be on the page. As a consequence, you cannot use them directly within a passage to modify elements within said passage, since the elements they are targeting are still rendering, thus not yet on the page. You must, generally, use them with an interactive macro—e.g., <<link>>
macro—the <<done>>
macro, or within the PassageDone
special passage. Elements that are already part of the page, on the other hand, present no issues.
<<addclass selector classNames>>
Adds classes to the selected element(s).
See: DOM macro warning.
v2.0.0
: Introduced.selector
: The CSS/jQuery-style selector used to target element(s).classNames
: The names of the classes, separated by spaces.<<addclass "body" "day rain">> → Add the classes "day" and "rain" to the <body> element
<<addclass "#pie" "cherry">> → Add the class "cherry" to the element with the ID "pie"
<<addclass ".joe" "angry">> → Add the class "angry" to all elements containing the class "joe"
<<append selector [transition|t8n]>> … <</append>>
Executes its contents and appends the output to the contents of the selected element(s).
See: DOM macro warning.
v2.0.0
: Introduced.v2.25.0
: Added and keywords.transition
t8n
selector
: The CSS/jQuery-style selector used to target element(s).transition
: (optional) Keyword, used to signify that a CSS transition should be applied to the incoming insertions.t8n
: (optional) Keyword, alias for transition
.→ Example setup
I saw a <span id="dog">dog</span>.
→ Append to the contents of the target element
<<link "Doing">>
<<append "#dog">> chasing a cat<</append>>
<</link>>
→ Result, after clicking
I saw a <span id="dog">dog chasing a cat</span>.
→ Example setup
I saw a <span id="dog">dog</span>.
→ Append to the contents of the target element
<<link "Doing">>
<<append "#dog" t8n>> chasing a cat<</append>>
<</link>>
→ Result, after clicking
I saw a <span id="dog">dog<span class="macro-append-insert"> chasing a cat</span></span>.
<<copy selector>>
Outputs a copy of the contents of the selected element(s).
Warning:
Most interactive elements—e.g., passage links, interactive macros, etc.—cannot be properly copied via . Attempting to do so will, usually, result in something that's non-functional.
<<copy>>
See: DOM macro warning.
v2.0.0
: Introduced.selector
: The CSS/jQuery-style selector used to target element(s).→ Example setup
I'd like a <span id="snack-source">slice of Key lime pie</span>, please.
I'll have a <span id="snack-dest">breadstick</span>, thanks.
→ Replace the contents of the source target element with a copy of the destination target element
<<link "Have the same">>
<<replace "#snack-dest">><<copy "#snack-source">> too<</replace>>
<</link>>
→ Result, after the click
I'd like a <span id="snack-source">slice of Key lime pie</span>, please.
I'll have a <span id="snack-dest">slice of Key lime pie too</span>, thanks.
<<prepend selector [transition|t8n]>> … <</prepend>>
Executes its contents and prepends the output to the contents of the selected element(s).
See: DOM macro warning.
v2.0.0
: Introduced.v2.25.0
: Added and keywords.transition
t8n
selector
: The CSS/jQuery-style selector used to target element(s).transition
: (optional) Keyword, used to signify that a CSS transition should be applied to the incoming insertions.t8n
: (optional) Keyword, alias for transition
.→ Example setup
I saw a <span id="dog">dog</span>.
→ Prepend to the contents of the target element
<<link "Size">>
<<prepend "#dog">>big <</prepend>>
<</link>>
→ Result, after clicking
I saw a <span id="dog">big dog</span>.
→ Example setup
I saw a <span id="dog">dog</span>.
→ Prepend to the contents of the target element
<<link "Size">>
<<prepend "#dog" t8n>>big <</prepend>>
<</link>>
→ Result, after clicking
I saw a <span id="dog"><span class="macro-prepend-insert">big </span>dog</span>.
<<remove selector>>
Removes the selected element(s).
See: DOM macro warning.
Note:
If you simply want to empty the selected element(s), not remove them outright, you should use an empty <<replace>>
macro instead.
v2.0.0
: Introduced.selector
: The CSS/jQuery-style selector used to target element(s).→ Given the following
I'd like a <span id="huge-cupcake">humongous </span>cupcake, please.
→ Remove the target element
<<link "Go small">>
<<remove "#huge-cupcake">>
<</link>>
→ Result, after the click
I'd like a cupcake, please.
<<removeclass selector [classNames]>>
Removes classes from the selected element(s).
See: DOM macro warning.
v2.0.0
: Introduced.selector
: The CSS/jQuery-style selector used to target element(s).classNames
: (optional) The names of the classes, separated by spaces. If no class names are given, removes all classes.<<removeclass "body" "day rain">> → Remove the classes "day" and "rain" from the <body> element
<<removeclass "#pie" "cherry">> → Remove the class "cherry" from the element with the ID "pie"
<<removeclass ".joe" "angry">> → Remove the class "angry" from all elements containing the class "joe"
<<removeclass "#begone">> → Remove all classes from the element with the ID "begone"
<<replace selector [transition|t8n]>> … <</replace>>
Executes its contents and replaces the contents of the selected element(s) with the output.
See: DOM macro warning.
v2.0.0
: Introduced.v2.25.0
: Added and keywords.transition
t8n
selector
: The CSS/jQuery-style selector used to target element(s).transition
: (optional) Keyword, used to signify that a CSS transition should be applied to the incoming insertions.t8n
: (optional) Keyword, alias for transition
.→ Example setup
I saw a <span id="dog">dog</span>.
→ Replace the contents of the target element
<<link "Breed">>
<<replace "#dog">>Catahoula Cur<</replace>>
<</link>>
→ Result, after clicking
I saw a <span id="dog">Catahoula Cur</span>.
→ Example setup
I saw a <span id="dog">dog</span>.
→ Replace the contents of the target element
<<link "Breed">>
<<replace "#dog" t8n>>Catahoula Cur<</replace>>
<</link>>
→ Result, after clicking
I saw a <span id="dog"><span class="macro-replace-insert">Catahoula Cur</span></span>.
<<toggleclass selector classNames>>
Toggles classes on the selected element(s)—i.e., adding them if they don't exist, removing them if they do.
See: DOM macro warning.
v2.0.0
: Introduced.selector
: The CSS/jQuery-style selector used to target element(s).classNames
: The names of the classes, separated by spaces.<<toggleclass "body" "day rain">> → Toggle the classes "day" and "rain" on the <body> element
<<toggleclass "#pie" "cherry">> → Toggle the class "cherry" on the element with the ID "pie"
<<toggleclass ".joe" "angry">> → Toggle the class "angry" on all elements containing the class "joe"
Warning: The audio subsystem that supports the audio macros comes with some built-in limitations and it is strongly recommended that you familiarize yourself with them.
<<audio trackIdList actionList>>
Controls the playback of audio tracks, which must be set up via <<cacheaudio>>
.
See: Audio macro limitations.
Note:
The macro cannot affect playlist tracks whose ownership has been transferred to their respective playlist. Meaning those set up via <<createplaylist>>
with its action, as owned playlist tracks are solely under the control of their playlist.
<<audio>>
own
Note:
The Config.audio.pauseOnFadeToZero
setting (default: ) controls whether tracks that have been faded to volume (silent) are automatically paused.
true
0
v2.0.0
: Introduced.v2.1.0
: Added action.fadeoverto
v2.8.0
: Added group ID(s).v2.28.0
: Added and actions.load
unload
v2.37.0
: Added predefined group ID.:stopped
trackIdList
: The list of track and/or group IDs, separated by spaces. See below for details on group IDs.actionList
: The list of actions to perform. Available actions are:
fadein
: Start playback of the selected tracks and fade them from their current volume level to (loudest) over seconds.1
5
fadeout
: Start playback of the selected tracks and fade them from their current volume level to (silent) over seconds.0
5
fadeoverto
seconds
level
: Start playback of the selected tracks and fade them from their current volume level to the specified level over the specified number of seconds.fadeto
level
: Start playback of the selected tracks and fade them from their current volume level to the specified level over seconds.5
goto
passage
: Forwards the player to the passage with the given name when playback of the first of the selected tracks ends normally. May be called either with the passage name or with a link markup.load
: Pause playback of the selected tracks and, if they're not already in the process of loading, force them to drop any existing data and begin loading. NOTE: This should not be done lightly if your audio sources are on the network, as it forces the player to begin downloading them.loop
: Set the selected tracks to repeat playback upon ending normally.mute
: Mute the volume of the selected tracks—effectively volume , except without changing the volume level.0
pause
: Pause playback of the selected tracks.play
: Start playback of the selected tracks.stop
: Stop playback of the selected tracks.time
seconds
: Set the current playback time of the selected tracks to the specified number of seconds. Valid values are floating-point numbers in the range (start) to the maximum duration—e.g., is is sixty seconds in, is ninety-point-five seconds in.0
60
60
90.5
unload
: Stop playback of the selected tracks and force them to drop any existing data. NOTE: Once unloaded, playback cannot occur until a action is issued.load
unloop
: Set the selected tracks to not repeat playback (this is the default).unmute
: Unmute the volume of the selected tracks (this is the default).volume
level
: Set the volume of the selected tracks to the specified level. Valid values are floating-point numbers in the range (silent) to (loudest)—e.g., is 0%, is 50%, is 100%.0
1
0
0.5
1
Group IDs allow several tracks to be selected simultaneously without needing to specify each one individually. There are several predefined group IDs (, , , , , ) and custom IDs may be defined via <<createaudiogroup>>
. The group modifier syntax () allows a group to have some of its tracks excluded from selection.:all
:looped
:muted
:paused
:playing
:stopped
:not()
groupId:not(trackIdList)
→ Start playback of paused tracks
<<audio ":paused" play>>
→ Pause playback of playing tracks
<<audio ":playing" pause>>
→ Stop playback of playing tracks
<<audio ":playing" stop>>
→ Stop playback of all tracks
<<audio ":all" stop>>
→ Stop playback of playing tracks except those in the ":ui" group
<<audio ":playing:not(:ui)" stop>>
→ Change the volume of all tracks except those in the ":ui" group
→ to 40%, without changing the current playback state
<<audio ":all:not(:ui)" volume 0.40>>
→ Given the following (best done in the StoryInit special passage)
<<cacheaudio "bgm_space" "media/audio/space_quest.mp3" "media/audio/space_quest.ogg">>
→ Start playback
<<audio "bgm_space" play>>
→ Start playback at 50% volume
<<audio "bgm_space" volume 0.5 play>>
→ Start playback at 120 seconds in
<<audio "bgm_space" time 120 play>>
→ Start repeating playback
<<audio "bgm_space" loop play>>
→ Start playback and fade from 0% to 100% volume
<<audio "bgm_space" volume 0 fadein>>
→ Start playback and fade from 75% to 0% volume
<<audio "bgm_space" volume 0.75 fadeout>>
→ Start playback and fade from 25% to 75% volume
<<audio "bgm_space" volume 0.25 fadeto 0.75>>
→ Start playback and fade from 25% to 75% volume over 30 seconds
<<audio "bgm_space" volume 0.25 fadeoverto 30 0.75>>
→ Start playback and goto the "Peace Moon" passage upon ending normally
<<audio "bgm_space" play goto "Peace Moon">>
→ Pause playback
<<audio "bgm_space" pause>>
→ Stop playback
<<audio "bgm_space" stop>>
→ Mute playback, without changing the current playback state
<<audio "bgm_space" mute>>
→ Unmute playback, without changing the current playback state
<<audio "bgm_space" unmute>>
→ Change the volume to 40%, without changing the current playback state
<<audio "bgm_space" volume 0.40>>
→ Seek to 90 seconds in, without changing the current playback state
<<audio "bgm_space" time 90>>
load
unload
Warning: Be very careful with these if your audio sources are on the network, as you are forcing players to begin downloading them. Not everyone has blazing fast internet with unlimited data—especially true for mobile users. Pease, do not take your players' bandwidth and data usage lightly.
→ If it's not currently loading, drop existing data buffers and load the track
<<audio "bgm_space" load>>
→ Unload the track, dropping existing data buffers
<<audio "bgm_space" unload>>
<<cacheaudio trackId sourceList>>
Caches an audio track for use by the other audio macros.
Note:
The StoryInit
special passage is normally the best place to set up tracks.
v2.0.0
: Introduced.trackId
: The ID of the track, which will be used to reference it.sourceList
: A space separated list of sources for the track. Only one is required, though supplying additional sources in differing formats is recommended, as no single format is supported by all browsers. A source must be either a URL (absolute or relative) to an audio resource, the name of an audio passage, or a data URI. In rare cases where the audio format cannot be automatically detected from the source (URLs are parsed for a file extension, data URIs are parsed for the media type), a format specifier may be prepended to the front of each source to manually specify the format (syntax: , where is the audio format—generally, whatever the file extension would normally be; e.g., , , , , ).formatId|
formatId
mp3
mp4
ogg
weba
wav
→ Cache a track with the ID "boom" and one source via relative URL
<<cacheaudio "boom" "media/audio/explosion.mp3">>
→ Cache a track with the ID "boom" and one source via audio passage
<<cacheaudio "boom" "explosion">>
→ Cache a track with the ID "bgm_space" and two sources via relative URLs
<<cacheaudio "bgm_space" "media/audio/space_quest.mp3" "media/audio/space_quest.ogg">>
→ Cache a track with the ID "what" and one source via URL with a format specifier
<<cacheaudio "what" "mp3|http://an-audio-service.com/a-user/a-track-id">>
<<createaudiogroup groupId>>
[<<track trackId>> …]
<</createaudiogroup>>
Collects tracks, which must be set up via <<cacheaudio>>
, into a group via its children. Groups are useful for applying actions to multiple tracks simultaneously and/or excluding the included tracks from a larger set when applying actions.<<track>>
Note:
The StoryInit
special passage is normally the best place to set up groups.
v2.19.0
: Introduced.v2.37.0
: Added predefined group ID.:stopped
<<createaudiogroup>>
groupId
: The ID of the group that will be used to reference it and must begin with a colon. NOTE: There are several predefined group IDs (, , , , , ) and the group modifier that cannot be reused/overwritten.:all
:looped
:muted
:paused
:playing
:stopped
:not
<<track>>
trackId
: The ID of the track.→ Given the following (best done in the StoryInit special passage)
<<cacheaudio "ui_beep" "media/audio/ui/beep.mp3">>
<<cacheaudio "ui_boop" "media/audio/ui/boop.mp3">>
<<cacheaudio "ui_swish" "media/audio/ui/swish.mp3">>
→ Set up a group ":ui" with the tracks: "ui_beep", "ui_boop", and "ui_swish"
<<createaudiogroup ":ui">>
<<track "ui_beep">>
<<track "ui_boop">>
<<track "ui_swish">>
<</createaudiogroup>>
<<createplaylist listId>>
[<<track trackId actionList>> …]
<</createplaylist>>
Collects tracks, which must be set up via <<cacheaudio>>
, into a playlist via its children.<<track>>
Note:
The StoryInit
special passage is normally the best place to set up playlists.
v2.8.0
: Introduced.<<createplaylist>>
listId
: The ID of the playlist, which will be used to reference it.<<track>>
trackId
: The ID of the track.actionList
: The list of actions to perform. Available actions are:
volume
level
: (optional) Set the base volume of the track within the playlist to the specified level. If omitted, defaults to the track's current volume. Valid values are floating-point numbers in the range (silent) to (loudest)—e.g., is 0%, is 50%, is 100%.0
1
0
0.5
1
own
: (optional) Keyword, used to signify that the playlist should create its own independent copy of the track, rather than simply referencing the existing version. Owned copies are solely under the control of their playlist—meaning <<audio>>
actions cannot affect them, even when using group IDs.→ Given the following setup (best done in the StoryInit special passage)
<<cacheaudio "swamped" "media/audio/Swamped.mp3">>
<<cacheaudio "heavens_a_lie" "media/audio/Heaven's_A_Lie.mp3">>
<<cacheaudio "closer" "media/audio/Closer.mp3">>
<<cacheaudio "to_the_edge" "media/audio/To_The_Edge.mp3">>
→ Create a playlist "bgm_lacuna" with the tracks: "swamped", "heavens_a_lie", "closer", and "to_the_edge"
<<createplaylist "bgm_lacuna">>
<<track "swamped" volume 1>> → Add "swamped" at 100% volume
<<track "heavens_a_lie" volume 0.5>> → Add "heavens_a_lie" at 50% volume
<<track "closer" own>> → Add an owned copy of "closer" at its current volume
<<track "to_the_edge" volume 1 own>> → Add an owned copy of "to_the_edge" at 100% volume
<</createplaylist>>
<<masteraudio actionList>>
Controls the master audio settings.
See: Audio macro limitations.
v2.8.0
: Introduced.v2.28.0
: Added , , , and actions.load
muteonhide
nomuteonhide
unload
actionList
: The list of actions to perform. Available actions are:
load
: Pause playback of all tracks and, if they're not already in the process of loading, force them to drop any existing data and begin loading. NOTE: This should not be done lightly if your audio sources are on the network, as it forces the player to begin downloading them.mute
: Mute the master volume (effectively volume , except without changing the volume level).0
muteonhide
: Enable automatic muting of the master volume when losing visibility—i.e., when switched to another tab or the browser window is minimized.nomuteonhide
: Disable automatic muting of the master volume when losing visibility (this is the default).stop
: Stop playback of all tracks.unload
: Stop playback of all tracks and force them to drop any existing data. NOTE: Once unloaded, playback cannot occur until a action is issued for each track—either a master action, to affect all tracks, or an / action, to affect only certain tracks.load
load
<<audio>>
<<playlist>>
load
unmute
: Unmute the master volume (this is the default).volume
level
: Set the master volume to the specified level. Valid values are floating-point numbers in the range (silent) to (loudest)—e.g., is 0%, is 50%, is 100%.0
1
0
0.5
1
→ Stop playback of all registered tracks, no exceptions
<<masteraudio stop>>
→ Change the master volume to 40%
<<masteraudio volume 0.40>>
→ Mute the master volume
<<masteraudio mute>>
→ Unmute the master volume
<<masteraudio unmute>>
→ Enable automatic muting of the master volume when losing visibility
<<masteraudio muteonhide>>
→ Disable automatic muting of the master volume when losing visibility
<<masteraudio nomuteonhide>>
load
unload
Warning: Be very careful with these if your audio sources are on the network, as you are forcing players to begin downloading them. Not everyone has blazing fast internet with unlimited data—especially true for mobile users. Pease, do not take your players' bandwidth and data usage lightly.
→ If they're not currently loading, drop existing data buffers and load all tracks
<<masteraudio load>>
→ Unload all tracks, dropping existing data buffers
<<masteraudio unload>>
<<playlist listId actionList>>
Controls the playback of the playlist, which must be set up via <<createplaylist>>
.
See: Audio macro limitations.
Note:
The Config.audio.pauseOnFadeToZero
setting (default: ) controls whether tracks that have been faded to volume (silent) are automatically paused.
true
0
v2.0.0
: Introduced, compatible with .<<setplaylist>>
v2.1.0
: Added action.fadeoverto
v2.8.0
: Added argument, compatible with .listId
<<createplaylist>>
v2.28.0
: Added and actions.load
unload
<<createplaylist>>
-compatible formlistId
: The ID of the playlist.actionList
: The list of actions to perform. Available actions are:
fadein
: Start playback of the playlist and fade the current track from its current volume level to (loudest) over seconds.1
5
fadeout
: Start playback of the playlist and fade the current track from its current volume level to (silent) over seconds.0
5
fadeoverto
seconds
level
: Start playback of the playlist and fade the current track from its current volume level to the specified level over the specified number of seconds.fadeto
level
: Start playback of the playlist and fade the current track from its current volume level to the specified level over seconds.5
load
: Pause playback of the playlist and, if its tracks are not already in the process of loading, force them to drop any existing data and begin loading. NOTE: This should not be done lightly if your audio sources are on the network, as it forces the player to begin downloading them.loop
: Set the playlist to repeat playback upon ending.mute
: Mute the volume of the playlist (effectively volume , except without changing the volume level).0
pause
: Pause playback of the playlist.play
: Start playback of the playlist.shuffle
: Set the playlist to randomly shuffle.skip
: Skip ahead to the next track in the queue. An empty queue will not be refilled unless repeat playback has been set.stop
: Stop playback of the playlist.unload
: Stop playback of the playlist and force its tracks to drop any existing data. NOTE: Once unloaded, playback cannot occur until a action is issued.load
unloop
: Set the playlist to not repeat playback (this is the default).unmute
: Unmute the volume of the playlist (this is the default).unshuffle
: Set the playlist to not randomly shuffle (this is the default).volume
level
: Set the volume of the playlist to the specified level. Valid values are floating-point numbers in the range (silent) to (loudest)—e.g., is 0%, is 50%, is 100%.0
1
0
0.5
1
<<setplaylist>>
-compatible formactionList
: Identical to the <<createplaylist>>
-compatible form.<<createplaylist>>
-compatible form shown)→ Given the following (best done in the StoryInit special passage)
<<cacheaudio "swamped" "media/audio/Swamped.mp3">>
<<cacheaudio "heavens_a_lie" "media/audio/Heaven's_A_Lie.mp3">>
<<cacheaudio "closer" "media/audio/Closer.mp3">>
<<cacheaudio "to_the_edge" "media/audio/To_The_Edge.mp3">>
<<createplaylist "bgm_lacuna">>
<<track "swamped" volume 1>>
<<track "heavens_a_lie" volume 1>>
<<track "closer" volume 1>>
<<track "to_the_edge" volume 1>>
<</createplaylist>>
→ Start playback
<<playlist "bgm_lacuna" play>>
→ Start playback at 50% volume
<<playlist "bgm_lacuna" volume 0.5 play>>
→ Start non-repeating playback
<<playlist "bgm_lacuna" unloop play>>
→ Start playback with a randomly shuffled playlist
<<playlist "bgm_lacuna" shuffle play>>
→ Start playback and fade from 0% to 100% volume
<<playlist "bgm_lacuna" volume 0 fadein>>
→ Start playback and fade from 75% to 0% volume
<<playlist "bgm_lacuna" volume 0.75 fadeout>>
→ Start playback and fade from 25% to 75% volume
<<playlist "bgm_lacuna" volume 0.25 fadeto 0.75>>
→ Start playback and fade from 25% to 75% volume over 30 seconds
<<playlist "bgm_lacuna" volume 0.25 fadeoverto 30 0.75>>
→ Pause playback
<<playlist "bgm_lacuna" pause>>
→ Stop playback
<<playlist "bgm_lacuna" stop>>
→ Mute playback, without changing the current playback state
<<playlist "bgm_lacuna" mute>>
→ Unmute playback, without changing the current playback state
<<playlist "bgm_lacuna" unmute>>
→ Change the volume to 40%, without changing the current playback state
<<playlist "bgm_lacuna" volume 0.40>>
→ Set the playlist to randomly shuffle, without changing the current playback state
<<playlist "bgm_lacuna" shuffle>>
load
unload
Warning: Be very careful with these if your audio sources are on the network, as you are forcing players to begin downloading them. Not everyone has blazing fast internet with unlimited data—especially true for mobile users. Pease, do not take your players' bandwidth and data usage lightly.
→ If they're not currently loading, drop existing data buffers and load all of the playlist's tracks
<<playlist "bgm_lacuna" load>>
→ Unload all of the playlist's tracks, dropping existing data buffers
<<playlist "bgm_lacuna" unload>>
<<removeaudiogroup groupId>>
Removes the audio group with the given ID.
Note:
You may not remove the predefined group IDs (, , , , , ) or the group modifier.
:all
:looped
:muted
:paused
:playing
:stopped
:not
v2.28.0
: Introduced.v2.37.0
: Added predefined group ID.:stopped
groupId
: The ID of the group.→ Given a group set up via <<createaudiogroup ":ui">>…<</createplaylist>>
<<removeaudiogroup ":ui">>
<<removeplaylist listId>>
Removes the playlist with the given ID.
v2.8.0
: Introduced.listId
: The ID of the playlist.→ Given a playlist set up via <<createplaylist "bgm_lacuna">>…<</createplaylist>>
<<removeplaylist "bgm_lacuna">>
<<waitforaudio>>
Displays the loading screen until all currently registered audio has either loaded to a playable state or aborted loading due to errors. Requires tracks to be set up via <<cacheaudio>>
.
Note:
This macro should be invoked once following any invocations of and , if any definitions used the keyword, for which you want the loading screen displayed.
<<cacheaudio>>
<<createplaylist>>
<<track>>
copy
v2.8.0
: Introduced.<<cacheaudio "a" "a_track.…">>
<<cacheaudio "b" "b_track.…">>
<<cacheaudio "c" "c_track.…">>
<<cacheaudio "d" "d_track.…">>
<<waitforaudio>>
→ First, register the tracks that will be needed soon
<<cacheaudio "a" "a_track.…">>
<<cacheaudio "b" "b_track.…">>
→ Next, load all currently registered tracks (meaning: "a" and "b")
<<waitforaudio>>
→ Finally, register any tracks that won't be needed until later
<<cacheaudio "c" "c_track.…">>
<<cacheaudio "d" "d_track.…">>
<<done>> … <</done>>
Silently executes its contents when the incoming passage is done rendering and has been added to the page. Generally, only really useful for running code that needs to manipulate elements from the incoming passage, since you must wait until they've been added to the page.
Tip:
If you need to run the same code on multiple passages, consider using the PassageDone
special passage or, for a JavaScript/TwineScript solution, a :passagedisplay
event instead. They serve the same basic purpose as the macro, but are run each time passage navigation occurs.
<<done>>
v2.35.0
: Introduced.v2.36.0
: Changed delay mechanism to improve waiting on the DOM.@@#spy;@@
<<done>>
<<replace "#spy">>I spy with my little eye, a crab rangoon.<</replace>>
<</done>>
<<goto passageName>>
<<goto linkMarkup>>
Immediately forwards the player to the passage with the given name. May be called either with the passage name or with a link markup.
Note:
In most cases, you will not need to use as there are often better and easier ways to forward the player. For example, a common use of <<link>>
is to perform various actions before forwarding the player to another passage. In that case, unless you need to dynamically determine the destination passage within the body, is unnecessary as already includes the ability to forward the player.
<<goto>>
<<link>>
<<goto>>
<<link>>
Warning:
Using to automatically forward players from one passage to another with no input from them will both create junk moments within the story history and make it extremely difficult for players to navigate the history. It is strongly recommended that you look into other methods to achieve your goals instead—e.g., Config.navigation.override
.
<<goto>>
Warning:
does not terminate passage rendering in the passage where it was encountered, so care must be taken to ensure that no unwanted state modifications occur after its call.
<<goto>>
v2.0.0
: Introduced.passageName
: The name of the passage to go to.linkMarkup
: The link markup to use (regular syntax only, no setters).→ Passage name form
<<goto "Somewhere over yonder">>
<<goto $selectedPassage>>
→ Link markup form
<<goto [[Somewhere over yonder]]>>
<<goto [[$selectedPassage]]>>
<<repeat delay [transition|t8n]>> … <</repeat>>
Repeatedly executes its contents after the given delay, inserting any output into the passage in its place. May be terminated by a <<stop>>
macro.
Note: Passage navigation terminates all pending timed executions.
v2.0.0
: Introduced.delay
: The amount of time to delay, as a valid CSS time value—e.g., and . The minimum delay is .5s
500ms
40ms
transition
: (optional) Keyword, used to signify that a CSS transition should be applied to the incoming insertions.t8n
: (optional) Keyword, alias for transition
.→ A countdown timer
<<set $seconds to 10>>\
Countdown: <span id="countdown">$seconds seconds remaining</span>!\
<<silent>>
<<repeat 1s>>
<<set $seconds to $seconds - 1>>
<<if $seconds gt 0>>
<<replace "#countdown">>$seconds seconds remaining<</replace>>
<<else>>
<<replace "#countdown">>Too Late<</replace>>
/* do something useful here */
<<stop>>
<</if>>
<</repeat>>
<</silent>>
<<stop>>
Used within <<repeat>>
macros. Terminates the execution of the current .<<repeat>>
v2.0.0
: Introduced.<<timed delay [transition|t8n]>> …
[<<next [delay]>> …]
<</timed>>
Executes its contents after the given delay, inserting any output into the passage in its place. Additional timed executions may be chained via .<<next>>
Note: Passage navigation terminates all pending timed executions.
v2.0.0
: Introduced.<<timed>>
delay
: The amount of time to delay, as a valid CSS time value—e.g., and . The minimum delay is .5s
500ms
40ms
transition
: (optional) Keyword, used to signify that a CSS transition should be applied to the incoming insertions.t8n
: (optional) Keyword, alias for transition
.<<next>>
delay
: (optional) The amount of time to delay, as a valid CSS time value—e.g., and . The minimum delay is . If omitted, the last delay specified, from a or the parent , will be used.5s
500ms
40ms
<<next>>
<<timed>>
→ Insert some text after 5 seconds with a transition
I want to go to…<<timed 5s t8n>> WONDERLAND!<</timed>>
→ Replace some text after 10 seconds
I like green <span id="eggs">eggs</span> and ham!\
<<timed 10s>><<replace "#eggs">>pancakes<</replace>><</timed>>
→ A execute <<goto>> after 10 seconds
<<timed 10s>><<goto "To the Moon, Alice">><</timed>>
→ Insert some text in 2 second intervals three times (at: 2s, 4s, 6s)
<<timed 2s>>Hi! Ho!
<<next>>Hi! Ho!
<<next>>It's off to work we go!
<</timed>>
→ Set a $variable after 4 seconds, 3 seconds, 2 seconds, and 1 second
<<silent>>
<<set $choice to 0>>
<<timed 4s>>
<<set $choice to 1>>
<<next 3s>>
<<set $choice to 2>>
<<next 2s>>
<<set $choice to 3>>
<<next 1s>>
<<set $choice to 4>>
<</timed>>
<</silent>>
→ Replace some text with a variable interval
→ Given: _delay is "2s" the interval will be 2 seconds
I'll have <span id="drink">some water</span>, please.\
<<timed _delay>><<replace "#drink">>a glass of milk<</replace>>\
<<next>><<replace "#drink">>a can of soda<</replace>>\
<<next>><<replace "#drink">>a cup of coffee<</replace>>\
<<next>><<replace "#drink">>tea, southern style, sweet<</replace>>\
<<next>><<replace "#drink">>a scotch, neat<</replace>>\
<<next>><<replace "#drink">>a bottle of your finest absinthe<</replace>>\
<</timed>>
<<widget widgetName [container]>> … <</widget>>
Creates a new widget macro (henceforth, widget) with the given name. Widgets allow you to create macros by using the standard macros and markup that you use normally within your story. All widgets may access arguments passed to them via the special variable. Block widgets may access the contents they enclose via the special variable._args
_contents
Warning:
Widgets should always be defined within a -tagged passage—any widgets that are not may be lost on page reload—and you may use as few or as many such passages as you desire. Do not add a tag to any of the specially named passages and attempt to define your widgets there.
widget
widget
Warning:
The array-like object stored in the variable should be treated as though it were immutable—i.e., unable to be modified—because in the future it will be made thus, so any attempt to modify it will cause an error.
_args
v2.0.0
: Introduced.v2.36.0
: Added the keyword, variable, and variable. Deprecated the variable in favor of .container
_args
_contents
$args
_args
v2.37.0
: Added the property._args.name
widgetName
: The name of the created widget, which should not contain whitespace or angle brackets (, ). If the name of an existing widget is chosen, the new widget will overwrite the older version. NOTE: The names of existing macros are invalid widget names and any attempts to use such a name will cause an error.<
>
container
: (optional) Keyword, used to signify that the widget should be created as a container widget—i.e., non-void, requiring a closing tag; e.g., .<<foo>>…<</foo>>
_args
_contents
The special variable is used internally to store arguments passed to the widget—as zero-based indices; i.e., is the first parsed argument, is the second, etc—the full argument string in raw and parsed forms—accessed via the and properties—and the widgets' name via the property._args
_args[0]
_args[1]
_args.raw
_args.full
_args.name
The special variable is used internally, by container widgets, to store the contents they enclose._contents
When a widget is called, any existing variable, and for container widgets , is stored for the duration of the call and restored after. This means that non-widget uses of these special variable are completely safe, though this does have the effect that uses external to widgets are inaccessible within them unless passed in as arguments._args
_contents
When calling one container widget directly from within another container widget, the special variable of the outer widget must not be included within the body of the call of the inner widget. Doing so will cause uncontrolled recursion. E.g.,_contents
<<widget "inner" container>>
_contents
<</widget>>
<<widget "outer" container>>
<<inner>>_contents<</inner>>
<</widget>>
<<outer>>ford<</outer>>
Warning:
Unless localized by use of the <<capture>>
macro, any story or other temporary variables used within widgets are part of a story's normal variable store, so care must be taken not to accidentally either overwrite or pick up an existing value.
Note:
No line-break control mechanisms are used in the following examples for readability. In practice, you'll probably want to use either line continuations or one of the no-break methods: Config.passages.nobr
setting, nobr
special tag, <<nobr>>
macro.
→ Creating a gender pronoun widget
<<widget "he">>
<<if $pcSex eq "male">>
he
<<elseif $pcSex eq "female">>
she
<<else>>
it
<</if>>
<</widget>>
→ Using it
"Are you sure that <<he>> can be trusted?"
→ Creating a silly print widget
<<widget "pm">>
<<if _args[0]>>
<<print _args[0]>>
<<else>>
Mum's the word!
<</if>>
<</widget>>
→ Using it
<<pm>> → Outputs: Mum's the word!
<<pm "Hi!">> → Outputs: Hi!
→ Creating a simple dialog box widget
<<widget "say" container>>
<div class="say-box">
<img class="say-image" @src="'images/' + _args[0].toLowerCase() + '.png'">
<p class="say-text">_contents</p>
</div>
<</widget>>
→ Using it
<<say "Chapel">>Tweego is a pathway to many abilities some consider to be… unnatural.<</say>>
clone(original)
→ any
Returns a deep copy of the given value.
Only primitives, generic objects, , , , , and are supported by default. Unsupported object types, either native or custom, will need to implement a method to be properly supported by the function—when called on such an object, it will defer to the local method; see the Non-generic object types (classes) guide for more information.Array
Date
Map
RegExp
Set
.clone()
clone()
Warning: Referential relationships between objects are not maintained—i.e., after cloning multiple references to an object will refer to seperate yet equivalent objects, as each reference receives its own clone of the original.
Warning: Generic objects have only their own enumerable properties copied. Non-enumerable properties and property descriptors are not duplicated. In particular, this means that getters/setters are not properly duplicated. If you need getters/setters, then you'll need to use a non-generic object/class.
v2.0.0
: Introduced.original
: () The value to clone.any
A deep copy () of the original value.any
// Without clone(); given the generic object: $foo = { id : 1 }
<<set $bar to $foo>>
<<set $bar.id to 5>>
$foo.id → Returns: 5
$bar.id → Returns: 5
// With clone(); given the generic object: $foo = { id : 1 }
<<set $bar to clone($foo)>>
<<set $bar.id to 5>>
$foo.id → Returns: 1
$bar.id → Returns: 5
either(list…)
→ any
Returns a random value from its given arguments.
v2.0.0
: Introduced.list
: () The list of values to operate on. May be any combination of singular values, actual arrays, or array-like objects. All values will be concatenated into a single list for selection. NOTE: Does not flatten nested arrays—if this is required, the <Array>.flat()
method may be used to flatten the nested arrays prior to passing them to .any
either()
A random value from its given arguments.
// Using singular values
either("Blueberry", "Cherry", "Pecan") → Returns a random pie from the whole list
// Using arrays; given: $pies = ["Blueberry", "Cherry", "Pecan"]
either($pies) → Returns a random pie from the whole array
// Using singular values and arrays; given: $letters = ["A", "B"]
either($letters, "C", "D") → Returns a random value from the whole list—i.e., "A", "B", "C", "D"
// Using multiple arrays; given: $letters = ["A", "B"] & $numerals = ["1", "2"]
either($letters, $numerals) → Returns a random value from the whole list—i.e., "A", "B", "1", "2"
forget(key)
Removes the specified key, and its associated value, from the story metadata store.
See Also:
memorize()
, recall()
.
v2.29.0
: Introduced.key
: () The key to remove.string
An or instance.Error
TypeError
<<run forget('achievements')>>
hasVisited(passages…)
→ boolean
Returns whether the passage with the given name occurred within the story history. If multiple passage names are given, returns the logical-AND aggregate of the set—i.e., if all were found, if any were not found.true
false
v2.7.0
: Introduced.passages
: ( | ) The name(s) of the passage(s) to search for. May be a list or an array of passages.string
Array<string>
Boolean if all were found, elsewise .true
false
An instance.Error
<<if hasVisited("Bar")>>…has been to the Bar…<</if>>
<<if not hasVisited("Bar")>>…has never been to the Bar…<</if>>
<<if hasVisited("Bar", "Café")>>…has been to both the Bar and Café<</if>>
<<if not hasVisited("Bar", "Café")>>…has never been to either the Bar, Café, or both…<</if>>
lastVisited(passages…)
→ integer
Returns the number of turns that have passed since the last instance of the passage with the given name occurred within the story history or if it does not exist. If multiple passage names are given, returns the lowest count (which can be ).-1
-1
v2.0.0
: Introduced.passages
: ( | ) The name(s) of the passage(s) to search for. May be a list or an array of passages.string
Array<string>
The lowest count (), elsewise .integer
-1
An instance.Error
<<if lastVisited("Bar") is -1>>…has never been to the Bar…<</if>>
<<if lastVisited("Bar") is 0>>…is currently in the Bar…<</if>>
<<if lastVisited("Bar") is 1>>…was in the Bar one turn ago…<</if>>
<<if lastVisited("Bar", "Café") is -1>>…has never been to the Bar, Café, or both…<</if>>
<<if lastVisited("Bar", "Café") is 2>>…has been to both the Bar and Café, most recently two turns ago…<</if>>
importScripts(urls…)
→ Promise
Load and integrate external JavaScript scripts.
Note:
Loading is done asynchronously at run time, so if the script must be available within a tight time frame, then you should use the returned by the function to ensure that the script is loaded before it is needed.
Promise
Note:
Your project's JavaScript section (Twine 2: the Story JavaScript; Twine 1/Twee: a -tagged passage) is normally the best place to call .
script
importScripts()
v2.16.0
: Introduced.v2.37.0
: Added the ability to load JS Modules.urls
: ( | | ) The URLs of the external scripts to import. Loose URLs are imported concurrently, arrays of URLs are imported sequentially. URLs may also be specified as objects with a and a property.string
object
Array<string | object>
type
src
Note:
URLs ending in are imported as modules.
.mjs
A that simply resolves, or rejects with an error if the script could not be loaded.Promise
An instance.Error
// Import scripts a.js as normal, b.mjs as a module, and c.js as a
// module
importScripts(
"https://somesite/a/path/a.js",
"https://somesite/a/path/b.mjs",
{
type : "module",
src : "https://somesite/a/path/c.js"
}
);
// Import all scripts concurrently
importScripts(
"https://somesite/a/path/a.js",
"https://somesite/a/path/b.js",
"https://somesite/a/path/c.js",
"https://somesite/a/path/d.js"
);
// Import all scripts sequentially
importScripts([
"https://somesite/a/path/a.js",
"https://somesite/a/path/b.js",
"https://somesite/a/path/c.js",
"https://somesite/a/path/d.js"
]);
// Import scripts a.js, b.js, and the c.js/d.js group concurrently,
// while importing c.js and d.js sequentially relative to each other
importScripts(
"https://somesite/a/path/a.js",
"https://somesite/a/path/b.js",
[
"https://somesite/a/path/c.js",
"https://somesite/a/path/d.js"
]
);
Promise
// Import a script while using the returned Promise to ensure that
// the script has been fully loaded before executing dependent code
importScripts("https://somesite/a/path/a.js")
.then(function () {
// Code that depends on the script goes here
})
.catch(function (err) {
// There was an error loading the script, log it to the console
console.log(err);
});
Promise
// Import a script while saving the returned Promise so it may be used later
setup.aScriptImport = importScripts("https://somesite/a/path/aScript.js");
// Use the returned Promise later on to ensure that the script has been fully
// loaded before executing dependent code
setup.aScriptImport
.then(function () {
// Code that depends on the script goes here
})
.catch(function (err) {
// There was an error loading the script, log it to the console
console.log(err);
});
importStyles(urls…)
→ Promise
Load and integrate external CSS stylesheets.
Note:
Loading is done asynchronously at run time, so if the stylesheet must be available within a tight time frame, then you should use the returned by the function to ensure that the stylesheet is loaded before it is needed.
Promise
Note:
Your project's JavaScript section (Twine 2: the Story JavaScript; Twine 1/Twee: a -tagged passage) is normally the best place to call .
script
importStyles()
v2.16.0
: Introduced.urls
: ( | ) The URLs of the external stylesheets to import. Loose URLs are imported concurrently, arrays of URLs are imported sequentially.string
Array<string>
A that simply resolves, or rejects with an error if the style could not be loaded.Promise
An instance.Error
// Import all stylesheets concurrently
importStyles(
"https://somesite/a/path/a.css",
"https://somesite/a/path/b.css",
"https://somesite/a/path/c.css",
"https://somesite/a/path/d.css"
);
// Import all stylesheets sequentially
importStyles([
"https://somesite/a/path/a.css",
"https://somesite/a/path/b.css",
"https://somesite/a/path/c.css",
"https://somesite/a/path/d.css"
]);
// Import stylesheets a.css, b.css, and the c.css/d.css group concurrently,
// while importing c.css and d.css sequentially relative to each other
importStyles(
"https://somesite/a/path/a.css",
"https://somesite/a/path/b.css",
[
"https://somesite/a/path/c.css",
"https://somesite/a/path/d.css"
]
);
Promise
// Grab a loading screen lock
var lsLockId = LoadScreen.lock();
// Import a stylesheet while using the returned Promise to ensure that the
// stylesheet has been fully loaded before unlocking the loading screen
importStyles("https://somesite/a/path/a.css")
.then(function () {
// The stylesheet has been loaded, release the loading screen lock
LoadScreen.unlock(lsLockId);
})
.catch(function (err) {
// There was an error loading the stylesheet, log it to the console
console.log(err);
});
memorize(key, value)
Sets the specified key and value within the story metadata store, which causes them to persist over story and browser restarts. To update the value associated with a key, simply set it again.
Note: The story metadata, like saves, is tied to the specific story it was generated with. It is not a mechanism for moving data between stories.
Warning: The story metadata store is not, and should not be used as, a replacement for saves. Examples of good uses: achievement tracking, new game+ data, playthrough statistics, etc.
Warning: This feature is largely incompatible with private browsing modes, which cause all in-browser storage mechanisms to either persist only for the lifetime of the browsing session or fail outright.
v2.29.0
: Introduced.key
: () The key that should be set.string
value
: () The value to set.any
An instance.TypeError
// Sets 'achievements', with the given value, in the metadata store.
<<run memorize('achievements', { ateYellowSnow : true })>>
// Sets 'ngplus', with the given value, in the metadata store.
<<run memorize('ngplus', true)>>
passage()
→ string
Returns the name of the active (present) passage.
v2.0.0
: Introduced.The name () of the passage.string
<<if passage() is "Café">>…the active passage is the Café passage…<</if>>
previous()
→ string
Returns the name of the most recent previous passage whose name does not match that of the active passage or an empty string, if there is no such passage.
v2.0.0
: Introduced.The name () of the passage, elsewise an empty string ().string
''
<<if previous() is "Café">>…the most recent non-active passage is the Café passage…<</if>>
→ Commonly used as part of a link to return to the most recent non-active passage
[[Return|previous()]]
random([min ,] max)
→ integer
Returns a pseudo-random whole number (integer) within the range of the given bounds (inclusive)—i.e., [min, max].
Note:
By default, it uses Math.random()
as its source of (non-deterministic) randomness, however, when the seedable PRNG has been enabled, via State.prng.init()
, it uses that (deterministic) seeded PRNG instead.
v2.0.0
: Introduced.min
: (optional, ) The lower bound of the random number (inclusive). If omitted, will default to .integer
0
max
: () The upper bound of the random number (inclusive).integer
A random whole number ().integer
An or instance.Error
TypeError
random(5) → Returns a number in the range 0–5
random(1, 6) → Returns a number in the range 1–6
randomFloat([min ,] max)
→ decimal
Returns a pseudo-random decimal number (floating-point) within the range of the given bounds (inclusive for the minimum, exclusive for the maximum)—i.e., [min, max).
Note:
By default, it simply returns non-deterministic results from Math.random()
, however, when the seedable PRNG has been enabled, via State.prng.init()
, it returns deterministic results from the seeded PRNG instead.
v2.0.0
: Introduced.min
: (optional, ) The lower bound of the random number (inclusive). If omitted, will default to .decimal
0.0
max
: () The upper bound of the random number (exclusive).decimal
A random floating-point number ().decimal
An or instance.Error
TypeError
randomFloat(5.0) → Returns a number in the range 0.0–4.9999999…
randomFloat(1.0, 6.0) → Returns a number in the range 1.0–5.9999999…
recall(key [, defaultValue])
→ any
Returns the value associated with the specified key from the story metadata store or, if no such key exists, the specified default value, if any.
See Also:
forget()
, memorize()
.
v2.29.0
: Introduced.key
: () The key whose value should be returned.string
defaultValue
: (optional, ) The value to return if the key doesn't exist.any
A value () from the specified key, elsewise the default value if specified.any
A instance.TypeError
// Set setup.achievements to the 'achievements' metadata or an empty generic object.
<<set setup.achievements to recall('achievements', {})>>
// Set setup.ngplus to the 'ngplus' metadata, with no default.
<<set setup.ngplus to recall('ngplus')>>
setPageElement(idOrElement , passages [, defaultText])
→ | HTMLElement
null
Renders the selected passage into the target element, replacing any existing content, and returns the element. If no passages are found and default text is specified, it will be used instead.
v2.0.0
: Introduced.idOrElement
: ( | ) The ID of the element or the element itself.string
HTMLElement
passages
: ( | ) The name(s) of the passage(s) to search for. May be a single passage or an array of passages. If an array of passage names is specified, the first passage to be found is used.string
Array<string>
defaultText
: (optional, ) The default text to use if no passages are found.string
An , elsewise .HTMLElement
null
Note: As it is highly unlikely that either an array of passage names or default text will be needed in the vast majority of cases, only a few basic examples will be given.
// Using an ID; given an existing element on the page: <div id="my-display"></div>
setPageElement("my-display", "MyPassage");
// Using an element; given a reference to an existing element: myElement
setPageElement(myElement, "MyPassage");
tags([passages…])
→ Array<string>
Returns a new array consisting of all of the tags of the given passages.
v2.0.0
: Introduced.passages
: (optional, | ) The passages from which to collect tags. May be a list or an array of passages. If omitted, will default to the active (present) passage—included passages do not count for this purpose; e.g., passages pulled in via , , etc.string
Array<string>
<<include>>
PassageHeader
The tags ().Array<string>
<<if tags().includes("forest")>>…the active passage is part of the forest…<</if>>
<<if tags("Lonely Glade").includes("forest")>>…the Lonely Glade passage is part of the forest…<</if>>
temporary()
→ object
Returns a reference to the current temporary variables store (equivalent to: State.temporary
). This is only really useful within pure JavaScript code, as within TwineScript you may simply access temporary variables natively.
v2.19.0
: Introduced.A reference to the temporary variable store ().object
// Given: _selection is 'Zagnut Bar'
if (temporary().selection === 'Zagnut Bar') {
/* Do something… */
}
time()
→ integer
Returns the number of milliseconds that have passed since the current passage was rendered to the page.
v2.0.0
: Introduced.The number of milliseconds () since the passage was rendered.integer
→ Links that vary based on the time
In the darkness, something wicked this way comes. Quickly! Do you \
<<link "try to run back into the light">>
<<if time() lt 5000>>
/% The player clicked the link in under 5s, so they escape %/
<<goto "Well lit passageway">>
<<else>>
/% Else, they're eaten by a grue %/
<<goto "Eaten by a grue">>
<</if>>
<</link>> \
or [[stand your ground|Eaten by a grue]]?
triggerEvent(name [, targets [, options]])
Dispatches a synthetic event with the given name, optionally on the given targets and with the given options.
v2.37.0
: Introduced.Tip: If dispatching custom events, it is recommended that you limit your custom event names to the following characters: letters, digits, periods (), hyphens (), underscores (), and colons (). .-_:
name
: () The name of the event to trigger. Both native and custom events are supported.string
targets
: (optional, | | | | ) The target(s) to trigger the event on. If omitted, will default to .Document
HTMLElement
jQuery
NodeList
Array<HTMLElement>
document
options
: (optional, ) The options to be used when dispatching the event. See below for details.object
Warning:
Adding additional properties directly to event options objects is not recommended. Instead, use the property.
detail
An event options object should have some of the following properties:
bubbles
: (optional, ) Whether the event bubbles (default: ).boolean
true
cancelable
: (optional, ) Whether the event is cancelable (default: ).boolean
true
composed
: (optional, ) Whether the event triggers listeners outside of a shadow root (default: ).boolean
false
detail
: (optional, ) Custom data sent with the event (default: ). Although any type is allowable, an object is often the most practical.any
undefined
fnord
document
triggerEvent('fnord');
click
some-menu
triggerEvent('click', document.getElementById('some-menu'));
update-meter
document
triggerEvent('update-meter', document, {
detail : {
tags : ['health', 'magick']
}
});
mouseover
flippable
triggerEvent('mouseover', document.getElementsByClassName('flippable'));
triggerEvent('mouseover', document.querySelectorAll('.flippable'));
triggerEvent('mouseover', jQuery('.flippable'));
turns()
→ integer
Returns the total number (count) of played turns currently in effect—i.e., the number of played moments up to the present moment; future (rewound/undone) moments are not included within the total.
v2.0.0
: Introduced.The turn count ().integer
<<print "This is turn #" + turns()>>
variables()
→ object
Returns a reference to the active (present) story variables store (equivalent to: State.variables
). This is only really useful within pure JavaScript code, as within TwineScript you may simply access story variables natively.
v2.0.0
: Introduced.A reference to the story variable store ().object
// Given: $hasGoldenKey is true
if (variables().hasGoldenKey) {
/* Do something… */
}
visited([passages…])
→ integer
Returns the number of times that the passage with the given title occurred within the story history. If multiple passage titles are given, returns the lowest count.
v2.0.0
: Introduced.passages
: (optional, | ) The title(s) of the passage(s) to search for. May be a list or an array of passages. If omitted, will default to the current passage.string
Array<string>
The passage count ().integer
<<if visited() is 3>>…this is the third visit to the current passage…<</if>>
<<if visited("Bar")>>…has been to the Bar at least once…<</if>>
<<if visited("Café") is 1>>…has been to the Café exactly once…<</if>>
<<if visited("Bar", "Café") is 4>>…has been to both the Bar and Café at least four times…<</if>>
visitedTags(tags…)
→ integer
Returns the number of passages within the story history that are tagged with all of the given tags.
v2.0.0
: Introduced.tags
: ( | ) The tags to search for. May be a list or an array of tags.string
Array<string>
The number () of passages that are tagged with the given tags.integer
An instance.Error
<<if visitedTags("forest")>>…has been to some part of the forest at least once…<</if>>
<<if visitedTags("forest", "haunted") is 1>>…has been to the haunted part of the forest exactly once…<</if>>
<<if visitedTags("forest", "burned") is 3>>…has been to the burned part of the forest three times…<</if>>
Most of the methods listed below are SugarCube extensions, with the rest being either JavaScript natives or bundled library methods that are listed here for their utility—though, this is not an exhaustive list.
For more information see:
Additionally. SugarCube includes polyfills for virtually all JavaScript (ECMAScript) 5 & 6 native object methods—via the es5-shim and es6-shim polyfill libraries (shims only, no shams)—so they may be safely used even if your project will be played in ancient browsers that do not natively support them.
<Array>.concat(members…)
→ Array<any> Concatenates one or more members to the end of the base array and returns the result as a new array. Does not modify the original.
members
: (any…) The members to concatenate. Members that are arrays will be merged—i.e., their members will be concatenated, rather than the array itself.// Given: $fruits1 = ["Apples", "Oranges"], $fruits2 = ["Pears", "Plums"]
$fruits1.concat($fruits2) → Returns ["Apples", "Oranges", "Pears", "Plums"]
$fruits1.concat($fruits2, $fruits2) → Returns ["Apples", "Oranges", "Pears", "Plums", "Pears", "Plums"]
$fruits1.concat("Pears") → Returns ["Apples", "Oranges", "Pears"]
$fruits1.concat("Pears", "Pears") → Returns ["Apples", "Oranges", "Pears", "Pears"]
$fruits1.concat($fruits2, "Pears") → Returns ["Apples", "Oranges", "Pears", "Plums", "Pears"]
<Array>.concatUnique(members…)
→ Array<any> Concatenates one or more unique members to the end of the base array and returns the result as a new array. Does not modify the original.
v2.21.0
: Introduced.members
: (any…) The members to concatenate. Members that are arrays will be merged—i.e., their members will be concatenated, rather than the array itself.// Given: $fruits1 = ["Apples", "Oranges"], $fruits2 = ["Pears", "Plums"]
$fruits1.concatUnique($fruits2) → Returns ["Apples", "Oranges", "Pears", "Plums"]
$fruits1.concatUnique($fruits2, $fruits2) → Returns ["Apples", "Oranges", "Pears", "Plums"]
$fruits1.concatUnique("Pears") → Returns ["Apples", "Oranges", "Pears"]
$fruits1.concatUnique("Pears", "Pears") → Returns ["Apples", "Oranges", "Pears"]
$fruits1.concatUnique($fruits2, "Pears") → Returns ["Apples", "Oranges", "Pears", "Plums"]
<Array>.count(needle [, position])
→ integer Returns the number of times that the given member was found within the array, starting the search at .position
v2.0.0
: Introduced.needle
: (any) The member to count.position
: (optional, integer) The zero-based index at which to begin searching for . If omitted, will default to .needle
0
// Given: $fruits = ["Apples", "Oranges", "Plums", "Oranges"]
$fruits.count("Oranges") → Returns 2
$fruits.count("Oranges", 2) → Returns 1
<Array>.countWith(predicate [, thisArg])
→ integer Returns the number of times that members within the array pass the test implemented by the given predicate function.
v2.36.0
: Introduced.predicate
: (function) The function used to test each member. It is called with three arguments:
value
: (any) The member being processed.index
: (optional, integer) The index of member being processed.array
: (optional, array) The array being processed.thisArg
: (optional, any) The value to use as when executing .this
predicate
// Given: $fruits = ["Apples", "Oranges", "Plums", "Oranges"]
$fruits.countWith(function (fruit) { return fruit === "Oranges"; }) → Returns 2
// Given: $numbers = [1, 2.3, 4, 76, 3.1]
$numbers.countWith(Number.isInteger) → Returns 3
// Given: $items = [
// { name : 'Healing potion', kind : 'potion' },
// { name : 'Longsword', kind : 'weapon' },
// { name : 'Mana potion', kind : 'potion' },
// { name : 'Dead rat', kind : 'junk' },
// { name : 'Endurance potion', kind : 'potion' },
// { name : 'Shortbow', kind : 'weapon' }
// ]
$items.countWith(function (item) { return item.kind === 'junk'; }) → Returns 1
<Array>.deleteAll(needles…)
→ Array<any> Removes all instances of the given members from the array and returns a new array containing the removed members.
v2.37.0
: Introduced.needles
: (any… | Array<any>) The members to remove. May be a list of members or an array.// Given: $fruits = ["Apples", "Oranges", "Plums", "Oranges"]
$fruits.deleteAll("Oranges") → Returns ["Oranges", "Oranges"]; $fruits ["Apples", "Plums"]
$fruits.deleteAll("Apples", "Plums") → Returns ["Apples", "Plums"]; $fruits ["Oranges", "Oranges"]
<Array>.deleteAt(indices…)
→ Array<any> Removes all of the members at the given indices from the array and returns a new array containing the removed members.
v2.5.0
: Introduced.indices
: (integer… | Array<integer>) The indices of the members to remove. May be a list or array of indices.// Given: $fruits = ["Apples", "Oranges", "Plums", "Oranges"]
$fruits.deleteAt(2) → Returns ["Plums"]; $fruits ["Apples", "Oranges", "Oranges"]
$fruits.deleteAt(1, 3) → Returns ["Oranges", "Oranges"]; $fruits ["Apples", "Plums"]
$fruits.deleteAt(0, 2) → Returns ["Apples", "Plums"]; $fruits ["Oranges", "Oranges"]
<Array>.deleteFirst(needles…)
→ Array<any> Removes the first instance of the given members from the array and returns a new array containing the removed members.
v2.37.0
: Introduced.needles
: (any… | Array<any>) The members to remove. May be a list of members or an array.// Given: $fruits = ["Apples", "Oranges", "Plums", "Oranges"]
$fruits.deleteFirst("Oranges") → Returns ["Oranges"]; $fruits ["Apples", "Plums", "Oranges"]
$fruits.deleteFirst("Apples", "Plums") → Returns ["Apples", "Plums"]; $fruits ["Oranges", "Oranges"]
<Array>.deleteLast(needles…)
→ Array<any> Removes the last instance of the given members from the array and returns a new array containing the removed members.
v2.37.0
: Introduced.needles
: (any… | Array<any>) The members to remove. May be a list of members or an array.// Given: $fruits = ["Apples", "Oranges", "Plums", "Oranges"]
$fruits.deleteLast("Oranges") → Returns ["Oranges"]; $fruits ["Apples", "Oranges", "Plums"]
$fruits.deleteLast("Apples", "Plums") → Returns ["Apples", "Plums"]; $fruits ["Oranges", "Oranges"]
<Array>.deleteWith(predicate [, thisArg])
→ Array<any> Removes all of the members from the array that pass the test implemented by the given predicate function and returns a new array containing the removed members.
v2.25.0
: Introduced.predicate
: (function) The function used to test each member. It is called with three arguments:
value
: (any) The member being processed.index
: (optional, integer) The index of member being processed.array
: (optional, array) The array being processed.thisArg
: (optional, any) The value to use as when executing .this
predicate
// Given: $fruits = ["Apples", "Apricots", "Oranges"]
→ Returns ["Apricots"]; $fruits ["Apples", "Oranges"]
$fruits.deleteWith(function (val) {
return val === "Apricots";
})
→ Returns ["Apples", "Apricots"]; $fruits ["Oranges"]
$fruits.deleteWith(function (val) {
return val.startsWith("Ap");
})
// Given: $fruits = [{ name : "Apples" }, { name : "Apricots" }, { name : "Oranges" }]
→ Returns [{ name : "Apricots" }]; $fruits [{ name : "Apples" }, { name : "Oranges" }]
$fruits.deleteWith(function (val) {
return val.name === "Apricots";
})
→ Returns [{ name : "Apples" }, { name : "Apricots" }]; $fruits [{ name : "Oranges" }]
$fruits.deleteWith(function (val) {
return val.name.startsWith("Ap");
})
<Array>.first()
→ any Returns the first member from the array. Does not modify the original.
v2.27.0
: Introduced.// Given: $pies = ["Blueberry", "Cherry", "Cream", "Pecan", "Pumpkin"]
$pies.first() → Returns "Blueberry"
<Array>.flat(depth)
→ Array<any> Returns a new array consisting of the source array with all sub-array elements concatenated into it recursively up to the given depth. Does not modify the original.
depth
: (optional, integer) The number of nested array levels should be flattened. If omitted, will default to .1
// Given: $npa = [["Alfa", "Bravo"], [["Charlie", "Delta"], ["Echo"]], "Foxtrot"]
$npa.flat() → Returns ["Alfa", "Bravo", ["Charlie", "Delta"], ["Echo"], "Foxtrot"]
$npa.flat(1) → Returns ["Alfa", "Bravo", ["Charlie", "Delta"], ["Echo"], "Foxtrot"]
$npa.flat(2) → Returns ["Alfa", "Bravo", "Charlie", "Delta", "Echo", "Foxtrot"]
<Array>.flatMap(callback [, thisArg])
→ Array<any> Returns a new array consisting of the result of calling the given mapping function on every element in the source array and then concatenating all sub-array elements into it recursively up to a depth of . Does not modify the original.1
Note:
Identical to calling .
<Array>.map(…).flat()
callback
: (function) The function used to produce members of the new array. It is called with three arguments:
value
: (any) The member being processed.index
: (optional, integer) The index of member being processed.array
: (optional, array) The array being processed.thisArg
: (optional, any) The value to use as when executing .this
callback
// Given: $npa = ["Alfa", "Bravo Charlie", "Delta Echo Foxtrot"]
→ Returns ["Alfa", "Bravo", "Charlie", "Delta", "Echo", "Foxtrot"]
$npa.flatMap(function (val) {
return val.split(" ");
})
<Array>.includes(needle [, position])
→ boolean Returns whether the given member was found within the array, starting the search at .position
needle
: (any) The member to find.position
: (optional, integer) The zero-based index at which to begin searching for . If omitted, will default to .needle
0
// Given: $pies = ["Blueberry", "Cherry", "Cream", "Pecan", "Pumpkin"]
<<if $pies.includes("Cherry")>>…found Cherry pie…<</if>>
<<if $pies.includes("Pecan", 3)>>…found Pecan pie within ["Pecan", "Pumpkin"]…<</if>>
<Array>.includesAll(needles…)
→ boolean Returns whether all of the given members were found within the array.
v2.10.0
: Introduced.needles
: (any… | Array<any>) The members to find. May be a list of members or an array.// Given: $pies = ["Blueberry", "Cherry", "Cream", "Pecan", "Pumpkin"]
<<if $pies.includesAll("Cherry", "Pecan")>>…found Cherry and Pecan pies…<</if>>
// Given: $search = ["Blueberry", "Pumpkin"]
<<if $pies.includesAll($search)>>…found Blueberry and Pumpkin pies…<</if>>
<Array>.includesAny(needles…)
→ boolean Returns whether any of the given members were found within the array.
v2.10.0
: Introduced.needles
: (any… | Array<any>) The members to find. May be a list of members or an array.// Given: $pies = ["Blueberry", "Cherry", "Cream", "Pecan", "Pumpkin"]
<<if $pies.includesAny("Cherry", "Pecan")>>…found Cherry or Pecan pie…<</if>>
// Given: $search = ["Blueberry", "Pumpkin"]
<<if $pies.includesAny($search)>>…found Blueberry or Pumpkin pie…<</if>>
<Array>.last()
→ any Returns the last member from the array. Does not modify the original.
v2.27.0
: Introduced.// Given: $pies = ["Blueberry", "Cherry", "Cream", "Pecan", "Pumpkin"]
$pies.last() → Returns "Pumpkin"
<Array>.pluck()
→ any Removes and returns a random member from the base array.
v2.0.0
: Introduced.// Given: $pies = ["Blueberry", "Cherry", "Cream", "Pecan", "Pumpkin"]
$pies.pluck() → Removes and returns a random pie from the array
<Array>.pluckMany(want)
→ Array<any> Randomly removes the given number of members from the base array and returns the removed members as a new array.
v2.20.0
: Introduced.want
: (integer) The number of members to pluck. Cannot pluck more members than the base array contains.// Given: $pies = ["Blueberry", "Cherry", "Cream", "Pecan", "Pumpkin"]
$pies.pluckMany(3) → Removes three random pies from the array and returns them as a new array
<Array>.pop()
→ any Removes and returns the last member from the array, or if the array is empty.undefined
// Given: $fruits = ["Apples", "Oranges", "Pears"]
$fruits.pop() → Returns "Pears"; $fruits ["Apples", "Oranges"]
<Array>.push(members…)
→ number Appends one or more members to the end of the base array and returns its new length.
members
: (any…) The members to append.// Given: $fruits = ["Apples", "Oranges"]
$fruits.push("Apples") → Returns 3; $fruits ["Apples", "Oranges", "Apples"]
// Given: $fruits = ["Apples", "Oranges"]
$fruits.push("Plums", "Plums") → Returns 4; $fruits ["Apples", "Oranges", "Plums", "Plums"]
<Array>.pushUnique(members…)
→ number Appends one or more unique members to the end of the base array and returns its new length.
v2.21.0
: Introduced.members
: (any…) The members to append.// Given: $fruits = ["Apples", "Oranges"]
$fruits.pushUnique("Apples") → Returns 2; $fruits ["Apples", "Oranges"]
// Given: $fruits = ["Apples", "Oranges"]
$fruits.pushUnique("Plums", "Plums") → Returns 3; $fruits ["Apples", "Oranges", "Plums"]
<Array>.random()
→ any Returns a random member from the base array. Does not modify the original.
v2.0.0
: Introduced.// Given: $pies = ["Blueberry", "Cherry", "Cream", "Pecan", "Pumpkin"]
$pies.random() → Returns a random pie from the array
<Array>.randomMany(want)
→ Array<any> Randomly selects the given number of unique members from the base array and returns the selected members as a new array. Does not modify the original.
v2.20.0
: Introduced.want
: (integer) The number of members to select. Cannot select more members than the base array contains.// Given: $pies = ["Blueberry", "Cherry", "Cream", "Pecan", "Pumpkin"]
$pies.randomMany(3) → Returns a new array containing three unique random pies from the array
<Array>.shift()
→ any Removes and returns the first member from the array, or if the array is empty.undefined
// Given: $fruits = ["Apples", "Oranges", "Pears"]
$fruits.shift() → Returns "Apples"; $fruits ["Oranges", "Pears"]
<Array>.shuffle()
→ Array<any> Randomly shuffles the array.
v2.0.0
: Introduced.// Given: $pies = ["Blueberry", "Cherry", "Cream", "Pecan", "Pumpkin"]
$pies.shuffle() → Randomizes the order of the pies in the array
<Array>.toShuffled()
→ Array<any> Returns a new copy of the base array created by shuffling the array. Does not modify the original.
v2.37.0
: Introduced.// Given: $pies = ["Blueberry", "Cherry", "Cream", "Pecan", "Pumpkin"]
$pies.toShuffled() → Randomizes the order of the pies in the array w/o modifying the original
<Array>.toUnique()
→ Array<any> Returns a new copy of the base array created by removing all duplicate members. Does not modify the original.
v2.37.0
: Introduced.// Given: $fruits = ["Apples", "Oranges", "Plums", "Plums", "Apples"]
$fruits.toUnique() → Returns ["Apples", "Oranges", "Plums"]
<Array>.unshift(members…)
→ number Prepends one or more members to the beginning of the base array and returns its new length.
members
: (any…) The members to append.// Given: $fruits = ["Oranges", "Plums"]
$fruits.unshift("Oranges") → Returns 3; $fruits ["Oranges", "Oranges", "Plums"]
// Given: $fruits = ["Oranges", "Plums"]
$fruits.unshift("Apples", "Apples") → Returns 4; $fruits ["Apples", "Apples", "Oranges", "Plums"]
<Array>.unshiftUnique(members…)
→ number Prepends one or more unique members to the beginning of the base array and returns its new length.
v2.21.0
: Introduced.members
: (any…) The members to append.// Given: $fruits = ["Oranges", "Plums"]
$fruits.unshiftUnique("Oranges") → Returns 2; $fruits ["Oranges", "Plums"]
// Given: $fruits = ["Oranges", "Plums"]
$fruits.unshiftUnique("Apples", "Apples") → Returns 3; $fruits ["Apples", "Oranges", "Plums"]
<Array>.delete(needles…)
→ Array<any> Deprecated:
This instance method has been deprecated and should no longer be used. See the <Array>.deleteAll()
instance method.
v2.5.0
: Introduced.v2.37.0
: Deprecated in favor of .<Array>.deleteAll()
<jQuery>.ariaClick([options ,] handler)
→ jQuery
object Makes the target element(s) WAI-ARIA-compatible clickables—meaning that various accessibility attributes are set and, in addition to mouse clicks, enter/return and spacebar key presses also activate them. Returns a reference to the current object for chaining.jQuery
v2.0.0
: Introduced.v2.37.0
: Add option.tabindex
options
: (optional, object) The options to be used when creating the clickables. See below for details.handler
: (function) The callback to invoke when the target element(s) are activated.An options object should have some of the following properties:
namespace
: (string) A period-separated list of event namespaces.one
: (boolean) Whether the clickables are single-use—i.e., the handler callback runs only once and then removes itself. If omitted, defaults to .false
selector
: (string) A selector applied to the target element(s) to filter the descendants that triggered the event. If omitted or , the event is always handled when it reaches the target element(s).null
data
: (any) Data to be passed to the handler in event.data
when an event is triggered.tabindex
: (integer) Value for the attribute. If omitted, defaults to .tabindex
0
controls
: (string) Value for the attribute.aria-controls
pressed
: (string) Value for the attribute (valid values: , ).aria-pressed
"true"
"false"
label
: (string) Value for the and attributes.aria-label
title
// Given an existing element: <a id="so-clicky">Click me</a>
$('#so-clicky').ariaClick(function (event) {
/* do stuff */
});
// Creates a basic link and appends it to the `output` element
$('<a>Click me</a>')
.ariaClick(function (event) {
/* do stuff */
})
.appendTo(output);
// Creates a basic button and appends it to the `output` element
$('<button>Click me</button>')
.ariaClick(function (event) {
/* do stuff */
})
.appendTo(output);
// Creates a link with options and appends it to the `output` element
$('<a>Click me</a>')
.ariaClick({
one : true,
label : 'This single-use link does stuff.'
}, function (event) {
/* do stuff */
})
.appendTo(output);
<jQuery>.ariaDisabled(state)
→ jQuery
object Changes the disabled state of the target WAI-ARIA-compatible clickable element(s). Returns a reference to the current object for chaining.jQuery
Note:
This method is meant to work with clickables created via <jQuery>.ariaClick()
and may not work with clickables from other sources. SugarCube uses internally to handle all of its various link markup and macros.
<jQuery>.ariaClick()
v2.26.0
: Introduced.state
: (boolean) The disabled state to apply. Truthy to disable the element(s), falsy to enable them.// Given an existing WAI-ARIA-compatible clickable element with the ID "so-clicky"
$('#so-clicky').ariaDisabled(true) → Disables the target element
$('#so-clicky').ariaDisabled(false) → Enables the target element
<jQuery>.ariaIsDisabled()
→ boolean
Returns whether any of the target WAI-ARIA-compatible clickable element(s) are disabled.
Note:
This method is meant to work with clickables created via <jQuery>.ariaClick()
and may not work with clickables from other sources. SugarCube uses internally to handle all of its various link markup and macros.
<jQuery>.ariaClick()
v2.26.0
: Introduced.// Given an existing WAI-ARIA-compatible clickable element with the ID "so-clicky"
// If "#so-clicky" is disabled:
$('#so-clicky').ariaIsDisabled() → Returns true
// If "#so-clicky" is enabled:
$('#so-clicky').ariaIsDisabled() → Returns false
jQuery.wiki(sources…)
Wikifies the given content source(s) and discards the result. If there were errors, an exception is thrown. This is only really useful when you want to invoke a macro for its side-effects and aren't interested in its output.
v2.17.0
: Introduced.sources
: (string…) The list of content sources.$.wiki('<<somemacro>>'); → Invokes the <<somemacro>> macro, discarding any output
jQuery.wikiPassage(name)
Wikifies the passage by the given name and discards the result. If there were errors, an exception is thrown. This is only really useful when you want to invoke a macro for its side-effects and aren't interested in its output.
v2.37.0
: Introduced.name
: (string) The name of the passage.$.wikiPassage('Fight Init'); → Renders the passage, discarding any output
<jQuery>.wiki(sources…)
→ jQuery
object Wikifies the given content source(s) and appends the result to the target element(s). Returns a reference to the current object for chaining.jQuery
v2.0.0
: Introduced.sources
: (string…) The list of content sources.// Given an element: <div id="the-box"></div>
$('#the-box').wiki('Who //are// you?'); → Appends "Who <em>are</em> you?" to the target element
<jQuery>.wikiPassage(name)
→ jQuery
object Wikifies the passage by the given name and appends the result to the target element(s). Returns a reference to the current object for chaining.jQuery
v2.37.0
: Introduced.name
: (string) The name of the passage.// Given an element: <div id="notebook"></div>
$('#notebook').wikiPassage('Notes'); → Appends the rendered passage to the target element
JSON.reviveWrapper(code [, data])
→ array Deprecated:
This static method has been deprecated and should no longer be used. See the Serial.createReviver()
static method.
v2.0.0
: Introduced.v2.9.0
: Added parameter.data
v2.37.0
: Deprecated in favor of .Serial.createReviver()
Math.clamp(num , min , max)
→ number Returns the given number clamped to the specified bounds. Does not modify the original.
v2.0.0
: Introduced.num
: (number) The number to clamp. May be an actual number or a numerical string.min
: (number) The lower bound of the number.max
: (number) The upper bound of the number.Math.clamp($stat, 0, 200) → Clamps $stat to the bounds 0–200 and returns the new value
Math.clamp($stat, 1, 6.6) → Clamps $stat to the bounds 1–6.6 and returns the new value
Math.trunc(num)
→ integer Returns the whole (integer) part of the given number by removing its fractional part, if any. Does not modify the original.
num
: (number) The number to truncate to an integer.Math.trunc(12.7) → Returns 12
Math.trunc(-12.7) → Returns -12
<Number>.clamp(min , max)
→ number Deprecated:
This static method has been deprecated and should no longer be used. See the Math.clamp()
static method.
v2.0.0
: Introduced.v2.37.0
: Deprecated.RegExp.escape(text)
→ string Returns the given string with all regular expression metacharacters escaped. Does not modify the original.
v2.0.0
: Introduced.text
: (string) The string to escape.RegExp.escape('That will be $5 (cash only)') → Returns 'That will be \$5 \(cash only\)'
Serial
Methods Serial.createReviver(code [, data])
→ ArrayReturns the given code string, and optional data, wrapped within the deserialization reviver. Intended to allow authors to easily create the reviver required to revive their custom object types (classes). The reviver should be returned from an object instance's method, so that the instance may be properly revived upon deserialization..toJSON()
See: The Non-generic object types (classes) guide for more detailed information.
v2.37.0
: Introduced.code
: (string) The revival code string.data
: (optional, any) The data that should be made available to the evaluated revival code during deserialization via the special variable. WARNING: Attempting to pass the value of an object instance's directly as the parameter will trigger out of control recursion in the serializer, so a clone of the instance's own data must be passed instead.$ReviveData$
this
reviveData
Serial.createReviver( /* valid JavaScript code string */ ); → Without data chunk
Serial.createReviver( /* valid JavaScript code string */ , myOwnData); → With data chunk
// E.g., Assume that you're attempting to revive an instance of a custom class named
// `Character`, which is assigned to a story variable named `$pc`. The call
// to `Serial.createReviver()` might look something like the following.
var ownData = {};
Object.keys(this).forEach(function (pn) { ownData[pn] = clone(this[pn]); }, this);
return Serial.createReviver('new Character($ReviveData$)', ownData);
Note: Strings in TwineScript/JavaScript are Unicode, however, due to historic reasons they are comprised of, and indexed by, individual UTF-16 code units rather than code points. This means that some code points may span multiple code units—e.g., the emoji 💩 is one code point, but two code units.
<String>.count(needle [, position])
→ integer Returns the number of times that the given substring was found within the string, starting the search at .position
v2.0.0
: Introduced.needle
: (any) The substring to count.position
: (optional, integer) The zero-based index at which to begin searching for . If omitted, will default to .needle
0
// Given: $text = "How now, brown cow."
$text.count("ow") → Returns 4
$text.count("ow", 8) → Returns 2
<String>.first()
→ string Returns the first Unicode code point within the string. Does not modify the original.
See: String methods note.
v2.27.0
: Introduced.// Given: $text = "abc"
$text.first() → Returns "a"
// Given: $text = "🙈🙉🙊"
$text.first() → Returns "🙈"
String.format(format , arguments…)
→ string Returns a formatted string, after replacing each format item in the given format string with the text equivalent of the corresponding argument's value.
v2.0.0
: Introduced.format
: (string) The format string, which consists of normal text and format items.arguments
: (any… | Array<any>) Either a list of arguments, which correspond by-index to the format items within the format string, or an array, whose members correspond by-index.A format item has the syntax , square-brackets denoting optional elements.{index[,alignment]}
index
: (integer) The (zero-based) index of the argument whose string representation will replace the format item.alignment
: (optional, integer) The total length of the field into which the argument is inserted, and whether it's right- or left-aligned (positive aligns right, negative aligns left).String.format("{0}, {1}!", "Hello", "World") → List of arguments; Returns "Hello, World!"
String.format("{0}, {1}!", [ "Hello", "World" ]) → Array argument; Returns "Hello, World!"
String.format("{0,6}", "foo") → Returns " foo"
String.format("{0,-6}", "foo") → Returns "foo "
<String>.includes(needle [, position])
→ boolean Returns whether the given substring was found within the string, starting the search at .position
needle
: (any) The substring to find.position
: (optional, integer) The zero-based index at which to begin searching for . If omitted, will default to .needle
0
// Given: $text = "How now, brown cow."
$text.includes("row") → Returns true
$text.includes("row", 14) → Returns false
$text.includes("cow", 14) → Returns true
$text.includes("pow") → Returns false
<String>.last()
→ string Returns the last Unicode code point within the string. Does not modify the original.
See: String methods note.
v2.27.0
: Introduced.// Given: $text = "abc"
$text.last() → Returns "c"
// Given: $text = "🙈🙉🙊"
$text.last() → Returns "🙊"
<String>.toLocaleUpperFirst()
→ string Returns the string with its first Unicode code point converted to upper case, according to any locale-specific rules. Does not modify the original.
See: String methods note.
v2.9.0
: Introduced.// Using the Turkish (Türkçe) locale and given: $text = "ışık"
$text.toLocaleUpperFirst() → Returns "Işık"
// Using the Turkish (Türkçe) locale and given: $text = "iki"
$text.toLocaleUpperFirst() → Returns "İki"
<String>.toUpperFirst()
→ string Returns the string with its first Unicode code point converted to upper case. Does not modify the original.
See: String methods note.
v2.9.0
: Introduced.// Given: $text = "hello."
$text.toUpperFirst() → Returns "Hello."
// Given: $text = "χαίρετε."
$text.toUpperFirst() → Returns "Χαίρετε."
Passage, tag, and variable names that have special meaning to SugarCube.
Passages that are used only as code and should not be navigated to. They exist simply to fill in parts of the UI—e.g., —or execute code at specific times—e.g., —or both—e.g., .StoryCaption
PassageReady
PassageHeader
PassageDone
Used for post-passage-display tasks, like redoing dynamic changes (happens after the rendering and display of each passage). Generates no output.
Roughly equivalent to the :passagedisplay
event.
v2.0.0
: Introduced.PassageFooter
Appended to each rendered passage.
Roughly equivalent to the :passagerender
event.
v2.0.0
: Introduced.PassageHeader
Prepended to each rendered passage.
Roughly equivalent to the :passagestart
event.
v2.0.0
: Introduced.PassageReady
Used for pre-passage-display tasks, like redoing dynamic changes (happens before the rendering of each passage). Generates no output.
Roughly equivalent to the :passagestart
event.
v2.0.0
: Introduced.StoryAuthor
Used to populate the authorial byline area in the UI bar (element ID: ).story-author
v2.0.0
: Introduced.StoryBanner
Used to populate the story's banner area in the UI bar (element ID: ).story-banner
v2.0.0
: Introduced.StoryCaption
Used to populate the story's caption area in the UI bar (element ID: ). May also be, and often is, used to add additional story UI elements and content to the UI bar.story-caption
v2.0.0
: Introduced.StoryDisplayTitle
Sets the story's display title in the browser's titlebar and the UI bar (element ID: ). If omitted, the story title will be used instead.story-title
v2.31.0
: Introduced.StoryInit
Used for pre-story-start initialization tasks, like variable initialization (happens at the beginning of story initialization). Generates no output.
v2.0.0
: Introduced.StoryInterface
Used to replace SugarCube's default UI. Its contents are treated as raw HTML markup—i.e., none of SugarCube's special HTML processing is performed. The markup is contained within a element and must itself contain, at least, an element with the ID that will be the main passage display area. For example:<div id="story" role="main">
passages
<div id="story" role="main">
<!-- StoryInterface elements added here -->
</div>
Additional elements, aside from the element, may include either the or content attribute, whose value is the name of the passage used to populate the element—the passage will be processed as normal, meaning that markup and macros will work as expected. The attribute causes the element to be updated once at initialization, while the attribute causes the element to be updated upon each passage navigation.#passages
data-init-passage
data-passage
data-init-passage
data-passage
Warning:
Elements that include either a or content attribute should not themselves contain additional elements. This is because such elements' contents are replaced via their associated passage, so any child elements will be lost.
data-init-passage
data-passage
v2.18.0
: Introduced.v2.28.0
: Added processing of the content attribute.data-passage
v2.36.0
: Added processing of the content attribute.data-init-passage
v2.37.0
: Fixed processing of the content attribute. Added the container element.data-init-passage
<div#story>
<div id="passages"></div>
Combined with the built-in wrapper:
<div id="story" role="main">
<div id="passages"></div>
</div>
data-init-passage
data-passage
<div id="menu" data-init-passage="Menu"></div>
<div id="notifications" data-passage="Notifications"></div>
<div id="passages"></div>
Combined with the built-in wrapper:
<div id="story" role="main">
<div id="menu" data-init-passage="Menu"></div>
<div id="notifications" data-passage="Notifications"></div>
<div id="passages"></div>
</div>
StoryMenu
Used to populate the story's menu items in the UI bar (element ID: ).menu-story
Note:
The story menu only displays links—specifically, anything that creates an anchor element (). While it renders content just as any other passage does, instead of displaying the rendered output as-is, it sifts through the output and builds its menu from the generated links contained therein.
<a>
v2.0.0
: Introduced.[[Inventory]]
<<link "Schedule">>…<</link>>
StorySettings
Warning:
Twine 1.4 code passage unused by SugarCube. The Config
API serves the same basic purpose.
StorySubtitle
Sets the story's subtitle in the UI bar (element ID: ).story-subtitle
v2.0.0
: Introduced.StoryTitle
Warning: The story title is used to create the storage ID that is used to store all player data, both temporary and persistent. It should be plain text, containing no code, markup, or macros of any kind.
Tip:
If you want to set a title for display that contains code, markup, or macros, see the StoryDisplayTitle
code passage.
Twine 2: Unused, not a code passage. The story's title is part of the story project.
Twine 1/Twee: Required. Sets the story's title.
v2.0.0
: Introduced.StoryShare
Deprecated: This special passage has been deprecated and should no longer be used.
v2.0.0
: Introduced.v2.37.0
: Deprecated.Passages that receive some kind of special treatment from the engine.
Note: Some special passages are conditional and may not always be special passages. The conditions will be noted within each such passsge's entry.
Start
Twine 2: Not a special passage. Any passage may be chosen as the starting passage by selecting it via the Start Story Here passage context-menu item—n.b. older versions of Twine 2 used a icon for the same purpose.
Twine 1/Twee: Required. The starting passage, the first passage displayed. Configurable, see Config.passages.start
for more information.
v2.0.0
: Introduced.Passages tagged with code tags are used only as code or data and cannot be navigated to.
Note: Some code tags are conditional and may not always act as code tags. The conditions will be noted within each such tag's entry.
init
Registers the passage as an initialization passage. Used for pre-story-start initialization tasks, like variable initialization (happens at the beginning of story initialization). Generates no output.
Note:
This is chiefly intended for use by add-ons/libraries. For normal projects, authors are strongly encouraged to continue to use the StoryInit
special named passage.
v2.36.0
: Introduced.script
Twine 2: Unused, not a code tag. Use the Edit Story JavaScript story editor menu item for scripts.
Twine 1/Twee: Registers the passage as JavaScript code, which is executed during startup.
v2.0.0
: Introduced.stylesheet
Twine 2: Unused, not a code tag. Use the Edit Story Stylesheet story editor menu item for styles.
Twine 1/Twee: Registers the passage as a CSS stylesheet, which is loaded during startup. It is strongly recommended that you use only one stylesheet passage. Additionally, see the tagged stylesheet warning.
v2.0.0
: Introduced.Twine.audio
Registers the passage as an audio passage. See Guide: Media Passages for more information.
v2.24.0
: Introduced.Twine.image
Registers the passage as an image passage. See Guide: Media Passages for more information.
v2.0.0
: Introduced.Twine.video
Registers the passage as a video passage. See Guide: Media Passages for more information.
v2.24.0
: Introduced.Twine.vtt
Registers the passage as a VTT passage. See Guide: Media Passages for more information.
v2.24.0
: Introduced.widget
Registers the passage as <<widget>>
macro definitions, which are loaded during startup.
v2.0.0
: Introduced.nobr
Causes leading/trailing newlines to be removed and all remaining sequences of newlines to be replaced with single spaces before the passage is rendered. Equivalent to wrapping the entire passage in a <<nobr>>
macro. See the Config.passages.nobr
setting for a way to apply the same processing to all passages at once.
Note:
Does not affect or tagged passages, for Twine 1/Twee.
script
stylesheet
v2.0.0
: Introduced.bookmark
Deprecated: This special tag has been deprecated and should no longer be used.
v2.0.0
: Introduced.v2.37.0
: Deprecated.$
Alias for , by default. NOTE: This should not be confused with story variables, which start with a —e.g., .jQuery
$
$foo
v2.0.0
: Introduced._args
Widget arguments array (only inside widgets). See <<widget>>
for more information.
v2.36.0
: Introduced._contents
Widget contents string (only inside block widgets). See <<widget>>
for more information.
v2.36.0
: Introduced.Config
Configuration API. See Config
API for more information.
v2.0.0
: Introduced.Dialog
Dialog API. See Dialog
API for more information.
v2.0.0
: Introduced.Engine
Engine API. See Engine
API for more information.
v2.0.0
: Introduced.Fullscreen
Fullscreen API. See Fullscreen
API for more information.
v2.31.0
: Introduced.jQuery
jQuery library function.
v2.0.0
: Introduced.l10nStrings
Strings localization object. See Localization for more information.
v2.10.0
: Introduced.LoadScreen
LoadScreen API. See LoadScreen
API for more information.
v2.15.0
: Introduced.Macro
Macro API. See Macro
API for more information.
v2.0.0
: Introduced.Passage
Passage API. See Passage
API for more information.
v2.0.0
: Introduced.Save
Save API. See Save
API for more information.
v2.0.0
: Introduced.Setting
Setting API. See Setting
API for more information.
v2.0.0
: Introduced.settings
Player settings object, set up by the author/developer. See Setting
API for more information.
v2.0.0
: Introduced.setup
Object that authors/developers may use to set up various bits of static data. Generally, you would use this for data that does not change and should not be stored within story variables, which would make it part of the history.
v2.0.0
: Introduced.SimpleAudio
SimpleAudio API. See SimpleAudio
API for more information.
v2.28.0
: Introduced.State
State API. See State
API for more information.
v2.0.0
: Introduced.Story
Story API. See Story
API for more information.
v2.0.0
: Introduced.Template
Template API. See Template
API for more information.
v2.29.0
: Introduced.UI
UI API. See UI
API for more information.
v2.0.0
: Introduced.UIBar
UIBar API. See UIBar
API for more information.
v2.17.0
: Introduced.$args
Deprecated:
The special variable has been deprecated and should no longer be used. See the _args
special variable for its replacement.
$args
v2.0.0
: Introduced.v2.36.0
: Deprecated.postdisplay
Deprecated:
tasks have been deprecated and should no longer be used. See the :passagedisplay
event for its replacement.
postdisplay
v2.0.0
: Introduced.v2.31.0
: Deprecated.postrender
Deprecated:
tasks have been deprecated and should no longer be used. See the :passagerender
event for its replacement.
postrender
v2.0.0
: Introduced.v2.31.0
: Deprecated.predisplay
Deprecated:
tasks have been deprecated and should no longer be used. See the :passagestart
event for its replacement.
predisplay
v2.0.0
: Introduced.v2.31.0
: Deprecated.prehistory
Deprecated:
tasks have been deprecated and should no longer be used. See the :passageinit
event for its replacement.
prehistory
v2.0.0
: Introduced.v2.31.0
: Deprecated.prerender
Deprecated:
tasks have been deprecated and should no longer be used. See the :passagestart
event for its replacement.
prerender
v2.0.0
: Introduced.v2.31.0
: Deprecated.IDs and classes automatically generated from passage names and tags are normalized to kebab case with all lowercase letters—which entails: removing characters that are not alphanumerics, underscores, hyphens, en-/em-dashes, or whitespace, then replacing any remaining non-alphanumeric characters with hyphens, one per group, and finally converting the result to lowercase.
Passage names have prepended to their converted forms and are converted both into IDs and classes depending on how the passage is used—an ID for the active passage, classes for included (via <<include>>
) passages.passage-
For example, if the passage name was , then:Gone fishin'
passage-gone-fishin
#passage-gone-fishin
passage-gone-fishin
.passage-gone-fishin
When displaying a passage, its tags are:
<html>
<body>
data-tags
<body>
Twine 2: | debug , , , , and any tag starting with nobr passage widget twine. |
---|---|
Twine 1/Twee: | debug , , , , , , and any tag starting with nobr passage script stylesheet widget twine. |
For example, if the tag name was , then it would become both the attribute member (selector: ) and the class (selector: ).Sector_42
data-tags
Sector_42
[data-tags~="Sector_42"]
sector-42
.sector-42
Selector | Description |
---|---|
html |
The document element. The default font stack is set here. The active passage's tags will be added to its attribute (see: Passage Conversions). |
body |
The body of the page. The default foreground and background colors are set here. The active passage's tags will be added to its attribute and classes (see: Passage Conversions). |
#story |
Selects the story element. |
#passages |
Selects the element that contains passage elements. All created passage elements will be children of this element. |
.passage |
Selects the passage element. Normally, there will be only one such passage per turn, however, during passage navigation there may briefly be two—the incoming (a.k.a. active) and outgoing passages. The active passage's name will be added as its ID (see: Passage Conversions). The active passage's tags will be added to its attribute and classes (see: Passage Conversions). |
.passage a |
Selects all elements within the passage element.<a> |
.passage a:hover |
Selects elements within the passage element that are being hovered over.<a> |
.passage a:active |
Selects elements within the passage element that are being clicked on.<a> |
.passage .link-broken |
Selects all internal link elements within the passage element whose passages do not exist within the story. |
.passage .link-disabled |
Selects all internal link elements within the passage element who have been disabled—e.g., already chosen macro links.<<choice>> |
.passage .link-external |
Selects all external link elements within the passage element—e.g., links to other pages and websites. |
.passage .link-internal |
Selects all internal link elements within the passage element—e.g., passage and macro links. |
.passage .link-visited1 |
Selects all internal link elements within the passage element whose passages are within the in-play story history—i.e., passages the player has been to before. |
.passage .link-internal:not(.link-visited)1 |
Selects all internal link elements within the passage element whose passages are not within the in-play story history—i.e., passages the player has never been to before. |
Config.addVisitedLinkClass
property for more information..link-visited
Config
When using Twine 1/Twee, it is strongly recommended that you use only a single tagged passage. CSS styles cascade in order of load, so if you use multiple tagged passages, then it is all too easy for your styles to be loaded in the wrong order, since Twine 1/Twee gives you no control over the order that multiple tagged passages load.stylesheet
stylesheet
stylesheet
SugarCube does not support the Twine 1.4+ vanilla story formats' tagged stylesheets. In SugarCube, you would instead simply prefix the selectors of your styles with the appropriate tag-based selectors—e.g., either attribute selectors or class selectors.[data-tags~="…"]
For example, if some story passages were tagged with , then styles for those forest passages might look like this:forest
/* Using [data-tags~="…"] attribute selectors on <html> */
html[data-tags~="forest"] { background-image: url(forest-bg.jpg); }
html[data-tags~="forest"] .passage { color: darkgreen; }
html[data-tags~="forest"] a { color: green; }
html[data-tags~="forest"] a:hover { color: lime; }
/* Using [data-tags~="…"] attribute selectors on <body> */
body[data-tags~="forest"] { background-image: url(forest-bg.jpg); }
body[data-tags~="forest"] .passage { color: darkgreen; }
body[data-tags~="forest"] a { color: green; }
body[data-tags~="forest"] a:hover { color: lime; }
/* Using class selectors on <body> */
body.forest { background-image: url(forest-bg.jpg); }
body.forest .passage { color: darkgreen; }
body.forest a { color: green; }
body.forest a:hover { color: lime; }
These are SugarCube's built-in stylesheets, in order of load/cascade. The most interesting of which, from an end-user's standpoint, are 5–13. The links go to the most recent release versions of each in SugarCube's source code repository.
normalize.css
init-screen.css
font-icons.css
font-emoji.css
core.css
core-display.css
core-passage.css
core-macro.css
ui-dialog.css
ui-dialog-saves.css
ui-dialog-settings.css
ui-dialog-legacy.css
ui-bar.css
ui-debug-bar.css
ui-debug-views.css
The hierarchy of the document body, including associated HTML IDs and class names is as follows.
…
#story-title-separator
StoryMenu
special passage is used.#menu-story
#menu-item-continue
Setting
API is used.#menu-item-settings
<body class="…">
<div id="init-screen"></div>
<div id="ui-overlay" class="ui-close"></div>
<div id="ui-dialog" tabindex="0" role="dialog" aria-labelledby="ui-dialog-title">
<div id="ui-dialog-titlebar">
<h1 id="ui-dialog-title"></h1>
<button id="ui-dialog-close" class="ui-close" tabindex="0" aria-label="…"></button>
</div>
<div id="ui-dialog-body"></div>
</div>
<div id="ui-bar">
<div id="ui-bar-tray">
<button id="ui-bar-toggle" tabindex="0" title="…" aria-label="…"></button>
<div id="ui-bar-history">
<button id="history-backward" tabindex="0" title="…" aria-label="…">…</button>
<button id="history-jumpto" tabindex="0" title="…" aria-label="…">…</button>
<button id="history-forward" tabindex="0" title="…" aria-label="…">…</button>
</div>
</div>
<div id="ui-bar-body">
<header id="title" role="banner">
<div id="story-banner"></div>
<h1 id="story-title"></h1>
<div id="story-subtitle"></div>
<div id="story-title-separator"></div>
<p id="story-author"></p>
</header>
<div id="story-caption"></div>
<nav id="menu" role="navigation">
<ul id="menu-story">…<ul>
<ul id="menu-core">
<li id="menu-item-continue"><a tabindex="0">…</a></li>
<li id="menu-item-saves"><a tabindex="0">…</a></li>
<li id="menu-item-settings"><a tabindex="0">…</a></li>
<li id="menu-item-restart"><a tabindex="0">…</a></li>
</ul>
</nav>
</div>
</div>
<div id="story" role="main">
<div id="passages">
<div class="passage …" id="…" data-passage="…">
<!-- The active (present) passage content -->
</div>
</div>
</div>
<!-- The story data chunk, which depends on the compiler release (see below) -->
<script id="script-sugarcube" type="text/javascript"><!-- The main SugarCube module --></script>
</body>
Periods of ellipsis () signify data that is generated at compile time.…
<tw-storydata name="…" startnode="…" creator="…" creator-version="…"
ifid="…" zoom="…" format="…" format-version="…" options="…" hidden>
<!-- Passage data nodes… -->
</tw-storydata>
<div id="store-area" data-size="…" hidden>
<!-- Passage data nodes… -->
</div>
Events are messages that are sent (a.k.a.: fired, triggered) to notify code that something has taken place, from player interactions to automated happenings. Each event is represented by an object that has properties that may be used to get additional information about what happened.
This section offers a list of SugarCube-specific events, triggered at various points during story operation.
See Also: For standard browser/DOM events, see the Event reference @MDN.
Dialog
Events Dialog
events allow the execution of JavaScript code at specific points during the opening and closing of dialogs.
See:
Dialog
API.
:dialogclosed
event Global event triggered as the last step in closing the dialog when Dialog.close()
is called.
Warning:
You cannot obtain data about the closing dialog from the dialog itself—e.g., title or classes—when using the event, as the dialog has already closed and been reset by the time the event is fired. If you need that kind of information from the dialog itself, then you may use the :dialogclosing
event instead.
:dialogclosed
v2.29.0
: Introduced.Note:
While there are no custom properties, the event is fired from the dialog's body, thus the property will refer to its body element—i.e., .
target
#ui-dialog-body
/* Execute the handler function when the event triggers. */
$(document).on(':dialogclosed', function (ev) {
/* JavaScript code */
});
/* Execute the handler function exactly once. */
$(document).one(':dialogclosed', function (ev) {
/* JavaScript code */
});
:dialogclosing
event Global event triggered as the first step in closing the dialog when Dialog.close()
is called.
v2.29.0
: Introduced.Note:
While there are no custom properties, the event is fired from the dialog's body, thus the property will refer to its body element—i.e., .
target
#ui-dialog-body
/* Execute the handler function when the event triggers. */
$(document).on(':dialogclosing', function (ev) {
/* JavaScript code */
});
/* Execute the handler function exactly once. */
$(document).one(':dialogclosing', function (ev) {
/* JavaScript code */
});
:dialogopened
event Global event triggered as the last step in opening the dialog when Dialog.open()
is called.
v2.29.0
: Introduced.Note:
While there are no custom properties, the event is fired from the dialog's body, thus the property will refer to its body element—i.e., .
target
#ui-dialog-body
/* Execute the handler function when the event triggers. */
$(document).on(':dialogopened', function (ev) {
/* JavaScript code */
});
/* Execute the handler function exactly once. */
$(document).one(':dialogopened', function (ev) {
/* JavaScript code */
});
:dialogopening
event Global event triggered as the first step in opening the dialog when Dialog.open()
is called.
v2.29.0
: Introduced.Note:
While there are no custom properties, the event is fired from the dialog's body, thus the property will refer to its body element—i.e., .
target
#ui-dialog-body
/* Execute the handler function when the event triggers. */
$(document).on(':dialogopening', function (ev) {
/* JavaScript code */
});
/* Execute the handler function exactly once. */
$(document).one(':dialogopening', function (ev) {
/* JavaScript code */
});
Navigation events allow the execution of JavaScript code at specific points during passage navigation.
In order of processing: (for reference, this also shows tasks and various special passages)
:passageinit
event.PassageReady
special passage.:passagestart
event.PassageHeader
special passage.PassageFooter
special passage.:passagerender
event.PassageDone
special passage.:passagedisplay
event.:passageend
event.:passageinit
event Triggered before the modification of the state history.
v2.20.0
: Introduced.v2.37.0
: Moved custom properties into the event's object.detail
detail
:passageinit
events have a property whose value is an object with the following properties:detail
passage
: (Passage
object) The incoming passage object. See the Passage
API for more information./* Execute the handler function each time the event triggers. */
$(document).on(':passageinit', function (ev) {
/* Log details about the current moment. */
console.group('Details about the current moment');
console.log('passage name:', ev.detail.passage.name);
console.log('passage tags:', ev.detail.passage.tags);
console.groupEnd();
/* Do something useful here. */
});
/* Execute the handler function exactly once. */
$(document).one(':passageinit', function (ev) {
/* Do something useful here. */
});
:passagestart
event Triggered before the rendering of the incoming passage.
v2.20.0
: Introduced.v2.37.0
: Moved custom properties into the event's object.detail
detail
:passagestart
events have a property whose value is an object with the following properties:detail
content
: (HTMLElement
object) The, currently, empty element that will eventually hold the rendered content of the incoming passage.passage
: (Passage
object) The incoming passage object. See the Passage
API for more information./* Execute the handler function each time the event triggers. */
$(document).on(':passagestart', function (ev) {
/* Log details about the current moment. */
console.group('Details about the current moment');
console.log('buffer:', ev.detail.content);
console.log('passage name:', ev.detail.passage.name);
console.log('passage tags:', ev.detail.passage.tags);
console.groupEnd();
/* Do something useful here. */
});
/* Execute the handler function exactly once. */
$(document).one(':passagestart', function (ev) {
/* Do something useful here. */
});
/*
Process the given markup and append the result to the incoming
passage's element.
*/
$(document).on(':passagestart', function (ev) {
$(ev.detail.content).wiki("In the //beginning//.");
});
:passagerender
event Triggered after the rendering of the incoming passage.
v2.20.0
: Introduced.v2.37.0
: Moved custom properties into the event's object.detail
detail
:passagerender
events have a property whose value is an object with the following properties:detail
content
: (HTMLElement
object) The element holding the fully rendered content of the incoming passage.passage
: (Passage
object) The incoming passage object. See the Passage
API for more information./* Execute the handler function each time the event triggers. */
$(document).on(':passagerender', function (ev) {
/* Log details about the current moment. */
console.group('Details about the current moment');
console.log('buffer:', ev.detail.content);
console.log('passage name:', ev.detail.passage.name);
console.log('passage tags:', ev.detail.passage.tags);
console.groupEnd();
/* Do something useful here. */
});
/* Execute the handler function exactly once. */
$(document).one(':passagerender', function (ev) {
/* Do something useful here. */
});
/*
Process the given markup and append the result to the incoming
passage's element.
*/
$(document).on(':passagerender', function (ev) {
$(ev.detail.content).wiki("At the //end// of some renderings.");
});
:passagedisplay
event Triggered after the display—i.e., output—of the incoming passage.
v2.20.0
: Introduced.v2.31.0
: Added property to event object.content
v2.37.0
: Moved custom properties into the event's object.detail
detail
:passagedisplay
events have a property whose value is an object with the following properties:detail
content
: (HTMLElement
object) The element holding the fully rendered content of the incoming passage.passage
: (Passage
object) The incoming passage object. See the Passage
API for more information./* Execute the handler function each time the event triggers. */
$(document).on(':passagedisplay', function (ev) {
/* Log details about the current moment. */
console.group('Details about the current moment');
console.log('buffer:', ev.detail.content);
console.log('passage name:', ev.detail.passage.name);
console.log('passage tags:', ev.detail.passage.tags);
console.groupEnd();
/* Do something useful here. */
});
/* Execute the handler function exactly once. */
$(document).one(':passagedisplay', function (ev) {
/* Do something useful here. */
});
/*
Process the given markup and append the result to the incoming
passage's element.
*/
$(document).on(':passagedisplay', function (ev) {
$(ev.detail.content).wiki("It's //showtime//!");
});
:passageend
event Triggered at the end of passage navigation.
v2.20.0
: Introduced.v2.31.0
: Added property to event object.content
v2.37.0
: Moved custom properties into the event's object.detail
detail
:passageend
events have a property whose value is an object with the following properties:detail
content
: (HTMLElement
object) The element holding the fully rendered content of the incoming passage.passage
: (Passage
object) The incoming passage object. See the Passage
API for more information./* Execute the handler function each time the event triggers. */
$(document).on(':passageend', function (ev) {
/* Log details about the current moment. */
console.group('Details about the current moment');
console.log('buffer:', ev.detail.content);
console.log('passage name:', ev.detail.passage.name);
console.log('passage tags:', ev.detail.passage.tags);
console.groupEnd();
/* Do something useful here. */
});
/* Execute the handler function exactly once. */
$(document).one(':passageend', function (ev) {
/* Do something useful here. */
});
/*
Process the given markup and append the result to the incoming
passage's element.
*/
$(document).on(':passageend', function (ev) {
$(ev.detail.content).wiki("So long and //thanks for all the fish//!");
});
prehistory
tasks Deprecated:
tasks have been deprecated and should no longer be used. See the :passageinit
event for its replacement.
prehistory
v2.0.0
: Introduced.v2.31.0
: Deprecated.predisplay
tasks Deprecated:
tasks have been deprecated and should no longer be used. See the :passagestart
event for its replacement.
predisplay
v2.0.0
: Introduced.v2.31.0
: Deprecated.prerender
tasks Deprecated:
tasks have been deprecated and should no longer be used. See the :passagestart
event for its replacement.
prerender
v2.0.0
: Introduced.v2.31.0
: Deprecated.postrender
tasks Deprecated:
tasks have been deprecated and should no longer be used. See the :passagerender
event for its replacement.
postrender
v2.0.0
: Introduced.v2.31.0
: Deprecated.postdisplay
tasks Deprecated:
tasks have been deprecated and should no longer be used. See the :passagedisplay
event for its replacement.
postdisplay
v2.0.0
: Introduced.v2.31.0
: Deprecated.SimpleAudio
Events SimpleAudio
events allow the execution of JavaScript code at specific points during audio playback.
SimpleAudio
API see:
:faded
event Track event triggered when a fade completes normally.
v2.29.0
: Introduced./* Execute the handler function when the event triggers for one track via <AudioTrack>. */
aTrack.on(':faded', function (ev) {
/* JavaScript code */
});
/* Execute the handler function when the event triggers for multiple tracks via <AudioRunner>. */
someTracks.on(':faded', function (ev) {
/* do something */
});
:fading
event Track event triggered when a fade starts.
v2.29.0
: Introduced./* Execute the handler function when the event triggers for one track via <AudioTrack>. */
aTrack.on(':fading', function (ev) {
/* JavaScript code */
});
/* Execute the handler function when the event triggers for multiple tracks via <AudioRunner>. */
someTracks.on(':fading', function (ev) {
/* do something */
});
:stopped
event Track event triggered when playback is stopped after <AudioTrack>.stop()
or <AudioRunner>.stop()
is called—either manually or as part of another process.
See Also:
ended
and pause
for information on somewhat similar native events.
v2.29.0
: Introduced./* Execute the handler function when the event triggers for one track via <AudioTrack>. */
aTrack.on(':stopped', function (ev) {
/* JavaScript code */
});
/* Execute the handler function when the event triggers for multiple tracks via <AudioRunner>. */
someTracks.on(':stopped', function (ev) {
/* do something */
});
System events allow the execution of JavaScript code at specific points during story startup and teardown.
:enginerestart
event Global event triggered once just before the page is reloaded when Engine.restart()
is called.
v2.23.0
: Introduced./* Execute the handler function when the event triggers. */
$(document).one(':enginerestart', function (ev) {
/* JavaScript code */
});
:storyready
event Global event triggered once just before the dismissal of the loading screen at startup.
v2.31.0
: Introduced./* Execute the handler function exactly once, since it's only fired once. */
$(document).one(':storyready', function (ev) {
/* JavaScript code */
});
:uiupdate
event Global event triggered when the built-in user interface is being updated.
v2.37.0
: Introduced./* Execute the handler function when the event triggers. */
$(document).on(':uiupdate', function (ev) {
/* JavaScript code */
});
<<type>>
Events <<type>>
macro events allow the execution of JavaScript code at specific points during typing.
:typingcomplete
event Global event triggered when all macros within a passage have completed.<<type>>
Note:
Injecting additional macro invocations after a event has been fired will cause another event to eventually be generated, since you're creating a new sequence of typing.
<<type>>
:typingcomplete
v2.32.0
: Introduced./* Execute the handler function when the event triggers. */
$(document).on(':typingcomplete', function (ev) {
/* JavaScript code */
});
:typingstart
event Local event triggered on the typing wrapper when the typing of a section starts.
v2.32.0
: Introducedv2.33.0
: Changed to a local event that bubbles up the DOM tree./* Execute the handler function when the event triggers. */
$(document).on(':typingstart', function (ev) {
/* JavaScript code */
});
:typingstop
event Local event triggered on the typing wrapper when the typing of a section stops.
v2.32.0
: Introducedv2.33.0
: Changed to a local event that bubbles up the DOM tree./* Execute the handler function when the event triggers. */
$(document).on(':typingstop', function (ev) {
/* JavaScript code */
});
Config
API The object controls various aspects of SugarCube's behavior.Config
Note:
object settings should be placed within your project's JavaScript section (Twine 2: the Story JavaScript; Twine 1/Twee: a -tagged passage).
Config
script
Config.addVisitedLinkClass
↔ boolean (default: false
) Determines whether the class is added to internal passage links that go to previously visited passages—i.e., the passage already exists within the story history.link-visited
Note:
You must provide your own styling for the class as none is provided by default.
link-visited
v2.0.0
: Introduced.Config.addVisitedLinkClass = true;
You will also need to specify a style that defines the properties visited links should have. For example:.link-visited
.link-visited {
color: purple;
}
Config.cleanupWikifierOutput
↔ boolean (default: false
) Determines whether the output of the Wikifier is post-processed into more sane markup—i.e., where appropriate, it tries to transition the plethora of elements into elements.<br>
<p>
v2.0.0
: Introduced.Config.cleanupWikifierOutput = true;
Config.debug
↔ boolean (default: false
) Indicates whether SugarCube is running in test mode, which enables debug views and various optional debugging errors and warnings. See the Test Mode guide for more information.
Note:
This setting is automatically set based on whether you're using a testing mode in a Twine compiler—i.e., Test mode in Twine 2, Test Play From Here in Twine 1, or the test mode option (, ) in Tweego. You may, however, forcibly enable it if you need to for some reason—e.g., if you're using another compiler, which doesn't offer a way to enable test mode.
-t
--test
See Also:
Config.enableOptionalDebugging
setting.
v2.2.0
: Introduced.// Forcibly enable test mode
Config.debug = true;
if (Config.debug) {
/* do something debug related */
}
<<if Config.debug>>
/* do something debug related */
<</if>>
Config.enableOptionalDebugging
↔ boolean (default: false
) Determines whether various optional debugging errors and warnings are enabled outside of test mode.
See Also:
Config.debug
setting.
List of optional errors and warnings: (not exhaustive)
<<if>>
macro assignment error. If enabled, returns an error when the assignment operator is used within its conditional—e.g., . Does not flag other assignment operators.=
<<if $suspect = "Bob">>
v2.37.0
: Introduced.Config.enableOptionalDebugging = true;
Config.loadDelay
↔ integer (default: 0
) Sets the integer delay (in milliseconds) before the loading screen is dismissed, once the document has signaled its readiness. Not generally necessary, however, some browsers render slower than others and may need a little extra time to get a media-heavy page done. This allows you to fine tune for those cases.
v2.0.0
: Introduced.// Delay the dismissal of the loading screen by 2000ms (2s)
Config.loadDelay = 2000;
Config.audio.pauseOnFadeToZero
↔ boolean (default: true
) Determines whether the audio subsystem automatically pauses tracks that have been faded to volume (silent).0
v2.28.0
: Introduced.Config.audio.pauseOnFadeToZero = false;
Config.audio.preloadMetadata
↔ boolean (default: true
) Determines whether the audio subsystem attempts to preload track metadata—meaning information about the track (e.g., duration), not its audio frames.
Note: It is unlikely that you will ever want to disable this setting.
v2.28.0
: Introduced.Config.audio.preloadMetadata = false;
Config.history.controls
↔ boolean (default: true
) Determines whether the story's history controls (Backward, Jump To, & Forward buttons) are enabled within the UI bar.
v2.0.0
: Introduced.Config.history.controls = false;
Config.history.maxStates
↔ integer (default: 40
) Sets the maximum number of states (moments) to which the history is allowed to grow. Should the history exceed the limit, states will be dropped from the past (oldest first).
Tip:
For game-oriented projects, as opposed to more story-oriented interactive fiction, a setting of is strongly recommended.
1
v2.0.0
: Introduced.v2.36.0
: Reduced the default to .40
// Limit the history to a single state (recommended for games)
Config.history.maxStates = 1;
// Limit the history to 25 states
Config.history.maxStates = 25;
Config.macros.maxLoopIterations
↔ integer (default: 1000
) Sets the maximum number of iterations allowed before the <<for>>
macro conditional forms are terminated with an error.
Note: This setting exists to prevent a misconfigured loop from making the browser unresponsive.
v2.0.0
: Introduced.// Allow only 5000 iterations
Config.macros.maxLoopIterations = 5000;
Config.macros.typeSkipKey
↔ string (default: , space) " "
Sets the default KeyboardEvent.key
value that causes the currently running <<type>>
macro instance to finish typing its content immediately.
v2.33.1
: Introduced.// Change the default skip key to Control (CTRL)
Config.macros.typeSkipKey = "Control";
Config.macros.typeVisitedPassages
↔ boolean (default: true
) Determines whether the <<type>>
macro types out content on previously visited passages or simply outputs it immediately.
v2.32.0
: Introduced.// Do not type on previously visited passages
Config.macros.typeVisitedPassages = false;
Config.macros.ifAssignmentError
↔ boolean (default: true
) Deprecated:
This setting has been deprecated and should no longer be used. See the Config.enableOptionalDebugging
setting for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of the setting.Config.enableOptionalDebugging
Config.navigation.override
↔ function (default: none) Allows the destination of passage navigation to be overridden. The callback is passed one parameter, the original destination passage title. If its return value is falsy, the override is cancelled and navigation to the original destination continues unperturbed. If its return value is truthy, the override succeeds and that value is used as the new destination of the navigation.
v2.13.0
: Introduced.Config.navigation.override = function (destinationPassage) {
/* code that returns a passage name or a falsy value */
};
// Force the player to the "You Died" passage if they let $health get too low.
Config.navigation.override = function (dest) {
var sv = State.variables;
// If $health is less-than-or-equal to 0, go to the "You Died" passage instead.
if (sv.health <= 0) {
return "You Died";
}
};
Config.passages.displayTitles
↔ boolean (default: false
) Determines whether passage titles are combined with the story title, within the browser's/tab's titlebar, when passages are displayed.
v2.0.0
: Introduced.Config.passages.displayTitles = true;
Config.passages.nobr
↔ boolean (default: false
) Determines whether rendering passages have their leading/trailing newlines removed and all remaining sequences of newlines replaced with single spaces before they're rendered. Equivalent to including the nobr
special tag on every passage.
Note:
Does not affect or tagged passages, for Twine 1/Twee, or the Story JavaScript or Story Stylesheet sections, for Twine 2.
script
stylesheet
v2.19.0
: Introduced.Config.passages.nobr = true;
Config.passages.onProcess
↔ function (default: none) Allows custom processing of passage text. The function is invoked each time the <Passage>.processText()
method is called. It is passed an abbreviated version of the associated passage's Passage
instance—containing only the , , and properties. Its return value should be the post-processed text.tags
text
title
Note:
Does not affect or tagged passages, for Twine 1/Twee, or the Story JavaScript or Story Stylesheet sections, for Twine 2.
script
stylesheet
Note:
The function will be called just before the built-in no-break passage processing if you're also using that—see the Config.passages.nobr
setting and nobr
special tag.
v2.30.0
: Introduced.// Change instancess of "cat" to "dog"
Config.passages.onProcess = function (p) {
return p.text.replace(/\bcat(s?)\b/g, "dog$1");
};
Config.passages.start
↔ string (Twine 2 default: user-selected; Twine 1/Twee default: "Start"
) Sets the starting passage, the very first passage that will be displayed.
v2.0.0
: Introduced.Config.passages.start = "That Other Starting Passage";
Config.passages.transitionOut
↔ string | integer (default: none) Determines whether outgoing passage transitions are enabled. Valid values are the name of the property being animated, which causes the outgoing passage element to be removed once that transition animation is complete, or an integer delay (in milliseconds), which causes the outgoing passage element to be removed once the delay has expired. You will also need some CSS styles to make this work—examples given below.
Note: If using an integer delay, ideally, it should probably be slightly longer than the outgoing transition delay that you intend to use—e.g., an additional 10ms or so should be sufficient.
v2.0.0
: Introduced.// Remove outgoing elements when their opacity animation ends
Config.passages.transitionOut = "opacity";
// Remove outgoing elements after 1010ms (1.01s)
Config.passages.transitionOut = 1010;
At the very least you will need to specify a style that defines the transition's end state. For example:.passage-out
.passage-out {
opacity: 0;
}
That probably won't be very pleasing to the eye, however, so you will likely need several styles to make something that looks half-decent. For example, the following will give you a basic crossfade:
#passages {
position: relative;
}
.passage {
left: 0;
position: absolute;
top: 0;
transition: opacity 1s ease;
}
.passage-out {
opacity: 0;
}
Config.passages.descriptions
↔ boolean | object | function (default: none) Deprecated:
This setting has been deprecated and should no longer be used. See the Config.saves.descriptions
setting for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of the setting.Config.saves.descriptions
Config.saves.descriptions
↔ function (default: none) Sets browser saves descriptions. If unset, a brief description of the current turn is used. If a callback function is assigned, it is passed one parameter, the type of save being attempted. If its return value is truthy, the returned description is used, elsewise the default description is used.
See:
Save.Type
pseudo-enumeration for more information on save types.
v2.37.0
: Introduced.Config.saves.descriptions = function (saveType) {
return passage();
};
var saveDescriptions = {
"passage_title_a" : "description text a…",
"passage_title_b" : "description text b…",
"passage_title_c" : "description text c…"
};
Config.saves.descriptions = function (saveType) {
return saveDescriptions[passage()];
};
Config.saves.descriptions = function (saveType) {
const base = `(${L10n.get("turn")} ${State.turns})`;
switch (saveType) {
case Save.Type.Auto:
return `${base} A browser auto save…`;
case Save.Type.Base64:
return `${base} A base64 save…`;
case Save.Type.Disk:
return `${base} A local disk save…`;
case Save.Type.Slot:
return `${base} A browser slot save…`;
}
};
Config.saves.id
↔ string (default: slugified story title) Sets the story ID associated with saves.
v2.0.0
: Introduced.Config.saves.id = "a-big-huge-story-part-1";
Config.saves.isAllowed
↔ function (default: none) Determines whether saving is allowed within the current context. If unset, saves are always allowed. If a callback function is assigned, it is passed one parameter, the type of save being attempted. If its return value is truthy, the save is allowed, elsewise it is disallowed.
See:
Save.Type
pseudo-enumeration for more information on save types.
v2.0.0
: Introduced.v2.37.0
: Added save type parameter.Allows saves on passages if it returns a truthy value.
Config.saves.isAllowed = function (saveType) {
/* code returning a boolean value */
};
Disallow saving on passages tagged with .menu
Config.saves.isAllowed = function (saveType) {
return !tags().includes("menu");
};
Attempt a new auto save only on passages tagged with . Other save types are not limited.autosave
Config.saves.isAllowed = function (saveType) {
if (saveType === Save.Type.Auto) {
return tags().includes("autosave");
}
return true;
};
Attempt a new auto save only on every eighth turn and limit all other save types to passages tagged with .cansave
// Using an `if` statement
Config.saves.isAllowed = function (saveType) {
if (saveType === Save.Type.Auto) {
return turns() % 8 === 0;
}
return tags().includes("cansave");
};
Different logic for most save types.
Note: For example purposes only, not really recommended.
Config.saves.isAllowed = function (saveType) {
switch (saveType) {
case Save.Type.Auto:
// Only every tenth turn
return turns() % 10 === 0;
case Save.Type.Disk:
case Save.Type.Slot:
// Only on passages tagged `cansave`
return tags().includes("cansave");
case Save.Type.Base64:
// Always
return true;
}
};
Config.saves.maxAutoSaves
integer (default: 0
) Sets the maximum number of available auto saves. Using a value of disables auto saves.0
Note:
When enabled, an auto save is attempted each turn by default. Thus, it is recommended that the Config.saves.isAllowed
setting be used to limit the frequency.
Warning:
As available browser-based storage is very limited, it is strongly recommended that the number of available saves not be set too high. A range of – is suggested.
1
10
v2.37.0
: Introduced.Config.saves.maxAutoSaves = 3;
Config.saves.maxSlotSaves
integer (default: 8
) Sets the maximum number of available slot saves. Using a value of disables slot saves.0
Warning:
As available browser-based storage is very limited, it is strongly recommended that the number of available saves not be set too high. A range of – is suggested.
1
10
v2.37.0
: Introduced.Config.saves.maxSlotSaves = 4;
Config.saves.version
↔ any (default: none) Sets the property of saves.version
Note:
This setting is only used to set the property of saves. Thus, it is only truly useful if you plan to upgrade out-of-date saves via the Save
Events API—specifically the Save.onLoad.add()
static method.
version
v2.0.0
: Introduced.// As an integer (recommended)
Config.saves.version = 3;
// As a string (strongly not recommended)
Config.saves.version = "v3";
Config.saves.autoload
↔ boolean | string | function (default: none) Deprecated:
This setting has been deprecated and should no longer be used. The default UI now includes a Continue button, which loads the latest save. If disabling or replacing the default UI, see the Save.browser.continue()
method to replicate the functionality.
v2.0.0
: Introduced.v2.37.0
: Deprecated.Config.saves.autosave
↔ boolean | Array<string> | function (default: none) Deprecated:
This setting has been deprecated and should no longer be used. See the Config.saves.maxAutoSaves
setting to set the number of available auto saves and the Config.saves.isAllowed
setting to control when new auto saves are created.
v2.0.0
: Introduced.v2.30.0
: Added function values and deprecated string values.v2.37.0
: Deprecated.Config.saves.onLoad
↔ function (default: none) Deprecated:
This setting has been deprecated and should no longer be used. See the Save.onLoad.add()
method for its replacement.
v2.0.0
: Introduced.v2.36.0
: Deprecated in favor of the Save
Events API.Config.saves.onSave
↔ function (default: none) Deprecated:
This setting has been deprecated and should no longer be used. See the Save.onSave.add()
method for its replacement.
v2.0.0
: Introduced.v2.33.0
: Added save operation details object parameter to the callback function.v2.36.0
: Deprecated in favor of the Save
Events API.Config.saves.slots
integer (default: 8
) Deprecated:
This setting has been deprecated and should no longer be used. See the Config.saves.maxSlotSaves
setting for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of the setting.Config.saves.maxSlotSaves
Config.saves.tryDiskOnMobile
↔ boolean (default: true
) Deprecated: This setting has been deprecated and should no longer be used. Saving to disk on mobile devices is now unconditionally enabled.
v2.34.0
: Introduced.v2.37.0
: Deprecated.Config.ui.stowBarInitially
↔ boolean | integer (default: 800
) Determines whether the UI bar (sidebar) starts in the stowed (shut) state initially. Valid values are boolean /, which causes the UI bar to always/never start in the stowed state, or an integer, which causes the UI bar to start in the stowed state if the viewport width is less-than-or-equal-to the specified number of pixels.true
false
v2.11.0
: Introduced.// As a boolean; always start stowed
Config.ui.stowBarInitially = true;
// As a boolean; never start stowed
Config.ui.stowBarInitially = false;
// As an integer; start stowed if the viewport is 800px or less
Config.ui.stowBarInitially = 800;
Config.ui.updateStoryElements
↔ boolean (default: true
) Determines whether certain elements within the UI bar are updated when passages are displayed. The affected elements are the story: banner, subtitle, author, caption, and menu.
Note: The story title is not included in updates because SugarCube uses it as the basis for the key used to store and load data used when playing the story and for saves.
v2.0.0
: Introduced.// If you don't need those elements to update
Config.ui.updateStoryElements = false;
Dialog
API Dialog.append(content)
→ Dialog
object Appends the given content to the dialog's content area. Returns a reference to the object for chaining.Dialog
Note:
If your content contains any SugarCube markup, you'll need to use the Dialog.wiki()
method instead.
v2.9.0
: Introduced.content
: (Node | string) The content to append. As this method is essentially a shortcut for , see jQuery's append()
method for the range of valid content types.jQuery(Dialog.body()).append(…)
Dialog.append("Cry 'Havoc!', and let slip the <em>ponies</em> of <strong>friendship</strong>.");
Dialog.append( /* DOM nodes */ );
Dialog.body()
→ HTMLElement
object Returns a reference to the dialog's content area.
v2.0.0
: Introduced.jQuery(Dialog.body())
.append("Cry 'Havoc!', and let slip the <em>ponies</em> of <strong>friendship</strong>.");
jQuery(Dialog.body())
.wiki("Cry 'Havoc!', and let slip the //ponies// of ''friendship''.");
Dialog.close()
→ Dialog
object Closes the dialog. Returns a reference to the object for chaining.Dialog
v2.0.0
: Introduced.Dialog.close();
Dialog.create([title [, classNames]])
→ Dialog
object Prepares the dialog for use. Returns a reference to the object for chaining.Dialog
v2.37.0
: Introduced.title
: (optional, string) The title of the dialog.classNames
: (optional, string) The space-separated-list of classes to add to the dialog.Dialog.create();
Dialog.create("Character Sheet");
Dialog.create("Character Sheet", "charsheet");
Dialog
.create("Character Sheet", "charsheet")
.wikiPassage("Player Character")
.open();
Dialog.empty()
→ HTMLElement
object Empties the dialog's content area. Returns a reference to the object for chaining.Dialog
v2.37.0
: Introduced.Dialog.empty();
Dialog
.empty()
.wikiPassage("Quests");
Dialog.isOpen([classNames])
→ boolean Returns whether the dialog is currently open.
v2.0.0
: Introduced.classNames
: (optional, string) The space-separated-list of classes to check for when determining the state of the dialog. Each of the built-in dialogs contains a name-themed class that can be tested for in this manner—e.g., the Saves dialog contains the class .saves
if (Dialog.isOpen()) {
/* code to execute if the dialog is open… */
}
saves
if (Dialog.isOpen("saves")) {
/* code to execute if the Saves dialog is open… */
}
Dialog.open([options [, closeFn]])
→ Dialog
object Opens the dialog. Returns a reference to the object for chaining.Dialog
Note: Call this only after populating the dialog with content.
v2.0.0
: Introduced.options
: (optional, null | object) The options to be used when opening the dialog.closeFn
: (optional, null | function) The function to execute whenever the dialog is closed.An options object should have some of the following properties:
top
: Top y-coordinate of the dialog (default: ; in pixels, but without the unit).50
Dialog.open();
Dialog.wiki(wikiMarkup)
→ Dialog
object Renders the given markup and appends it to the dialog's content area. Returns a reference to the object for chaining.Dialog
Note:
If you simply want to render a passage, see the Dialog.wikiPassage()
method instead.
Warning:
If your content consists of DOM nodes, you'll need to use the Dialog.append()
method instead.
v2.9.0
: Introduced.wikiMarkup
: (string) The markup to render.Dialog.wiki("Cry 'Havoc!', and let slip the //ponies// of ''friendship''.");
Dialog.wikiPassage(name)
→ Dialog
object Renders the passage by the given name and appends it to the dialog's content area. Returns a reference to the object for chaining.Dialog
v2.37.0
: Introduced.name
: (string) The name of the passage to render.Dialog.wikiPassage("Inventory");
Dialog.setup([title [, classNames]])
→ HTMLElement
object Deprecated: This method has been deprecated and should no longer be used.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of .Dialog.create()
Engine
API Engine.lastPlay
→ number Returns a timestamp representing the last time was called.Engine.play()
v2.0.0
: Introduced.Engine.lastPlay → The timestamp at which Engine.play() was last called
Engine.state
→ string Returns the current state of the engine (, , )."idle"
"playing"
"rendering"
v2.7.0
: Introduced."idle"
: The engine is idle, awaiting the triggering of passage navigation—the default state."playing"
: Passage navigation has been triggered and a turn is being processed."rendering"
: The incoming passage is being rendered and added to the page—takes place during turn processing, so implies ."playing"
Engine.state → Returns the current state of the engine
Engine.backward()
→ boolean Moves backward one moment within the full history (past + future), if possible, activating and showing the moment moved to. Returns whether the history navigation was successful (should only fail if already at the beginning of the full history).
v2.0.0
: Introduced.Engine.backward() → Rewinds the full history by one moment—i.e., undoes the moment
Engine.forward()
→ boolean Moves forward one moment within the full history (past + future), if possible, activating and showing the moment moved to. Returns whether the history navigation was successful (should only fail if already at the end of the full history).
v2.0.0
: Introduced.Engine.forward() → Fast forwards the full history by one moment—i.e., redoes the moment
Engine.go(offset)
→ boolean Activates the moment at the given offset from the active (present) moment within the full state history and show it. Returns whether the history navigation was successful (should only fail if the offset from the active (present) moment is not within the bounds of the full history).
v2.0.0
: Introduced.offset
: (integer) The offset from the active (present) moment of the moment to go to.Engine.go(2) → Fast forwards the full history by two moments—i.e., redoes the moments
Engine.go(-4) → Rewinds the full history by four moments—i.e., undoes the moments
Engine.goTo(index)
→ boolean Activates the moment at the given index within the full state history and show it. Returns whether the history navigation was successful (should only fail if the index is not within the bounds of the full history).
v2.0.0
: Introduced.index
: (integer) The index of the moment to go to.Engine.goTo(0) → Goes to the first moment
Engine.goTo(9) → Goes to the tenth moment
Engine.isIdle()
→ boolean Returns whether the engine is idle.
v2.16.0
: Introduced.Engine.isIdle() → Returns whether the engine is idle
Engine.isPlaying()
→ boolean Returns whether the engine is processing a turn—i.e., passage navigation has been triggered.
v2.16.0
: Introduced.Engine.isPlaying() → Returns whether the engine is playing
Engine.isRendering()
→ boolean Returns whether the engine is rendering the incoming passage.
v2.16.0
: Introduced.Engine.isRendering() → Returns whether the engine is rendering
Engine.play(passageTitle [, noHistory])
→ HTMLElement
object Renders and displays the passage referenced by the given title, optionally without adding a new moment to the history.
v2.0.0
: Introduced.passageTitle
: (string) The title of the passage to play.noHistory
: (optional, boolean) Disables the update of the history—i.e., no moment is added to the history.Engine.play("Foo") → Renders, displays, and adds a moment for the passage "Foo" to the history
Engine.play("Foo", true) → Renders and displays the passage "Foo", but does not add new history
Engine.restart()
Causes the browser to immediately attempt to reload the window, thus restarting the story.
Warning: The player will not be prompted and all unsaved state will be lost.
Note:
In general, you should not call this method directly. Instead, call the UI.restart()
static method, which prompts the player with an OK/Cancel dialog before itself calling , if they accept.
Engine.restart()
v2.0.0
: Introduced.Engine.restart() → Restarts the story
Engine.show()
→ HTMLElement
object Renders and displays the active (present) moment's associated passage without adding a new moment to the history.
v2.0.0
: Introduced.Engine.show() → Renders and displays the present passage without adding new history
Fullscreen
API Provides access to browsers' fullscreen functionality.
If you wish to use custom backgrounds, either simply colors or with images, then you should place them on the element. For example:body
body {
background: #111 fixed url("images/background.png") center / contain no-repeat;
}
Warning:
It is strongly recommended that you do not place background properties on the element in addition to the element as this can cause background jitter in Internet Explorer when scrolling outside of fullscreen mode.
html
body
Warning:
If setting a background image via the shorthand property, then you should also specify a value with it or include a separate property after the property. The reason being is that the property resets the background color, so if you do not set one either as one of its values or via a following property, then the browser's default background color could show through if the background image does not cover the entire viewport or includes transparency.
background
background-color
background-color
background
background
background-color
The API comes with some built-in limitations:Fullscreen
Fullscreen.element
→ HTMLElement
object | null Returns the current fullscreen element or, if fullscreen mode is not active, .null
v2.31.0
: Introduced.Fullscreen.element → The current fullscreen element
Fullscreen.isEnabled()
→ boolean Returns whether fullscreen is both supported and enabled.
v2.31.0
: Introduced.Fullscreen.isEnabled() → Whether fullscreen mode is available
Fullscreen.isFullscreen()
→ boolean Returns whether fullscreen mode is currently active.
v2.31.0
: Introduced.Fullscreen.isFullscreen() → Whether fullscreen mode is active
Fullscreen.request([options [, requestedEl]])
→ Promise
object Request that the browser enter fullscreen mode.
See: Backgrounds and limitations.
v2.31.0
: Introduced.options
: (optional, object) The fullscreen options object.requestedEl
: (optional, HTMLElement
object) The element to enter fullscreen mode with. If omitted, defaults to the entire page.A fullscreen options object should have some of the following properties:
navigationUI
: (string) Determines the fullscreen navigation UI preference. Valid values are (default: ):
"auto"
"auto"
: Indicates no preference."hide"
: Request that the browser's navigation UI be hidden. The full dimensions of the screen will be used to display the element."show"
: Request that the browser's navigation UI be shown. The screen dimensions allocated to the element will be clamped to leave room for the UI.Note:
Browsers are not currently required to honor the setting.
navigationUI
/* Request to enter fullscreen mode. */
Fullscreen.request();
/* Request to enter fullscreen mode while showing its navigation UI and with the given element. */
Fullscreen.request({ navigationUI : "show" }, myElement);
Fullscreen.exit()
→ Promise
object Request that the browser exit fullscreen mode.
v2.31.0
: Introduced./* Request to exit fullscreen mode. */
Fullscreen.exit();
Fullscreen.toggle([options [, requestedEl]])
→ Promise
object Request that the browser toggle fullscreen mode—i.e., enter or exit as appropriate.
v2.31.0
: Introduced.options
: (optional, object) The fullscreen options object. See Fullscreen.request()
for more information.requestedEl
: (optional, HTMLElement
object) The element to toggle fullscreen mode with. If omitted, defaults to the entire page./* Request to toggle fullscreen mode. */
Fullscreen.toggle();
/* Request to toggle fullscreen mode while showing its navigation UI and with the given element. */
Fullscreen.toggle({ navigationUI : "show" }, myElement);
Fullscreen.onChange(handlerFn [, requestedEl])
Attaches fullscreen change event handlers.
v2.31.0
: Introduced.handlerFn
: (function) The function to invoke when fullscreen mode is changed.requestedEl
: (optional, HTMLElement
object) The element to attach the handler to./* Attach a hander to listen for fullscreen change events. */
Fullscreen.onChange(function (ev) {
/* Fullscreen mode changed, so do something. */
});
/* Attach a hander to the given element to listen for fullscreen change events. */
Fullscreen.onChange(function (ev) {
/* Fullscreen mode changed on myElement, so do something. */
}, myElement);
Fullscreen.offChange([handlerFn [, requestedEl]])
Removes fullscreen change event handlers.
v2.31.0
: Introduced.handlerFn
: (optional, function) The function to remove. If omitted, will remove all handler functions.requestedEl
: (optional, HTMLElement
object) The element to remove the handler(s) from./* Remove all fullscreen change event handers. */
Fullscreen.offChange();
/* Remove the given fullscreen change event hander. */
/* NOTE: Requires that the original handler function was saved. */
Fullscreen.offChange(originalHandlerFn);
/* Remove all fullscreen change event handers from myElement. */
Fullscreen.offChange(null, myElement);
/* Remove the given fullscreen change event hander from myElement. */
/* NOTE: Requires that the original handler function was saved. */
Fullscreen.offChange(originalHandlerFn, myElement);
Fullscreen.onError(handlerFn [, requestedEl])
Attaches fullscreen error event handlers.
v2.31.0
: Introduced.handlerFn
: (function) The function to invoke when fullscreen mode encounters an error.requestedEl
: (optional, HTMLElement
object) The element to attach the handler to./* Attach a hander to listen for fullscreen error events. */
Fullscreen.onError(function (ev) {
/* Fullscreen mode changed, so do something. */
});
/* Attach a hander to the given element to listen for fullscreen error events. */
Fullscreen.onError(function (ev) {
/* Fullscreen mode changed on myElement, so do something. */
}, myElement);
Fullscreen.offError([handlerFn [, requestedEl]])
Removes fullscreen error event handlers.
v2.31.0
: Introduced.handlerFn
: (optional, function) The function to remove. If omitted, will remove all handler functions.requestedEl
: (optional, HTMLElement
object) The element to remove the handler(s) from./* Remove all fullscreen error event handers. */
Fullscreen.offError();
/* Remove the given fullscreen error event hander. */
/* NOTE: Requires that the original handler function was saved. */
Fullscreen.offError(originalHandlerFn);
/* Remove all fullscreen error event handers from myElement. */
Fullscreen.offError(null, myElement);
/* Remove the given fullscreen error event hander from myElement. */
/* NOTE: Requires that the original handler function was saved. */
Fullscreen.offError(originalHandlerFn, myElement);
LoadScreen
API Note:
To simply add a delay to the dismissal of the loading screen to hide initial flashes of unstyled content (FOUC)—e.g., style changes and page reflows—you do not need to use this API. See the Config.loadDelay
configuration setting.
LoadScreen.lock()
→ number Acquire a loading screen lock and, if necessary, display the loading screen.
v2.15.0
: Introduced.The (integer) lock ID.
See the LoadScreen.unlock()
static method for additional examples.
// Lock the loading screen and get the lock ID.
var lockId = LoadScreen.lock();
LoadScreen.unlock(lockId)
Release the loading screen lock with the given ID and, if no other locks exist, hide the loading screen.
v2.15.0
: Introduced.lockId
: (integer) The loading screen lock ID.// Lock the loading screen and get the lock ID.
var lockId = LoadScreen.lock();
// Do something whose timing is unpredictable that should be hidden by the loading screen.
// Release the given lock ID.
LoadScreen.unlock(lockId);
Macro
API See Also:
MacroContext
API.
Macro.add(name , definition)
Add new macro(s).
v2.0.0
: Introducedv2.33.0
: Obsoleted the parameter.deep
name
: (string | Array<string>) Name, or array of names, of the macro(s) to add. NOTE: Names must consist of characters from the basic Latin alphabet and start with a letter, which may be optionally followed by any number of letters, numbers, the underscore, or the hyphen.definition
: (object | string) Definition of the macro(s) or the name of an existing macro whose definition to copy.A macro definition object should have some of the following properties (only is absolutely required):handler
skipArgs
: (optional, boolean | Array<string>) Disables parsing argument strings into discrete arguments. Used by macros that only use the raw/full argument strings. Boolean to affect all tags or an array of tag names to affect.true
tags
: (optional, null | Array<string>) Signifies that the macro is a container macro—i.e., not self-closing. An array child tag names or , if there are no child tags.null
handler
: (function) The macro's main function. It will be called without arguments, but with its set to a macro context object.this
Additional properties may be added for internal use.
/*
Example of a very simple/naive <<if>>/<<elseif>>/<<else>> macro implementation.
*/
Macro.add('if', {
skipArgs : true,
tags : ['elseif', 'else'],
handler : function () {
try {
for (var i = 0, len = this.payload.length; i < len; ++i) {
if (
this.payload[i].name === 'else' ||
!!Scripting.evalJavaScript(this.payload[i].args.full)
) {
jQuery(this.output).wiki(this.payload[i].contents);
break;
}
}
}
catch (ex) {
return this.error('bad conditional expression: ' + ex.message);
}
}
});
Macro.delete(name)
Remove existing macro(s).
v2.0.0
: Introduced.name
: (string | Array<string>) Name, or array of names, of the macro(s) to remove.Macro.delete("amacro")
Macro.delete(["amacro", "bmacro"])
Macro.get(name)
→ object Return the named macro definition, or on failure.null
v2.0.0
: Introduced.name
: (string) Name of the macro whose definition should be returned.Macro.get("print")
Macro.has(name)
→ boolean Returns whether the named macro exists.
v2.0.0
: Introduced.name
: (string) Name of the macro to search for.Macro.has("print")
Macro.tags.get(name)
→ Array<string> Return the named macro tag's parents array (includes the names of all macros who have registered the tag as a child), or on failure.null
v2.0.0
: Introduced.name
: (string) Name of the macro tag whose parents array should be returned.Macro.tags.get("else") → For the standard library, returns: ["if"]
Macro.tags.has(name)
→ boolean Returns whether the named macro tag exists.
v2.0.0
: Introduced.name
: (string) Name of the macro tag to search for.Macro.tags.has("else")
MacroContext
API See Also:
Macro
API.
Macro handlers are called with no arguments, but with their set to a macro (execution) context object. Macro context objects contain the following data and method properties.this
<MacroContext>.args
→ Array<any> An array of discrete arguments parsed from the argument string.
v2.0.0
: Introduced.// Given: <<someMacro "a" "b" "c">>
this.args.length // Returns 3
this.args[0] // Returns 'a'
this.args[1] // Returns 'b'
this.args[2] // Returns 'c'
<MacroContext>.args.full
→ string The argument string after converting all TwineScript syntax elements into their native JavaScript counterparts.
v2.0.0
: Introduced.// Given: <<if $a is "b">>
this.args.full // Returns 'State.variables.a === "b"'
<MacroContext>.args.raw
→ string The unprocessed argument string.
v2.0.0
: Introduced.// Given: <<if "a" is "b">>
this.args.raw // Returns '"a" is "b"'
<MacroContext>.name
→ string The name of the macro.
v2.0.0
: Introduced.// Given: <<someMacro …>>
this.name // Returns 'someMacro'
<MacroContext>.output
→ HTMLElement
object The current output element.
v2.0.0
: Introduced.<MacroContext>.parent
→ null | object The (execution) context object of the macro's parent, or if the macro has no parent.null
v2.0.0
: Introduced.<MacroContext>.parser
→ object The parser instance that generated the macro call.
v2.0.0
: Introduced.<MacroContext>.payload
→ null | Array<object> The text of a container macro parsed into discrete payload objects by tag. Payload objects have the following properties:
name
: (string) Name of the current tag.args
: (Array<any>) The current tag's argument string parsed into an array of discrete arguments. Equivalent in function to <MacroContext>.args
.
args.full
: (string) The current tag's argument string after converting all TwineScript syntax elements into their native JavaScript counterparts. Equivalent in function to <MacroContext>.args.full
.args.raw
: (string) The current tag's unprocessed argument string. Equivalent in function to <MacroContext>.args.raw
.contents
: (string) The current tag's contents—i.e., the text between the current tag and the next.v2.0.0
: Introduced.<MacroContext>.self
→ object The macro's definition—created via Macro.add()
.
v2.0.0
: Introduced.<MacroContext>.contextFilter(predicate)
→ Array<object> Returns a new array containing all of the macro's ancestors that passed the test implemented by the given predicate function or an empty array, if no members pass.
v2.37.0
: Introduced.predicate
: (function) The function used to test each ancestor execution context object, which is passed in as its sole parameter.var isInclude = function (ctx) { return ctx.name === "include"; };
this.contextFilter(isInclude); // Returns an array of all <<include>> macro ancestors
<MacroContext>.contextFind(predicate)
→ object | undefined Returns the first of the macro's ancestors that passed the test implemented by the given predicate function or , if no members pass.undefined
v2.37.0
: Introduced.predicate
: (function) The function used to test each ancestor execution context object, which is passed in as its sole parameter.var isInclude = function (ctx) { return ctx.name === "include"; };
this.contextFind(isInclude); // Returns the first <<include>> macro ancestor
<MacroContext>.contextSome(predicate)
→ boolean Returns whether any of the macro's ancestors passed the test implemented by the given predicate function.
v2.37.0
: Introduced.predicate
: (function) The function used to test each ancestor execution context object, which is passed in as its sole parameter.var isInclude = function (ctx) { return ctx.name === "include"; };
this.contextSome(isInclude); // Returns true if any ancestor was an <<include>> macro
<MacroContext>.error(message)
→ boolean:false Renders the message prefixed with the name of the macro and returns .false
v2.0.0
: Introduced.message
: (string) The error message to output.// Given: <<someMacro …>>
return this.error("oops"); // Outputs '<<someMacro>>: oops'
<MacroContext>.shadowHandler(callback [, doneCallback [, startCallback]])
→ function Returns a callback function that wraps the specified callback functions to provide access to the variable shadowing system used by the <<capture>>
macro.
Note:
All of the specified callbacks are invoked as the wrapper is invoked—meaning, with their set to the of the wrapper and with whatever parameters were passed to the wrapper.
this
this
Warning:
Only useful when you have an asynchronous callback that invokes code/content that needs to access story and/or temporary variables shadowed by . If you don't know what that means, then this API is likely not for you.
<<capture>>
v2.37.0
: Introduced.callback
: (function) The main callback function, executed when the wrapper is invoked. Receives access to variable shadows.doneCallback
: (optional, function) The finalization callback function, executed after the main returns. Does not receive access to variable shadows.callback
startCallback
: (optional, function) The initialization callback function, executed before the main is invoked. Does not receive access to variable shadows.callback
$someElement.on('some_event', this.shadowHandler(function (ev) {
/* main asynchronous code */
}));
doneCallback
$someElement.on('some_event', this.shadowHandler(
function (ev) {
/* main asynchronous code */
},
function (ev) {
/* asynchronous code invoked after the main code */
}
));
doneCallback
startCallback
$someElement.on('some_event', this.shadowHandler(
function (ev) {
/* main asynchronous code */
},
function (ev) {
/* asynchronous code invoked after the main code */
},
function (ev) {
/* asynchronous code invoked before the main code */
}
));
<MacroContext>.contextHas(filter)
→ boolean Deprecated:
This method has been deprecated and should no longer be used. See the <MacroContext>.contextSome()
method for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of .<MacroContext>.contextSome()
<MacroContext>.contextSelect(filter)
→ null | object Deprecated:
This method has been deprecated and should no longer be used. See the <MacroContext>.contextFind()
method for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of .<MacroContext>.contextFind()
<MacroContext>.contextSelectAll(filter)
→ Array<object> Deprecated:
This method has been deprecated and should no longer be used. See the <MacroContext>.contextFilter()
method for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of .<MacroContext>.contextFilter()
<MacroContext>.createShadowWrapper(callback [, doneCallback [, startCallback]])
→ function Deprecated:
This method has been deprecated and should no longer be used. See the <MacroContext>.shadowHandler()
method for its replacement.
v2.14.0
: Introduced.v2.23.3
: Fixed an issue where shadows would fail for multiple layers of nested asynchronous code due to loss of context.v2.37.0
: Deprecated in favor of .<MacroContext>.shadowHandler()
Passage
API Instances of the object are returned by the Story.get()
static method.Passage
All properties of objects should be treated as if they were read-only, as modifying them could result in unexpected behavior.Passage
<Passage>.id
→ string The DOM-compatible ID of the passage, created from the slugified passage title.
v2.37.0
: Introduced.<Passage>.name
→ string The name of the passage.
v2.37.0
: Introduced.<Passage>.tags
→ Array<string> The tags of the passage.
v2.0.0
: Introduced.<Passage>.text
→ string The raw text of the passage.
v2.0.0
: Introduced.<Passage>.processText()
→ string Returns the processed text of the passage, created from applying tag and image passage processing to its raw text.nobr
v2.0.0
: Introduced.var passage = Story.get("The Ducky");
passage.processText() → Returns the fully processed text of "The Ducky" passage
<Passage>.domId
→ string Deprecated:
This property has been deprecated and should no longer be used. See the <Passage>.id
property for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of .<Passage>.id
<Passage>.title
→ string Deprecated:
This property has been deprecated and should no longer be used. See the <Passage>.name
property for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of .<Passage>.name
<Passage>.description()
→ string Deprecated: This method has been deprecated and should no longer be used.
v2.0.0
: Introduced.v2.37.0
: Deprecated.Save
API Note: There are several configuration settings for saves that it would be wise for you to familiarize yourself with.
Warning: Browser saves—i.e., auto and slot saves—are largely incompatible with private browsing modes, which cause all in-browser storage mechanisms to either persist only for the lifetime of the browsing session or fail outright.
Note:
Adding additional properties directly to save data objects is not recommended. Instead, use the property.
metadata
A save data object has the following properties:
date
: () The save's creation date (in milliseconds elapsed since epoch).integer
desc
: () The save's description.string
id
: () The save ID. See the Config.saves.id
for details.string
metadata
: (optional, ) The save's metadata, which must be JSON-serializable. Exists only if specified. See the appropriate save API or Config.saves.metadata
for details.any
state
: () The marshaled story state. See below for details.object
type
: () The save's type. See Save.Type
for details.Save.Type
version
: (optional, ) The save's version. Exists only if specified. See Config.saves.version
for details.any
The marshaled story state object, from the state
property, has the following properties:
expired
: (optional, ) The array of expired moment passage titles. Exists only if any moments have expired.Array<string>
history
: () The array of moment objects. See below for details.Array<object>
index
: () The index of the active moment.integer
seed
: (optional, ) The seed of the seedable PRNG. Exists only if enabled.string
Each moment object, from the history
property's array, has the following properties:
pull
: (optional, ) The current pull count of the seedable PRNG. Exists only if enabled.integer
title
: () The name of the associated passage.string
variables
: () The current variable store object, which contains sigil-less name ⇒ value pairs—e.g., exists as the property .object
$foo
foo
Save descriptor objects are only provided for browser saves and are identical to save data objects save that they do not include a propertystate
Save.Type
Save types pseudo-enumeration. Used to denote the type of save.
v2.33.0
: Introduced.v2.37.0
: Changed into a public API.Type | Description |
---|---|
Save.Type.Auto |
Browser auto saves. |
Save.Type.Base64 |
Base64 string saves. |
Save.Type.Disk |
Disk saves. |
Save.Type.Slot |
Browser slot saves. |
Save.browser.size
→ integer
The total number of existing browser saves, both auto and slot.
v2.37.0
: Introduced.The count of existing browser saves.integer
console.log(`There are currently ${Save.browser.size} browser saves`);
if (Save.browser.size > 0) {
/* Browser saves exist. */
}
if (Save.browser.size === 0) {
/* No browser saves exist. */
}
Save.browser.clear()
Deletes all existing browser saves, both auto and slot.
v2.37.0
: Introduced.Save.browser.clear();
Save.browser.continue()
→ Promise
Loads the most recent browser save, either auto or slot.
Note: The default UI includes a Continue button that makes use of this API. Thus, unless you disable or replace the default UI, players already have access to this functionality.
Warning: Saves cannot be loaded during startup and any attempt to do so will cause an error.
v2.37.0
: Introduced.A that simply resolves, or rejects with an error if the save could not be loaded.Promise
Load the most recent browser save, only handling failure. This should be sufficient in the majority of cases.
if (Save.browser.size > 0) {
Save.browser.continue()
.catch(error => {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
});
}
else {
/* No browser saves exist. */
}
Load the most recent browser save, handling both success and failure.
if (Save.browser.size > 0) {
Save.browser.continue()
.then(() => {
/* Success. Do something special. */
})
.catch(error => {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
});
}
else {
/* No browser saves exist. */
}
Save.browser.isEnabled()
→ boolean
Determines whether any browser saves are enabled, either auto, slot, or both.
v2.37.0
: Introduced.Boolean if any browser saves are enabled, elsewise .true
false
if (Save.browser.isEnabled()) {
/* Some browser saves are enabled. */
}
Save.browser.auto.size
→ integer
The total number of existing browser auto saves.
v2.37.0
: Introduced.The count of existing browser auto saves.integer
console.log(`There are currently ${Save.browser.auto.size} browser auto saves`);
if (Save.browser.auto.size > 0) {
/* Browser auto saves exist. */
}
if (Save.browser.auto.size === 0) {
/* No browser auto saves exist. */
}
Save.browser.auto.clear()
Deletes all existing auto saves.
v2.37.0
: Introduced.Save.browser.auto.clear();
Save.browser.auto.delete(index)
Deletes the auto save at the given index.
v2.37.0
: Introduced.index
: () Auto save index (-based). Must be in the range –.integer
0
0
Config.saves.maxAutoSaves
An instance.Error
Delete the auto save at the given index, handling failure.
try {
Save.browser.auto.delete(index);
}
catch (error) {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
}
Save.browser.auto.entries()
→ Array<object>
Provides an array of details about all auto saves.
v2.37.0
: Introduced.An of generic objects, or an empty if no auto saves exist.Array
{ index, info }
Array
index
: () The auto save's index (-based).integer
0
info
: () The save's descriptor object.object
An instance.Error
Save.browser.auto.entries().forEach(function (entry) {
console.log(`Descriptor of the auto save at index ${entry.index}:`, entry.info);
});
Save.browser.auto.get(index)
→ object
Details the auto save at the given index.
v2.37.0
: Introduced.index
: () Auto save index (-based). Must be in the range –.integer
0
0
Config.saves.maxAutoSaves
The descriptor object for the auto save if it exists, elsewise .null
An instance.Error
console.log(`Descriptor of the auto save at index ${index}:`, Save.browser.auto.get(index));
Save.browser.auto.has(index)
→ boolean
Determines whether the auto save at the given index exists.
v2.37.0
: Introduced.index
: () Auto save index (-based). Must be in the range –.integer
0
0
Config.saves.maxAutoSaves
Boolean if the auto save exists, elsewise .true
false
An instance.Error
if (Save.browser.auto.has(index)) {
/* The auto save at the given index exists. */
}
Save.browser.auto.isEnabled()
→ boolean
Determines whether auto saves are enabled.
v2.37.0
: Introduced.Boolean if auto saves are anabled, elsewise .true
false
if (Save.browser.auto.isEnabled()) {
/* Auto saves are enabled. */
}
Save.browser.auto.load(index)
→ Promise
Loads the auto save at the given index.
Warning: Saves cannot be loaded during startup and any attempt to do so will cause an error.
v2.37.0
: Introduced.index
: () Auto save index (-based). Must be in the range –.integer
0
0
Config.saves.maxAutoSaves
A that simply resolves, or rejects with an error if the save could not be loaded.Promise
Load the auto save at the given index. This should be sufficient in the majority of cases.
Save.browser.auto.load(index)
.then(() => {
Engine.show();
})
.catch(error => {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
});
Save.browser.auto.save([desc [, metadata]])
Saves an auto save. If all auto save positions are full, replaces the oldest auto save.
v2.37.0
: Introduced.desc
: (optional, ) The description of the auto save. If omitted or , defaults to the active passage's description.string
null
metadata
: (optional, ) The data to be stored in the save object's property. Must be JSON-serializable.any
metadata
An instance.Error
Save an auto save with the default description and no metadata, handling failure.
try {
Save.browser.auto.save();
}
catch (error) {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
}
Save an auto save with a description and no metadata, handling failure.
try {
Save.browser.auto.save("In the wilds");
}
catch (error) {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
}
Save an auto save with the default description and metadata, handling failure.
try {
const saveMetadata = {
chars : ['Celes', 'Locke', 'Edward'],
gold : 2345
};
Save.browser.auto.save(null, saveMetadata);
}
catch (error) {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
}
Save an auto save with a description and metadata, handling failure.
try {
const saveMetadata = {
chars : ['Celes', 'Locke', 'Edward'],
gold : 2345
};
Save.browser.auto.save("In the wilds", saveMetadata);
}
catch (error) {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
}
Save.browser.slot.size
→ integer
The total number of existing browser slot saves.
v2.37.0
: Introduced.The count of existing browser slot saves.integer
console.log(`There are currently ${Save.browser.slot.size} browser slot saves`);
if (Save.browser.slot.size > 0) {
/* Browser slot saves exist. */
}
if (Save.browser.slot.size === 0) {
/* No browser slot saves exist. */
}
Save.browser.slot.clear()
Deletes all existing slot saves.
v2.37.0
: Introduced.Save.browser.slot.clear();
Save.browser.slot.delete(index)
Deletes the slot save at the given index.
v2.37.0
: Introduced.index
: () Slot save index (-based). Must be in the range –.integer
0
0
Config.saves.maxSlotSaves
An instance.Error
Delete the slot save at the given index, handling failure.
try {
Save.browser.slot.delete(index);
}
catch (error) {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
}
Save.browser.slot.entries()
→ Array<object>
Provides an array of details about all slot saves.
v2.37.0
: Introduced.An of generic objects, or an empty if no slot saves exist.Array
{ index, info }
Array
index
: () The slot save's index (-based).integer
0
info
: () The save's descriptor object.object
An instance.Error
Save.browser.slot.entries().forEach(function (entry) {
console.log(`Descriptor of the slot save at index ${entry.index}:`, entry.info);
});
Save.browser.slot.get(index)
→ object
Details the slot save at the given index.
v2.37.0
: Introduced.index
: () Slot save index (-based). Must be in the range –.integer
0
0
Config.saves.maxSlotSaves
The descriptor object for the slot save if it exists, elsewise .null
An instance.Error
console.log(`Descriptor of the slot save at index ${index}:`, Save.browser.slot.get(index));
Save.browser.slot.has(index)
→ boolean
Determines whether the slot save at the given index exists.
v2.37.0
: Introduced.index
: () Slot save index (-based). Must be in the range –.integer
0
0
Config.saves.maxSlotSaves
Boolean if the slot save exists, elsewise .true
false
An instance.Error
if (Save.browser.slot.has(index)) {
/* The slot save at the given index exists. */
}
Save.browser.slot.isEnabled()
→ boolean
Determines whether slot saves are enabled.
v2.37.0
: Introduced.Boolean if slot saves are anabled, elsewise .true
false
if (Save.browser.slot.isEnabled()) {
/* Slot saves are enabled. */
}
Save.browser.slot.load(index)
→ Promise
Loads the slot save at the given index.
Warning: Saves cannot be loaded during startup and any attempt to do so will cause an error.
v2.37.0
: Introduced.index
: () Slot save index (-based). Must be in the range –.integer
0
0
Config.saves.maxSlotSaves
A that simply resolves, or rejects with an error if the save could not be loaded.Promise
Load the slot save at the given index. This should be sufficient in the majority of cases.
Save.browser.slot.load(index)
.then(() => {
Engine.show();
})
.catch(error => {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
});
Save.browser.slot.save(index, [desc [, metadata]])
Saves a slot save to the given index.
v2.37.0
: Introduced.index
: () Slot save index (-based). Must be in the range –.integer
0
0
Config.saves.maxSlotSaves
desc
: (optional, ) The description of the slot save. If omitted or , defaults to the active passage's description.string
null
metadata
: (optional, ) The data to be stored in the save object's property. Must be JSON-serializable.any
metadata
An instance.Error
Save to slot save index with the default description and no metadata, handling failure.0
try {
Save.browser.slot.save(0);
}
catch (error) {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
}
Save to slot save index with a description and no metadata, handling failure.0
try {
Save.browser.slot.save(0, "In the wilds");
}
catch (error) {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
}
Save to slot save index with the default description and metadata, handling failure.0
try {
const saveMetadata = {
chars : ['Celes', 'Locke', 'Edward'],
gold : 2345
};
Save.browser.slot.save(0, null, saveMetadata);
}
catch (error) {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
}
Save to slot save index with a description and metadata, handling failure.0
try {
const saveMetadata = {
chars : ['Celes', 'Locke', 'Edward'],
gold : 2345
};
Save.browser.slot.save(0, "In the wilds", saveMetadata);
}
catch (error) {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
}
Save.disk.export(filename)
Exports all existing browser saves as a bundle to disk, which may be restored via Save.disk.import()
.
v2.37.0
: Introduced.filename
: () The base filename of the browser save export, which gets slugified to remove most symbols. Appended to this is a datestamp (format: ) and the file extension —e.g., would result in the full filename: .string
YYYMMDD-hhmmss
.savesbundle
"The Scooby Chronicles"
the-scooby-chronicles-{datestamp}.savesbundle
An instance.Error
Export all saves as a bundle with a base filename, handling failure.
try {
Save.disk.export('The 6th Fantasy');
}
catch (error) {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
}
Save.disk.import(event)
→ Promise
Imports a saves bundle from disk, created via Save.disk.export()
.
Note:
This method must be used as, or be called by, the event handler of an element.
change
<input type="file">
Warning: All existing browser saves will be deleted as part of restoring the exported save bundle.
v2.37.0
: Introduced.event
: () The event object that was passed to the event handler of the associated element.Event
change
<input type="file">
A that simply resolves, or rejects with an error if the browser saves bundle could not be imported.Promise
Import the saves bundle from disk, only handling failure. This should be sufficient in the majority of cases.
jQuery(document.createElement('input'))
.prop({
id : 'saves-import-file',
name : 'saves-import-file',
type : 'file'
})
.on('change', ev => {
// You must provide the event to Save.disk.import()
Save.disk.import(ev)
.catch(error => {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
});
});
Import the saves bundle from disk, handling both success and failure.
jQuery(document.createElement('input'))
.prop({
id : 'saves-import-file',
name : 'saves-import-file',
type : 'file'
})
.on('change', function (ev) {
// You must provide the event to Save.browser.import()
Save.disk.import(ev)
.then(() => {
/* Success. Do something special. */
})
.catch(error => {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
});
});
Save.disk.load(event)
→ Promise
Loads the given save from disk, created via Save.disk.save()
.
Note:
This method must be used as, or be called by, the event handler of an element.
change
<input type="file">
Warning: Saves cannot be loaded during startup and any attempt to do so will cause an error.
v2.37.0
: Introduced.event
: () The event object that was passed to the event handler of the associated element.Event
change
<input type="file">
A that resolves with the save's metadata (), or rejects with an error if the save could not be loaded.Promise
any
Load the disk save. This should be sufficient in the majority of cases.
jQuery(document.createElement('input'))
.prop({
id : 'saves-disk-load-file',
name : 'saves-disk-load-file',
type : 'file'
})
.on('change', ev => {
// You must provide the event to Save.disk.load()
Save.disk.load(ev)
.then(metadata => {
Engine.show();
})
.catch(error => {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
});
});
<<button "Load From Disk">>
<<script>>
jQuery(document.createElement('input'))
.prop('type', 'file')
.on('change', ev => {
// You must provide the event to Save.disk.load()
Save.disk.load(ev)
.then(metadata => {
Engine.show();
})
.catch(error => {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
});
})
.trigger('click');
<</script>>
<</button>>
Save.disk.save(filename [, metadata])
Saves the current story state to disk, which may be restored via Save.disk.load()
.
v2.37.0
: Introduced.filename
: () The base filename of the disk save, which gets slugified to remove most symbols. Appended to this is a datestamp (format: ) and the file extension —e.g., would result in the full filename: .string
YYYMMDD-hhmmss
.save
"The Scooby Chronicles"
the-scooby-chronicles-{datestamp}.save
metadata
: (optional, ) The data to be stored in the save object's property. Must be JSON-serializable.any
metadata
An instance.Error
Save with a base filename and no metadata, handling failure.
try {
Save.disk.save("The 6th Fantasy");
}
catch (error) {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
}
Save with a base filename and metadata, handling failure.
try {
const saveMetadata = {
chars : ['Celes', 'Locke', 'Edward'],
gold : 2345
};
Save.disk.save("The 6th Fantasy", saveMetadata);
}
catch (error) {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
}
Save.base64.export()
→ string
Exports all existing browser saves as a bundle to a Base64 string, which may be restored via Save.base64.import()
.
v2.37.0
: Introduced.An instance.Error
Export all saves as a bundle, handling failure.
try {
const base64Save = Save.base64.export();
/* Do something with the saves bundle. */
}
catch (error) {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
}
Save.base64.import(bundle)
→ Promise
Imports the given Base64 saves bundle string, created via Save.base64.export()
.
Warning: All existing browser saves will be deleted as part of restoring the exported save bundle.
v2.37.0
: Introduced.bundle
: () The Base64 saves bundle string.string
A that simply resolves, or rejects with an error if the browser saves bundle could not be imported.Promise
Import the saves bundle, only handling failure. This should be sufficient in the majority of cases.
Save.base64.import(base64Bundle)
.catch(error => {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
});
Import the saves bundle, handling both success and failure.
Save.base64.import(base64Bundle)
.then(() => {
/* Success. Do something special. */
})
.catch(error => {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
});
Save.base64.load(save)
→ Promise
Loads the given Base64 save string, created via Save.base64.save()
.
Warning: Saves cannot be loaded during startup and any attempt to do so will cause an error.
v2.37.0
: Introduced.save
: () The Base64 save string.string
A that resolves with the save's metadata (), or rejects with an error if the save could not be loaded.Promise
any
Load the save string. This should be sufficient in the majority of cases.
Save.base64.load(base64Save)
.then(metadata => {
Engine.show();
})
.catch(error => {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
});
Save.base64.save([metadata])
→ string
Saves the current story state as a Base64 string.
v2.37.0
: Introduced.metadata
: (optional, ) The data to be stored in the save object's property. Must be JSON-serializable.any
metadata
A Base64 save .string
An instance.Error
Save without metadata, handling failure.
try {
const base64Save = Save.base64.save();
/* Do something with the save. */
}
catch (error) {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
}
Save with metadata, handling failure.
try {
const saveMetadata = {
chars : ['Celes', 'Locke', 'Edward'],
gold : 2345
};
const base64Save = Save.base64.save(saveMetadata);
/* Do something with the save. */
}
catch (error) {
/* Failure. Handle the error. */
console.error(error);
UI.alert(error);
}
Save.onLoad.size
→ integer
The total number of currently registered on-load handlers.
v2.36.0
: Introduced.The count of currently registered on-load handlers.integer
console.log('There are %d onLoad handlers registered.', Save.onLoad.size);
Save.onLoad.add(handler)
Performs any required processing before the save data is loaded—e.g., upgrading out-of-date save data. The handler is passed one parameter, the save object to be processed. If it encounters an unrecoverable problem during its processing, it may throw an exception containing an error message; the message will be displayed to the player and loading of the save will be terminated.
v2.36.0
: Introduced.handler
: (function) The handler function to be executed upon the loading of a save.An instance.Error
save
: () The save object to be processed.object
Save.onLoad.add(function (save) {
/* code to process the save object before it's loaded */
});
type
Save.Type
Save.onLoad.add(function (save) {
switch (save.type) {
case Save.Type.Auto: {
/* code to process an auto save object before it's loaded */
break;
}
case Save.Type.Base64: {
/* code to process a base64 save object before it's loaded */
break;
}
case Save.Type.Disk: {
/* code to process a disk save object before it's loaded */
break;
}
case Save.Type.Slot: {
/* code to process a slot save object before it's loaded */
break;
}
}
});
Save.onLoad.clear()
Deletes all currently registered on-load handlers.
v2.36.0
: Introduced.Save.onLoad.clear();
Save.onLoad.delete(handler)
→ boolean
Deletes the specified on-load handler.
v2.36.0
: Introduced.handler
: (function) The handler function to be deleted.Boolean if the handler existed, elsewise .true
false
// Given:
// let myOnLoadHandler = function (save) {
// /* code to process the save object before it's loaded */
// };
// Save.onLoad.add(myOnLoadHandler);
Save.onLoad.delete(myOnLoadHandler);
Save.onSave.size
→ integer
The total number of currently registered on-save handlers.
v2.36.0
: Introduced.The count of currently registered on-save handlers.integer
console.log('There are %d onSave handlers registered.', Save.onSave.size);
Save.onSave.add(handler)
Performs any required processing before the save data is saved. The handler is passed one parameter, the save object to be processed.
v2.36.0
: Introduced.v2.37.0
: Deprecated handlers' parameter.details
handler
: (function) The handler function to be executed upon the saving of a save.An instance.Error
save
: () The save object to be processed.object
Save.onSave.add(function (save) {
/* code to process the save object before it's saved */
});
type
Save.Type
Save.onSave.add(function (save) {
switch (save.type) {
case Save.Type.Auto: {
/* code to process an auto save object before it's saved */
break;
}
case Save.Type.Base64: {
/* code to process a base64 save object before it's saved */
break;
}
case Save.Type.Disk: {
/* code to process a disk save object before it's saved */
break;
}
case Save.Type.Slot: {
/* code to process a slot save object before it's saved */
break;
}
}
});
Save.onSave.clear()
Deletes all currently registered on-save handlers.
v2.36.0
: Introduced.Save.onSave.clear();
Save.onSave.delete(handler)
→ boolean
Deletes the specified on-save handler.
v2.36.0
: Introduced.handler
: (function) The handler function to be deleted.Boolean if the handler existed, elsewise .true
false
// Given:
// let myOnSaveHandler = function (save) {
// /* code to process the save object before it's saved */
// };
// Save.onSave.add(myOnSaveHandler);
Save.onSave.delete(myOnSaveHandler);
Save.clear()
Deprecated:
This method has been deprecated and should no longer be used. See the Save.browser.clear()
method for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of the method.Save.browser.clear()
Save.get()
Deprecated: This method has been deprecated and should no longer be used.
v2.0.0
: Introduced.v2.37.0
: Deprecated.Save.ok()
→ boolean
Deprecated:
This method has been deprecated and should no longer be used. See the Save.browser.isEnabled()
method for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of the method.Save.browser.isEnabled()
Save.autosave.delete()
Deprecated:
This method has been deprecated and should no longer be used. See the Save.browser.auto.delete()
method for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of the method.Save.browser.auto.delete()
Save.autosave.get()
→ object
Deprecated:
This method has been deprecated and should no longer be used. See the Save.browser.auto.get()
method for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of the method.Save.browser.auto.get()
Save.autosave.has()
→ boolean
Deprecated:
This method has been deprecated and should no longer be used. See the Save.browser.auto.has()
method for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of the method.Save.browser.auto.has()
Save.autosave.load()
Deprecated:
This method has been deprecated and should no longer be used. See the Save.browser.auto.load()
method for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of the method.Save.browser.auto.load()
Save.autosave.ok()
→ boolean
Deprecated:
This method has been deprecated and should no longer be used. See the Save.browser.auto.isEnabled()
method for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of the method.Save.browser.auto.isEnabled()
Save.autosave.save([title [, metadata]])
Deprecated:
This method has been deprecated and should no longer be used. See the Save.browser.auto.save()
method for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of the method.Save.browser.auto.save()
Save.slots.length
→ integer
Deprecated:
This method has been deprecated and should no longer be used. See the Save.browser.slot.size
property for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of the property.Save.browser.slot.size
Save.slots.count()
→ integer
Deprecated: This method has been deprecated and should no longer be used.
v2.0.0
: Introduced.v2.37.0
: Deprecated.Save.slots.delete(slot)
Deprecated:
This method has been deprecated and should no longer be used. See the Save.browser.slot.delete()
method for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of the method.Save.browser.slot.delete()
Save.slots.get(slot)
→ object
Deprecated:
This method has been deprecated and should no longer be used. See the Save.browser.slot.get()
method for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of the method.Save.browser.slot.get()
Save.slots.has(slot)
→ boolean
Deprecated:
This method has been deprecated and should no longer be used. See the Save.browser.slot.has()
method for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of the method.Save.browser.slot.has()
Save.slots.isEmpty()
→ boolean
Deprecated: This method has been deprecated and should no longer be used.
v2.0.0
: Introduced.v2.37.0
: Deprecated.Save.slots.load(slot)
Deprecated:
This method has been deprecated and should no longer be used. See the Save.browser.slot.load()
method for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of the method.Save.browser.slot.load()
Save.slots.ok()
→ boolean
Deprecated:
This method has been deprecated and should no longer be used. See the Save.browser.slot.isEnabled()
method for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of the method.Save.browser.slot.isEnabled()
Save.slots.save(slot [, title [, metadata]])
Deprecated:
This method has been deprecated and should no longer be used. See the Save.browser.slot.save()
method for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of the method.Save.browser.slot.save()
Save.import(event)
Deprecated:
This method has been deprecated and should no longer be used. See the Save.disk.load()
method for its replacement.
v2.0.0
: Introduced.v2.37.0
: Deprecated in favor of the method.Save.disk.load()
Save.export([filename [, metadata]])
Deprecated:
This method has been deprecated and should no longer be used. See the Save.disk.save()
method for its replacement.
v2.0.0
: Introduced.v2.8.0
: Added parameter.metadata
v2.37.0
: Deprecated in favor of the method.Save.disk.save()
Save.deserialize(saveStr)
→ any
| null
Deprecated:
This method has been deprecated and should no longer be used. See the Save.base64.load()
method for its replacement.
v2.21.0
: Introduced.v2.37.0
: Deprecated in favor of the method.Save.base64.load()
Save.serialize([metadata])
→ string
| null
Deprecated:
This method has been deprecated and should no longer be used. See the Save.base64.save()
method for its replacement.
v2.21.0
: Introduced.v2.37.0
: Deprecated in favor of the method.Save.base64.save()
Setting
API Manages the Settings dialog and settings
object.
Warning:
API method calls must be placed within your project's JavaScript section (Twine 2: the Story JavaScript; Twine 1/Twee: a -tagged passage) or settings will not function correctly.
Setting
script
Setting.addHeader(name [, desc])
Adds a header to the Settings dialog.
v2.7.1
: Introduced.name
: (string) Name of the header.desc
: (optional, string) Description explaining the header in greater detail. May contain markup.// Setting up a basic header
Setting.addHeader("Content Settings");
// Setting up a header w/ a description
Setting.addHeader("Content Settings", "Settings controlling what content is made available in the game.");
Setting.addList(name, definition)
Adds the named property to the object and a list control for it to the Settings dialog.settings
v2.0.0
: Introduced.v2.26.0
: Added property to definition object.desc
name
: (string) Name of the property to add, which the control will manage.settings
definition
: (object) Definition of the setting and control.A list-type definition object should have some of the following properties:
label
: (string) Label to use for the control.list
: (Array<string>) The array of members.desc
: (optional, string) Description explaining the control in greater detail. May contain markup.default
: (optional, [as list
array]) The default value for the setting and default state of the control. It should have the same value as one of the members of the list
array. Leaving it undefined means to use the first array member as the default.onInit
: (optional, function) The function to call during initialization. It is called with a result object as its sole parameter and, if possible, set as its .this
onChange
: (optional, function) The function to call when the control's state is changed. It is called with a result object as its sole parameter and, if possible, set as its .this
name
: (string) Name of the property.settings
value
: ([as list
array]) The current value of the setting.default
: ([as list
array]) The default value for the setting.list
: (Array<string>) The array of members.// Setting up a basic list control for the settings property 'difficulty'
Setting.addList("difficulty", {
label : "Choose a difficulty level.",
list : ["Easy", "Normal", "Hard", "INSANE"],
default : "Normal"
});
// Setting up a list control for the settings property 'theme' w/ callbacks
var settingThemeNames = ["(none)", "Bright Lights", "Charcoal", "Midnight", "Tinsel City"];
var settingThemeHandler = function () {
// cache the jQuery-wrapped <html> element
var $html = $("html");
// remove any existing theme class
$html.removeClass("theme-bright-lights theme-charcoal theme-midnight theme-tinsel-city");
// switch on the theme name to add the requested theme class
switch (settings.theme) {
case "Bright Lights":
$html.addClass("theme-bright-lights");
break;
case "Charcoal":
$html.addClass("theme-charcoal");
break;
case "Midnight":
$html.addClass("theme-midnight");
break;
case "Tinsel City":
$html.addClass("theme-tinsel-city");
break;
}
};
Setting.addList("theme", {
label : "Choose a theme.",
list : settingThemeNames,
onInit : settingThemeHandler,
onChange : settingThemeHandler
}); // default value not defined, so the first array member "(none)" is used
Setting.addRange(name, definition)
Adds the named property to the object and a range control for it to the Settings dialog.settings
v2.26.0
: Introduced.name
: (string) Name of the property to add, which the control will manage.settings
definition
: (object) Definition of the setting and control.A range-type definition object should have some of the following properties:
label
: (string) Label to use for the control.max
: (number) The maximum value.min
: (number) The minimum value.step
: (number) Limits the increments to which the value may be set. It must be evenly divisible into the full range—i.e., .max - min
desc
: (optional, string) Description explaining the control in greater detail. May contain markup.default
: (optional, number) The default value for the setting and default state of the control. Leaving it undefined means to use the value of as the default.max
onInit
: (optional, function) The function to call during initialization. It is called with a result object as its sole parameter and, if possible, set as its .this
onChange
: (optional, function) The function to call when the control's state is changed. It is called with a result object as its sole parameter and, if possible, set as its .this
name
: (string) Name of the property.settings
value
: (number) The current value of the setting.default
: (number) The default value for the setting.max
: (number) The maximum value for the setting.min
: (number) The minimum value for the setting.step
: (number) The step value for the setting.// Setting up a volume control for the settings property 'masterVolume' w/ callback
var settingMasterVolumeHandler = function () {
SimpleAudio.volume(settings.masterVolume / 10);
};
Setting.addRange("masterVolume", {
label : "Master volume.",
min : 0,
max : 10,
step : 1,
onInit : settingMasterVolumeHandler,
onChange : settingMasterVolumeHandler
}); // default value not defined, so max value (10) is used
Setting.addToggle(name, definition)
Adds the named property to the object and a toggle control for it to the Settings dialog.settings
v2.0.0
: Introduced.v2.26.0
: Added property to definition object.desc
name
: (string) Name of the property to add, which the control will manage.settings
definition
: (object) Definition of the setting and control.A toggle-type definition object should have some of the following properties:
label
: (string) Label to use for the control.desc
: (optional, string) Description explaining the control in greater detail. May contain markup.default
: (optional, boolean) The default value for the setting and default state of the control. Leaving it undefined means to use as the default.false
onInit
: (optional, function) The function to call during initialization. It is called with a result object as its sole parameter and, if possible, set as its .this
onChange
: (optional, function) The function to call when the control's state is changed. It is called with a result object as its sole parameter and, if possible, set as its .this
name
: (string) Name of the property.settings
value
: (boolean) The current value of the setting.default
: (boolean) The default value for the setting.// Setting up a basic toggle control for the settings property 'mature'
Setting.addToggle("mature", {
label : "Content for mature audiences?"
}); // default value not defined, so false is used
// Setting up a toggle control for the settings property 'widescreen' w/ callbacks
var settingWidescreenHandler = function () {
if (settings.widescreen) { // is true
$("html").addClass("widescreen");
}
else { // is false
$("html").removeClass("widescreen");
}
};
Setting.addToggle("widescreen", {
label : "Allow the story to use the full width of your browser window?",
default : false,
onInit : settingWidescreenHandler,
onChange : settingWidescreenHandler
});
And the requisite CSS style rule:
html.widescreen #passages {
max-width: none;
}
Setting.addValue(name [, definition])
Adds the named property to the object.settings
Note: Does not add a control to the Settings dialog.
v2.37.0
: Introduced.name
: (string) Name of the property to add.settings
definition
: (optional, object) Definition of the setting. May be omitted.A value-type definition object should have some of the following properties:
default
: (optional, any) The default value for the setting.onInit
: (optional, function) The function to call during initialization. It is called with a result object as its sole parameter and, if possible, set as its .this
onChange
: (optional, function) The function to call when the control's state is changed. It is called with a result object as its sole parameter and, if possible, set as its .this
name
: (string) Name of the property.settings
value
: (any) The current value of the setting.default
: (any) The default value for the setting.Setting.addValue("someSetting");
Setting.addValue("anotherSetting", {
default : 42,
onInit : function () {
/* Do something when the setting is initialized. */
},
onChange : function () {
/* Do something when the setting is changed. */
}
});
Setting.getValue(name)
→ any
Returns the setting's current value.
Note:
Calling this method is equivalent to using .
settings[name]
v2.37.0
: Introduced.// Assume `disableAudio` is a toggle-type setting.
if (Setting.getValue("disableAudio")) {
/* Audio should be disabled. */
}
Setting.load()
Loads the settings from storage.
Note: This method is automatically called during startup, so you should never need to call it manually.
v2.0.0
: Introduced.Setting.load();
Setting.reset([name])
Resets the setting with the given name to its default value. If no name is given, resets all settings.
v2.0.0
: Introduced.name
: (optional, string) Name of the object property to reset.settings
// Reset the setting 'difficulty'
Setting.reset("difficulty");
// Reset all settings
Setting.reset();
Setting.save()
Saves the settings to storage.
Note:
The controls of the Settings dialog and the Setting.setValue()
method automatically call this method when settings are changed, so you should normally never need to call this method manually. Only when directly modifying the values of object properties, outside of the controls or method, would you need to call this method.
settings
Setting.setValue()
v2.0.0
: Introduced.Setting.save();
Setting.setValue(name, value)
Sets the setting's value.
Note:
This method automatically calls the Setting.save()
method.
Warning: If manually changing a setting that has an associated control, be mindful that the value you set makes sense for the setting in question, elsewise shenanigans could occur—e.g., don't set a range-type setting to non-number or out-of-range values.
v2.37.0
: Introduced.name
: (string) Name of the property.settings
value
: (any) The new value for the setting.Setting.setValue("theme", "dark");
settings
object A prototype-less generic object whose properties and values are defined by the Setting.addList()
, Setting.addRange()
, Setting.addToggle()
, and Setting.addValue()
methods.
For all types of setting types except value-types, the values of its properties are automatically managed by the Settings dialog controls. If necessary, you may manually change setting values via the Setting.setValue()
method.
Note:
You may also manually change setting values by assigning directly to the associated property—e.g., . Doing so, however, does not automatically save any values so updated, thus you must manually call the Setting.save()
method afterwards.
settings["mode"] = "day"
Warning: If manually changing a setting that has an associated control, be mindful that the value you set makes sense for the setting in question, elsewise shenanigans could occur—e.g., don't set a range-type setting to non-number or out-of-range values.
v2.0.0
: Introduced.SimpleAudio
API The core audio subsystem and backend for the audio macros.
See Also:
AudioTrack
API, AudioRunner
API, and AudioList
API.
The audio subsystem is based upon the HTML Media Elements APIs and comes with some built-in limitations:
<<timed>>
SimpleAudio.load()
Pauses playback of all currently registered tracks and, if they're not already in the process of loading, force them to drop any existing data and begin loading.
Warning: This should not be done lightly if your audio sources are on the network, as it forces players to begin downloading them.
v2.28.0
: Introduced.SimpleAudio.load();
SimpleAudio.loadWithScreen()
Displays the loading screen until all currently registered audio tracks have either loaded to a playable state or aborted loading due to errors. The loading process is as described in SimpleAudio.load()
.
Warning: This should not be done lightly if your audio sources are on the network, as it forces players to begin downloading them.
v2.28.0
: Introduced.SimpleAudio.loadWithScreen();
SimpleAudio.mute([state])
→ get: boolean | set: undefined Gets or sets the mute state for the master volume (default: ).false
v2.28.0
: Introduced.state
: (optional, boolean) The mute state.// Get the current master volume mute state.
var isMuted = SimpleAudio.mute();
// Mute the master volume.
SimpleAudio.mute(true);
// Unmute the master volume.
SimpleAudio.mute(false);
SimpleAudio.muteOnHidden([state])
→ get: boolean | set: undefined Gets or sets the mute-on-hidden state for the master volume (default: ). The mute-on-hidden state controls whether the master volume is automatically muted/unmuted when the story's browser tab loses/gains visibility. Loss of visibility is defined as when the browser window is either switched to another tab or minimized.false
v2.28.0
: Introduced.state
: (optional, boolean) The mute-on-hidden state.// Get the current master volume mute-on-hidden state.
var isMuteOnHidden = SimpleAudio.muteOnHidden();
// Enable automatic muting of the master volume when visibility is lost.
SimpleAudio.muteOnHidden(true);
// Disable automatic muting of the master volume when visibility is lost.
SimpleAudio.muteOnHidden(false);
SimpleAudio.select(selector)
→ AudioRunner
object Returns an AudioRunner
instance for the tracks matching the given selector.
v2.28.0
: Introduced.v2.37.0
: Added predefined group ID.:stopped
selector
: (string) The list of audio track(s) and/or group ID(s), separated by spaces. There are several predefined group IDs (, , , , , ). The group modifier syntax () allows a group to have some of its tracks excluded from selection.:all
:looped
:muted
:paused
:playing
:stopped
:not()
groupId:not(selector)
SimpleAudio.select(":ui") → Returns the AudioRunner instance for the tracks matching ":ui"
// Return the AudioTrack instance matching "swamped" and do something with it
SimpleAudio.select("swamped").volume(1).play();
// Start playback of paused audio tracks
SimpleAudio.select(":paused").play();
// Pause playback of playing audio tracks
SimpleAudio.select(":playing").pause();
// Stop playback of playing audio tracks
SimpleAudio.select(":playing").stop();
// Stop playback of all audio tracks (not uniquely part of a playlist)
SimpleAudio.select(":all").stop();
// Stop playback of playing audio tracks except those in the ":ui" group
SimpleAudio.select(":playing:not(:ui)").stop();
// Change the volume of all audio tracks except those in the ":ui" group
// to 40%, without changing the current playback state
SimpleAudio.select(":all:not(:ui)").volume(0.40);
SimpleAudio.stop()
Stops playback of all currently registered tracks.
v2.28.0
: Introduced.SimpleAudio.stop();
SimpleAudio.unload()
Stops playback of all currently registered tracks and force them to drop any existing data.
Note: Once a track has been unloaded, playback cannot occur until it is reloaded.
v2.28.0
: Introduced.SimpleAudio.unload();
SimpleAudio.volume([level])
→ get: number | set: undefined Gets or sets the master volume level (default: ).1
v2.28.0
: Introduced.level
: (optional, number) The volume level to set. Valid values are floating-point numbers in the range (silent) to (loudest)—e.g., is 0%, is 50%, is 100%.0
1
0
0.5
1
// Get the current master volume level.
var currentMasterVolume = SimpleAudio.volume();
// Set the master volume level to 75%.
SimpleAudio.volume(0.75);
SimpleAudio.tracks.add(trackId, sources…)
Adds an audio track with the given track ID.
v2.28.0
: Introduced.trackId
: (string) The ID of the track, which will be used to reference it.sources
: (string… | Array<string>) The audio sources for the track, which may be a list of sources or an array. Only one is required, though supplying additional sources in differing formats is recommended, as no single format is supported by all browsers. A source must be either a URL (absolute or relative) to an audio resource, the name of an audio passage, or a data URI. In rare cases where the audio format cannot be automatically detected from the source (URLs are parsed for a file extension, data URIs are parsed for the media type), a format specifier may be prepended to the front of each source to manually specify the format (syntax: , where is the audio format—generally, whatever the file extension would normally be; e.g., , , , , ).formatId|
formatId
mp3
mp4
ogg
weba
wav
// Cache a track with the ID "boom" and one source via relative URL
SimpleAudio.tracks.add("boom", "media/audio/explosion.mp3");
// Cache a track with the ID "boom" and one source via audio passage
SimpleAudio.tracks.add("boom", "explosion");
// Cache a track with the ID "bgm_space" and two sources via relative URLs
SimpleAudio.tracks.add("bgm_space", "media/audio/space_quest.mp3", "media/audio/space_quest.ogg");
// Cache a track with the ID "what" and one source via URL with a format specifier
SimpleAudio.tracks.add("what", "mp3|http://an-audio-service.com/a-user/a-track-id");
SimpleAudio.tracks.clear()
Deletes all audio tracks.
Note: Cannot delete tracks solely under the control of a playlist.
v2.28.0
: Introduced.SimpleAudio.tracks.clear();
SimpleAudio.tracks.delete(trackId)
Deletes the audio track with the given track ID.
Note: Cannot delete tracks solely under the control of a playlist.
Warning: Does not currently remove the track from either groups or playlists. Thus, any groups or playlists containing the deleted track should be rebuilt.
v2.28.0
: Introduced.trackId
: (string) The ID of the track.SimpleAudio.tracks.delete("bgm_space");
SimpleAudio.tracks.get(trackId)
→ AudioTrack
object | null Returns the AudioTrack
instance with the given track ID, or on failure.null
Note:
To affect multiple tracks and/or groups at once, see the SimpleAudio.select()
method.
v2.28.0
: Introduced.trackId
: (string) The ID of the track.SimpleAudio.tracks.get("swamped") → Returns the AudioTrack instance matching "swamped"
// Return the AudioTrack instance matching "swamped" and do something with it
SimpleAudio.tracks.get("swamped").volume(1).play();
SimpleAudio.tracks.has(trackId)
→ boolean Returns whether an audio track with the given track ID exists.
v2.28.0
: Introduced.trackId
: (string) The ID of the track.if (SimpleAudio.tracks.has("bgm_space")) {
// Track "bgm_space" exists.
}
SimpleAudio.groups.add(groupId, trackIds…)
Adds an audio group with the given group ID. Groups are useful for applying actions to multiple tracks simultaneously and/or excluding the included tracks from a larger set when applying actions.
Note: If you want to play tracks in a sequence, then you want a playlist instead.
v2.28.0
: Introduced.v2.37.0
: Added predefined group ID.:stopped
groupId
: (string) The ID of the group, which will be used to reference it and must begin with a colon. NOTE: There are several predefined group IDs (, , , , , ) and the group modifier that cannot be reused/overwritten.:all
:looped
:muted
:paused
:playing
:stopped
:not
trackIds
: (string… | Array<string>) The IDs of the tracks to make part of the group, which may be a list of track IDs or an array.// Set up a group ":ui" with the tracks: "ui_beep", "ui_boop", and "ui_swish"
SimpleAudio.groups.add(":ui", "ui_beep", "ui_boop", "ui_swish");
SimpleAudio.groups.clear()
Deletes all audio groups.
Note: Only deletes the groups themselves, does not affect their component tracks.
v2.28.0
: Introduced.SimpleAudio.groups.clear();
SimpleAudio.groups.delete(groupId)
Deletes the audio group with the given group ID.
Note: Only deletes the group itself, does not affect its component tracks.
v2.28.0
: Introduced.groupId
: (string) The ID of the group.SimpleAudio.groups.delete(":ui");
SimpleAudio.groups.get(groupId)
→ Array<string> | null Returns the array of track IDs with the given group ID, or on failure.null
Note:
To actually affect multiple tracks and/or groups, see the SimpleAudio.select()
method.
v2.28.0
: Introduced.groupId
: (string) The ID of the group.SimpleAudio.groups.get(":ui") → Returns the array of track IDs matching ":ui"
SimpleAudio.groups.has(groupId)
→ boolean Returns whether an audio group with the given group ID exists.
v2.28.0
: Introduced.groupId
: (string) The ID of the group.if (SimpleAudio.groups.has(":ui")) {
// Group ":ui" exists.
}
SimpleAudio.lists.add(listId, sources…)
Adds a playlist with the given list ID. Playlists are useful for playing tracks in a sequence—i.e., one after another.
Note: If you simply want to apply actions to multiple tracks simultaneously, then you want a group instead.
v2.28.0
: Introduced.v2.29.0
: Changed descriptor object property to .copy
own
listId
: (string) The ID of the list, which will be used to reference it.sources
: (string | object | Array<string | object>) The track IDs or descriptors of the tracks to make part of the list, which may be specified as a list or an array.Track descriptor objects come in two forms and should have some of the noted properties:
{ id, [own], [volume] }
id
: (string) The ID of an existing track.own
: (optional, boolean) When , signifies that the playlist should create its own independent copy of the track, rather than simply referencing the existing instance. Owned copies are solely under the control of their playlist and cannot be selected with either the SimpleAudio.tracks.get()
method or the SimpleAudio.select()
method.true
volume
: (optional, number) The base volume level of the track within the playlist. If omitted, defaults to the track's current volume. Valid values are floating-point numbers in the range (silent) to (loudest)—e.g., is 0%, is 50%, is 100%.0
1
0
0.5
1
{ sources, [volume] }
sources
: (Array<string>) The audio sources for the track. Only one is required, though supplying additional sources in differing formats is recommended, as no single format is supported by all browsers. A source must be either a URL (absolute or relative) to an audio resource, the name of an audio passage, or a data URI. In rare cases where the audio format cannot be automatically detected from the source (URLs are parsed for a file extension, data URIs are parsed for the media type), a format specifier may be prepended to the front of each source to manually specify the format (syntax: , where is the audio format—generally, whatever the file extension would normally be; e.g., , , , , ).formatId|
formatId
mp3
mp4
ogg
weba
wav
volume
: (optional, number) The base volume level of the track within the playlist. If omitted, defaults to (loudest). Valid values are floating-point numbers in the range (silent) to (loudest)—e.g., is 0%, is 50%, is 100%.1
0
1
0
0.5
1
// Add existing tracks at their current volumes
SimpleAudio.lists.add("bgm_lacuna", "swamped", "heavens_a_lie", "closer", "to_the_edge");
SimpleAudio.lists.add("bgm_lacuna",
// Add existing track "swamped" at its current volume
"swamped",
// Add existing track "heavens_a_lie" at 50% volume
{
id : "heavens_a_lie",
volume : 0.5
},
// Add an owned copy of existing track "closer" at its current volume
{
id : "closer",
own : true
},
// Add an owned copy of existing track "to_the_edge" at 100% volume
{
id : "to_the_edge",
own : true,
volume : 1
}
);
SimpleAudio.lists.add("bgm_lacuna",
// Add a track from the given sources at the default volume (100%)
{
sources : ["media/audio/Swamped.mp3"]
}
// Add a track from the given sources at 50% volume
{
sources : ["media/audio/Heaven's_A_Lie.mp3"],
volume : 0.5
},
// Add a track from the given sources at the default volume (100%)
{
sources : ["media/audio/Closer.mp3"]
},
// Add a track from the given sources at 100% volume
{
sources : ["media/audio/To_The_Edge.mp3"],
volume : 1
}
);
SimpleAudio.lists.clear()
Deletes all playlists.
v2.28.0
: Introduced.SimpleAudio.lists.clear();
SimpleAudio.lists.delete(listId)
Deletes the playlist with the given list ID.
v2.28.0
: Introduced.listId
: (string) The ID of the playlist.SimpleAudio.lists.delete("bgm_lacuna");
SimpleAudio.lists.get(listId)
→ AudioList
object | null Returns the AudioList
instance with the given list ID, or on failure.null
v2.28.0
: Introduced.listId
: (string) The ID of the playlist.SimpleAudio.lists.get("bgm_lacuna") → Returns the AudioList instance matching "bgm_lacuna"
// Return the AudioList instance matching "bgm_lacuna" and do something with it
SimpleAudio.lists.get("bgm_lacuna").volume(1).loop(true).play();
SimpleAudio.lists.has(listId)
→ boolean Returns whether a playlist with the given list ID exists.
v2.28.0
: Introduced.listId
: (string) The ID of the playlist.if (SimpleAudio.lists.has("bgm_lacuna")) {
// Playlist "bgm_lacuna" exists.
}
AudioTrack
API Audio tracks encapsulate and provide a consistent interface to an audio resource.
See Also:
SimpleAudio
API, AudioRunner
API, and AudioList
API.
<AudioTrack>.clone()
→ AudioTrack
object Returns a new independent copy of the track.
v2.28.0
: Introduced.var trackCopy = aTrack.clone();
<AudioTrack>.duration()
→ number Returns the track's total playtime in seconds, for a stream, or if no metadata exists.Infinity
NaN
v2.28.0
: Introduced.var trackLength = aTrack.duration();
<AudioTrack>.fade(duration , toVol [, fromVol])
→ Promise
object Starts playback of the track and fades it between the specified starting and destination volume levels over the specified number of seconds.
Note:
The Config.audio.pauseOnFadeToZero
setting (default: ) determines whether the audio subsystem automatically pauses tracks that have been faded to volume (silent).
true
0
v2.28.0
: Introduced.duration
: (number) The number of seconds over which the track should be faded.toVol
: (number) The destination volume level.fromVol
: (optional, number) The starting volume level. If omitted, defaults to the track's current volume level.// Fade the track from volume 0 to 1 over 6 seconds.
aTrack.fade(6, 1, 0);
<AudioTrack>.fadeIn(duration [, fromVol])
→ Promise
object Starts playback of the track and fades it from the specified volume level to (loudest) over the specified number of seconds.1
v2.28.0
: Introduced.v2.29.0
: Updated to return a .Promise
duration
: (number) The number of seconds over which the track should be faded.fromVol
: (optional, number) The starting volume level. If omitted, defaults to the track's current volume level.// Fade the track in from volume 0 over 5 seconds.
aTrack.fadeIn(5, 0);
<AudioTrack>.fadeOut(duration [, fromVol])
→ Promise
object Starts playback of the track and fades it from the specified volume level to (silent) over the specified number of seconds.0
Note:
The Config.audio.pauseOnFadeToZero
setting (default: ) determines whether the audio subsystem automatically pauses tracks that have been faded to volume (silent).
true
0
v2.28.0
: Introduced.v2.29.0
: Updated to return a .Promise
duration
: (number) The number of seconds over which the track should be faded.fromVol
: (optional, number) The starting volume level. If omitted, defaults to the track's current volume level.// Fade the track out from volume 1 over 8 seconds.
aTrack.fadeOut(8, 1);
<AudioTrack>.fadeStop()
Interrupts an in-progress fade of the track, or does nothing if no fade is progressing.
Note: This does not alter the volume level.
v2.28.0
: Introduced.aTrack.fadeStop();
<AudioTrack>.hasData()
→ boolean Returns whether enough data has been loaded to play the track through to the end without interruption.
Note: This is an estimate calculated by the browser based upon the currently downloaded data and the download rate.
v2.28.0
: Introduced.if (aTrack.hasData()) {
/* do something */
}
<AudioTrack>.hasMetadata()
→ boolean Returns whether, at least, the track's metadata has been loaded.
v2.28.0
: Introduced.if (aTrack.hasMetadata()) {
/* do something */
}
<AudioTrack>.hasNoData()
→ boolean Returns whether none of the track's data has been loaded.
v2.28.0
: Introduced.if (aTrack.hasNoData()) {
/* do something */
}
<AudioTrack>.hasSomeData()
→ boolean Returns whether, at least, some of the track's data has been loaded.
Tip:
The <AudioTrack>.hasData()
method is generally more useful.
v2.28.0
: Introduced.if (aTrack.hasSomeData()) {
/* do something */
}
<AudioTrack>.hasSource()
→ boolean Returns whether any valid sources were registered.
v2.28.0
: Introduced.if (aTrack.hasSource()) {
/* do something */
}
<AudioTrack>.isEnded()
→ boolean Returns whether playback of the track has ended.
v2.28.0
: Introduced.if (aTrack.isEnded()) {
/* do something */
}
<AudioTrack>.isFading()
→ boolean Returns whether a fade is in-progress on the track.
v2.28.0
: Introduced.if (aTrack.isFading()) {
/* do something */
}
<AudioTrack>.isFailed()
→ boolean Returns whether an error has occurred.
v2.28.0
: Introduced.if (aTrack.isFailed()) {
/* do something */
}
<AudioTrack>.isLoading()
→ boolean Returns whether the track is loading data.
v2.28.0
: Introduced.if (aTrack.isLoading()) {
/* do something */
}
<AudioTrack>.isPaused()
→ boolean Returns whether playback of the track has been paused.
v2.28.0
: Introduced.if (aTrack.isPaused()) {
/* do something */
}
<AudioTrack>.isPlaying()
→ boolean Returns whether the track is playing.
v2.28.0
: Introduced.if (aTrack.isPlaying()) {
/* do something */
}
<AudioTrack>.isSeeking()
→ boolean Returns whether the track is seeking.
v2.28.0
: Introduced.if (aTrack.isSeeking()) {
/* do something */
}
<AudioTrack>.isStopped()
→ boolean Returns whether playback of the track has been stopped.
v2.29.0
: Introduced.if (aTrack.isStopped()) {
/* do something */
}
<AudioTrack>.isUnavailable()
→ boolean Returns whether the track is currently unavailable for playback. Possible reasons include: no valid sources are registered, no sources are currently loaded, an error has occurred.
v2.28.0
: Introduced.if (aTrack.isUnavailable()) {
/* do something */
}
<AudioTrack>.isUnloaded()
→ boolean Returns whether the track's sources are currently unloaded.
v2.28.0
: Introduced.if (aTrack.isUnloaded()) {
/* do something */
}
<AudioTrack>.load()
Pauses playback of the track and, if it's not already in the process of loading, forces it to drop any existing data and begin loading.
Warning: This should not be done lightly if your audio sources are on the network, as it forces players to begin downloading them.
v2.28.0
: Introduced.aTrack.load();
<AudioTrack>.loop([state])
→ get: boolean | set: AudioTrack
object Gets or sets the track's repeating playback state (default: ). When used to set the loop state, returns a reference to the current instance for chaining.false
AudioTrack
v2.28.0
: Introduced.state
: (optional, boolean) The loop state.// Get the track's current loop state.
var isLooped = aTrack.loop();
// Loop the track.
aTrack.loop(true);
// Unloop the track.
aTrack.loop(false);
<AudioTrack>.mute([state])
→ get: boolean | set: AudioTrack
object Gets or sets the track's volume mute state (default: ). When used to set the mute state, returns a reference to the current instance for chaining.false
AudioTrack
v2.28.0
: Introduced.state
: (optional, boolean) The mute state.// Get the track's current volume mute state.
var isMuted = aTrack.mute();
// Mute the track's volume.
aTrack.mute(true);
// Unmute the track's volume.
aTrack.mute(false);
<AudioTrack>.off(...args)
→ AudioTrack
object Removes event handlers from the track. Returns a reference to the current instance for chaining.AudioTrack
Note:
Shorthand for jQuery's .off()
method applied to the audio element.
Warning:
The APIs use events internally for various pieces of functionality. To prevent conflicts, it is strongly suggested that you specify a custom user namespace—e.g., —when attaching your own handlers. It is further strongly suggested that you provide that same custom user namespace when removing them.
SimpleAudio
.myEvents
v2.28.0
: Introduced.See:
<jQuery>.off()
in the jQuery API docs for more information.
// Remove any handlers for the ended event.
aTrack.off('ended.myEvents');
<AudioTrack>.on(...args)
→ AudioTrack
object Attaches event handlers to the track. Returns a reference to the current instance for chaining.AudioTrack
Note:
Shorthand for jQuery's .on()
method applied to the audio element.
Warning:
The APIs use events internally for various pieces of functionality. To prevent conflicts, it is strongly suggested that you specify a custom user namespace—e.g., —when attaching your own handlers. It is further strongly suggested that you provide that same custom user namespace when removing them.
SimpleAudio
.myEvents
v2.28.0
: Introduced.See:
<jQuery>.on()
in the jQuery API docs for more information.
// Add a handler for the ended event.
aTrack.on('ended.myEvents', function () {
/* do something */
});
<AudioTrack>.one(...args)
→ AudioTrack
object Attaches single-use event handlers to the track. Returns a reference to the current instance for chaining.AudioTrack
Note:
Shorthand for jQuery's .one()
method applied to the audio element.
Warning:
The APIs use events internally for various pieces of functionality. To prevent conflicts, it is strongly suggested that you specify a custom user namespace—e.g., —when attaching your own handlers. It is further strongly suggested that you provide that same custom user namespace when removing them.
SimpleAudio
.myEvents
v2.28.0
: Introduced.See:
<jQuery>.one()
in the jQuery API docs for more information.
// Add a single-use handler for the ended event.
aTrack.one('ended.myEvents', function () {
/* do something */
});
<AudioTrack>.pause()
Pauses playback of the track.
v2.28.0
: Introduced.aTrack.pause();
<AudioTrack>.play()
→ Promise
object Begins playback of the track.
v2.28.0
: Introduced.aTrack.play();
Promise
aTrack.play()
.then(function () {
console.log('The track is playing.');
})
.catch(function (problem) {
console.warn('There was a problem with playback: ' + problem);
});
<AudioTrack>.playWhenAllowed()
Begins playback of the track or, failing that, sets the track to begin playback as soon as the player has interacted with the document.
v2.28.0
: Introduced.aTrack.playWhenAllowed();
<AudioTrack>.remaining()
→ number Returns how much remains of the track's total playtime in seconds, for a stream, or if no metadata exists.Infinity
NaN
v2.28.0
: Introduced.var trackRemains = aTrack.remaining();
<AudioTrack>.stop()
Stops playback of the track.
v2.28.0
: Introduced.someTrack.stop();
<AudioTrack>.time([seconds])
→ get: number | set: AudioTrack
object Gets or sets the track's current time in seconds. When used to set a value, returns a reference to the current instance for chaining.AudioTrack
v2.28.0
: Introduced.seconds
: (optional, number) The time to set. Valid values are floating-point numbers in the range (start) to the maximum duration—e.g., is is sixty seconds in, is ninety-point-five seconds in.0
60
60
90.5
// Get the track's current time.
var trackTime = aTrack.time();
// Set the track's current time to 30 seconds from its beginning.
aTrack.time(30);
// Set the track's current time to 30 seconds from its end.
aTrack.time(aTrack.duration() - 30);
<AudioTrack>.unload()
Stops playback of the track and forces it to drop any existing data.
Note: Once unloaded, playback cannot occur until the track's data is loaded again.
v2.28.0
: Introduced.aTrack.unload();
<AudioTrack>.volume([level])
→ get: number | set: AudioTrack
object Gets or sets the track's volume level (default: ). When used to set the volume, returns a reference to the current instance for chaining.1
AudioTrack
v2.28.0
: Introduced.level
: (optional, number) The volume level to set. Valid values are floating-point numbers in the range (silent) to (loudest)—e.g., is 0%, is 50%, is 100%.0
1
0
0.5
1
// Get the track's current volume level.
var trackVolume = aTrack.volume();
// Set the track's volume level to 75%.
aTrack.volume(0.75);
AudioRunner
API Audio runners are useful for performing actions on multiple tracks at once.
See Also:
SimpleAudio
API, AudioTrack
API, and AudioList
API.
<AudioRunner>.fade(duration , toVol [, fromVol])
Starts playback of the selected tracks and fades them between the specified starting and destination volume levels over the specified number of seconds.
Note:
The Config.audio.pauseOnFadeToZero
setting (default: ) determines whether the audio subsystem automatically pauses tracks that have been faded to volume (silent).
true
0
v2.28.0
: Introduced.duration
: (number) The number of seconds over which the tracks should be faded.toVol
: (number) The destination volume level.fromVol
: (optional, number) The starting volume level. If omitted, defaults to the tracks' current volume level.// Fade the selected tracks from volume 0 to 1 over 6 seconds.
someTracks.fade(6, 1, 0);
<AudioRunner>.fadeIn(duration [, fromVol])
Starts playback of the selected tracks and fades them from the specified volume level to (loudest) over the specified number of seconds.1
v2.28.0
: Introduced.duration
: (number) The number of seconds over which the tracks should be faded.fromVol
: (optional, number) The starting volume level. If omitted, defaults to the tracks' current volume level.// Fade the selected tracks in from volume 0 over 5 seconds.
someTracks.fadeIn(5, 0);
<AudioRunner>.fadeOut(duration [, fromVol])
Starts playback of the selected tracks and fades them from the specified volume level to (silent) over the specified number of seconds.0
Note:
The Config.audio.pauseOnFadeToZero
setting (default: ) determines whether the audio subsystem automatically pauses tracks that have been faded to volume (silent).
true
0
v2.28.0
: Introduced.duration
: (number) The number of seconds over which the tracks should be faded.fromVol
: (optional, number) The starting volume level. If omitted, defaults to the tracks' current volume level.// Fade the selected tracks out from volume 1 over 8 seconds.
someTracks.fadeOut(8, 1);
<AudioRunner>.fadeStop()
Interrupts an in-progress fade of the selected tracks, or does nothing if no fade is progressing.
Note: This does not alter the volume level.
v2.28.0
: Introduced.someTracks.fadeStop();
<AudioRunner>.load()
Pauses playback of the selected tracks and, if they're not already in the process of loading, forces them to drop any existing data and begin loading.
Warning: This should not be done lightly if your audio sources are on the network, as it forces players to begin downloading them.
v2.28.0
: Introduced.someTracks.load();
<AudioRunner>.loop(state)
→ AudioRunner
object Sets the selected tracks' repeating playback state (default: ). Returns a reference to the current instance for chaining.false
AudioRunner
v2.28.0
: Introduced.state
: (boolean) The loop state.// Loop the selected tracks.
someTracks.loop(true);
// Unloop the selected tracks.
someTracks.loop(false);
<AudioRunner>.mute(state)
→ AudioRunner
object Sets the selected tracks' volume mute state (default: ). Returns a reference to the current instance for chaining.false
AudioRunner
v2.28.0
: Introduced.state
: (boolean) The mute state.// Mute the selected tracks' volume.
someTracks.mute(true);
// Unmute the selected tracks' volume.
someTracks.mute(false);
<AudioRunner>.off(...args)
→ AudioRunner
object Removes event handlers from the selected tracks. Returns a reference to the current instance for chaining.AudioRunner
Note:
Shorthand for jQuery's .off()
method applied to each of the audio elements.
Warning:
The APIs use events internally for various pieces of functionality. To prevent conflicts, it is strongly suggested that you specify a custom user namespace—e.g., —when attaching your own handlers. It is further strongly suggested that you provide that same custom user namespace when removing them.
SimpleAudio
.myEvents
v2.28.0
: Introduced.See:
<jQuery>.off()
in the jQuery API docs for more information.
// Remove any handlers for the ended event.
someTracks.off('ended.myEvents');
<AudioRunner>.on(...args)
→ AudioRunner
object Attaches event handlers to the selected tracks. Returns a reference to the current instance for chaining.AudioRunner
Note:
Shorthand for jQuery's .on()
method applied to each of the audio elements.
Warning:
The APIs use events internally for various pieces of functionality. To prevent conflicts, it is strongly suggested that you specify a custom user namespace—e.g., —when attaching your own handlers. It is further strongly suggested that you provide that same custom user namespace when removing them.
SimpleAudio
.myEvents
v2.28.0
: Introduced.See:
<jQuery>.on()
in the jQuery API docs for more information.
// Add a handler for the ended event.
someTracks.on('ended.myEvents', function () {
/* do something */
});
<AudioRunner>.one(...args)
→ AudioRunner
object Attaches single-use event handlers to the selected tracks. Returns a reference to the current instance for chaining.AudioRunner
Note:
Shorthand for jQuery's .one()
method applied to each of the audio elements.
Warning:
The APIs use events internally for various pieces of functionality. To prevent conflicts, it is strongly suggested that you specify a custom user namespace—e.g., —when attaching your own handlers. It is further strongly suggested that you provide that same custom user namespace when removing them.
SimpleAudio
.myEvents
v2.28.0
: Introduced.See:
<jQuery>.one()
in the jQuery API docs for more information.
// Add a single-use handler for the ended event.
someTracks.one('ended.myEvents', function () {
/* do something */
});
<AudioRunner>.pause()
Pauses playback of the selected tracks.
v2.28.0
: Introduced.someTracks.pause();
<AudioRunner>.play()
Begins playback of the selected tracks.
v2.28.0
: Introduced.someTracks.play();
<AudioRunner>.playWhenAllowed()
Begins playback of the selected tracks or, failing that, sets the tracks to begin playback as soon as the player has interacted with the document.
v2.28.0
: Introduced.someTracks.playWhenAllowed();
<AudioRunner>.stop()
Stops playback of the selected tracks.
v2.28.0
: Introduced.someTracks.stop();
<AudioRunner>.time(seconds)
→ AudioRunner
object Sets the selected tracks' current time in seconds. Returns a reference to the current instance for chaining.AudioRunner
v2.28.0
: Introduced.seconds
: (number) The time to set. Valid values are floating-point numbers in the range (start) to the maximum duration—e.g., is is sixty seconds in, is ninety-point-five seconds in.0
60
60
90.5
// Set the selected tracks' current time to 30 seconds from their beginning.
someTracks.time(30);
<AudioRunner>.unload()
Stops playback of the selected tracks and forces them to drop any existing data.
Note: Once unloaded, playback cannot occur until the selected tracks' data is loaded again.
v2.28.0
: Introduced.someTracks.unload();
<AudioRunner>.volume(level)
→ AudioRunner
object Sets the selected tracks' volume level (default: ). Returns a reference to the current instance for chaining.1
AudioRunner
v2.28.0
: Introduced.level
: (number) The volume level to set. Valid values are floating-point numbers in the range (silent) to (loudest)—e.g., is 0%, is 50%, is 100%.0
1
0
0.5
1
// Set the selected tracks' volume level to 75%.
someTracks.volume(0.75);
AudioList
API Audio lists (playlists) are useful for playing tracks in a sequence—i.e., one after another.
See Also:
SimpleAudio
API, AudioTrack
API, and AudioRunner
API.
<AudioList>.duration()
→ number Returns the playlist's total playtime in seconds, if it contains any streams, or if no metadata exists.Infinity
NaN
v2.28.0
: Introduced.var listLength = aList.duration();
<AudioList>.fade(duration , toVol [, fromVol])
→ Promise
object Starts playback of the playlist and fades the currently playing track between the specified starting and destination volume levels over the specified number of seconds.
Note:
The Config.audio.pauseOnFadeToZero
setting (default: ) determines whether the audio subsystem automatically pauses tracks that have been faded to volume (silent).
true
0
v2.28.0
: Introduced.v2.29.0
: Updated to return a .Promise
duration
: (number) The number of seconds over which the currently playing track should be faded.toVol
: (number) The destination volume level.fromVol
: (optional, number) The starting volume level. If omitted, defaults to the currently playing track's current volume level.// Fade the playlist from volume 0 to 1 over 6 seconds.
aList.fade(6, 1, 0);
<AudioList>.fadeIn(duration [, fromVol])
→ Promise
object Starts playback of the playlist and fades the currently playing track from the specified volume level to (loudest) over the specified number of seconds.1
v2.28.0
: Introduced.v2.29.0
: Updated to return a .Promise
duration
: (number) The number of seconds over which the currently playing track should be faded.fromVol
: (optional, number) The starting volume level. If omitted, defaults to the currently playing track's current volume level.// Fade the playlist in from volume 0 over 5 seconds.
aList.fadeIn(5, 0);
<AudioList>.fadeOut(duration [, fromVol])
→ Promise
object Starts playback of the playlist and fades the currently playing track from the specified volume level to (silent) over the specified number of seconds.0
Note:
The Config.audio.pauseOnFadeToZero
setting (default: ) determines whether the audio subsystem automatically pauses tracks that have been faded to volume (silent).
true
0
v2.28.0
: Introduced.v2.29.0
: Updated to return a .Promise
duration
: (number) The number of seconds over which the currently playing track should be faded.fromVol
: (optional, number) The starting volume level. If omitted, defaults to the currently playing track's current volume level.// Fade the playlist out from volume 1 over 8 seconds.
aList.fadeOut(8, 1);
<AudioList>.fadeStop()
Interrupts an in-progress fade of the currently playing track, or does nothing if no fade is progressing.
Note: This does not alter the volume level.
v2.29.0
: Introduced.aList.fadeStop();
<AudioList>.isEnded()
→ boolean Returns whether playback of the playlist has ended.
v2.28.0
: Introduced.if (aList.isEnded()) {
/* do something */
}
<AudioList>.isFading()
→ boolean Returns whether a fade is in-progress on the currently playing track.
v2.29.0
: Introduced.if (aList.isFading()) {
/* do something */
}
<AudioList>.isPaused()
→ boolean Returns whether playback of the playlist has been paused.
v2.28.0
: Introduced.if (aList.isPaused()) {
/* do something */
}
<AudioList>.isPlaying()
→ boolean Returns whether the playlist is playing.
v2.28.0
: Introduced.if (aList.isPlaying()) {
/* do something */
}
<AudioList>.isStopped()
→ boolean Returns whether playback of the playlist has been stopped.
v2.29.0
: Introduced.if (aList.isStopped()) {
/* do something */
}
<AudioList>.load()
Pauses playback of the playlist and, if they're not already in the process of loading, forces its tracks to drop any existing data and begin loading.
Warning: This should not be done lightly if your audio sources are on the network, as it forces players to begin downloading them.
v2.28.0
: Introduced.aList.load();
<AudioList>.loop([state])
→ get: boolean | set: AudioList
object Gets or sets the playlist's repeating playback state (default: ). When used to set the loop state, returns a reference to the current instance for chaining.false
AudioList
v2.28.0
: Introduced.state
: (optional, boolean) The loop state.// Get the playlist's current loop state.
var isLooped = aList.loop();
// Loop the playlist.
aList.loop(true);
// Unloop the playlist.
aList.loop(false);
<AudioList>.mute([state])
→ get: boolean | set: AudioList
object Gets or sets the playlist's volume mute state (default: ). When used to set the mute state, returns a reference to the current instance for chaining.false
AudioList
v2.28.0
: Introduced.state
: (optional, boolean) The mute state.// Get the playlist's current volume mute state.
var isMuted = aList.mute();
// Mute the playlist's volume.
aList.mute(true);
// Unmute the playlist's volume.
aList.mute(false);
<AudioList>.pause()
Pauses playback of the playlist.
v2.28.0
: Introduced.aList.pause();
<AudioList>.play()
→ Promise
object Begins playback of the playlist.
v2.28.0
: Introduced.v2.29.0
: Updated to return a .Promise
aList.play();
Promise
aList.play()
.then(function () {
console.log('The playlist is playing.');
})
.catch(function (problem) {
console.warn('There was a problem with playback: ' + problem);
});
<AudioList>.playWhenAllowed()
Begins playback of the playlist or, failing that, sets the playlist to begin playback as soon as the player has interacted with the document.
v2.29.0
: Introduced.aList.playWhenAllowed();
<AudioList>.remaining()
→ number Returns how much remains of the playlist's total playtime in seconds, if it contains any streams, or if no metadata exists.Infinity
NaN
v2.28.0
: Introduced.var listRemains = aList.remaining();
<AudioList>.shuffle([state])
→ get: boolean | set: AudioList
object Gets or sets the playlist's randomly shuffled playback state (default: ). When used to set the shuffle state, returns a reference to the current instance for chaining.false
AudioList
v2.28.0
: Introduced.state
: (optional, boolean) The shuffle state.// Get the playlist's current shuffle state.
var isShuffled = aList.shuffle();
// Enable shuffling of the playlist.
aList.shuffle(true);
// Disable shuffling of the playlist.
aList.shuffle(false);
<AudioList>.skip()
Skips ahead to the next track in the playlist, if any.
v2.28.0
: Introduced.someTrack.skip();
<AudioList>.stop()
Stops playback of the playlist.
v2.28.0
: Introduced.someTrack.stop();
<AudioList>.time()
→ number Returns the playlist's current time in seconds, or if no metadata exists.NaN
v2.28.0
: Introduced.var listTime = aList.time();
<AudioList>.unload()
Stops playback of the playlist and forces its tracks to drop any existing data.
Note: Once unloaded, playback cannot occur until the track's data is loaded again.
v2.28.0
: Introduced.aList.unload();
<AudioList>.volume([level])
→ get: number | set: AudioList
object Gets or sets the playlist's volume level (default: ). When used to set the volume, returns a reference to the current instance for chaining.1
AudioList
v2.28.0
: Introduced.level
: (optional, number) The volume level to set. Valid values are floating-point numbers in the range (silent) to (loudest)—e.g., is 0%, is 50%, is 100%.0
1
0
0.5
1
// Get the playlist's current volume level.
var trackVolume = aList.volume();
// Set the playlist's volume level to 75%.
aList.volume(0.75);
State
API The story history contains moments (states) created during play. Since it is possible to navigate the history—i.e., move backward and forward though the moments within the history—it may contain both past moments—i.e., moments that have been played—and future moments—i.e., moments that had been played, but have been rewound/undone, yet are still available to be restored.
In addition to the history, there is also the active moment—i.e., present—and expired moments—i.e., moments that had been played, but have expired from the history, thus cannot be navigated to.
API members dealing with the history work upon either the active moment—i.e., present—or one of the history subsets: the full in-play history—i.e., past + future—the past in-play subset—i.e., past only—or the extended past subset—i.e., expired + past. These instances will be noted.
State.active
→ object Returns the active (present) moment.
Note:
Using directly is generally unnecessary as there exist a number of shortcut properties, State.passage
and State.variables
, and story functions, passage()
and variables()
, which grant access to its normal properties.
State.active
v2.0.0
: Introduced.State.active.title → The title of the present moment
State.active.variables → The variables of the present moment
State.bottom
→ object Returns the bottommost (least recent) moment from the full in-play history (past + future).
v2.0.0
: Introduced.State.bottom.title → The title of the least recent moment within the full in-play history
State.bottom.variables → The variables of the least recent moment within the full in-play history
State.current
→ object Returns the current moment from the full in-play history (past + future), which is the pre-play version of the active moment.
Warning:
is not a synonym for State.active
. You will, very likely, never need to use directly within your code.
State.current
State.current
v2.8.0
: Introduced.State.current.title → The title of the current moment within the full in-play history
State.current.variables → The variables of the current moment within the full in-play history
State.length
→ integer Returns the number of moments within the past in-play history (past only).
v2.0.0
: Introduced.if (State.length === 0) {
/* No moments within the past in-play history. Egad! */
}
State.passage
→ string Returns the title of the passage associated with the active (present) moment.
v2.0.0
: Introduced.State.passage → The passage title of the present moment
State.size
→ integer Returns the number of moments within the full in-play history (past + future).
v2.0.0
: Introduced.if (State.size === 0) {
/* No moments within the full in-play history. Egad! */
}
State.temporary
→ object Returns the current temporary variables.
v2.13.0
: Introduced.State.temporary → The current temporary variables
State.top
→ object Returns the topmost (most recent) moment from the full in-play history (past + future).
Warning:
is not a synonym for State.active
. You will, very likely, never need to use directly within your code.
State.top
State.top
v2.0.0
: Introduced.State.top.title → The title of the most recent moment within the full in-play history
State.top.variables → The variables of the most recent moment within the full in-play history
State.turns
→ integer Returns the total number (count) of played moments within the extended past history (expired + past).
v2.0.0
: Introduced.if (State.turns === 1) {
/* Initial turn. The starting passage is displayed. */
}
State.variables
→ object Returns the variables from the active (present) moment.
v2.0.0
: Introduced.State.variables → The variables of the present moment
State.getVar(varName)
→ any Returns the value of the story or temporary variable by the given name.
v2.22.0
: Introduced.varName
: (string) The name of the story or temporary variable, including its sigil—e.g., .$charName
State.getVar("$charName") → Returns the value of $charName
State.has(passageTitle)
→ boolean Returns whether any moments with the given title exist within the past in-play history (past only).
Note:
does not check expired moments. If you need to know if the player has ever been to a particular passage, then you must use the State.hasPlayed()
method or the hasVisited()
story function.
State.has()
v2.0.0
: Introduced.passageTitle
: (string) The title of the moment whose existence will be verified.State.has("The Ducky") → Returns whether a moment matching "The Ducky" exists
State.hasPlayed(passageTitle)
→ boolean Returns whether any moments with the given title exist within the extended past history (expired + past).
Note:
If you need to check for multiple passages, the hasVisited()
story function will likely be more convenient to use.
v2.0.0
: Introduced.passageTitle
: (string) The title of the moment whose existence will be verified.State.hasPlayed("The Ducky") → Returns whether a moment matching "The Ducky" ever existed
State.index(index)
→ object Returns the moment, relative to the bottom of the past in-play history (past only), at the given index.
v2.0.0
: Introduced.index
: (integer) The index of the moment to return.State.index(0) → Returns the least recent moment within the past in-play history
State.index(1) → Returns the second to least recent moment within the past in-play history
State.index(State.length - 1) → Returns the most recent moment within the past in-play history
State.isEmpty()
→ boolean Returns whether the full in-play history (past + future) is empty.
v2.0.0
: Introduced.if (State.isEmpty()) {
/* No moments within the full in-play history. Egad! */
}
State.peek([offset])
→ object Returns the moment, relative to the top of the past in-play history (past only), at the, optional, offset.
v2.0.0
: Introduced.offset
: (optional, integer) The offset, from the top of the past in-play history, of the moment to return. If not given, an offset of is used.0
State.peek() → Returns the most recent moment within the past in-play history
State.peek(0) → Returns the most recent moment within the past in-play history
State.peek(1) → Returns the second most recent moment within the past in-play history
State.peek(State.length - 1) → Returns the least recent moment within the past in-play history
State.metadata.size
→ integer Returns the size of the story metadata store—i.e., the number of stored pairs.
v2.30.0
: Introduced.// Determines whether the metadata store has any members.
if (State.metadata.size > 0) {
/* store is not empty */
}
State.metadata.clear()
Empties the story metadata store.
v2.29.0
: Introduced.// Removes all values from the metadata store.
State.metadata.clear();
State.metadata.delete(key)
Removes the specified key, and its associated value, from the story metadata store.
v2.29.0
: Introduced.key
: (string) The key to delete.// Removes 'achievements' from the metadata store.
State.metadata.delete('achievements');
State.metadata.entries()
→ Array<Array<string, any>> Returns an array of the story metadata store's key/value pairs as arrays.[key, value]
v2.36.0
: Introduced.// Iterate over the pairs with a `for` loop.
var metadata = State.metadata.entries();
for (var i = 0; i < metadata.length; ++i) {
var key = metadata[i][0];
var value = metadata[i][1];
/* do something */
}
// Iterate over the pairs with `<Array>.forEach()`.
State.metadata.entries().forEach(function (pair) {
var key = pair[0];
var value = pair[1];
/* do something */
});
State.metadata.get(key)
→ any Returns the value associated with the specified key from the story metadata store.
v2.29.0
: Introduced.key
: (string) The key whose value should be returned.// Returns the value of 'achievements' from the metadata store.
var playerAchievements = State.metadata.get('achievements');
State.metadata.has(key)
→ boolean Returns whether the specified key exists within the story metadata store.
v2.29.0
: Introduced.key
: (string) The key whose existence should be tested.// Returns whether 'achievements' exists within the metadata store.
if (State.metadata.has('achievements')) {
/* do something */
}
State.metadata.keys()
→ Array<string> Returns an array of the story metadata store's keys.
v2.36.0
: Introduced.// Iterate over the keys with a `for` loop.
var metadataKeys = State.metadata.keys();
for (var i = 0; i < metadataKeys.length; ++i) {
var key = metadataKeys[i];
/* do something */
}
// Iterate over the keys with `<Array>.forEach()`.
State.metadata.keys().forEach(function (key) {
/* do something */
});
State.metadata.set(key, value)
Sets the specified key and value within the story metadata store, which causes them to persist over story and browser restarts—n.b. private browsing modes do interfere with this. To update the value associated with a key, simply set it again.
Note: The story metadata, like saves, is tied to the specific story it was generated with. It is not a mechanism for moving data between stories.
Warning: The story metadata store is not, and should not be used as, a replacement for saves. Examples of good uses: achievement tracking, new game+ data, playthrough statistics, etc.
Warning: This feature is largely incompatible with private browsing modes, which cause all in-browser storage mechanisms to either persist only for the lifetime of the browsing session or fail outright.
v2.29.0
: Introduced.key
: (string) The key that should be set.value
: (any) The value to set.// Sets 'achievements', with the given value, in the metadata store.
State.metadata.set('achievements', { ateYellowSnow : true });
// Sets 'ngplus', with the given value, in the metadata store.
State.metadata.set('ngplus', true);
State.prng.init([seed [, useEntropy]])
Initializes the seedable pseudo-random number generator (PRNG) and integrates it into the story state and saves. Once initialized, the State.random()
method and story functions, random()
and randomFloat()
, return deterministic results from the seeded PRNG—by default, they return non-deterministic results from Math.random()
.
Note:
must be called during story initialization, within either your project's JavaScript section (Twine 2: the Story JavaScript; Twine 1/Twee: a -tagged passage) or the special passage. Additionally, it is strongly recommended that you do not specify any arguments to and allow it to automatically seed itself. If you should chose to use an explicit seed, however, it is strongly recommended that you also enable additional entropy, otherwise all playthroughs for all players will be exactly the same.
State.prng.init()
script
StoryInit
State.prng.init()
v2.29.0
: Introduced.seed
: (optional, string) The explicit seed used to initialize the pseudo-random number generator.useEntropy
: (optional, boolean) Enables the use of additional entropy to pad the specified explicit seed.State.prng.init() → Automatically seed the PRNG (recommended)
State.prng.init("aVeryLongSeed") → Seed the PRNG with "aVeryLongSeed" (not recommended)
State.prng.init("aVeryLongSeed", true) → Seed the PRNG with "aVeryLongSeed" and pad it with extra entropy
State.prng.isEnabled()
→ boolean Returns whether the seedable PRNG has been enabled.
v2.29.0
: Introduced.State.prng.isEnabled() → Returns whether the seedable PRNG is enabled
State.prng.pull
→ integer | NaN Returns the current pull count—i.e., how many requests have been made—from the seedable PRNG or, if the PRNG is not enabled, .NaN
Note: The pull count is automatically included within saves and sessions, so this is not especially useful outside of debugging purposes.
v2.29.0
: Introduced.State.prng.pull → Returns the current PRNG pull count
State.prng.seed
→ string | null Returns the seed from the seedable PRNG or, if the PRNG is not enabled, .null
Note: The seed is automatically included within saves and sessions, so this is not especially useful outside of debugging purposes.
v2.29.0
: Introduced.State.prng.seed → Returns the PRNG seed
State.random()
→ number Returns a pseudo-random decimal number (floating-point) in the range (inclusive) up to, but not including, (exclusive).0
1
Note:
By default, it simply returns non-deterministic results from Math.random()
, however, when the seedable PRNG has been enabled, via State.prng.init()
, it returns deterministic results from the seeded PRNG instead.
v2.0.0
: Introduced.State.random() → Returns a pseudo-random floating-point number in the range [0, 1)
State.setVar(varName, value)
→ boolean Sets the value of the story or temporary variable by the given name. Returns whether the operation was successful.
v2.22.0
: Introduced.varName
: (string) The name of the story or temporary variable, including its sigil—e.g., .$charName
value
: (any) The value to assign.State.setVar("$charName", "Jane Doe") → Assigns the string "Jane Doe" to $charName
Story
API Story.id
→ string The DOM-compatible ID of the story.
v2.37.0
: Introduced.The DOM-compatible ID of the story, created from the slugified story name.string
Story.ifId
→ string The IFID (Interactive Fiction IDentifier) of the story.
v2.5.0
: Introduced.The IFID of the story, or an empty string if no IFID exists. The Twine 2 ecosystem's IFIDs are v4 random UUIDs.string
Story.name
→ string The name of the story.
v2.37.0
: Introduced.The name of the story.string
Story.add(descriptor)
→ boolean Adds the passage to the passage store.
Note: This method cannot add code passages or passages tagged with code tags.
v2.37.0
: Introduced.descriptor
: (Object
) The passage descriptor object.A passage descriptor object should have the following properties:
name
: (string
) The passage's name.tags
: (string
) The passage's whitespace separated list of tags.text
: (string
) The passage's text.Boolean if the passage was added, elsewise .true
false
// Add a passage
const descriptor = {
name : "Forest 4",
tags : "forest heavy",
text : "You can barely see farther than arm's length for all the trees.",
};
if (Story.add(descriptor)) {
/* The "Forest 4" passage was added. */
}
Story.delete(name)
→ boolean Deletes the instance with the given name.Passage
Note: This method cannot add code passages or passages tagged with code tags.
v2.37.0
: Introduced.name
: (string) The name of the instance.Passage
Boolean if a instance with the given name was deleted, elsewise .true
Passage
false
// Delete the Passage instance with the name "The Ducky"
if (Story.delete("The Ducky")) {
/* The "The Ducky" passage was deleted. */
}
Story.filter(predicate [, thisArg])
→ Array<Passage>
Searches all instances for those that pass the test implemented by the given predicate function.Passage
Note: This method cannot retrieve passages tagged with code tags.
v2.37.0
: Introduced.predicate
: (function) The function used to test each instance, which is passed into the function as its sole parameter. If the function returns , then the instance is added to the results.Passage
true
Passage
thisArg
: (optional, any) The value to use as when executing the function.this
predicate
A new filled with all instances that pass the test implemented by the given predicate function, or an empty if no instances pass.Array<Passage>
Array
// Returns all 'forest'-tagged Passage instances
Story.filter(function (p) {
return p.tags.includes("forest");
});
// Returns all Passage instances whose names include whitespace
var hasWhitespaceRegExp = /\s/;
Story.filter(function (p) {
return hasWhitespaceRegExp.test(p.name);
});
Story.find(predicate [, thisArg])
→ Passage
Searches all instances for the first that passes the test implemented by the given predicate function.Passage
Note: This method cannot retrieve passages tagged with code tags.
v2.37.0
: Introduced.predicate
: (function) The function used to test each object, which is passed into the function as its sole parameter. If the function returns , then the instance is added to the results.Passage
true
Passage
thisArg
: (optional, any) The value to use as when executing the function.this
predicate
The first instance that passed the test implemented by the given predicate function, or if no instance passes.Passage
undefined
// Returns the first 'forest'-tagged Passage instance
Story.find(function (p) {
return p.tags.includes("forest");
});
// Returns the first Passage instance whose name includes whitespace
var hasWhitespaceRegExp = /\s/;
Story.find(function (p) {
return hasWhitespaceRegExp.test(p.name);
});