简介

本文档是 SugarCube v2 的中文参考手册，这是一个为 Twine/Twee 设计的免费且自由的故事格式。

提示： 本文档为单页结构，您可使用浏览器的页面内搜索功能——CTRL+F、CMD+F、F3——快速定位关键词。

注意：
若您发现 SugarCube 的漏洞或有改进建议，请前往其 源代码仓库 提交新议题。
若您发现汉化有问题或有更好的建议，请前往汉化文档仓库

文档贡献者（排名不分先后）:

简体中文翻译贡献者（排名不分先后）:

 标记语法

注意： 除非特别说明，所有标记语法自 v2.0.0 版本起可用。

 裸变量

除了使用打印宏（<<print>>、<<=>>、<<->>）来输出变量值，SugarCube 的裸变量标记允许直接在段落文本中插入变量——即段落文本中的变量会被自动替换为其值的字符串表示。

裸变量标记支持以下形式：

类型 语法 示例
简单变量 
$variable
 
$name
属性访问
（点号表示法）		 
$variable.property
 
$thing.name
索引/属性访问
（方括号表示法）		 
$variable[数字索引]
$variable["属性名"]
$variable['属性名']
$variable[$索引或属性变量]
 
$thing[0]
$thing["name"]
$thing['name']
$thing[$member]

如需进行更复杂的操作（例如使用计算表达式：$variable[_i + 1]，或方法调用：$variable.someMethod()），仍需使用打印宏。

示例：

/* 使用 <<print>> 宏显式打印 $name 的值 */
你好啊，<<print $name>>。

/* 使用裸变量标记隐式打印 $name 的值 */
你好啊，$name。

/* 假设 $name 的值为 "Mr. Freeman"，两种方式都会输出： */
你好啊，Mr. Freeman。

由于段落文本中的变量会自动转换为它们的值，如果您需要按原样输出变量（不进行插值，例如用于教程、调试输出等用途），则需要通过某种方式对其进行转义。例如：

/* 使用 nowiki 标记："""..."""（三重双引号） */
变量 """$name""" 的值为：$name

/* 使用 nowiki 标记：<nowiki>...</nowiki> */
变量 <nowiki>$name</nowiki> 的值为：$name

/* 使用双美元符号标记（转义$符号）：$$ */
变量 $$name 的值为：$name

/* 假设 $name 的值为 "Mr. Freeman"，所有示例将输出： */
变量 $name 的值为：Mr. Freeman

此外，您可以使用内联代码标记来转义变量，但这样做会将转义的变量包裹在 <code> 元素中，因此可能最适合示例和教程使用。例如：

/* 使用内联代码标记：{{{...}}}（三重花括号） */
变量 {{{$name}}} 的值为：$name

/* 假设 $name 的值为 "Mr. Freeman"，将输出： */
变量 <code>$name</code> 的值为：Mr. Freeman

SugarCube 的链接标记由必需的 Link 组件和可选的 Text、Setter 组件组成。

Link 组件可以是纯文本或任何有效的 TwineScript 表达式（会在链接初始化时解析），其值应为段落名称或有效 URL（本地或远程）。

Text 组件（可选）可以是纯文本或任何有效的 TwineScript 表达式（会在链接初始化时解析）。

Setter 组件（仅适用于段落链接，可选）必须是有效的 TwineScript 表达式，格式与 <<set>> 宏相同（会在点击链接时解析）。如需多个表达式，请用分号分隔（;）——例如：$a to 5; $b to true。

除标准管道符 (|) 分隔外，SugarCube 还支持箭头分隔符 (-> & <-)。箭头方向决定组件顺序，箭头始终指向 Link 组件——右箭头为 Text->Link，左箭头为 Link<-Text。

警告 (Twine 2): 由于 Twine 2 的自动段落创建机制，使用表达式作为 Link 组件会生成以表达式命名的冗余段落。建议在 Twine 2 中使用 <<link>> 宏的独立参数形式来避免此问题。

以下示例假设：$go 为 "Grocery"，$show 为 "Go buy milk"
语法 示例 
[[Link]]
 
[[Grocery]]
[[$go]]
 
[[Text|Link]]
 
[[Go buy milk|Grocery]]
[[$show|$go]]
 
[[Link][Setter]]
 
[[Grocery][$bought to "milk"]]
[[$go][$bought to "milk"]]
 
[[Text|Link][Setter]]
 
[[Go buy milk|Grocery][$bought to "milk"]]
[[$show|$go][$bought to "milk"]]

 图片

SugarCube 的图片标记由必需的 Image 组件和可选的 Text、Link、Setter 组件组成。

Image 组件可以是纯文本或任何有效的 TwineScript 表达式（会在图片初始化时解析），其值应为图片资源的有效 URL（本地或远程）或媒体（图片）段落名称。

Text 组件（可选）可以是纯文本或任何有效的 TwineScript 表达式（会在图片初始化时解析），其值将作为图片的替代文本（alt 文本）。

Link 组件（可选）可以是纯文本或任何有效的 TwineScript 表达式（会在图片初始化时解析），其值应为段落名称或有效 URL（本地或远程）。

Setter 组件（仅适用于段落链接，可选）必须是有效的 TwineScript 表达式，格式与 <<set>> 宏相同（会在点击链接时解析）。如需多个表达式，请用分号分隔（;）——例如：$a to 5; $b to true。

除标准管道符 (|) 分隔外，SugarCube 还支持箭头分隔符 (-> & <-)。箭头方向决定组件顺序，箭头始终指向 Image 组件——右箭头为 Text->Image，左箭头为 Image<-Text。

警告 (Twine 2): 由于 Twine 2 的自动段落创建机制，使用表达式作为 Link 组件会生成以表达式命名的冗余段落。建议在 Twine 2 中使用 <<link>> 宏的独立参数形式来避免此问题。

以下示例假设：$src 为 home.png，$go 为 "Home"，$show 为 "Go home"
语法 示例 
[img[Image]]
 
[img[home.png]]
[img[$src]]
 
[img[Text|Image]]
 
[img[Go home|home.png]]
[img[$show|$src]]
 
[img[Image][Link]]
 
[img[home.png][Home]]
[img[$src][$go]]
 
[img[Text|Image][Link]]
 
[img[Go home|home.png][Home]]
[img[$show|$src][$go]]
 
[img[Image][Link][Setter]]
 
[img[home.png][Home][$done to true]]
[img[$src][$go][$done to true]]
 
[img[Text|Image][Link][Setter]]
 
[img[Go home|home.png][Home][$done to true]]
[img[$show|$src][$go][$done to true]]

在样式表中

样式表中可使用图片标记的受限子集，仅允许使用 Image 组件——主要是便于使用媒体（图片）段落。例如：

/* 使用外部图片 "forest.png" 作为 <body> 背景 */
body {
	background-image: [img[forest.png]];
}

/* 使用媒体段落 "lagoon" 作为 <body> 背景 */
body {
	background-image: [img[lagoon]];
}

 HTML & SVG 属性

注意： 以下功能在原始 HTML 标记中均不可用。

 特殊属性

SugarCube 提供了一些特殊的 HTML 和 SVG 属性，您可以将它们添加到标签中以启用特殊行为。这些属性用于段落链接、媒体段落和设置器。

类型 属性 示例
段落链接 
data-passage
 
<a data-passage="PassageName">执行操作</a>
<area shape="rect" coords="25,25,75,75" data-passage="PassageName">
<button data-passage="PassageName">执行操作</button>
音频段落 
data-passage
 
<audio data-passage="AudioPassageName">
图片段落 
data-passage
 
<img data-passage="ImagePassageName">
<image data-passage="ImagePassageName" />
资源段落 
data-passage
 
<source data-passage="AudioOrVideoPassageName">
视频段落 
data-passage
 
<video data-passage="VideoPassageName">
设置器 
data-setter
 
<a data-passage="PassageName" data-setter="$thing to 'done'">执行操作</a>
<area shape="rect" coords="25,25,75,75" data-passage="PassageName"
	data-setter="$thing to 'done'">
<button data-passage="PassageName" data-setter="$thing to 'done'">执行操作</button>

版本历史：

 属性指令

HTML和SVG 属性可通过添加指令前缀（特殊文本）来触发特殊处理。

求值指令：sc-eval:, @

此指令会将属性值作为 TwineScript 表达式进行求值。处理后，指令前缀将从属性名中移除，求值结果将作为属性实际值。

警告： data-setter 属性禁止使用求值指令（因其功能是在元素激活时求值内容），尝试使用将导致错误。

以下示例假设：_id 为 "foo"
语法 示例 渲染结果 
sc-eval:属性名
 
<span sc-eval:id="_id">…</span>
 
<span id="foo">…</span>
 
sc-eval:属性名
 
<span sc-eval:id="'pre-' + _id + '-suf'">…</span>
 
<span id="pre-foo-suf">…</span>
 
@属性名
 
<span @id="_id">…</span>
 
<span id="foo">…</span>
 
@属性名
 
<span @id="'pre-' + _id + '-suf'">…</span>
 
<span id="pre-foo-suf">…</span>

版本历史：

 行继续标记

相关参考： 各类无间断功能——<<nobr>> 宏、nobr 特殊标签和Config.passages.nobr 设置——均提供类似但略有差异的功能。

注意： 行继续标记（或任何依赖行定位的标记）与无间断功能不兼容，因其工作原理存在冲突。

行首或行尾的反斜杠（\）即行继续标记。处理时会移除反斜杠、关联的换行符及两者间的所有空格——从而实现多行内容的无缝拼接。此功能主要用于需要换行排版提升可读性，但又不想在显示时产生额外空格的场景，当需要输出内容时可用此替代无法使用的<<silently>> 宏。

例如以下写法（注：·表示将被移除的空格，¬表示换行符）：

西班牙的降水 \¬
主要集中在平原.

西班牙的降水 \····¬
主要集中在平原.

西班牙的降水¬
\ 主要集中在平原.

西班牙的降水¬
····\ 主要集中在平原.

在最终输出中将会输出此行:

西班牙的降水主要集中在平原.

 标题

行首的感叹号（!）用于定义标题标记。1 到 6 个感叹号分别对应不同层级的标题，数量越多层级越低。

类型 语法与示例 渲染结果 显示效果（大致）
一级标题 
!一级标题
 
<h1>一级标题</h1>

一级标题
二级标题 
!!二级标题
 
<h2>二级标题</h2>

二级标题
三级标题 
!!!三级标题
 
<h3>三级标题</h3>

三级标题
四级标题 
!!!!四级标题
 
<h4>四级标题</h4>

四级标题
五级标题 
!!!!!五级标题
 
<h5>五级标题</h5>
五级标题
六级标题 
!!!!!!六级标题
 
<h6>六级标题</h6>
六级标题

 样式

注意： 由于样式标记使用相同符号作为起止符，同类型样式不能嵌套使用。

类型 语法与示例 渲染结果 显示效果（大致）
强调 
//强调//
 
<em>强调</em>
 强调
加粗 
''加粗''
 
<strong>加粗</strong>
 加粗
下划线 
__下划线__
 
<u>下划线</u>
 下划线
删除线 
==删除线==
 
<s>删除线</s>
 删除线
上标 
文字^^上标^^
 
文字<sup>上标</sup>
 文字上标
下标 
文字~~下标~~
 
文字<sub>下标</sub>
 文字下标

 列表

行首的星号（*）或井号（#）分别用于定义无序列表和有序列表的成员项。

类型 语法与示例 渲染结果 显示效果（大致）
无序列表 
* 列表项
* 另一个列表项
 
<ul>
<li>列表项</li>
<li>另一个列表项</li>
</ul>
  • 列表项
  • 另一个列表项
有序列表 
# 列表项
# 另一个列表项
 
<ol>
<li>列表项</li>
<li>另一个列表项</li>
</ol>
  1. 列表项
  2. 另一个列表项

 块引用

行首的右尖括号（>）用于定义块引用标记。多个右尖括号表示嵌套的块引用层级。

语法与示例 渲染结果 显示效果（大致） 
>第一行
>第二行
>>嵌套第一层
>>嵌套第二层
 
<blockquote>第一行<br>
第二行<br>
<blockquote>嵌套第一层<br>
嵌套第二层<br>
</blockquote></blockquote>
第一行
第二行
嵌套第一层
嵌套第二层

 Code

Type Syntax & Example Rendered As Displays As (roughly)
Inline 
{{{Code}}}
 
<code>Code</code>
 
Code
Block 
{{{
Code
More code
}}}
 
<pre><code>Code
More code
</code></pre>
 
Code
More code

 Horizontal Rule

A set of four, or more, hyphen-minus (-) characters that begin a line, and are the only things on the line, define the horizontal rule markup.

Type Syntax & Example Rendered As Displays As (roughly)
Horizontal rule 
----
 
<hr>

 Verbatim Text

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//"""
 
No //format//
 No //format//
<nowiki> tag 
<nowiki>No //format//</nowiki>
 
No //format//
 No //format//

 Verbatim HTML

A set of opening and closing <html> tags—i.e., <html></html>—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.

Note: You should virtually never need to use the verbatim HTML markup.

 Custom Style

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 
@@style-list1;Text@@
 
@@#alfa;.bravo;Text@@
 
<span id="alfa" class="bravo">Text</span>
 
@@color:red;Text@@
 
<span style="color:red">Text</span>
Block 
@@style-list1;
Text
@@
 
@@#alfa;.bravo;
Text
@@
 
<div id="alfa" class="bravo">Text</div>
 
@@color:red;
Text
@@
 
<div style="color:red">Text</div>
  1. The style-list should be a semi-colon (;) separated list consisting of one or more of the following: As of v2.31.0, the ID and class names components may be conjoined without need of extra semi-colons—e.g., #alfa;.bravo;.charlie; may also be written as #alfa.bravo.charlie;.

 Template

A text replacement markup. The template markup begins with a question mark (?) followed by the template name—e.g., ?yolo—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.

For example, consider the following markup:

?He was always willing to lend ?his ear to anyone.

Assuming that ?He resolves to She and ?his to her, then that will produce the following output:

She was always willing to lend her ear to anyone.

History:

 Comment

Note: Comments used within passage markup are not rendered into the page output.

Type Syntax & Example Supported Within…
C-style, Block 
/* This is a comment. */
 Passage markup, JavaScript, Stylesheets
TiddlyWiki, Block 
/% This is a comment. %/
 Passage markup
HTML, Block 
<!-- This is a comment. -->
 Passage markup

 TwineScript

TwineScript in SugarCube is, essentially, JavaScript with an extra spoonful of sugar on top to make it a bit nicer for the uninitiated.

 Variables

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 $name to store the main player character's name or the story variable $cash to store how much money the player has on hand.

Values may be of most primitive types and some object types, see Supported Types for more information.

Note:

There are two other variables where you may store values:

Variable Names

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., A-Za-z$_)—after their initial use as the sigil, the dollar sign and underscore become regular variable characters.

Subsequent, optional, characters have the same set as the second with the addition of numerals (i.e., 0-9, so the full set is A-Za-z0-9$_). No other characters are allowed.

A few examples of valid names:

/* Story variables */
$cash
$hasKeyCard5
$met_alice
$TIMES_POKED_MR_BEAR

/* Temporary variables */
_i
_something2
_some_loop_value
_COUNT

Using Variables

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.

To print the values contained within variables, see the naked variable markup and the <<print>>, <<=>>, and <<->> macros.

To control aspects of your project based on the values contained within variables, see the <<if>> and <<switch>> macros.

 Supported Types

The following types of values are natively supported by SugarCube and may be safely used within story and temporary variables.

Primitives

Objects

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 .clone() and .toJSON() methods for them—see the Non-generic object types (classes) guide for more information.

Warning:

Due to how SugarCube stores the state history a few constructs are not supported within story variables.

 Expressions

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., $a, 69, and "hello". Complex expressions consist of basic expressions joined together by operators—e.g., = and +.

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)

Using Expressions

You will, in all likelihood, use expressions most often within macros—e.g., <<set>>, <<print>>, <<if>>, <<for>>.

 Operators

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

Assignment operators assign a value to their left-hand operand based on the value of their right-hand operand.

TwineScript assignment operators:

Operator Description Example
to Assigns the value on the right-hand side of the operator to the left-hand side. 
$apples to 6

JavaScript assignment operators: (not an exhaustive list)

Operator Description Example
= Assigns the value on the right-hand side of the operator to the left-hand side. 
$apples = 6
+= 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. 
$apples += 1
-= 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. 
$apples -= 1
*= 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. 
$apples *= 2
/= 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. 
$apples /= 2
%= 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. 
$apples %= 10

Conditional operators

Comparison operators compare their operands and return a boolean value based on whether the comparison is true.

TwineScript conditional operators:

Operator Description Example
is Evaluates to true if both sides are strictly equal. 
$bullets is 6
isnot Evaluates to true if both sides are strictly not equal. 
$pie isnot "cherry"
eq Evaluates to true if both sides are equivalent. Not recommended, use the is operator. 
$bullets eq 6
neq Evaluates to true if both sides are not equivalent. Not recommended, use the isnot operator. 
$pie neq "cherry"
gt Evaluates to true if the left side is greater-than the right side. 
$cash gt 5
gte Evaluates to true if the left side is greater-than-or-equal-to the right side. 
$foundStars gte $neededStars
lt Evaluates to true if the left side is less-than the right side. 
$shoeCount lt ($peopleCount * 2)
lte Evaluates to true if the left side is less-than-or-equal-to the right side. 
$level lte 30
not Flips a true evaluation to false, and vice versa. 
not $hungry
and Evaluates to true if all subexpressions evaluate to true. 
$age gte 20 and $age lte 30
or Evaluates to true if any subexpressions evaluate to true. 
$friend is "Sue" or $friend is "Dan"
def Evaluates to true if the right side is defined. See the precedence warning below. 
def $mushrooms
ndef Evaluates to true if the right side is not defined. See the precedence warning below. 
ndef $bottlecaps

Warning: The def and ndef 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 $style) and ($style is "girly").

JavaScript conditional operators: (not an exhaustive list)

Operator Description Example
=== Evaluates to true if both sides are strictly equal. 
$bullets === 6
!== Evaluates to true if both sides are strictly not equal. 
$pie !== "cherry"
== Evaluates to true if both sides are equivalent. Not recommended, use the === operator. 
$bullets == 6
!= Evaluates to true if both sides are not equivalent. Not recommended, use the !== operator. 
$pie != "cherry"
> Evaluates to true if the left side is greater-than the right side. 
$cash > 5
>= Evaluates to true if the left side is greater-than-or-equal-to the right side. 
$foundStars >= $neededStars
< Evaluates to true if the left side is less-than the right side. 
$shoeCount < ($peopleCount * 2)
<= Evaluates to true if the left side is less-than-or-equal-to the right side. 
$level <= 30
! Flips a true evaluation to false, and vice versa. 
!$hungry
&& Evaluates to true if all subexpressions evaluate to true. 
$age >= 20 && $age <= 30
|| Evaluates to true if any subexpressions evaluate to true. 
$friend === "Sue" || $friend === "Dan"

 Macros

 Macro Arguments

Macros fall into two broad categories based on the kind of arguments they accept: those that want an expression—e.g., <<set>> and <<print>>—and those that want discrete arguments separated by whitespace—e.g., <<link>> and <<audio>>. The documentation for each macro will tell you what it expects.

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.

Argument type macros: passing a variable's name as an 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 <<textbox>>—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 $pie as normal, you'd pass "$pie". These, rare, instances are noted in the macros' documentation and shown in their examples.

Argument type macros: passing an expression as an argument

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>>
  1. A backquote is also known as a grave and is often paired with the tilde (~) on keyboards.

 Variables Macros

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

History:

Arguments:

Examples:

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

History:

Arguments:

Examples:

Using the TwineScript "to" operator
<<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
Using the standard JavaScript operators
<<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.

History:

Arguments:

Examples:

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']>>

 Scripting Macros

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

History:

Arguments:

Examples:

Basic usage
<<script>>
	/* JavaScript code */
<</script>>

<<script TwineScript>>
	/* TwineScript code */
<</script>>
Accessing managed variables
<<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>>
Modifying the content buffer

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

 Display Macros

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

History:

Arguments:

Examples:

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

History:

Arguments:

Examples:

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

History:

Arguments:

Examples:

Basic usage
<<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>>
Filtering updates
''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.

History:

Arguments:

Passage name form
Link markup form

Examples:

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

History:

Arguments: none

Examples:

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

History:

Arguments:

Examples:

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

History:

Arguments:

Examples:

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.

History:

Arguments: none

Examples:

→ 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., <<linkreplace>>, <<timed>>, etc.—may or may not behave as you'd expect. Testing is strongly advised.

See Also: Config.macros.typeSkipKey, Config.macros.typeVisitedPassages, <<type>> Events.

History:

Arguments:

Examples:

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

CSS styles:

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 macro-type class. For example:

.macro-type {
	color: limegreen;
	font-family: monospace, monospace;
}

There's also a macro-type-done class that is added to text that has finished typing, which may be used to style it differently from actively typing text.

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 :after pseudo-element of the macro-type-cursor class. For example:

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

History:

 Control Macros

 <<if conditional>> … [<<elseif conditional>> …] [<<else>> …] <</if>>

Executes its contents if the given conditional expression evaluates to true. If the condition evaluates to false and an <<elseif>> or <<else>> exists, then other contents can be executed.

Note: SugarCube does not trim whitespace from the contents of <<if>> 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.

History:

Arguments:

Examples:

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

History:

Notes:

Conditional forms

Executes its contents while the given conditional expression evaluates to true. If no conditional expression is given, it is equivalent to specifying 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.

Range form

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.

Arguments:

Conditional forms
Range form
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.

Examples:

Conditional forms

Iterating over an array.

/* Given the following: */
<<set $pies to ["Apple", "Blueberry", "Cherry", "Pecan", "Raspberry"]>>

<<for _i to 0; _i lt $pies.length; _i++>>
<<print _i + 1>>. $pies[_i]
<</for>>

/* Outputs */
1. Apple
2. Blueberry
3. Cherry
4. Pecan
5. Raspberry
Range form

Ranging over an array.

/* Given the following: */
<<set $pies to ["Apple", "Blueberry", "Cherry", "Pecan", "Raspberry"]>>

<<for _i, _name range $pies>>
<<print _i + 1>>. _name
<</for>>

/* Outputs */
1. Apple
2. Blueberry
3. Cherry
4. Pecan
5. Raspberry

Ranging over an integer.

<<for _value range 5>>
<<print _value + 1>>.
<</for>>

/* Outputs */
1.
2.
3.
4.
5.

 <<break>>

Used within <<for>> macros. Terminates the execution of the current <<for>>.

History:

Arguments: none

 <<continue>>

Used within <<for>> macros. Terminates the execution of the current iteration of the current <<for>> and begins execution of the next iteration.

Note: May eat line-breaks in certain situations.

History:

Arguments: none

 <<switch expression>>
[<<case valueList>> …]
[<<default>> …]
<</switch>>

Evaluates the given expression and compares it to the value(s) within its <<case>> children. The value(s) within each case are compared to the result of the expression given to the parent <<switch>>. Upon a successful match, the matching case will have its contents executed. If no cases match and an optional <<default>> case exists, which must be the final case, then its contents will be executed. At most one case will execute.

Note: SugarCube does not trim whitespace from the contents of <<case>>/<<default>> 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.

History:

Arguments:

<<switch>>
<<case>>

Examples:

→ 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

 Warning

Interactive macros are both asynchronous and require interaction from the player. Thus, there are some potential pitfalls to consider:

  1. If you plan on using interactive macros within a loop you will likely need to use the <<capture>> macro due to their asynchronous nature.
  2. Reloading the page or revisiting a passage may not restore the state of some interactive macros, so it is recommended that you only use them in instances where this will not be an issue or where you can work around it.

 <<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 (<button>) rather than an anchor element (<a>).

History:

Arguments:

Separate argument form
Link markup form
Image markup form

Examples:

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

History:

Arguments:

Examples:

Basic usage
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?
With a <label> element

Tip: For accessibility reasons, it's recommended that you wrap each <<checkbox>> and its accompanying text within a <label> element. Doing so allows interactions with the text to also trigger its <<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 <<option>> and/or <<optionsfrom>>.

See: Interactive macro warning.

History:

Arguments:

<<cycle>>
<<option>>
<<optionsfrom>>

Examples:

Using <<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>>
Using <<optionsfrom>> with an array
→ Given: _pieOptions = ["blueberry", "cherry", "coconut cream"]
What's your favorite pie?
<<cycle "$pie" autoselect>>
	<<optionsfrom _pieOptions>>
<</cycle>>
Using <<optionsfrom>> with an generic object
→ Given: _pieOptions = { "Blueberry" : "blueberry", "Cherry" : "cherry", "Coconut cream" : "coconut cream" }
What's your favorite pie?
<<cycle "$pie" autoselect>>
	<<optionsfrom _pieOptions>>
<</cycle>>
Using the once keyword
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>>

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.

History:

Arguments:

Separate argument form
Link markup form
Image markup form

Examples:

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

History:

Arguments:

Examples:

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

History:

Arguments:

Examples:

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

History:

Arguments:

Examples:

→ 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 <<option>> and/or <<optionsfrom>>.

See: Interactive macro warning.

History:

Arguments:

<<listbox>>
<<option>>
<<optionsfrom>>

Examples:

Using <<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>>
Using <<optionsfrom>> with an array
→ Given: _pieOptions = ["blueberry", "cherry", "coconut cream"]
What's your favorite pie?
<<listbox "$pie" autoselect>>
	<<optionsfrom _pieOptions>>
<</listbox>>
Using <<optionsfrom>> with an generic object
→ 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.

History:

Arguments:

Examples:

→ 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 <<radiobutton>> macros may be set up to modify the same variable, which makes them part of a radio button group.

See: Interactive macro warning.

History:

Arguments:

Examples:

Basic usage
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?
With a <label> element

Tip: For accessibility reasons, it's recommended that you wrap each <<radiobutton>> and its accompanying text within a <label> element. Doing so allows interactions with the text to also trigger its <<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.

History:

Arguments:

Examples:

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

History:

Arguments:

Examples:

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

History:

Arguments:

Separate argument form
Link markup form
Image markup form

Examples:

Visual aid

Assume your story history consists of three moments:

A, B, [C]

N.b., the square brackets there denote the active moment.

Using <<back>> once upon that history will change it to be thus:

A, [B], C

I.e., the history was rolled back to the previous moment.

Basic usage
→ Creates a link that undoes the most recent moment, with default text
<<back>>
Separate argument form
→ 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">>
Link markup form
→ 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]]>>
Image markup form
→ 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.

History:

Arguments:

Separate argument form
Link markup form
Image markup form

Examples:

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.

Visual aid

Assume your story history consists of three moments:

A, B, [C]

N.b., the square brackets there denote the active moment.

Using <<return>> once upon that history will change it to be thus:

A, B, C, [B]

I.e., a new moment, to the same passage as the previous moment, was added to the history.

Basic usage
→ Creates a link that forwards to the previous passage, with default text
<<return>>
Separate argument form
→ 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">>
Link markup form
→ 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]]>>
Image markup form
→ 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.

History:

 <<choice passageName [linkText]>>
<<choice linkMarkup>>
<<choice imageMarkup>>

Deprecated: This macro has been deprecated and should no longer be used.

History:

 DOM Macros

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.

History:

Arguments:

Examples:

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

History:

Arguments:

Examples:

Without a 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>.
With a transition
→ 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 <<copy>>. Attempting to do so will, usually, result in something that's non-functional.

See: DOM macro warning.

History:

Arguments:

Examples:

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

History:

Arguments:

Examples:

Without a 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>.
With a transition
→ 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.

History:

Arguments:

Examples:

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

History:

Arguments:

Examples:

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

History:

Arguments:

Usage

Without a 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>.
With a transition
→ 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.

History:

Arguments:

Examples:

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

 Audio Macros

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 <<audio>> macro cannot affect playlist tracks whose ownership has been transferred to their respective playlist. Meaning those set up via <<createplaylist>> with its own action, as owned playlist tracks are solely under the control of their playlist.

Note: The Config.audio.pauseOnFadeToZero setting (default: true) controls whether tracks that have been faded to 0 volume (silent) are automatically paused.

History:

Arguments:

Group IDs:

Group IDs allow several tracks to be selected simultaneously without needing to specify each one individually. There are several predefined group IDs (:all, :looped, :muted, :paused, :playing, :stopped) and custom IDs may be defined via <<createaudiogroup>>. The :not() group modifier syntax (groupId:not(trackIdList)) allows a group to have some of its tracks excluded from selection.

Examples:

Basic usage with group IDs
→ 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>>
Basic usage with track IDs
→ 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>>
Using the load and unload actions

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.

History:

Arguments:

Examples:

→ 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 <<track>> children. Groups are useful for applying actions to multiple tracks simultaneously and/or excluding the included tracks from a larger set when applying actions.

Note: The StoryInit special passage is normally the best place to set up groups.

History:

Arguments:

<<createaudiogroup>>
<<track>>

Examples:

→ 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 <<track>> children.

Note: The StoryInit special passage is normally the best place to set up playlists.

History:

Arguments:

<<createplaylist>>
<<track>>

Examples:

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

History:

Arguments:

Examples:

Basic usage
→ 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>>
Using the load and unload actions

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: true) controls whether tracks that have been faded to 0 volume (silent) are automatically paused.

History:

Arguments:

<<createplaylist>>-compatible form
<<setplaylist>>-compatible form

Examples: (only <<createplaylist>>-compatible form shown)

Basic usage
→ 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>>
Using the load and unload actions

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 (:all, :looped, :muted, :paused, :playing, :stopped) or the :not group modifier.

History:

Arguments:

Examples:

→ Given a group set up via <<createaudiogroup ":ui">>…<</createplaylist>>
<<removeaudiogroup ":ui">>

 <<removeplaylist listId>>

Removes the playlist with the given ID.

History:

Arguments:

Examples:

→ 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 <<cacheaudio>> and <<createplaylist>>, if any <<track>> definitions used the copy keyword, for which you want the loading screen displayed.

History:

Arguments: none

Examples:

Basic usage
<<cacheaudio "a" "a_track.…">>
<<cacheaudio "b" "b_track.…">>
<<cacheaudio "c" "c_track.…">>
<<cacheaudio "d" "d_track.…">>
<<waitforaudio>>
Load only selected audio at startup
→ 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.…">>

 Miscellaneous Macros

 <<done>> … <</done>>

Silently executes its contents when the page is done rendering and the engine has become idle. 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 <<done>> macro, but are run each time passage navigation occurs.

History:

Arguments: none

Examples:

@@#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 <<goto>> 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 <<link>> body, <<goto>> is unnecessary as <<link>> already includes the ability to forward the player.

Warning: Using <<goto>> 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.

Warning: <<goto>> 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.

History:

Arguments:

Passage name form
Link markup form

Examples:

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

History:

Arguments:

Examples:

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

History:

Arguments: none

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

History:

Arguments:

<<timed>>
<<next>>

Examples:

→ 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 _args special variable. Block widgets may access the contents they enclose via the _contents special variable.

Warning: Widgets should always be defined within a widget-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 widget tag to any of the specially named passages and attempt to define your widgets there.

Warning: The array-like object stored in the _args 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.

History:

Arguments:

Special variables, _args & _contents:

The _args special variable is used internally to store arguments passed to the widget—as zero-based indices; i.e., _args[0] is the first parsed argument, _args[1] is the second, etc—the full argument string in raw and parsed forms—accessed via the _args.raw and _args.full properties—and the widgets' name via the _args.name property.

The _contents special variable is used internally, by container widgets, to store the contents they enclose.

When a widget is called, any existing _args variable, and for container widgets _contents, 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.

Warning:

When calling one container widget directly from within another container widget, the _contents 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.,

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

Examples:

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.

Basic usage (non-container)
→ 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!
Basic usage (container)
→ 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>>

 Functions

 clone(original) → any

Returns a deep copy of the given value.

Only primitives, generic objects, Array, Date, Map, RegExp, and Set are supported by default. Unsupported object types, either native or custom, will need to implement a .clone() method to be properly supported by the clone() 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.

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.

History:

Parameters:

Returns:

A deep copy (any) of the original value.

Throws: none

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $foo to { id : 1 }>>

/* Without clone() */
<<set $bar to $foo>>
<<set $bar.id to 5>>
<<= $foo.id>> // Prints 5
<<= $bar.id>> // Prints 5

/* With clone() */
<<set $bar to clone($foo)>>
<<set $bar.id to 5>>
<<= $foo.id>> // Prints 1
<<= $bar.id>> // Prints 5
Basic usage (in JavaScript)
// Given the following:
let foo = { id : 1 };

// Without clone()
let bar = foo;
bar.id = 5;
foo.id; // Yields 5
bar.id; // Yields 5

// With clone()
let bar = clone(foo);
bar.id = 5;
foo.id; // Yields 1
bar.id; // Yields 5

 either(list…) → any

Returns a random value from its given arguments.

History:

Parameters:

Returns:

A random value (any) from its given arguments.

Throws: none

Examples:

Basic usage (in macros)

Using singular values.

/* Returns a random pie from the whole list */
<<set $pie to either('Blueberry', 'Cherry', 'Pecan')>>

Using arrays.

/* Returns a random pie from the whole array */
<<set $pies to ['Blueberry', 'Cherry', 'Pecan']>>
<<set $pie to either($pies)>>

Using singular values and arrays.

/* Returns a random value from the whole list—i.e., 'A', 'B', 'C', 'D' */
<<set $letters to ['A', 'B']>>
<<set $letter to either($letters, 'C', 'D')>>

Using multiple arrays.

/* Returns a random value from the whole list—i.e., 'A', 'B', '1', '2' */
<<set $letters to ['A', 'B']>>
<<set $numerals to ['1', '2']>>
<<set $alphaNum to either($letters, $numerals)>>
Basic usage (in JavaScript)

Using singular values.

// Returns a random pie from the whole list
let pie = either('Blueberry', 'Cherry', 'Pecan');

Using arrays.

// Returns a random pie from the whole array
let pies = ['Blueberry', 'Cherry', 'Pecan'];
let pie  = either(pies);

Using singular values and arrays.

// Returns a random value from the whole list—i.e., 'A', 'B', 'C', 'D'
let letters = ['A', 'B'];
let letter  = either(letters, 'C', 'D');

Using multiple arrays.

// Returns a random value from the whole list—i.e., 'A', 'B', '1', '2'
let letters  = ['A', 'B'];
let numerals = ['1', '2']
let alphaNum = either(letters, numerals);

 forget(key)

Removes the specified key, and its associated value, from the story metadata store.

See Also: memorize(), recall().

History:

Parameters:

Returns: none

Throws:

An Error or TypeError instance.

Examples:

Basic usage (in macros)
/* Clears 'achievements' from the metadata store. */
<<run forget('achievements')>>
Basic usage (in JavaScript)
// Clears 'achievements' from the metadata store.
forget('achievements');

 hasVisited(passageNames…) → 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., true if all were found, false if any were not found.

History:

Parameters:

Returns:

Boolean true if all were found, elsewise false.

Throws:

An Error instance.

Examples:

Basic usage (in macros)
<<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>>
Basic usage (in JavaScript)
if (hasVisited('Bar')) {
	// Has been to the Bar.
}

if (!hasVisited('Bar')) {
	// Has never been to the Bar.
}

if (hasVisited('Bar', 'Café')) {
	// Has been to both the Bar and Café.
}

if (!hasVisited('Bar', 'Café')) {
	// Has never been to either the Bar, Café, or both.
}

 lastVisited(passageNames…) → integer number

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 -1, if it does not exist. If multiple passage names are given, returns the lowest count among them, which can be -1.

History:

Parameters:

Returns:

The lowest count (integer number), elsewise -1.

Throws:

An Error instance.

Examples:

Basic usage (in macros)
<<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>>
Basic usage (in JavaScript)
if (lastVisited('Bar') === -1) {
	// Has never been to the Bar.
}

if (lastVisited('Bar') === 0) {
	// Is currently in the Bar.
}

if (lastVisited('Bar') === 1) {
	// Was in the Bar one turn ago.
}

if (lastVisited('Bar', 'Café') === -1) {
	// Has never been to the Bar, Café, or both.
}

if (lastVisited('Bar', 'Café') === 2) {
	// Has been to both the Bar and Café, most recently two turns ago.
}

 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 Promise returned by the function to ensure that the script is loaded before it is needed.

Note: Your project's JavaScript section (Twine 2: the Story JavaScript; Twine 1/Twee: a script-tagged passage) is normally the best place to call importScripts().

History:

Parameters:

Returns:

A Promise that simply resolves, or rejects with an error if the script could not be loaded.

Throws:

An Error or TypeError instance.

Examples:

Basic usage
// 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'
	]
);
Basic usage with the returned Promise object
// 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(() => {
		// Code that depends on the script goes here
	})
	.catch((err) => {
		// There was an error loading the script, log it to the console
		console.log(err);
	});
Saving the returned Promise object for later use
// 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(() => {
		// Code that depends on the script goes here
	})
	.catch((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 Promise returned by the function to ensure that the stylesheet is loaded before it is needed.

Note: Your project's JavaScript section (Twine 2: the Story JavaScript; Twine 1/Twee: a script-tagged passage) is normally the best place to call importStyles().

History:

Parameters:

Returns:

A Promise that simply resolves, or rejects with an error if the style could not be loaded.

Throws:

An Error or TypeError instance.

Examples:

Basic usage
// 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'
	]
);
Basic usage with the returned Promise object
// 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(() => {
		// The stylesheet has been loaded, release the loading screen lock
		LoadScreen.unlock(lsLockId);
	})
	.catch((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.

See Also: forget(), recall().

History:

Parameters:

Returns: none

Throws:

An TypeError instance.

Examples:

Basic usage (in macros)
/* 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)>>
Basic usage (in JavaScript)
// Sets 'achievements', with the given value, in the metadata store.
memorize('achievements', { ateYellowSnow : true });

// Sets 'ngplus', with the given value, in the metadata store.
memorize('ngplus', true);

 passage() → string

Returns the name of the active (present) passage.

History:

Parameters: none

Returns:

The name (string) of the passage.

Throws: none

Examples:

Basic usage as part of a link
/* Link markup.*/
[[Reload passage|passage()]]

/* Link macro.*/
<<link "Reload passage" `passage()`>><</link>>
Basic usage (in macros)
/* Get the name of the active passage. */
<<set $passageName to passage()>>

<<if passage() is 'Café'>>
	…the active passage is the Café passage…
<</if>>
Basic usage (in JavaScript)
// Get the name of the active passage.
let passageName = passage();

if (passage() === 'Café') {
	// The active passage is the Café passage.
}

 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.

Warning: If you need to go back multiple passages—e.g., if you have a menu and you want the player to return from any depth—then previous() may be insufficient for your needs. In that case, you'll want to look at the arbitrarily long return.

History:

Parameters: none

Returns:

The name (string) of the passage, elsewise an empty string ('').

Throws: none

Examples:

Basic usage as part of a link
/* Link markup.*/
[[Return|previous()]]

/* Link macro.*/
<<link "Return" `previous()`>><</link>>
Basic usage (in macros)
/* Get the name of the most recent non-active passage. */
<<set $previousName to previous()>>

<<if previous() is 'Café'>>
	…the most recent non-active passage is the Café passage…
<</if>>
Basic usage (in JavaScript)
// Get the name of the most recent non-active passage.
let previousName = previous();

if (previous() === 'Café') {
	// The most recent non-active passage is the Café passage.
}

 random([min ,] max) → integer number

Returns a pseudo-random whole number (integer) within the range of the given bounds (inclusive)—i.e., [min, max].

Note: By default, it 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.

History:

Parameters:

Returns:

A random whole number (integer number).

Throws:

An Error or TypeError instance.

Examples:

Basic usage (in macros)
/* Returns a number in the range 0–5 */
<<set $randInt to random(5)>>

/* Returns a number in the range 1–6 */
<<set _randInt to random(1, 6)>>
Basic usage (in JavaScript)
// Returns a number in the range 0–5
let randInt = random(5);

// Returns a number in the range 1–6
let randInt = random(1, 6);

 randomFloat([min ,] max) → decimal number

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

History:

Parameters:

Returns:

A random floating-point number (decimal number).

Throws:

An Error or TypeError instance.

Examples:

Basic usage (in macros)
/* Returns a number in the range 0.0–4.9999999… */
<<set $randNum to randomFloat(5.0)>>

/* Returns a number in the range 1.0–5.9999999… */
<<set _randNum to randomFloat(1.0, 6.0)>>
Basic usage (in JavaScript)
// Returns a number in the range 0.0–4.9999999…
let randNum = randomFloat(5.0);

// Returns a number in the range 1.0–5.9999999…
let randNum = randomFloat(1.0, 6.0);

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

History:

Parameters:

Returns:

A value (any) from the specified key, elsewise the default value if specified.

Throws:

A TypeError instance.

Examples:

Basic usage (in macros)
/*
	Set setup.achievements to the 'achievements' metadata, defaulting
	to an empty generic object if no metadata exists.
*/
<<set setup.achievements to recall('achievements', {})>>

/* Set setup.ngplus to the 'ngplus' metadata, with no default. */
<<set setup.ngplus to recall('ngplus')>>
Basic usage (in JavaScript)
// Set setup.achievements to the 'achievements' metadata, defaulting
// to an empty generic object if no metadata exists.
setup.achievements = recall('achievements', {});

// Set setup.ngplus to the 'ngplus' metadata, with no default.
setup.ngplus = recall('ngplus');

 setPageElement(idOrElement , passageNames [, 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.

History:

Parameters:

Returns:

An HTMLElement instance, elsewise null.

Throws: none

Examples:

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.

Basic usage (in macros)
/* Using an ID; given an existing element on the page: <div id="my-display"></div> */
<<run setPageElement('my-display', 'MyPassage')>>

/* Using an element; given a reference to an existing element: myElement */
<<run setPageElement(myElement, 'MyPassage')>>
Basic usage (in JavaScript)
// 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([passageNames]) → Array<string>

Returns a new array consisting of all of the tags of the given passage names.

History:

Parameters:

Returns:

An Array<string> containing the tags.

Throws: none

Examples:

Basic usage (in macros)
/* Get the tags of the active passage. */
<<set $activeTags to tags()>>

/* Get the tags of the given passage. */
<<set $lonelyGladeTags to tags('Lonely Glade')>>

<<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>>
Basic usage (in JavaScript)
// Get the tags of the active passage.
let activeTags = tags();

// Get the tags of the given passage.
let lonelyGladeTags = tags('Lonely Glade');

if (tags().includes('forest')) {
	// The active passage is part of the forest.
}

if (tags('Lonely Glade').includes('forest')) {
	// The Lonely Glade passage is part of the forest.
}

 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.

History:

Parameters: none

Returns:

A reference to the temporary variable store (Object).

Throws: none

Examples:

// Given the following: _selection is 'Zagnut Bar'
if (temporary().selection === 'Zagnut Bar') {
	// Do something…
}

 time() → integer number

Returns the number of milliseconds that have passed since the current passage was rendered to the page.

History:

Parameters: none

Returns:

The milliseconds (integer number) since the passage was rendered.

Throws: none

Examples:

/* 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 10000>>
		/* The player clicked the link in under 10s, so they escape. */
		<<goto "Well lit passageway">>
	<<else>>
		/* Elsewise, 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.

History:

Parameters:

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

Options object:

Warning: Adding additional properties directly to event options objects is not recommended. Instead, use the detail property.

An event options object should have some of the following properties:

Returns: none

Throws: none

Examples:

Basic usage (in macros)

Note: The macro examples would be exactly the same as the JavaScript examples, just wrapped in a <<script>> macro.

Basic usage (in JavaScript)

Dispatch a custom fnord event on document.

triggerEvent('fnord');

Dispatch a click event on the element bearing the ID some-menu.

triggerEvent('click', document.getElementById('some-menu'));

Dispatch a custom update-meter event on document while specifying some options.

triggerEvent('update-meter', document, {
	detail : {
		tags : ['health', 'magick']
	}
});

Various ways to dispatch a mouseover event on all elements bearing the class flippable.

triggerEvent('mouseover', document.getElementsByClassName('flippable'));

triggerEvent('mouseover', document.querySelectorAll('.flippable'));

triggerEvent('mouseover', jQuery('.flippable'));

 turns() → integer number

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.

History:

Parameters: none

Returns:

The turn count (integer number).

Throws: none

Examples:

Basic usage (in macros)
/* Record the turn count. */
<<set $turnCount to turns()>>

<<= 'This is turn #' + turns()>>
Basic usage (in JavaScript)
// Record the turn count.
let turnCount = 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.

History:

Parameters: none

Returns:

A reference to the story variable store (Object).

Throws: none

Examples:

// Given: $hasGoldenKey is true
if (variables().hasGoldenKey) {
	/* Do something… */
}

 visited([passageNames]) → integer number

Returns the number of times that the passage with the given name occurred within the story history. If multiple passage names are given, returns the lowest count among them.

History:

Parameters:

Returns:

The passage count (integer number).

Throws: none

Examples:

Basic usage (in macros)
<<if visited() is 3>>
	…has been to the current passage exactly three times…
<</if>>

<<if visited('Bar')>>
	…has been to the Bar at least once…
<</if>>

<<if visited('Café') is 2>>
	…has been to the Café exactly twice…
<</if>>

<<if visited('Bar', 'Café') is 4>>
	…has been to both the Bar and Café four or more times…
<</if>>
Basic usage (in JavaScript)
if (visited() === 3) {
	// Has been to the current passage exactly three times.
}

if (visited('Bar')) {
	// Has been to the Bar at least once.
}

if (visited('Café') === 2) {
	// Has been to the Café exactly twice.
}

if (visited('Bar', 'Café') === 4) {
	// Has been to both the Bar and Café four or more times.
}

 visitedTags(tags…) → integer number

Returns the number of passages within the story history that are tagged with all of the given tags.

History:

Parameters:

Returns:

The number (integer number) of passages that are tagged with the given tags.

Throws:

An Error instance.

Examples:

Basic usage (in macros)
<<if visitedTags('forest')>>
	…has been to some part of the forest at least once…
<</if>>

<<if visitedTags('forest', 'haunted') is 2>>
	…has been to the haunted part of the forest exactly twice…
<</if>>

<<if visitedTags('forest', 'burned') gte 3>>
	…has been to the burned part of the forest three or more times…
<</if>>
Basic usage (in JavaScript)
if (visitedTags('forest')) {
	// Has been to some part of the forest at least once.
}

if (visitedTags('forest', 'haunted') === 2) {
	// Has been to the haunted part of the forest exactly twice.
}

if (visitedTags('forest', 'burned') >= 3) {
	// Has been to the burned part of the forest three or more times.
}

 Methods

Most of the methods listed below are SugarCube extensions, with the rest being either JavaScript built-ins or bundled library methods that are listed here for their utility—though, this is not an exhaustive list.

For more information see:

 Array Methods

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

History: JavaScript built-in

Parameters:

Returns:

A new Array formed from concatenating all array members in order.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $fruits1 to ['Apples', 'Oranges']>>
<<set $fruits2 to ['Pears', 'Plums']>>

<<set $result to $fruits1.concat($fruits2)>>
/* Returns ['Apples', 'Oranges', 'Pears', 'Plums'] */

<<set $result to $fruits1.concat($fruits2, $fruits2)>>
/* Returns ['Apples', 'Oranges', 'Pears', 'Plums', 'Pears', 'Plums'] */

<<set $result to $fruits1.concat('Pears')>>
/* Returns ['Apples', 'Oranges', 'Pears'] */

<<set $result to $fruits1.concat('Pears', 'Pears')>>
/* Returns ['Apples', 'Oranges', 'Pears', 'Pears'] */

<<set $result to $fruits1.concat($fruits2, 'Pears')>>
/* Returns ['Apples', 'Oranges', 'Pears', 'Plums', 'Pears'] */
Basic usage (in JavaScript)
// Given the following:
let fruits1 = ['Apples', 'Oranges'];
let fruits2 = ['Pears', 'Plums'];

let result = fruits1.concat(fruits2);
// Returns ['Apples', 'Oranges', 'Pears', 'Plums']

let result = fruits1.concat(fruits2, fruits2);
// Returns ['Apples', 'Oranges', 'Pears', 'Plums', 'Pears', 'Plums']

let result = fruits1.concat('Pears');
// Returns ['Apples', 'Oranges', 'Pears']

let result = fruits1.concat('Pears', 'Pears');
// Returns ['Apples', 'Oranges', 'Pears', 'Pears']

let result = 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.

History:

Parameters:

Returns:

A new Array formed from concatenating all unique array members in order.

Examples:

Basic usage (in macros):
/* Given the following: */
<<set $fruits1 to ['Apples', 'Oranges']>>
<<set $fruits2 to ['Pears', 'Plums']>>

<<set $result to $fruits1.concatUnique($fruits2)>>
/* Returns ['Apples', 'Oranges', 'Pears', 'Plums'] */

<<set $result to $fruits1.concatUnique($fruits2, $fruits2)>>
/* Returns ['Apples', 'Oranges', 'Pears', 'Plums'] */

<<set $result to $fruits1.concatUnique('Pears')>>
/* Returns ['Apples', 'Oranges', 'Pears'] */

<<set $result to $fruits1.concatUnique('Pears', 'Pears')>>
/* Returns ['Apples', 'Oranges', 'Pears'] */

<<set $result to $fruits1.concatUnique($fruits2, 'Pears')>>
/* Returns ['Apples', 'Oranges', 'Pears', 'Plums'] */
Basic usage (in JavaScript):
// Given the following:
let fruits1 = ['Apples', 'Oranges'];
let fruits2 = ['Pears', 'Plums'];

let result = fruits1.concatUnique(fruits2);
// Returns ['Apples', 'Oranges', 'Pears', 'Plums']

let result = fruits1.concatUnique(fruits2, fruits2);
// Returns ['Apples', 'Oranges', 'Pears', 'Plums']

let result = fruits1.concatUnique('Pears');
// Returns ['Apples', 'Oranges', 'Pears']

let result = fruits1.concatUnique('Pears', 'Pears');
// Returns ['Apples', 'Oranges', 'Pears']

let result = fruits1.concatUnique(fruits2, 'Pears');
// Returns ['Apples', 'Oranges', 'Pears', 'Plums']

 <Array>.count(needle [, position]) → integer number

Returns the number of times that the given member was found within the array, starting the search at position.

History:

Parameters:

Returns:

An integer number whose value is the number of times the given member was found within the array.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $fruits to ['Apples', 'Oranges', 'Plums', 'Oranges']>>

<<set $result to $fruits.count('Oranges')>>
/* Returns 2 */

<<set $result to $fruits.count('Oranges', 2)>>
/* Returns 1 */
Basic usage (in JavaScript)
// Given the following:
let fruits = ['Apples', 'Oranges', 'Plums', 'Oranges'];

let result = fruits.count('Oranges');
// Returns 2

let result = fruits.count('Oranges', 2);
// Returns 1

 <Array>.countWith(predicate [, thisArg]) → integer number

Returns the number of times that members within the array pass the test implemented by the given predicate function.

History:

Parameters:

Returns:

An integer number whose value is the number of times members passed the test.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $fruits to ['Apples', 'Oranges', 'Plums', 'Oranges']>>

<<set $result to $fruits.countWith((fruit) => fruit === 'Oranges')>>
/* Returns 2 */

/* Given the following: */
<<set $numbers to [1, 2.3, 4, 76, 3.1]>>

<<set $result to $numbers.countWith(Number.isInteger)>>
/* Returns 3 */

/* Given the following: */
<<set $items to [
	{ name : 'Arming sword',   kind : 'weapon' },
	{ name : 'Crested helm',   kind : 'armor' },
	{ name : 'Dead rat',       kind : 'junk' },
	{ name : 'Healing potion', kind : 'potion' }
]>>

<<set $result to $items.countWith((item) => item.kind === 'junk')>>
/* Returns 1 */
Basic usage (in JavaScript)
// Given the following:
let fruits = ['Apples', 'Oranges', 'Plums', 'Oranges'];

let result = fruits.countWith((fruit) => fruit === 'Oranges');
// Returns 2

// Given the following:
let numbers = [1, 2.3, 4, 76, 3.1];

let result = numbers.countWith(Number.isInteger);
// Returns 3

// Given the following:
let items = [
	{ name : 'Arming sword',   kind : 'weapon' },
	{ name : 'Crested helm',   kind : 'armor' },
	{ name : 'Dead rat',       kind : 'junk' },
	{ name : 'Healing potion', kind : 'potion' }
];

let result = items.countWith((item) => 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.

History:

Parameters:

Returns:

A new Array containing the removed members.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $fruits to ['Apples', 'Oranges', 'Plums', 'Oranges']>>

<<set $result to $fruits.deleteAll('Oranges')>>
/* Returns ['Oranges', 'Oranges'] */
/* $fruits ['Apples', 'Plums'] */

<<set $result to $fruits.deleteAll('Apples', 'Plums')>>
/* Returns ['Apples', 'Plums'] */
/* $fruits ['Oranges', 'Oranges'] */
Basic usage (in JavaScript)
// Given the following:
let fruits = ['Apples', 'Oranges', 'Plums', 'Oranges'];

let result = fruits.deleteAll('Oranges');
// Returns ['Oranges', 'Oranges']
// $fruits ['Apples', 'Plums']

let result = 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.

History:

Parameters:

Returns:

A new Array containing the removed members.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $fruits to ['Apples', 'Oranges', 'Plums', 'Oranges']>>

<<set $result to $fruits.deleteAt(2)>>
/* Returns ['Plums'] */
/* $fruits ['Apples', 'Oranges', 'Oranges'] */

<<set $result to $fruits.deleteAt(1, 3)>>
/* Returns ['Oranges', 'Oranges'] */
/* $fruits ['Apples', 'Plums'] */

<<set $result to $fruits.deleteAt(0, 2)>>
/* Returns ['Apples', 'Plums'] */
/* $fruits ['Oranges', 'Oranges'] */
Basic usage (in JavaScript)
// Given the following:
let fruits = ['Apples', 'Oranges', 'Plums', 'Oranges'];

let result = fruits.deleteAt(2);
// Returns ['Plums']
// fruits ['Apples', 'Oranges', 'Oranges']

let result = fruits.deleteAt(1, 3);
// Returns ['Oranges', 'Oranges']
// fruits ['Apples', 'Plums']

let result = 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.

History:

Parameters:

Returns:

A new Array containing the removed members.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $fruits to ['Apples', 'Oranges', 'Plums', 'Oranges']>>

<<set $result to $fruits.deleteFirst('Oranges')>>
/* Returns ['Oranges'] */
/* $fruits ['Apples', 'Plums', 'Oranges'] */

<<set $result to $fruits.deleteFirst('Apples', 'Plums')>>
/* Returns ['Apples', 'Plums'] */
/* $fruits ['Oranges', 'Oranges'] */
Basic usage (in JavaScript)
// Given the following:
let fruits = ['Apples', 'Oranges', 'Plums', 'Oranges'];

let result = fruits.deleteFirst('Oranges');
// Returns ['Oranges']
// fruits ['Apples', 'Plums', 'Oranges']

let result = 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.

History:

Parameters:

Returns:

A new Array containing the removed members.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $fruits to ['Apples', 'Oranges', 'Plums', 'Oranges']>>

<<set $result to $fruits.deleteLast('Oranges')>>
/* Returns ['Oranges'] */
/* $fruits ['Apples', 'Oranges', 'Plums'] */

<<set $result to $fruits.deleteLast('Apples', 'Plums')>>
/* Returns ['Apples', 'Plums'] */
/* $fruits ['Oranges', 'Oranges'] */
Basic usage (in JavaScript)
// Given the following:
let fruits = ['Apples', 'Oranges', 'Plums', 'Oranges'];

let result = fruits.deleteLast('Oranges');
// Returns ['Oranges']
// fruits ['Apples', 'Oranges', 'Plums']

let result = 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.

History:

Parameters:

Returns:

A new Array containing the removed members.

Examples:

Basic usage (in macros)

Usage with primitive values.

/* Given the following: */
<<set $fruits to ['Apples', 'Apricots', 'Oranges']>>

$fruits.deleteWith((val) => val === 'Apricots')
/* Returns ['Apricots'] */
/* $fruits ['Apples', 'Oranges'] */

$fruits.deleteWith((val) => val.startsWith('Ap'))
/* Returns ['Apples', 'Apricots'] */
/* $fruits ['Oranges'] */

Usage with object values.

/* Given the following: */
<<set $fruits to [{ name : 'Apples' }, { name : 'Apricots' }, { name : 'Oranges' }]>>

$fruits.deleteWith((val) => val.name === 'Apricots')
/* Returns [{ name : 'Apricots' }] */
/* $fruits [{ name : 'Apples' }, { name : 'Oranges' }] */

$fruits.deleteWith((val) => val.name.startsWith('Ap'))
/* Returns [{ name : 'Apples' }, { name : 'Apricots' }] */
/* $fruits [{ name : 'Oranges' }] */
Basic usage (in JavaScript)

Usage with primitive values.

// Given the following:
let fruits = ['Apples', 'Apricots', 'Oranges'];

let result = fruits.deleteWith((val) => val === 'Apricots');
// Returns ['Apricots']
// fruits ['Apples', 'Oranges']

let result = fruits.deleteWith((val) => val.startsWith('Ap'));
// Returns ['Apples', 'Apricots']
// fruits ['Oranges']

Usage with object values.

// Given the following:
let fruits = [{ name : 'Apples' }, { name : 'Apricots' }, { name : 'Oranges' }];

let result = fruits.deleteWith((val) => val.name === 'Apricots');
// Returns [{ name : 'Apricots' }]
// fruits [{ name : 'Apples' }, { name : 'Oranges' }]

let result = fruits.deleteWith((val) => val.name.startsWith('Ap'));
// Returns [{ name : 'Apples' }, { name : 'Apricots' }]
// fruits [{ name : 'Oranges' }]

 <Array>.first() → any

Returns the first member from the array. Does not modify the original.

History:

Parameters: none

The first member's value (any).

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $pies to ['Blueberry', 'Cherry', 'Cream', 'Pecan', 'Pumpkin']>>

<<set $result to $pies.first()>>
/* Returns 'Blueberry' */
Basic usage (in JavaScript)
// Given the following:
let pies = ['Blueberry', 'Cherry', 'Cream', 'Pecan', 'Pumpkin'];

let result = 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.

History: JavaScript built-in

Parameters:

Returns:

A new Array consisting of all members flattened up to the given depth.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $npa to [['Alfa', 'Bravo'], [[['Charlie'], 'Delta'], ['Echo']], 'Foxtrot']>>

<<set $result to $npa.flat()>>
/* Returns ['Alfa', 'Bravo', [['Charlie'], 'Delta'], ['Echo'], 'Foxtrot'] */

<<set $result to $npa.flat(1)>>
/* Returns ['Alfa', 'Bravo', [['Charlie'], 'Delta'], ['Echo'], 'Foxtrot'] */

<<set $result to $npa.flat(2)>>
/* Returns ['Alfa', 'Bravo', ['Charlie'], 'Delta', 'Echo', 'Foxtrot'] */

<<set $result to $npa.flat(Infinity)>>
/* Returns ['Alfa', 'Bravo', 'Charlie', 'Delta', 'Echo', 'Foxtrot'] */
Basic usage (in JavaScript)
// Given the following:
let npa = [['Alfa', 'Bravo'], [[['Charlie'], 'Delta'], ['Echo']], 'Foxtrot'];

let result = npa.flat();
// Returns ['Alfa', 'Bravo', [['Charlie'], 'Delta'], ['Echo'], 'Foxtrot']

let result = npa.flat(1);
// Returns ['Alfa', 'Bravo', [['Charlie'], 'Delta'], ['Echo'], 'Foxtrot']

let result = npa.flat(2);
// Returns ['Alfa', 'Bravo', ['Charlie'], 'Delta', 'Echo', 'Foxtrot']

let result = npa.flat(Infinity);
// 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 1. Does not modify the original.

Note: Identical to calling <Array>.map(…).flat().

History: JavaScript built-in

Parameters:

Returns:

A new Array consisting of all members flattened up to the given depth.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $npa to ['Alfa', 'Bravo Charlie', 'Delta Echo Foxtrot']>>

<<set $result to $npa.flatMap((val) => val.split(' '))>>
/* Returns ['Alfa', 'Bravo', 'Charlie', 'Delta', 'Echo', 'Foxtrot'] */
Basic usage (in JavaScript)
// Given the following:
let npa = ['Alfa', 'Bravo Charlie', 'Delta Echo Foxtrot'];

let result = npa.flatMap((val) => val.split(' '));
// Returns ['Alfa', 'Bravo', 'Charlie', 'Delta', 'Echo', 'Foxtrot']

 <Array>.includes(needle [, position]) → boolean

Returns whether the given member was found within the array, starting the search at position.

History: JavaScript built-in

Parameters:

Returns:

A boolean denoting whether the given member was found within the array.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $pies to ['Blueberry', 'Cherry', 'Cream', 'Pecan', 'Pumpkin']>>

<<set $result to $pies.includes('Cherry')>>
/* Returns true */

<<set $result to $pies.includes('Pecan', 3)>>
/* Returns true */
Basic usage (in JavaScript)
// Given the following:
let pies = ['Blueberry', 'Cherry', 'Cream', 'Pecan', 'Pumpkin'];

let result = pies.includes('Cherry');
// Returns true

let result = pies.includes('Pecan', 3);
// Returns true

 <Array>.includesAll(needles…) → boolean

Returns whether all of the given members were found within the array.

History:

Parameters:

Returns:

A boolean denoting whether all of the given members were found within the array.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $pies to ['Blueberry', 'Cherry', 'Cream', 'Pecan', 'Pumpkin']>>

<<set $result to $pies.includesAll('Cherry', 'Raspberry')>>
/* Returns false */

<<set $result to $pies.includesAll('Blueberry', 'Cream')>>
/* Returns true */
Basic usage (in JavaScript)
// Given the following:
let pies = ['Blueberry', 'Cherry', 'Cream', 'Pecan', 'Pumpkin'];

let result = pies.includesAll('Cherry', 'Raspberry');
// Returns false

let result = pies.includesAll('Blueberry', 'Cream');
// Returns true

 <Array>.includesAny(needles…) → boolean

Returns whether any of the given members were found within the array.

History:

Parameters:

Returns:

A boolean denoting whether any of the given members were found within the array.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $pies to ['Blueberry', 'Cherry', 'Cream', 'Pecan', 'Pumpkin']>>

<<set $result to $pies.includesAny('Cherry', 'Coconut')>>
/* Returns true */

<<set $result to $pies.includesAny('Coconut')>>
/* Returns false */
Basic usage (in JavaScript)
// Given the following:
let pies = ['Blueberry', 'Cherry', 'Cream', 'Pecan', 'Pumpkin'];

let result = pies.includesAny('Cherry', 'Coconut');
// Returns true

let result = pies.includesAny('Coconut');
// Returns false

 <Array>.last() → any

Returns the last member from the array. Does not modify the original.

History:

Parameters: none

Returns:

The last member's value (any).

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $pies to ['Blueberry', 'Cherry', 'Cream', 'Pecan', 'Pumpkin']>>

<<set $result to $pies.last()>>
/* Returns 'Pumpkin' */
Basic usage (in JavaScript)
// Given the following:
let pies = ['Blueberry', 'Cherry', 'Cream', 'Pecan', 'Pumpkin'];

let result = $pies.last();
// Returns 'Pumpkin'

 <Array>.pluck() → any

Removes and returns a random member from the base array.

History:

Parameters: none

Returns:

The removed member's value (any).

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $pies to ['Blueberry', 'Cherry', 'Cream', 'Pecan', 'Pumpkin']>>

<<set $result to $pies.pluck()>>
/* Removes and returns a random pie from the array */
Basic usage (in JavaScript)
// Given the following:
let pies = ['Blueberry', 'Cherry', 'Cream', 'Pecan', 'Pumpkin'];

// Removes and returns a random pie from the array
let result = $pies.pluck();

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

History:

Parameters:

Returns:

A new Array containing the randomly removed members.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $pies to ['Blueberry', 'Cherry', 'Cream', 'Pecan', 'Pumpkin']

/* Removes three random pies from the array and returns them as a new array */
<<set $result to $pies.pluckMany(3)>>
Basic usage (in JavaScript)
// Given the following:
let pies = ['Blueberry', 'Cherry', 'Cream', 'Pecan', 'Pumpkin'];

// Removes three random pies from the array and returns them as a new array
let result = pies.pluckMany(3);

 <Array>.pop() → any

Removes and returns the last member from the array, or undefined if the array is empty.

History: JavaScript built-in

Parameters: none

Returns:

The last member's value (any).

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $fruits to ['Apples', 'Oranges', 'Pears']>>

<<set $result to $fruits.pop()>>
/* Returns 'Pears' */
/* $fruits ['Apples', 'Oranges'] */
Basic usage (in JavaScript)
// Given the following:
let fruits = ['Apples', 'Oranges', 'Pears'];

let result = fruits.pop();
// Returns 'Pears'
// fruits ['Apples', 'Oranges']

 <Array>.push(members…) → integer number

Appends one or more members to the end of the base array and returns its new length.

History: JavaScript built-in

Parameters:

Returns:

An integer number whose value is the new length of the array.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $fruits to ['Apples', 'Oranges']>>

<<set $result to $fruits.push('Apples')>>
/* Returns 3 */
/* $fruits ['Apples', 'Oranges', 'Apples'] */

<<set $result to $fruits.push('Plums', 'Plums')>>
/* Returns 4 */
/* $fruits ['Apples', 'Oranges', 'Plums', 'Plums'] */
Basic usage (in JavaScript)
// Given the following:
let fruits = ['Apples', 'Oranges'];

let result = fruits.push('Apples');
// Returns 3
// fruits ['Apples', 'Oranges', 'Apples']

let result = fruits.push('Plums', 'Plums');
// Returns 4
// fruits ['Apples', 'Oranges', 'Plums', 'Plums']

 <Array>.pushUnique(members…) → integer number

Appends one or more unique members to the end of the base array and returns its new length.

History:

Parameters:

Returns:

An integer number whose value is the new length of the array.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $fruits to ['Apples', 'Oranges']>>

<<set $result to $fruits.pushUnique('Apples')>>
/* Returns 2 */
/* $fruits ['Apples', 'Oranges'] */

<<set $result to $fruits.pushUnique('Plums', 'Plums')>>
/* Returns 3 */
/* $fruits ['Apples', 'Oranges', 'Plums'] */
Basic usage (in JavaScript)
// Given the following:
let fruits = ['Apples', 'Oranges'];

let result = fruits.pushUnique('Apples');
// Returns 2
// fruits ['Apples', 'Oranges']

let result = 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.

History:

Parameters: none

Returns:

The selected member's value (any).

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $pies to ['Blueberry', 'Cherry', 'Cream', 'Pecan', 'Pumpkin']>>

/* Returns a random pie from the array */
<<set $result to $pies.random()>>
Basic usage (in JavaScript)
// Given the following:
let pies = ['Blueberry', 'Cherry', 'Cream', 'Pecan', 'Pumpkin'];

// Returns a random pie from the array
let result = pies.random();

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

History:

Parameters:

Returns:

A new Array containing the randomly selected members.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $pies to ['Blueberry', 'Cherry', 'Cream', 'Pecan', 'Pumpkin']>>

/* Returns a new array containing three unique random pies from the array */
<<set $result to $pies.randomMany(3)>>
Basic usage (in JavaScript)
// Given the following:
let pies = ['Blueberry', 'Cherry', 'Cream', 'Pecan', 'Pumpkin'];

// Returns a new array containing three unique random pies from the array
let result = pies.randomMany(3);

 <Array>.shift() → any

Removes and returns the first member from the array, or undefined if the array is empty.

History: JavaScript built-in

Parameters: none

Returns:

The first member's value (any) or undefined, if the array is empty.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $fruits to ['Apples', 'Oranges', 'Pears']>>

<<set $result to $fruits.shift()>>
/* Returns 'Apples' */
/* $fruits ['Oranges', 'Pears'] */
Basic usage (in JavaScript)
// Given the following:
let fruits = ['Apples', 'Oranges', 'Pears'];

let result = fruits.shift();
// Returns 'Apples'
// fruits ['Oranges', 'Pears']

 <Array>.shuffle() → Array<any>

Randomly shuffles the array.

History:

Parameters: none

Returns:

The original Array randomly shuffled.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $pies to ['Blueberry', 'Cherry', 'Cream', 'Pecan', 'Pumpkin']>>

/* Randomizes the order of the array */
<<run $pies.shuffle()>>
Basic usage (in JavaScript)
// Given the following:
let pies = ['Blueberry', 'Cherry', 'Cream', 'Pecan', 'Pumpkin'];

// Randomizes the order of the array
pies.shuffle();

 <Array>.toShuffled() → Array<any>

Returns a new copy of the base array created by shuffling the array. Does not modify the original.

History:

Parameters: none

Returns:

A new Array consisting of the original array randomly shuffled.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $pies to ['Blueberry', 'Cherry', 'Cream', 'Pecan', 'Pumpkin']>>

/* Randomizes the order of the array without modifying the original */
<<set $result to $pies.toShuffled()>>
Basic usage (in JavaScript)
// Given the following:
let pies = ['Blueberry', 'Cherry', 'Cream', 'Pecan', 'Pumpkin'];

// Randomizes the order of the array without modifying the original
let result = pies.toShuffled();

 <Array>.toUnique() → Array<any>

Returns a new copy of the base array created by removing all duplicate members. Does not modify the original.

History:

Parameters: none

Returns:

A new Array consisting of the original array with all duplicates removed.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $fruits to ['Apples', 'Oranges', 'Plums', 'Plums', 'Apples']>>

<<set $result to $fruits.toUnique()>>
/* Returns ['Apples', 'Oranges', 'Plums'] */
Basic usage (in JavaScript)
// Given the following:
let fruits = ['Apples', 'Oranges', 'Plums', 'Plums', 'Apples'];

let result = fruits.toUnique();
// Returns ['Apples', 'Oranges', 'Plums']

 <Array>.unshift(members…) → integer number

Prepends one or more members to the beginning of the base array and returns its new length.

History: JavaScript built-in

Parameters:

Returns:

An integer number whose value is the new length of the array.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $fruits to ['Oranges', 'Plums']>>

<<set $result to $fruits.unshift('Oranges')>>
/* Returns 3 */
/* $fruits ['Oranges', 'Oranges', 'Plums'] */

<<set $result to $fruits.unshift('Apples', 'Apples')>>
/* Returns 4 */
/* $fruits ['Apples', 'Apples', 'Oranges', 'Plums'] */
Basic usage (in JavaScript)
// Given the following:
let fruits = ['Oranges', 'Plums'];

let result = fruits.unshift('Oranges');
// Returns 3
// fruits ['Oranges', 'Oranges', 'Plums']

let result = fruits.unshift('Apples', 'Apples');
// Returns 4
// fruits ['Apples', 'Apples', 'Oranges', 'Plums']

 <Array>.unshiftUnique(members…) → integer number

Prepends one or more unique members to the beginning of the base array and returns its new length.

History:

Parameters:

Returns:

An integer number whose value is the new length of the array.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $fruits to ['Oranges', 'Plums']>>

<<set $result to $fruits.unshiftUnique('Oranges')>>
/* Returns 2 */
/* $fruits ['Oranges', 'Plums'] */

<<set $result to $fruits.unshiftUnique('Apples', 'Apples')>>
/* Returns 3 */
/* $fruits ['Apples', 'Oranges', 'Plums'] */
Basic usage (in JavaScript)
// Given the following:
let fruits = ['Oranges', 'Plums'];

let result = fruits.unshiftUnique('Oranges');
// Returns 2
// fruits ['Oranges', 'Plums']

let result = 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.

History:

 jQuery Methods

 <jQuery>.ariaClick([options ,] handler) → jQuery

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 jQuery instance for chaining.

History:

Parameters:

Options object:

An options object should have some of the following properties:

Returns:

The current jQuery instance.

Examples:

Basic usage (in macros)

Note: The macro examples would be exactly the same as the JavaScript examples, just wrapped in a <<script>> macro.

Basic usage (in JavaScript)
// Given an existing element: <a id="so-clicky">Click me</a>
$('#so-clicky').ariaClick((event) => {
	/* do stuff */
});

// Creates a basic link and appends it to the `output` element
$('<a>Click me</a>')
	.ariaClick((event) => {
		/* do stuff */
	})
	.appendTo(output);

// Creates a basic button and appends it to the `output` element
$('<button>Click me</button>')
	.ariaClick((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.'
	}, (event) => {
		/* do stuff */
	})
	.appendTo(output);

 <jQuery>.ariaDisabled(state) → jQuery

Changes the disabled state of the target WAI-ARIA-compatible clickable element(s). Returns a reference to the current jQuery instance for chaining.

Note: This method is meant to work with clickables created via <jQuery>.ariaClick() and may not work with clickables from other sources. SugarCube uses <jQuery>.ariaClick() internally to handle all of its various link markup and macros.

History:

Parameters:

Returns:

The current jQuery instance.

Examples:

Basic usage (in macros)
/* Given an existing WAI-ARIA-compatible clickable element with the ID "so-clicky" */

/* Disables the target element */
<<run $('#so-clicky').ariaDisabled(true)>>

/* Enables the target element */
<<run $('#so-clicky').ariaDisabled(false)>>
Basic usage (in JavaScript)
/* Given an existing WAI-ARIA-compatible clickable element with the ID "so-clicky" */

// Disables the target element
$('#so-clicky').ariaDisabled(true);

// Enables the target element
$('#so-clicky').ariaDisabled(false);

 <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 <jQuery>.ariaClick() internally to handle all of its various link markup and macros.

History:

Parameters: none

Returns:

A boolean denoting whether any of the elements are disabled.

Examples:

Basic usage (in macros)
/* Given an existing WAI-ARIA-compatible clickable element with the ID "so-clicky" */

<<set $result to $('#so-clicky').ariaIsDisabled()>>
/* Returns true, if "#so-clicky" is disabled */

<<set $result to $('#so-clicky').ariaIsDisabled()>>
/* Returns false, if "#so-clicky" is enabled */
Basic usage (in JavaScript)
/* Given an existing WAI-ARIA-compatible clickable element with the ID "so-clicky" */

let result = $('#so-clicky').ariaIsDisabled();
// Returns true, if "#so-clicky" is disabled

let result = $('#so-clicky').ariaIsDisabled();
// Returns false, if "#so-clicky" is enabled

 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.

History:

Parameters:

Returns: none

Examples:

Basic usage (in macros)
/* Invokes the <<somemacro>> macro, discarding any output */
<<run $.wiki('<<somemacro>>')>>
Basic usage (in JavaScript)
// Invokes the <<somemacro>> macro, discarding any output
$.wiki('<<somemacro>>');

 jQuery.wikiPassage(passageName)

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.

History:

Parameters:

Returns: none

Examples:

Basic usage (in macros)
/* Renders the passage, discarding any output */
<<run $.wikiPassage('Fight Init')>>
Basic usage (in JavaScript)
// Renders the passage, discarding any output
$.wikiPassage('Fight Init');

 <jQuery>.wiki(sources…) → jQuery

Wikifies the given content source(s) and appends the result to the target element(s). Returns a reference to the current jQuery instance for chaining.

History:

Parameters:

Returns:

The current jQuery instance.

Examples:

Basic usage (in macros)
/* Given an element: <div id="the-box"></div> */

/* Appends "Who <em>are</em> you?" to the target element */
<<run $('#the-box').wiki('Who //are// you?')>>
Basic usage (in JavaScript)
/* Given an element: <div id="the-box"></div> */

// Appends "Who <em>are</em> you?" to the target element
$('#the-box').wiki('Who //are// you?');

 <jQuery>.wikiPassage(passageName) → jQuery

Wikifies the passage by the given name and appends the result to the target element(s). Returns a reference to the current jQuery instance for chaining.

History:

Parameters:

Returns:

The current jQuery instance.

Examples:

Basic usage (in macros)
/* Given an element: <div id="notebook"></div> */

/* Appends the rendered passage to the target element */
<<run $('#notebook').wikiPassage('Notes')>>
Basic usage (in JavaScript)
/* Given an element: <div id="notebook"></div> */

// Appends the rendered passage to the target element
$('#notebook').wikiPassage('Notes');

 JSON Methods

 JSON.reviveWrapper(code [, data]) → Array

Deprecated: This static method has been deprecated and should no longer be used. See the Serial.createReviver() static method.

History:

 Math Methods

 Math.clamp(num , min , max) → number

Returns the given number clamped to the specified bounds. Does not modify the original.

History:

Parameters:

Returns:

A new number.

Examples:

Basic usage (in macros)
/* Returns a copy of the original clamped to the bounds 0–200 */
<<set $result to Math.clamp($stat, 0, 200)>>

/* Returns a copy of the original clamped to the bounds 1–6.6 */
<<set $result to Math.clamp($stat, 1, 6.6)>>
Basic usage (in JavaScript)
// Returns a copy of the original clamped to the bounds 0–200
let result = Math.clamp(stat, 0, 200);

// Returns a copy of the original clamped to the bounds 1–6.6
let result = Math.clamp(stat, 1, 6.6);

 Math.trunc(num) → integer number

Returns the whole (integer) part of the given number by removing its fractional part, if any. Does not modify the original.

History: JavaScript built-in

Parameters:

Returns:

A new integer number.

Examples:

Basic usage (in macros)
<<set $result to Math.trunc(12.7)>>
/* Returns 12 */

<<set $result to Math.trunc(-12.7)>>
/* Returns -12 */
Basic usage (in JavaScript)
let result = Math.trunc(12.7);
// Returns 12

let result = Math.trunc(-12.7);
// Returns -12

 Number Methods

 <Number>.clamp(min , max) → number

Deprecated: This static method has been deprecated and should no longer be used. See the Math.clamp() static method.

History:

 RegExp Methods

 RegExp.escape(text) → string

Returns the given string with all regular expression metacharacters escaped. Does not modify the original.

History: JavaScript built-in

Parameters:

Returns:

A new string that can be safely used as a literal pattern.

Examples:

Basic usage (in macros)
<<set $result to RegExp.escape('That will be $15, cash only.')>>
/* Returns '\x54hat\x20will\x20be\x20\$15\x2c\x20cash\x20only\.' */
Basic usage (in JavaScript)
let result = RegExp.escape('That will be $15, cash only.');
// Returns '\x54hat\x20will\x20be\x20\$15\x2c\x20cash\x20only\.'

 Serial Methods

 Serial.createReviver(code [, data]) → Array

Returns 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 .toJSON() method, so that the instance may be properly revived upon deserialization.

See: The Non-generic object types (classes) guide for more detailed information.

History:

Parameters:

Returns:

A new string containing the serialized code.

Examples:

Basic usage (in macros)

Note: The macro examples would be exactly the same as the JavaScript examples, just wrapped in a <<script>> macro.

Basic usage (in JavaScript)
Serial.createReviver(/* JavaScript code string */);            // without data chunk
Serial.createReviver(/* JavaScript code string */, myOwnData); // with data chunk

// 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.
const ownData = {};
Object.keys(this).forEach((pn) => ownData[pn] = clone(this[pn]));
return Serial.createReviver('new Character($ReviveData$)', ownData);

 String Methods

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 number

Returns the number of times that the given substring was found within the string, starting the search at position.

See: String methods note.

History:

Parameters:

Returns:

An integer number denoting the number of times that the given substring was found within the string.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $text to 'How now, brown cow.'>>

<<set $result to $text.count('ow')>>
/* Returns 4 */

<<set $result to $text.count('ow', 8)>>
/* Returns 2 */
Basic usage (in JavaScript)
// Given the following:
let text = 'How now, brown cow.';

let result = text.count('ow');
// Returns 4

let result = 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.

History:

Parameters: none

Returns:

A new string containing the first Unicode code point.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $text to 'abc'>>

<<set $result to $text.first()>>
/* Returns 'a' */

/* Given the following: */
<<set $text to '🙈🙉🙊'>>

<<set $result to $text.first()>>
/* Returns '🙈' */
Basic usage (in JavaScript)
// Given the following:
let text = 'abc';

let result = text.first();
// Returns 'a'

// Given the following:
let text = '🙈🙉🙊';

let result = 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.

History:

Parameters:

Format items:

A format item has the syntax {index[,alignment]}, square-brackets denoting optional elements.

Returns:

A new string based on the format and arguments.

Examples:

Basic usage (in macros)

Using a list of arguments.

<<set $result to String.format('{0}, {1}!', 'Hello', 'World')>>
/* Returns 'Hello, World!' */

Using an array argument.

<<set $result to String.format('{0}, {1}!', ['Hello', 'World'])>>
/* Returns 'Hello, World!' */

Using alignments.

<<set $result to String.format('{0,6}', 'foo')>>
/* Returns '   foo' */

<<set $result to String.format('{0,-6}', 'foo')>>
/* Returns 'foo   ' */
Basic usage (in JavaScript)

Using a list of arguments.

let result = String.format('{0}, {1}!', 'Hello', 'World');
// Returns 'Hello, World!'

Using an array argument.

let result = String.format('{0}, {1}!', ['Hello', 'World']);
// Returns 'Hello, World!'

Using alignments.

let result = String.format('{0,6}', 'foo');
// Returns '   foo'

let result = 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.

See: String methods note.

History: JavaScript built-in

Parameters:

Returns:

A boolean denoting whether the given substring was found within the string.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $text to 'How now, brown cow.'>>

<<set $result to $text.includes('row')>>
/* Returns true */

<<set $result to $text.includes('row', 14)>>
/* Returns false */

<<set $result to $text.includes('cow', 14)>>
/* Returns true */

<<set $result to $text.includes('pow')>>
/* Returns false */
Basic usage (in JavaScript)
// Given the following:
let text = 'How now, brown cow.';

let result = text.includes('row');
// Returns true

let result = text.includes('row', 14);
// Returns false

let result = text.includes('cow', 14);
// Returns true

let result = 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.

History:

Parameters: none

Returns:

A new string containing the last Unicode code point.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $text to 'abc'>>

<<set $result to $text.last()>>
/* Returns 'c' */

/* Given the following: */
<<set $text to '🙈🙉🙊'>>

<<set $result to $text.last()>>
/* Returns '🙊' */
Basic usage (in JavaScript)
// Given the following:
let text = 'abc';

let result = text.last();
// Returns 'c'

// Given the following:
let text = '🙈🙉🙊';

let result = 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.

History:

Parameters: none

Returns:

A new string with its first Unicode code point uppercased according to locale-specific rules.

Examples:

Basic usage (in macros)

Using the Turkish (Türkçe) locale.

/* Given the following: */
<<set $text to 'ışık'>>

<<set $result to $text.toLocaleUpperFirst()>>
/* Returns 'Işık' */

/* Given the following: */
<<set $text to 'iki'>>

<<set $result to $text.toLocaleUpperFirst()>>
/* Returns 'İki' */
Basic usage (in JavaScript)

Using the Turkish (Türkçe) locale.

// Given the following:
let text = 'ışık';

let result = text.toLocaleUpperFirst();
// Returns 'Işık'

// Given the following:
let text = 'iki';

let result = 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.

History:

Parameters: none

Returns:

A new string with its first Unicode code point uppercased.

Examples:

Basic usage (in macros)
/* Given the following: */
<<set $text to 'hello.'>>

<<set $result to $text.toUpperFirst()>>
/* Returns 'Hello.'*/

/* Given the following: */
<<set $text to 'χαίρετε.'>>

<<set $result to $text.toUpperFirst()>>
/* Returns 'Χαίρετε.'*/
Basic usage (in JavaScript)
// Given the following:
let text = 'hello.';

let result = text.toUpperFirst();
// Returns 'Hello.'

// Given the following:
let text = 'χαίρετε.';

let result = text.toUpperFirst();
// Returns 'Χαίρετε.'

 Special Names

Passage, tag, and variable names that have special meaning to SugarCube.

 Warning

  1. All special names listed herein are case sensitive, so their spelling and capitalization must be exactly as shown.
  2. Never combine special or code passages with code tags. By doing so, you will probably break things in subtle and hard to detect ways.

 Code Passages

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., StoryCaption—or execute code at specific times—e.g., PassageReady—or both—e.g., 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.

History:

 PassageFooter

Appended to each rendered passage.

Roughly equivalent to the :passagerender event.

History:

 PassageHeader

Prepended to each rendered passage.

Roughly equivalent to the :passagestart event.

History:

 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.

History:

 StoryAuthor

Used to populate the authorial byline area in the UI bar (element ID: story-author).

History:

 StoryBanner

Used to populate the story's banner area in the UI bar (element ID: story-banner).

History:

 StoryCaption

Used to populate the story's caption area in the UI bar (element ID: story-caption). May also be, and often is, used to add additional story UI elements and content to the UI bar.

History:

 StoryDisplayTitle

Sets the story's display title in the browser's titlebar and the UI bar (element ID: story-title). If omitted, the story title will be used instead.

History:

 StoryInit

Used for pre-story-start initialization tasks, like variable initialization (happens at the beginning of story initialization). Generates no output.

History:

 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 <div id="story" role="main"> element and must itself contain, at least, an element with the ID passages that will be the main passage display area. For example:

<div id="story" role="main">
	<!-- StoryInterface elements added here -->
</div>

Additional elements, aside from the #passages element, may include either the data-init-passage or data-passage 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 data-init-passage attribute causes the element to be updated once at initialization, while the data-passage attribute causes the element to be updated upon each passage navigation.

Warning: Elements that include either a data-init-passage or data-passage 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.

History:

Examples:

Minimal working example
<div id="passages"></div>

Combined with the built-in wrapper:

<div id="story" role="main">
	<div id="passages"></div>
</div>
With data-init-passage and data-passage content attributes
<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 (<a>). 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.

History:

Examples:

[[Inventory]]

<<if not $inventory.isEmpty()>>
	[[Inventory]]
<</if>>

<<link "Schedule">> … <</link>>

<<if $scheduleEnabled>>
	<<link "Schedule">> … <</link>>
<</if>>

<a data-passage="…">Equipment<a>

<<if $equipped.length > 0>>
	<a data-passage="…">Equipment<a>
<</if>>

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

History:

 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.

History:

 StoryShare

Deprecated: This special passage has been deprecated and should no longer be used.

History:

 Special Passages

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.

History:

 Code Tags

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.

History:

 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.

History:

 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.

History:

 Twine.audio

Registers the passage as an audio passage. See Guide: Media Passages for more information.

History:

 Twine.image

Registers the passage as an image passage. See Guide: Media Passages for more information.

History:

 Twine.video

Registers the passage as a video passage. See Guide: Media Passages for more information.

History:

 Twine.vtt

Registers the passage as a VTT passage. See Guide: Media Passages for more information.

History:

 widget

Registers the passage as <<widget>> macro definitions, which are loaded during startup.

History:

 Special Tags

 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 script or stylesheet tagged passages, for Twine 1/Twee.

History:

 bookmark

Deprecated: This special tag has been deprecated and should no longer be used.

History:

 Special Variables

 $

Alias for jQuery, by default.

Note: This should not be confused with story variables, which start with a $—e.g., $foo.

History:

 _args

Widget arguments array (only inside widgets). See <<widget>> for more information.

History:

 _contents

Widget contents string (only inside block widgets). See <<widget>> for more information.

History:

 Config

Configuration API. See Config API for more information.

History:

 Dialog

Dialog API. See Dialog API for more information.

History:

 Engine

Engine API. See Engine API for more information.

History:

 Fullscreen

Fullscreen API. See Fullscreen API for more information.

History:

 jQuery

jQuery library function.

History:

 l10nStrings

Strings localization object. See Localization for more information.

History:

 LoadScreen

LoadScreen API. See LoadScreen API for more information.

History:

 Macro

Macro API. See Macro API for more information.

History:

 Passage

Passage API. See Passage API for more information.

History:

 Save

Save API. See Save API for more information.

History:

 Setting

Setting API. See Setting API for more information.

History:

 settings

Player settings object, set up by the author/developer. See Setting API for more information.

History:

 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.

History:

 SimpleAudio

SimpleAudio API. See SimpleAudio API for more information.

History:

 State

State API. See State API for more information.

History:

 Story

Story API. See Story API for more information.

History:

 Template

Template API. See Template API for more information.

History:

 UI

UI API. See UI API for more information.

History:

 UIBar

UIBar API. See UIBar API for more information.

History:

 $args

Deprecated: The $args special variable has been deprecated and should no longer be used. See the _args special variable for its replacement.

History:

 postdisplay

Deprecated: postdisplay tasks have been deprecated and should no longer be used. See the :passagedisplay event for its replacement.

History:

 postrender

Deprecated: postrender tasks have been deprecated and should no longer be used. See the :passagerender event for its replacement.

History:

 predisplay

Deprecated: predisplay tasks have been deprecated and should no longer be used. See the :passagestart event for its replacement.

History:

 prehistory

Deprecated: prehistory tasks have been deprecated and should no longer be used. See the :passageinit event for its replacement.

History:

 prerender

Deprecated: prerender tasks have been deprecated and should no longer be used. See the :passagestart event for its replacement.

History:

 CSS

 段落转换规则

段落名称和标签会自动转换为短横线小写格式的 ID 和类名。转换过程包含以下步骤：移除所有非字母数字、下划线、连字符、长破折号或空格的字符，将剩余非字母数字字符替换为连字符（每组替换为一个），最后将结果转为全小写。

段落名称

段落名称前会添加 passage- 前缀，根据使用场景不同转换为 ID 或类名：

例如，段落名称为 Gone fishin' 时：

段落标签

段落显示时，其标签会：

  1. 添加至活动段落的容器元素、<html> 和 <body> 的 data-tags 属性（空格分隔列表）
  2. 添加至活动段落容器和 <body> 的类名（以下特殊标签除外）：
    Twine 2: debug, nobr, passage, widget 及以 twine. 开头的标签
    Twine 1/Twee: debug, nobr, passage, script, stylesheet, widget 及以 twine. 开头的标签

例如，标签 Sector_42 将转换为：

 常用选择器示例

选择器 描述
html

文档根元素，默认字体设置在此定义

活动段落的标签会添加到其 data-tags 属性（详见段落转换规则）
body

页面主体，默认前景色和背景色设置在此

活动段落的标签会添加到其 data-tags 属性和类名（详见段落转换规则）
#story 故事主容器元素
#passages 段落容器元素，所有段落元素都包含在此
.passage

段落元素。通常每回合只有一个，但在导航时可能短暂存在两个（进入/离开段落）

活动段落名称会作为其 ID（详见段落转换规则）

活动段落的标签会添加到其 data-tags 属性和类名（详见段落转换规则）
.passage a 段落内所有链接元素
.passage a:hover 段落内鼠标悬停的链接
.passage a:active 段落内被点击的链接
.passage .link-broken 指向不存在的段落的链接
.passage .link-disabled 被禁用的链接（如已选择的 <<choice>> 宏链接）
.passage .link-external 外部链接（指向其他网站的链接）
.passage .link-internal 内部链接（指向段落或宏的链接）
.passage .link-visited1 已访问过的内部链接（玩家历史中存在的段落）
.passage .link-internal:not(.link-visited)1 未访问过的内部链接（玩家从未到达的段落）
  1. .link-visited 类默认未启用，详见 Config API 的 Config.addVisitedLinkClass 属性

 注意事项

多样式表问题 (仅限 Twine 1/Twee)

在 Twine 1/Twee 中强烈建议只使用一个 stylesheet 标签的段落。由于 CSS 按加载顺序层叠，Twine 1/Twee 无法控制多个样式表的加载顺序，容易导致样式错乱。

标签样式表兼容性

SugarCube 不支持 Twine 1.4+ 原生的标签样式表功能。替代方案是使用属性选择器或类选择器：

例如，为带有 forest 标签的段落定义样式：

/* 在 <html> 使用属性选择器 */
html[data-tags~="forest"] { background-image: url(forest-bg.jpg); }

/* 在 <body> 使用属性选择器 */
body[data-tags~="forest"] .passage { color: darkgreen; }

/* 使用类选择器 */
body.forest a:hover { color: lime; }

 内置样式表

以下是 SugarCube 内置样式表（按加载顺序排列，5-13 最常用），链接指向最新版本: 源代码仓库.

  1. normalize.css - 标准化浏览器默认样式
  2. init-screen.css - 初始化加载界面
  3. font-icons.css - 图标字体
  4. font-emoji.css - Emoji 字体支持
  5. core.css - 核心基础样式
  6. core-display.css - 显示相关样式
  7. core-passage.css - 段落容器样式
  8. core-macro.css - 段落容器样式
  9. ui-dialog.css - 对话框基础样式
  10. ui-dialog-saves.css - 存档对话框样式
  11. ui-dialog-settings.css - 设置对话框样式
  12. ui-dialog-legacy.css - 旧版对话框兼容样式
  13. ui-bar.css - 界面工具栏样式
  14. ui-debug-bar.css - 调试工具栏样式（≥v2.23.0）
  15. ui-debug-views.css - 调试视图样式（≤v2.22.0）

 HTML

The hierarchy of the document body, including associated HTML IDs and class names is as follows.

Notes:

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

Story data chunks:

Periods of ellipsis (…) signify data that is generated at compile time.

Twine 2 style data chunk
<tw-storydata name="…" startnode="…" creator="…" creator-version="…"
	ifid="…" zoom="…" format="…" format-version="…" options="…" hidden>
	<!-- Passage data nodes… -->
</tw-storydata>
Twine 1 style data chunk
<div id="store-area" data-size="…" hidden>
	<!-- Passage data nodes… -->
</div>

 事件系统

事件(Events)是用于通知代码某些行为发生的消息机制（例如：触发、广播），涵盖从玩家交互到自动化流程的各种场景。每个事件对象都包含特定属性，可用于获取事件相关的附加信息。

本章节列出了 SugarCube 在故事运行过程中触发的各类专属事件。

参考阅读： 关于标准浏览器/DOM事件，请查阅 MDN 的事件参考手册。

 对话框事件

对话框事件允许在对话框打开和关闭的特定时刻执行 JavaScript 代码。

参见： Dialog API。

 :dialogclosed 事件

全局事件，在调用 Dialog.close() 方法时，作为关闭对话框的最后一步触发。

警告： 当使用 :dialogclosed 事件时，你无法从已关闭的对话框中获取数据（例如标题或类名），因为事件触发时对话框已经关闭并重置。如需获取此类信息，请改用 :dialogclosing 事件。

版本历史：

事件对象属性：无

注意： 虽然没有自定义属性，但事件是从对话框的 body 元素触发的，因此 target 属性会指向其 body 元素 (即 #ui-dialog-body)。

使用示例：

/* 当事件触发时执行处理函数 */
$(document).on(':dialogclosed', (ev) => {
    /* JavaScript 代码 */
});

/* 仅执行一次处理函数 */
$(document).one(':dialogclosed', (ev) => {
    /* JavaScript 代码 */
});

 :dialogclosing 事件

全局事件，在调用 Dialog.close() 方法时，作为关闭对话框的第一步触发。

版本历史：

事件对象属性：无

注意： 虽然没有自定义属性，但事件是从对话框的 body 元素触发的，因此 target 属性会指向其 body 元素 (即 #ui-dialog-body)。

使用示例：

/* 当对话框开始关闭时执行处理函数（持续监听） */
$(document).on(':dialogclosing', (ev) => {
    /* JavaScript 代码 */
});

/* 当对话框开始关闭时执行处理函数（仅执行一次） */
$(document).one(':dialogclosing', (ev) => {
    /* JavaScript 代码 */
});

 :dialogopened 事件

全局事件，在调用 Dialog.open() 方法时，作为打开对话框的最后一步触发。

版本历史：

事件对象属性：无

注意： 虽然没有自定义属性，但事件是从对话框的 body 元素触发的，因此 target 属性会指向其 body 元素 (即 #ui-dialog-body)。

使用示例：

/* 当事件触发时执行处理函数 */
$(document).on(':dialogopened', (ev) => {
    /* JavaScript 代码 */
});

/* 仅执行一次处理函数 */
$(document).one(':dialogopened', (ev) => {
    /* JavaScript 代码 */
});

 :dialogopening 事件

全局事件，在调用 Dialog.open() 方法时，作为打开对话框的第一步触发。

版本历史：

事件对象属性：无

注意： 虽然没有自定义属性，但事件是从对话框的 body 元素触发的，因此 target 属性会指向其 body 元素 (即 #ui-dialog-body)。

使用示例：

/* 当事件触发时执行处理函数 */
$(document).on(':dialogopening', (ev) => {
	/* JavaScript 代码 */
});

/* 仅执行一次处理函数 */
$(document).one(':dialogopening', (ev) => {
	/* JavaScript 代码 */
});

 导航事件

导航事件允许在段落跳转的不同阶段执行 JavaScript 代码。

完整处理顺序如下（包含 :uiupdate 事件和各类特殊段落）：

  1. 段落初始化
    发生在状态历史修改之前。

  2. 段落启动
    发生在新段落渲染之前。

  3. 段落渲染
    发生在新段落渲染完成后。

  4. 段落显示
    发生在新段落内容输出到页面后。

  5. 界面更新
    发生在导航结束前。

  6. 段落结束
    发生在导航流程完全结束时。

 :passageinit 事件

在状态记录修改前触发。

版本历史：

事件 detail 对象属性：

:passageinit 事件包含具有以下属性的 detail 属性：

使用示例：

/* 每次事件触发时执行处理函数 */
$(document).on(':passageinit', (ev) => {
	/* 记录当前时刻的详细信息 */
	console.group('当前时刻的详细信息');
	console.log('段落名称:', ev.detail.passage.name);
	console.log('段落标签:', ev.detail.passage.tags);
	console.groupEnd();

	/* 在此执行有效操作 */
});

/* 仅执行一次处理函数 */
$(document).one(':passageinit', (ev) => {
	/* 在此执行有效操作 */
});

 :passagestart event

Triggered before the rendering of the incoming passage.

History:

Event detail object properties:

:passagestart events have a detail property whose value is an object with the following properties:

Examples:

Basic usage
/* Execute the handler function each time the event triggers. */
$(document).on(':passagestart', (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', (ev) => {
	/* Do something useful here. */
});
Modifying the content buffer
/*
	Process the given markup and append the result to the incoming
	passage's element.
*/
$(document).on(':passagestart', (ev) => {
	$(ev.detail.content).wiki("In the //beginning//.");
});

 :passagerender event

Triggered after the rendering of the incoming passage.

History:

Event detail object properties:

:passagerender events have a detail property whose value is an object with the following properties:

Examples:

Basic usage
/* Execute the handler function each time the event triggers. */
$(document).on(':passagerender', (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', (ev) => {
	/* Do something useful here. */
});
Modifying the content buffer
/*
	Process the given markup and append the result to the incoming
	passage's element.
*/
$(document).on(':passagerender', (ev) => {
	$(ev.detail.content).wiki("At the //end// of some renderings.");
});

 :passagedisplay event

Triggered after the display—i.e., output—of the incoming passage.

History:

Event detail object properties:

:passagedisplay events have a detail property whose value is an object with the following properties:

Examples:

Basic usage
/* Execute the handler function each time the event triggers. */
$(document).on(':passagedisplay', (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', (ev) => {
	/* Do something useful here. */
});
Modifying the content buffer
/*
	Process the given markup and append the result to the incoming
	passage's element.
*/
$(document).on(':passagedisplay', (ev) => {
	$(ev.detail.content).wiki("It's //showtime//!");
});

 :passageend event

Triggered at the end of passage navigation.

History:

Event detail object properties:

:passageend events have a detail property whose value is an object with the following properties:

Examples:

Basic usage
/* Execute the handler function each time the event triggers. */
$(document).on(':passageend', (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', (ev) => {
	/* Do something useful here. */
});
Modifying the content buffer
/*
	Process the given markup and append the result to the incoming
	passage's element.
*/
$(document).on(':passageend', (ev) => {
	$(ev.detail.content).wiki("So long and //thanks for all the fish//!");
});

 prehistory tasks

Deprecated: prehistory tasks have been deprecated and should no longer be used. See the :passageinit event for its replacement.

History:

 predisplay tasks

Deprecated: predisplay tasks have been deprecated and should no longer be used. See the :passagestart event for its replacement.

History:

 prerender tasks

Deprecated: prerender tasks have been deprecated and should no longer be used. See the :passagestart event for its replacement.

History:

 postrender tasks

Deprecated: postrender tasks have been deprecated and should no longer be used. See the :passagerender event for its replacement.

History:

 postdisplay tasks

Deprecated: postdisplay tasks have been deprecated and should no longer be used. See the :passagedisplay event for its replacement.

History:

 SimpleAudio Events

SimpleAudio events allow the execution of JavaScript code at specific points during audio playback.

See: To add or remove event listeners to audio tracks managed by the SimpleAudio API see:

 :faded event

Track event triggered when a fade completes normally.

History:

Event object properties: none

Examples:

/* Execute the handler function when the event triggers for one track via <AudioTrack>. */
aTrack.on(':faded', (ev) => {
	/* JavaScript code */
});

/* Execute the handler function when the event triggers for multiple tracks via <AudioRunner>. */
someTracks.on(':faded', (ev) => {
	/* JavaScript code */
});

 :fading event

Track event triggered when a fade starts.

History:

Event object properties: none

Examples:

/* Execute the handler function when the event triggers for one track via <AudioTrack>. */
aTrack.on(':fading', (ev) => {
	/* JavaScript code */
});

/* Execute the handler function when the event triggers for multiple tracks via <AudioRunner>. */
someTracks.on(':fading', (ev) => {
	/* JavaScript code */
});

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

History:

Event object properties: none

Examples:

/* Execute the handler function when the event triggers for one track via <AudioTrack>. */
aTrack.on(':stopped', (ev) => {
	/* JavaScript code */
});

/* Execute the handler function when the event triggers for multiple tracks via <AudioRunner>. */
someTracks.on(':stopped', (ev) => {
	/* JavaScript code */
});

 System Events

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.

History:

Event object properties: none

Examples:

/* Execute the handler function when the event triggers. */
$(document).one(':enginerestart', (ev) => {
	/* JavaScript code */
});

 :storyready event

Global event triggered once just before the dismissal of the loading screen at startup.

History:

Event object properties: none

Examples:

/* Execute the handler function exactly once, since it's only fired once. */
$(document).one(':storyready', (ev) => {
	/* JavaScript code */
});

 :uiupdate event

Global event triggered when the built-in user interface is being updated when UI.update() is called.

History:

Event object properties: none

Examples:

/* Execute the handler function each time the event triggers. */
$(document).on(':uiupdate', (ev) => {
	/* JavaScript code */
});

/* Execute the handler function exactly once. */
$(document).one(':uiupdate', (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 <<type>> macros within a passage have completed.

Note: Injecting additional <<type>> macro invocations after a :typingcomplete event has been fired will cause another event to eventually be generated, since you're creating a new sequence of typing.

History:

Event object properties: none

Examples:

/* Execute the handler function when the event triggers. */
$(document).on(':typingcomplete', (ev) => {
	/* JavaScript code */
});

 :typingstart event

Local event triggered on the typing wrapper when the typing of a section starts.

History:

Event object properties: none

Examples:

/* Execute the handler function when the event triggers. */
$(document).on(':typingstart', (ev) => {
	/* JavaScript code */
});

 :typingstop event

Local event triggered on the typing wrapper when the typing of a section stops.

History:

Event object properties: none

Examples:

/* Execute the handler function when the event triggers. */
$(document).on(':typingstop', (ev) => {
	/* JavaScript code */
});

 Config API

The Config object controls various aspects of SugarCube's behavior.

Note: Config object settings should be placed within your project's JavaScript section (Twine 2: the Story JavaScript; Twine 1/Twee: a script-tagged passage).

 General Settings

 Config.addVisitedLinkClass ↔ boolean (default: false)

Determines whether the link-visited class is added to internal passage links that go to previously visited passages—i.e., the passage already exists within the story history.

Note: You must provide your own styling for the link-visited class as none is provided by default.

History:

Value:

A boolean value signifying whether links to visited passages have the class added.

Examples:

Config.addVisitedLinkClass = true;

CSS styles:

You will also need to specify a .link-visited style that defines the properties visited links should have. For example:

.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 <br> elements into <p> elements.

History:

Value:

A boolean value signifying whether post-processing occurs.

Examples:

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 (-t, --test) 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.

See Also: Config.enableOptionalDebugging setting.

History:

Value:

A boolean value signifying whether SugarCube is running in test mode.

Examples:

Forcibly enabling test mode
// Forcibly enable test mode.
Config.debug = true;
Check if test mode is enabled (in JavaScript)
if (Config.debug) {
	// Do something debug related.
}
Check if test mode is enabled (in macros)
<<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)

History:

Value:

A boolean value signifying whether optional debugging errors and warnings are enabled.

Examples:

Config.enableOptionalDebugging = true;

 Config.loadDelay ↔ integer number (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.

History:

Value:

An integer number value denoting the delay (in milliseconds) before the loading screen is dismissed.

Examples:

// Delay the dismissal of the loading screen by 2000ms (2s)
Config.loadDelay = 2000;

 Audio Settings

 Config.audio.pauseOnFadeToZero ↔ boolean (default: true)

Determines whether the audio subsystem automatically pauses tracks that have been faded to 0 volume (silent).

History:

Value:

A boolean value signifying whether tracks that have faded to 0 are automatically paused.

Examples:

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.

History:

Value:

A boolean value signifying whether track metadata is preloaded.

Examples:

Config.audio.preloadMetadata = false;

 History Settings

 Config.history.controls ↔ boolean (default: true)

Determines whether the story's history controls (Backward, Jump To, & Forward buttons) are enabled within the UI bar.

History:

Value:

A boolean value signifying whether the story history controls are enabled.

Examples:

Config.history.controls = false;

 Config.history.maxStates ↔ integer number (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 1 is strongly recommended.

History:

Value:

An integer number value denoting how many moments are allowed within the history.

Examples:

// Limit the history to a single moment (recommended for games)
Config.history.maxStates = 1;

// Limit the history to 25 moments
Config.history.maxStates = 25;

 Macros Settings

 Config.macros.maxLoopIterations ↔ integer number (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.

History:

Value:

An integer number value denoting the total allowed number of conditional form loop iteration (per instance).

Examples:

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

History:

Value:

A string value denoting the keyboard key that causes <<type>> to immediately finish typing.

Examples:

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

History:

Value:

A boolean value signifying whether <<type>> types out previously visited passages.

Examples:

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

History:

 Navigation Settings

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

History:

Value:

The callback value (Function).

Callback parameters:

Examples:

Basic usage
Config.navigation.override = (destinationPassage) => {
	/* code that returns a passage name or a falsy value */
};
Based upon a story variable
Config.navigation.override = (destinationPassage) => {
	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';
	}
};

 Passages Settings

 Config.passages.displayTitles ↔ boolean (default: false)

Determines whether the current passage name is combined with the story's name within the browser tab's title bar.

History:

Value:

A boolean value signifying whether passage names are combined with the story's name within the title bar.

Examples:

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 script or stylesheet tagged passages, for Twine 1/Twee, or the Story JavaScript or Story Stylesheet sections, for Twine 2.

History:

Value:

A boolean value signifying whether rendering passages have a global no-break enabled.

Examples:

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 name, tags, and text properties. Its return value should be the post-processed text.

Note: Does not affect script or stylesheet tagged passages, for Twine 1/Twee, or the Story JavaScript or Story Stylesheet sections, for Twine 2.

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.

History:

Value:

A callback value (Function).

Callback parameters:

Examples:

// Change instances of "cat" to "dog" in passages
Config.passages.onProcess = (p) => 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 name, the very first passage that will be displayed.

History:

Value:

A string value denoting the starting passage name.

Examples:

Config.passages.start = 'That Other Starting Passage';

 Config.passages.transitionOut ↔ string | integer number (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 25ms or so should be sufficient.

History:

Value:

A string value denoting the CSS property being animated or an integer number value denoting the integer delay.

Examples:

// Remove outgoing elements when their opacity animation ends
Config.passages.transitionOut = 'opacity';

// Remove outgoing elements after 1500ms (1.5s)
Config.passages.transitionOut = 1500;

CSS styles:

At the very least you will need to specify a .passage-out style that defines the transition's end state. For example:

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

History:

 Saves Settings

 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.

History:

Value:

A callback value (Function).

Callback parameters:

Examples:

Using passages' names
Config.saves.descriptions = (saveType) => passage();
Using descriptions mapped by passages' names
let saveDescriptions = {
	'passage_name_a' : 'description text a…',
	'passage_name_b' : 'description text b…',
	'passage_name_c' : 'description text c…'
};
Config.saves.descriptions = (saveType) => saveDescriptions[passage()];
Using the saveType parameter
Config.saves.descriptions = (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 name)

Sets the ID associated with saves.

History:

Value:

A string value denoting the ID associated with saves.

Examples:

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.

History:

Value:

A callback value (Function).

Callback parameters:

Examples:

Basic usage

Allows saves on passages if it returns a truthy value.

Config.saves.isAllowed = (saveType) => {
	/* code returning a boolean value */
};

Disallow saving on passages tagged with menu.

Config.saves.isAllowed = (saveType) => !tags().includes('menu');
Using the saveType parameter

Attempt a new auto save only on passages tagged with autosave. Other save types are not limited.

Config.saves.isAllowed = (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.

Config.saves.isAllowed = (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 = (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 number (default: 0)

Sets the maximum number of available auto saves. Using a value of 0 disables auto saves.

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 1–10 is suggested.

History:

Value:

An integer number value denoting the maximum number of browser auto saves.

Examples:

Config.saves.maxAutoSaves = 3;

 Config.saves.maxSlotSaves ↔ integer number (default: 8)

Sets the maximum number of available slot saves. Using a value of 0 disables slot saves.

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 1–10 is suggested.

History:

Value:

An integer number value denoting the maximum number of browser slot saves.

Examples:

Config.saves.maxSlotSaves = 4;

 Config.saves.metadata ↔ Function (default: none)

Sets the metadata property of saves. The callback is invoked each time a save is made. It is passed the type of save being attempted. Its return value should be an Object that will serve as the metadata of saves.

See: Save.Type pseudo-enumeration for more information on save types.

History:

Value:

A callback value (Function). The callback is passed one parameter, the type of save being attempted. It should return an Object that will serve as the metadata of saves and that must be JSON-serializable.

Callback parameters:

Examples:

Basic usage
Config.saves.metadata = (saveType) => {
	const sv = State.variables;

	return {
		party : sv.party, // e.g., ['Celes', 'Locke', 'Edward']
		gold  : sv.gold   // e.g., 2345
	};
};

Config.saves.metadata = (saveType) => {
	const metadata = {
		gameVersion : 'Release 12: "Horny Toads Need Love Too" edition'
	};

	if (/* some logic */) {
		metadata.someProp = 'a value';
	}

	return metadata;
};
Using the saveType parameter
Config.saves.isAllowed = (saveType) => {
	const metadata = {
		gameVersion : 'Release 2: Electric Boogaloo',
		inBrowser   : saveType === Save.Type.Auto || saveType === Save.Type.Slot
	};

	return metadata;
};

 Config.saves.version ↔ any (default: none)

Sets the version property of saves.

Note: It is strongly recommended that you use an integer number for the version.

Note: This setting is only used to set the version 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.

History:

Value:

An any value denoting the version of saves.

Examples:

// As an integer (strongly recommended)
Config.saves.version = 3;

// As a string (strongly NOT recommended)
Config.saves.version = "v3";
Config.saves.version = "1.3.12";

 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.

History:

 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.

History:

 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.

History:

 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.

History:

 Config.saves.slots ↔ integer number (default: 8)

Deprecated: This setting has been deprecated and should no longer be used. See the Config.saves.maxSlotSaves setting for its replacement.

History:

 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.

History:

 UI Settings

 Config.ui.stowBarInitially ↔ boolean | integer number (default: 800)

Determines whether the UI bar (sidebar) starts in the stowed (shut) state initially. Valid values are boolean true/false, 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.

History:

Value:

A boolean value signifying whether the UI bar starts stowed initially or an integer number whose value denotes the width in pixels that the viewport has to be less-than-or-equal-to for the UI bar to start stowed initially.

Examples:

// 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 upon passage navigation. The affected elements are (in order): StoryDisplayTitle, StoryBanner, StorySubtitle, StoryAuthor, StoryCaption, and StoryMenu.

Note: The StoryTitle passage 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. If you need a dynamic title, then that's the purpose of StoryDisplayTitle.

History:

Value:

A boolean value signifying whether certain UI bar elements are updated upon navigation.

Examples:

// If you don't need those elements to update
Config.ui.updateStoryElements = false;

 Dialog API

 Dialog.append(content) → Dialog

Appends the given content to the dialog's content area. Returns a reference to the Dialog object for chaining.

Warning: If your content contains any SugarCube markup, you'll need to use the Dialog.wiki() method instead.

History:

Parameters:

Returns:

The Dialog object for chaining.

Examples:

Dialog.append("Cry 'Havoc!', and let slip the <em>dogs</em> of <strong>war</strong>.");

Dialog.append( /* DOM nodes */ );

 Dialog.body() → HTMLElement

Returns a reference to the dialog's content area.

Note: In practice, this method should usually be unnecessary as the Dialog.append() method exists.

History:

Parameters: none

Returns:

The dialog's body element (HTMLElement).

Examples:

jQuery(Dialog.body())
	.append("Cry 'Havoc!', and let slip the <em>dogs</em> of <strong>war</strong>.");

jQuery(Dialog.body())
	.wiki("Cry 'Havoc!', and let slip the //dogs// of ''war''.");

 Dialog.close() → Dialog

Closes the dialog. Returns a reference to the Dialog object for chaining.

History:

Parameters: none

Returns:

The Dialog object for chaining.

Examples:

Dialog.close();

 Dialog.create([title [, classNames]]) → Dialog

Prepares the dialog for use. Returns a reference to the Dialog object for chaining.

History:

Parameters:

Returns:

The Dialog object for chaining.

Examples:

Basic usage
Dialog.create();
With the optional title parameter
Dialog.create('Character Sheet');
With the optional classNames parameter
Dialog.create(null, 'charsheet');
With both optional parameters
Dialog.create('Character Sheet', 'charsheet');
Making use of chaining
Dialog
	.create('Character Sheet', 'charsheet')
	.wikiPassage('Player Character')
	.open();

 Dialog.empty() → Dialog

Empties the dialog's content area. Returns a reference to the Dialog object for chaining.

History:

Parameters: none

Returns:

The Dialog object for chaining.

Examples:

Basic usage
Dialog.empty();
Replacing the open dialog's content
Dialog
	.empty()
	.wikiPassage('Quests');

 Dialog.isOpen([classNames]) → boolean

Returns whether the dialog is currently open.

History:

Parameters:

Returns:

A boolean denoting whether the dialog is currently open.

Examples:

Basic usage
if (Dialog.isOpen()) {
	/* code to execute if any dialog is open… */
}

if (!Dialog.isOpen()) {
	/* code to execute if no dialog is open… */
}
With the optional classNames parameter
if (Dialog.isOpen('saves')) {
	/* code to execute if the Saves dialog is open… */
}

if (!Dialog.isOpen('saves')) {
	/*
		code to execute if either no dialog or the Saves dialog,
		specifically, is not open…
	*/
}

 Dialog.open([options [, closeFn]]) → Dialog

Opens the dialog. Returns a reference to the Dialog object for chaining.

Note: Call this only after populating the dialog with content.

History:

Parameters:

Options object:

An options object should have some of the following properties:

Returns:

The Dialog object for chaining.

Examples:

Basic usage
Dialog.open();
With the optional options parameter
Dialog.open({ top : 100 });
With the optional closeFn parameter
Dialog.open(null, () => {
	/* code to execute on close… */
});
With both optional parameters
Dialog.open({ top : 100 }, () => {
	/* code to execute on close… */
});

 Dialog.wiki(wikiMarkup) → Dialog

Renders the given markup and appends it to the dialog's content area. Returns a reference to the Dialog object for chaining.

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.

History:

Parameters:

Returns:

The Dialog object for chaining.

Examples:

Dialog.wiki("Cry 'Havoc!', and let slip the //dogs// of ''war''.");

 Dialog.wikiPassage(passageName) → Dialog

Renders the passage by the given name and appends it to the dialog's content area. Returns a reference to the Dialog object for chaining.

History:

Parameters:

Returns:

The Dialog object for chaining.

Examples:

Dialog.wikiPassage('Inventory');

 Dialog.setup([title [, classNames]]) → HTMLElement

Deprecated: This method has been deprecated and should no longer be used.

History:

 Engine API

 Constants

 Engine.State

Engine state pseudo-enumeration. Used to denote the state of the engine.

As passage navigation occurs the engine cycles through the states thusly: idle (start) → playing → rendering → playing → idle (end).

History:

Values:

State Description
Engine.State.Idle The engine is currently idle, awaiting the triggering of passage navigation. This is the default state.
Engine.State.Playing Passage navigation has been triggered and the engine is playing/processing a passage.
Engine.State.Rendering The incoming passage is being rendered. This takes place during and implies Engine.State.Playing.

 Methods

 Engine.lastPlay → number

Returns a timestamp representing the last time Engine.play() was called.

History:

Value:

A timestamp (integer number) representing the last time Engine.play() was called.

Examples:

Recording the timestamp for later use.

let lastPlay = Engine.lastPlay;

Using the timestamp to determine elapsed time.

if ((now() - Engine.lastPlay) > 5000) {
	// 5000ms (5s) have elapsed since Engine.play() was last called
}

 Engine.state → Engine.State

Returns the current state of the engine.

History:

Value:

An Engine.State value.

Examples:

// Returns the current state of the engine
Engine.state;

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

History:

Parameters: none

Returns:

A boolean value denoting whether the history navigation was successful.

Examples:

// Rewinds the full history by one moment—i.e., undoes the moment
Engine.backward();

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

History:

Parameters: none

Returns:

A boolean value denoting whether the history navigation was successful.

Examples:

// Forwards the full history by one moment—i.e., redoes the moment
Engine.forward();

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

History:

Parameters:

Returns:

A boolean value denoting whether the history navigation was successful.

Examples:

// Forwards the full history by two moments—i.e., redoes the moments
Engine.go(2);

// Rewinds the full history by four moments—i.e., undoes the moments
Engine.go(-4);

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

History:

Parameters:

Returns:

A boolean value denoting whether the history navigation was successful.

Examples:

// Goes to the first moment
Engine.goTo(0);

// Goes to the tenth moment
Engine.goTo(9);

 Engine.isIdle() → boolean

Returns whether the engine is idle.

History:

Parameters: none

Returns:

A boolean value denoting whether the engine is idle.

Examples:

if (Engine.isIdle()) {
	// do something while idle…
}

if (!Engine.isIdle()) {
	// do something while not idle…
}

 Engine.isPlaying() → boolean

Returns whether the engine is processing a turn—i.e., passage navigation has been triggered.

History:

Parameters: none

Returns:

A boolean value denoting whether the engine is playing.

Examples:

if (Engine.isPlaying()) {
	// do something while playing…
}

if (!Engine.isPlaying()) {
	// do something while not playing…
}

 Engine.isRendering() → boolean

Returns whether the engine is rendering the incoming passage.

History:

Parameters: none

Returns:

A boolean value denoting whether the engine is rendering.

Examples:

if (Engine.isRendering()) {
	// do something while rendering…
}

if (!Engine.isRendering()) {
	// do something while not rendering…
}

 Engine.play(passageName [, noHistory]) → HTMLElement

Renders and displays the passage referenced by the given name, optionally without adding a new moment to the history.

History:

Parameters:

Returns:

An HTMLElement value.

Examples:

// Renders, displays, and adds a new moment to the history for the passage named "Foo" 
Engine.play('Foo');

// Renders and displays, but does not add a moment to the history for the passage named "Foo"
Engine.play('Foo', true);

 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 Engine.restart(), if they accept.

History:

Parameters: none

Returns: none

Examples:

Engine.restart();

 Engine.show() → HTMLElement

Renders and displays the active (present) moment's associated passage without adding a new moment to the history.

History:

Parameters: none

Returns:

An HTMLElement value.

Examples:

// Renders and displays the present passage without adding a new moment to the history
Engine.show();

 Fullscreen API

Provides access to browsers' fullscreen functionality.

 Backgrounds in fullscreen

If you wish to use custom backgrounds, either simply colors or with images, then you should place them on the body element. For example:

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 html element in addition to the body element as this can cause background jitter in Internet Explorer when scrolling outside of fullscreen mode.

Warning: If setting a background image via the background shorthand property, then you should also specify a background-color value with it or include a separate background-color property after the background property. The reason being is that the background property resets the background color, so if you do not set one either as one of its values or via a following background-color property, then the browser's default background color could show through if the background image does not cover the entire viewport or includes transparency.

 Fullscreen limitations

The Fullscreen API comes with some built-in limitations:

  1. Fullscreen requests must be initiated by the player, generally via click/touch—i.e., the request must be made as a result of player interaction; e.g., activating a button/link/etc whose code makes the request.

 Fullscreen.element → HTMLElement | null

Returns the current fullscreen element or, if fullscreen mode is not active, null.

History:

Examples:

Fullscreen.element  → The current fullscreen element

 Fullscreen.isEnabled() → boolean

Returns whether fullscreen is both supported and enabled.

History:

Parameters: none

Examples:

Fullscreen.isEnabled()  → Whether fullscreen mode is available

 Fullscreen.isFullscreen() → boolean

Returns whether fullscreen mode is currently active.

History:

Parameters: none

Examples:

Fullscreen.isFullscreen()  → Whether fullscreen mode is active

 Fullscreen.request([options [, requestedEl]]) → Promise

Request that the browser enter fullscreen mode.

See: Backgrounds and limitations.

History:

Parameters:

Options object:

A fullscreen options object should have some of the following properties:

Note: Browsers are not currently required to honor the navigationUI setting.

Examples:

Basic usage (recommended)
/* Request to enter fullscreen mode. */
Fullscreen.request();
With options and a specified element
/* Request to enter fullscreen mode while showing its navigation UI and with the given element. */
Fullscreen.request({ navigationUI : "show" }, myElement);

 Fullscreen.exit() → Promise

Request that the browser exit fullscreen mode.

History:

Parameters: none

Examples:

/* Request to exit fullscreen mode. */
Fullscreen.exit();

 Fullscreen.toggle([options [, requestedEl]]) → Promise

Request that the browser toggle fullscreen mode—i.e., enter or exit as appropriate.

History:

Parameters:

Examples:

Basic usage (recommended)
/* Request to toggle fullscreen mode. */
Fullscreen.toggle();
With options and a specified element
/* 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.

History:

Parameters:

Examples:

Basic usage (recommended)
/* Attach a hander to listen for fullscreen change events. */
Fullscreen.onChange(function (ev) {
	/* Fullscreen mode changed, so do something. */
});
With a specified element
/* 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.

History:

Parameters:

Examples:

Basic usage (recommended)
/* 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);
With a specified element
/* 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.

History:

Parameters:

Examples:

Basic usage (recommended)
/* Attach a hander to listen for fullscreen error events. */
Fullscreen.onError(function (ev) {
	/* Fullscreen mode changed, so do something. */
});
With a specified element
/* 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.

History:

Parameters:

Examples:

Basic usage (recommended)
/* 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);
With a specified element
/* 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() → integer number

Acquire a loading screen lock and, if necessary, display the loading screen.

History:

Parameters: none

Returns:

The (integer number) lock ID.

Throws: none

Examples:

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.

History:

Parameters:

Returns: none

Throws: none

Examples:

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

History:

Parameters:

Definition object:

A macro definition object should have some of the following properties (only handler is absolutely required):

Additional properties may be added for internal use.

Examples:

/*
	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).

History:

Parameters:

Examples:

Macro.delete("amacro")
Macro.delete(["amacro", "bmacro"])

 Macro.get(name) → Object

Return the named macro definition, or null on failure.

History:

Parameters:

Examples:

Macro.get("print")

 Macro.has(name) → boolean

Returns whether the named macro exists.

History:

Parameters:

Examples:

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 null on failure.

History:

Parameters:

Examples:

Macro.tags.get("else")  → For the standard library, returns: ["if"]

 Macro.tags.has(name) → boolean

Returns whether the named macro tag exists.

History:

Parameters:

Examples:

Macro.tags.has("else")

 MacroContext API

See Also: Macro API.

Macro handlers are called with no arguments, but with their this set to a macro (execution) context object. Macro context objects contain the following data and method properties.

 <MacroContext>.args → Array<any>

An array of discrete arguments parsed from the argument string.

History:

Value:

The Array of arguments.

Examples:

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

History:

Value:

The processed argument string.

Examples:

// Given: <<if $a is "b">>
this.args.full  // Returns 'State.variables.a === "b"'

 <MacroContext>.args.raw → string

The unprocessed argument string.

History:

Value:

The unprocessed argument string.

Examples:

// Given: <<if "a" is "b">>
this.args.raw  // Returns '"a" is "b"'

 <MacroContext>.name → string

The name of the macro.

History:

Value:

The macro's name (string).

Examples:

// Given: <<someMacro …>>
this.name  // Returns 'someMacro'

 <MacroContext>.output → HTMLElement

The current output element.

History:

Value:

The output element (HTMLElement).

Examples:

Usage with jQuery
$(this.output).wiki('Some //awesome// markup!');
Usage w/o jQuery
new Wikifier(this.output, 'Some //awesome// markup!');

 <MacroContext>.parent → Object | null

The macro context object of the macro's parent, or null if the macro has no parent.

History:

Value:

The macro context (Object), elsewise null.

 <MacroContext>.parser → Wikifier

The parser instance that generated the macro call.

History:

Value:

The parser instance (Wikifier).

 <MacroContext>.payload → Array<Object> | null

The text of a container macro parsed into discrete payload objects by tag. Payload objects have the following properties:

History:

Value:

The Array<Object> containing payloads, elsewise null.

 <MacroContext>.self → Object

The macro's definition—created via Macro.add().

History:

Value:

The macro definition (Object).

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

History:

Parameters:

Returns:

An Array<Object> containing the passing ancestors or an empty array, if none pass.

Throws:

A TypeError instance.

Examples:

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 undefined, if no members pass.

History:

Parameters:

Returns:

An Object or undefined, if no ancestors pass.

Throws:

A TypeError instance.

Examples:

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.

History:

Parameters:

Returns:

A Boolean.

Throws:

A TypeError instance.

Examples:

var isInclude = function (ctx) { return ctx.name === 'include'; };
this.contextSome(isInclude);  // Returns true if any ancestor was an <<include>> macro

 <MacroContext>.error(message) → boolean

Renders the message prefixed with the name of the macro and returns false.

History:

Parameters:

Returns:

Boolean false.

Throws: none

Examples:

// 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 this set to the this of the wrapper and with whatever parameters were passed to the wrapper.

Warning: Only useful when you have an asynchronous callback that invokes code/content that needs to access story and/or temporary variables shadowed by <<capture>>. If you don't know what that means, then this API is likely not for you.

History:

Parameters:

Returns:

A Function.

Throws: none

Examples:

Basic usage
$someElement.on('some_event', this.shadowHandler(function (ev) {
	/* main asynchronous code */
}));
With an optional doneCallback
$someElement.on('some_event', this.shadowHandler(
	function (ev) {
		/* main asynchronous code */
	},
	function (ev) {
		/* asynchronous code invoked after the main code */
	}
));
With an optional doneCallback and 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>.wiki(sources…)

Wikifies the given content source(s) and appends the result to the macro's output.

History:

Parameters:

Returns: none

Throws: none

Examples:

Basic usage
this.wiki('Who //are// you?'); // Outputs "Who <em>are</em> you?"
Using multiple content sources
this.wiki(
	'Goodnight…',
	'sweet prince.'
); // Outputs "Goodnight…sweet prince."

 <MacroContext>.contextHas(filter) → boolean

Deprecated: This method has been deprecated and should no longer be used. See the <MacroContext>.contextSome() method for its replacement.

History:

 <MacroContext>.contextSelect(filter) → Object | null

Deprecated: This method has been deprecated and should no longer be used. See the <MacroContext>.contextFind() method for its replacement.

History:

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

History:

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

History:

 Passage API

Instances of the Passage object are returned by the Story.get() static method.

All properties of Passage objects should be treated as if they were read-only, as modifying them could result in unexpected behavior.

 <Passage>.id → string

The passage's DOM-compatible ID, created from the slugified passage name.

History:

 <Passage>.name → string

The name of the passage.

History:

 <Passage>.tags → Array<string>

The tags of the passage.

History:

 <Passage>.text → string

The raw text of the passage.

History:

 <Passage>.processText() → string

Returns the processed text of the passage, created from applying nobr tag and image passage processing to its raw text.

History:

Parameters: none

Examples:

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.

History:

 <Passage>.title → string

Deprecated: This property has been deprecated and should no longer be used. See the <Passage>.name property for its replacement.

History:

 <Passage>.description() → string

Deprecated: This method has been deprecated and should no longer be used.

History:

 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.

 Save Objects

 Save Data

Note: Adding additional properties directly to save data objects is not recommended. Instead, use the metadata property.

Save Data Object

A save data object has the following properties:

Save State Object

The marshaled story state object, from the state property, has the following properties:

Save History Moment Objects

Each moment object, from the history property's array, has the following properties:

 Save Descriptor

Save descriptor objects are only provided for browser saves and are identical to save data objects save that they do not include a state property

 Constants

 Save.Type

Save types pseudo-enumeration. Used to denote the type of save.

History:

Values:

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.

 Browser Saves: General

 Save.browser.size → integer number

The total number of existing browser saves, both auto and slot.

History:

Value:

The integer number count of existing browser saves.

Examples:

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.

History:

Parameters: none

Returns: none

Throws: none

Examples:

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.

History:

Parameters: none

Returns:

A Promise that simply resolves, or rejects with an error if the save could not be loaded.

Throws: none

Examples:

Basic usage

Load the most recent browser save. This should be sufficient in the majority of cases.

if (Save.browser.size > 0) {
	Save.browser.continue()
		.then(() => {
			/* Success.  Show the passage. */
			Engine.show();
		})
		.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.

History:

Parameters: none

Returns:

Boolean true if any browser saves are enabled, elsewise false.

Throws: none

Examples:

if (Save.browser.isEnabled()) {
	/* Some browser saves are enabled. */
}

 Save.browser.newest() → Object | null

Details the most recent browser save, either auto or slot.

History:

Parameters: none

Returns:

The descriptor object for the save if it exists, elsewise null.

Throws: none

Examples:

console.log('Descriptor of the most recent save:', Save.browser.newest());

 Browser Saves: Auto

 Save.browser.auto.size → integer number

The total number of existing browser auto saves.

History:

Value:

The integer number count of existing browser auto saves.

Examples:

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.

History:

Parameters: none

Returns: none

Throws: none

Examples:

Save.browser.auto.clear();

 Save.browser.auto.delete(index)

Deletes the auto save at the given index.

History:

Parameters:

Returns: none

Throws:

An Error instance.

Examples:

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.

History:

Parameters: none

Returns:

An Array of { index, info } generic objects, or an empty Array if no auto saves exist.

Throws:

An Error instance.

Examples:

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.

History:

Parameters:

Returns:

The descriptor object for the auto save if it exists, elsewise null.

Throws:

An Error instance.

Examples:

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.

History:

Parameters:

Returns:

Boolean true if the auto save exists, elsewise false.

Throws:

An Error instance.

Examples:

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.

History:

Parameters: none

Returns:

Boolean true if auto saves are enabled, elsewise false.

Throws: none

Examples:

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.

History:

Parameters:

Returns: none

A Promise that simply resolves, or rejects with an error if the save could not be loaded.

Throws: none

Examples:

Basic usage

Load auto save index 0. This should be sufficient in the majority of cases.

Save.browser.auto.load(0)
	.then(() => {
		/* Success.  Show the passage. */
		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.

History:

Parameters:

Returns: none

Throws:

An Error instance.

Examples:

Basic usage

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);
}

 Browser Saves: Slot

 Save.browser.slot.size → integer number

The total number of existing browser slot saves.

History:

Value:

The integer number count of existing browser slot saves.

Examples:

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.

History:

Parameters: none

Returns: none

Throws: none

Examples:

Save.browser.slot.clear();

 Save.browser.slot.delete(index)

Deletes the slot save at the given index.

History:

Parameters:

Returns: none

Throws:

An Error instance.

Examples:

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.

History:

Parameters: none

Returns:

An Array of { index, info } generic objects, or an empty Array if no slot saves exist.

Throws:

An Error instance.

Examples:

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.

History:

Parameters:

Returns:

The descriptor object for the slot save if it exists, elsewise null.

Throws:

An Error instance.

Examples:

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.

History:

Parameters:

Returns:

Boolean true if the slot save exists, elsewise false.

Throws:

An Error instance.

Examples:

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.

History:

Parameters: none

Returns:

Boolean true if slot saves are enabled, elsewise false.

Throws: none

Examples:

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.

History:

Parameters:

Returns: none

A Promise that simply resolves, or rejects with an error if the save could not be loaded.

Throws: none

Examples:

Basic usage

Load slot save index 0. This should be sufficient in the majority of cases.

Save.browser.slot.load(0)
	.then(() => {
		/* Success.  Show the passage. */
		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.

History:

Parameters:

Returns: none

Throws:

An Error instance.

Examples:

Basic usage

Save to slot save index 0 with the default description and no metadata, handling failure.

try {
	Save.browser.slot.save(0);
}
catch (error) {
	/* Failure.  Handle the error. */
	console.error(error);
	UI.alert(error);
}

Save to slot save index 0 with a description and no metadata, handling failure.

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 0 with the default description and metadata, handling failure.

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 0 with a description and metadata, handling failure.

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);
}

 Disk Saves

 Save.disk.export(filename)

Exports all existing browser saves as a bundle to disk, which may be restored via Save.disk.import().

History:

Parameters:

Returns: none

Throws:

An Error instance.

Examples:

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 change event handler of an <input type="file"> element.

Warning: All existing browser saves will be deleted as part of restoring the exported save bundle.

History:

Parameters:

Returns:

A Promise that simply resolves, or rejects with an error if the browser saves bundle could not be imported.

Throws: none

Examples:

Basic usage

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 change event handler of an <input type="file"> element.

Warning: Saves cannot be loaded during startup and any attempt to do so will cause an error.

History:

Parameters:

Returns:

A Promise that resolves with the save's metadata (any), or rejects with an error if the save could not be loaded.

Throws: none

Examples:

Basic usage

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 => {
				/* Success.  Show the passage. */
				Engine.show();
			})
			.catch(error => {
				/* Failure.  Handle the error. */
				console.error(error);
				UI.alert(error);
			});
	});
As a self-contained button using macros
<<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 => {
					/* Success.  Show the passage. */
					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().

History:

Parameters:

Returns: none

Throws:

An Error instance.

Examples:

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);
}

 Base64 Saves

 Save.base64.export() → string

Exports all existing browser saves as a bundle to a Base64 string, which may be restored via Save.base64.import().

History:

Parameters: none

Returns: none

Throws:

An Error instance.

Examples:

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.

History:

Parameters:

Returns:

A Promise that simply resolves, or rejects with an error if the browser saves bundle could not be imported.

Throws: none

Examples:

Basic usage

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.

History:

Parameters:

Returns:

A Promise that resolves with the save's metadata (any), or rejects with an error if the save could not be loaded.

Throws: none

Examples:

Basic usage

Load the save string. This should be sufficient in the majority of cases.

Save.base64.load(base64Save)
	.then(metadata => {
		/* Success.  Show the passage. */
		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.

History:

Parameters:

Returns:

A Base64 save string.

Throws:

An Error instance.

Examples:

Basic usage

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 Events

 Save.onLoad.size → integer number

The total number of currently registered on-load handlers.

History:

Value:

The integer number count of currently registered on-load handlers.

Examples:

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.

History:

Parameters:

Returns: none

Throws:

An Error instance.

Handler parameters:

Examples:

Basic usage
Save.onLoad.add(function (save) {
	/* code to process the save object before it's loaded */
});
Using save objects' type property and the Save.Type pseudo-enumeration
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.

History:

Parameters: none

Returns: none

Throws: none

Examples:

Save.onLoad.clear();

 Save.onLoad.delete(handler) → boolean

Deletes the specified on-load handler.

History:

Parameters:

Returns:

Boolean true if the handler existed, elsewise false.

Throws: none

Examples:

// 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 number

The total number of currently registered on-save handlers.

History:

Value:

The integer number count of currently registered on-save handlers.

Examples:

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.

History:

Parameters:

Returns: none

Throws:

An Error instance.

Handler parameters:

Examples:

Basic usage
Save.onSave.add(function (save) {
	/* code to process the save object before it's saved */
});
Using save objects' type property and the Save.Type pseudo-enumeration
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.

History:

Parameters: none

Returns: none

Throws: none

Examples:

Save.onSave.clear();

 Save.onSave.delete(handler) → boolean

Deletes the specified on-save handler.

History:

Parameters:

Returns:

Boolean true if the handler existed, elsewise false.

Throws: none

Examples:

// Given:
// 	let myOnSaveHandler = function (save) {
// 		/* code to process the save object before it's saved */
// 	};
// 	Save.onSave.add(myOnSaveHandler);

Save.onSave.delete(myOnSaveHandler);

 Deprecated APIs

 Save.clear()

Deprecated: This method has been deprecated and should no longer be used. See the Save.browser.clear() method for its replacement.

History:

 Save.get()

Deprecated: This method has been deprecated and should no longer be used.

History:

 Save.ok() → boolean

Deprecated: This method has been deprecated and should no longer be used. See the Save.browser.isEnabled() method for its replacement.

History:

 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.

History:

 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.

History:

 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.

History:

 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.

History:

 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.

History:

 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.

History:

 Save.slots.length → integer number

Deprecated: This method has been deprecated and should no longer be used. See the Save.browser.slot.size property for its replacement.

History:

 Save.slots.count() → integer number

Deprecated: This method has been deprecated and should no longer be used.

History:

 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.

History:

 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.

History:

 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.

History:

 Save.slots.isEmpty() → boolean

Deprecated: This method has been deprecated and should no longer be used.

History:

 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.

History:

 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.

History:

 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.

History:

 Save.import(event)

Deprecated: This method has been deprecated and should no longer be used. See the Save.disk.load() method for its replacement.

History:

 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.

History:

 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.

History:

 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.

History:

 Setting API

Manages the Settings dialog and settings object.

Warning: Setting API method calls must be placed within your project's JavaScript section (Twine 2: the Story JavaScript; Twine 1/Twee: a script-tagged passage) or settings will not function correctly.

 Setting.addHeader(name [, desc])

Adds a header to the Settings dialog.

History:

Parameters:

Examples:

// 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 settings object and a list control for it to the Settings dialog.

History:

Parameters:

Definition object:

A list-type definition object should have some of the following properties:

Result object:

Examples:

// 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 settings object and a range control for it to the Settings dialog.

History:

Parameters:

Definition object:

A range-type definition object should have some of the following properties:

Result object:

Examples:

// 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 settings object and a toggle control for it to the Settings dialog.

History:

Parameters:

Definition object:

A toggle-type definition object should have some of the following properties:

Result object:

Examples:

Basic toggle 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
Toggle that adds/removes a CSS class
// 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 settings object.

Note: Does not add a control to the Settings dialog.

History:

Parameters:

Definition object:

A value-type definition object should have some of the following properties:

Result object:

Examples:

Basic usage
Setting.addValue("someSetting");
With a definition object
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].

History:

Parameters: none

Examples:

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

History:

Parameters: none

Examples:

Setting.load();

 Setting.reset([name])

Resets the setting with the given name to its default value. If no name is given, resets all settings.

History:

Parameters:

Examples:

// 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 settings object properties, outside of the controls or Setting.setValue() method, would you need to call this method.

History:

Parameters: none

Examples:

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.

History:

Parameters:

Examples:

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., settings["mode"] = "day". Doing so, however, does not automatically save any values so updated, thus you must manually call the Setting.save() method afterwards.

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.

History:

 SimpleAudio API

The core audio subsystem and backend for the audio macros.

See Also: AudioTrack API, AudioRunner API, and AudioList API.

 Audio limitations

The audio subsystem is based upon the HTML Media Elements APIs and comes with some built-in limitations:

  1. True gapless transitions between tracks is not supported.
  2. In mobile browsers, playback volume is controlled by the device hardware. Thus, all volume adjustments are ignored by the device, though muting should work normally.
  3. In mobile browsers and, more recently, most desktop browsers, playback must be initiated by the player—generally via click/touch. In these cases, audio will not automatically play on the starting passage, nor is it likely to play if initiated from within asynchronous code—e.g., via <<timed>>—though this ultimately depends on various factors. A simple solution for the former is to use some kind of click/touch-through screen—e.g., a splash screen, which the player goes through to the real starting passage. The latter is harder to resolve, so is best avoided.
  4. The load and playback states of tracks are not currently recorded within the active play session or saves. Thus, if you need either to be recoverable, then you'll have to handle that yourself.

 General

 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.

History:

Parameters: none

Examples:

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.

History:

Parameters: none

Examples:

SimpleAudio.loadWithScreen();

 SimpleAudio.mute([state]) → get: boolean | set: undefined

Gets or sets the mute state for the master volume (default: false).

History:

Parameters:

Examples:

// 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: false). 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.

History:

Parameters:

Examples:

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

History:

Parameters:

Examples:

Basic usage
SimpleAudio.select(":ui")  → Returns the AudioRunner instance for the tracks matching ":ui"
Typical usage
// 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.

History:

Parameters: none

Examples:

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.

History:

Parameters: none

Examples:

SimpleAudio.unload();

 SimpleAudio.volume([level]) → get: number | set: undefined

Gets or sets the master volume level (default: 1).

History:

Parameters:

Examples:

// Get the current master volume level.
var currentMasterVolume = SimpleAudio.volume();

// Set the master volume level to 75%.
SimpleAudio.volume(0.75);

 Tracks

 SimpleAudio.tracks.add(trackId, sources…)

Adds an audio track with the given track ID.

History:

Parameters:

Examples:

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

History:

Parameters: none

Examples:

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.

History:

Parameters:

Examples:

SimpleAudio.tracks.delete("bgm_space");

 SimpleAudio.tracks.get(trackId) → AudioTrack | null

Returns the AudioTrack instance with the given track ID, or null on failure.

Note: To affect multiple tracks and/or groups at once, see the SimpleAudio.select() method.

History:

Parameters:

Examples:

Basic usage
SimpleAudio.tracks.get("swamped")  → Returns the AudioTrack instance matching "swamped"
Typical usage
// 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.

History:

Parameters:

Examples:

if (SimpleAudio.tracks.has("bgm_space")) {
	// Track "bgm_space" exists.
}

 Groups

 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.

History:

Parameters:

Examples:

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

History:

Parameters: none

Examples:

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.

History:

Parameters:

Examples:

SimpleAudio.groups.delete(":ui");

 SimpleAudio.groups.get(groupId) → Array<string> | null

Returns the array of track IDs with the given group ID, or null on failure.

Note: To actually affect multiple tracks and/or groups, see the SimpleAudio.select() method.

History:

Parameters:

Examples:

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.

History:

Parameters:

Examples:

if (SimpleAudio.groups.has(":ui")) {
	// Group ":ui" exists.
}

 Lists

 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.

History:

Parameters:

Descriptor objects:

Track descriptor objects come in two forms and should have some of the noted properties:

Examples:

Basic usage with track IDs
// Add existing tracks at their current volumes
SimpleAudio.lists.add("bgm_lacuna", "swamped", "heavens_a_lie", "closer", "to_the_edge");
Using a mix of track IDs and descriptors
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
	}
);
Using descriptors with sources
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.

History:

Parameters: none

Examples:

SimpleAudio.lists.clear();

 SimpleAudio.lists.delete(listId)

Deletes the playlist with the given list ID.

History:

Parameters:

Examples:

SimpleAudio.lists.delete("bgm_lacuna");

 SimpleAudio.lists.get(listId) → AudioList | null

Returns the AudioList instance with the given list ID, or null on failure.

History:

Parameters:

Examples:

Basic usage
SimpleAudio.lists.get("bgm_lacuna")  → Returns the AudioList instance matching "bgm_lacuna"
Typical usage
// 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.

History:

Parameters:

Examples:

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

Returns a new independent copy of the track.

History:

Parameters: none

Examples:

var trackCopy = aTrack.clone();

 <AudioTrack>.duration() → number

Returns the track's total playtime in seconds, Infinity for a stream, or NaN if no metadata exists.

History:

Parameters: none

Examples:

var trackLength = aTrack.duration();

 <AudioTrack>.fade(duration , toVol [, fromVol]) → Promise

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: true) determines whether the audio subsystem automatically pauses tracks that have been faded to 0 volume (silent).

History:

Parameters:

Examples:

// Fade the track from volume 0 to 1 over 6 seconds.
aTrack.fade(6, 1, 0);

 <AudioTrack>.fadeIn(duration [, fromVol]) → Promise

Starts playback of the track and fades it from the specified volume level to 1 (loudest) over the specified number of seconds.

History:

Parameters:

Examples:

// Fade the track in from volume 0 over 5 seconds.
aTrack.fadeIn(5, 0);

 <AudioTrack>.fadeOut(duration [, fromVol]) → Promise

Starts playback of the track and fades it from the specified volume level to 0 (silent) over the specified number of seconds.

Note: The Config.audio.pauseOnFadeToZero setting (default: true) determines whether the audio subsystem automatically pauses tracks that have been faded to 0 volume (silent).

History:

Parameters:

Examples:

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

History:

Parameters: none

Examples:

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.

History:

Parameters: none

Examples:

if (aTrack.hasData()) {
	/* do something */
}

 <AudioTrack>.hasMetadata() → boolean

Returns whether, at least, the track's metadata has been loaded.

History:

Parameters: none

Examples:

if (aTrack.hasMetadata()) {
	/* do something */
}

 <AudioTrack>.hasNoData() → boolean

Returns whether none of the track's data has been loaded.

History:

Parameters: none

Examples:

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.

History:

Parameters: none

Examples:

if (aTrack.hasSomeData()) {
	/* do something */
}

 <AudioTrack>.hasSource() → boolean

Returns whether any valid sources were registered.

History:

Parameters: none

Examples:

if (aTrack.hasSource()) {
	/* do something */
}

 <AudioTrack>.isEnded() → boolean

Returns whether playback of the track has ended.

History:

Parameters: none

Examples:

if (aTrack.isEnded()) {
	/* do something */
}

 <AudioTrack>.isFading() → boolean

Returns whether a fade is in-progress on the track.

History:

Parameters: none

Examples:

if (aTrack.isFading()) {
	/* do something */
}

 <AudioTrack>.isFailed() → boolean

Returns whether an error has occurred.

History:

Parameters: none

Examples:

if (aTrack.isFailed()) {
	/* do something */
}

 <AudioTrack>.isLoading() → boolean

Returns whether the track is loading data.

History:

Parameters: none

Examples:

if (aTrack.isLoading()) {
	/* do something */
}

 <AudioTrack>.isPaused() → boolean

Returns whether playback of the track has been paused.

History:

Parameters: none

Examples:

if (aTrack.isPaused()) {
	/* do something */
}

 <AudioTrack>.isPlaying() → boolean

Returns whether the track is playing.

History:

Parameters: none

Examples:

if (aTrack.isPlaying()) {
	/* do something */
}

 <AudioTrack>.isSeeking() → boolean

Returns whether the track is seeking.

History:

Parameters: none

Examples:

if (aTrack.isSeeking()) {
	/* do something */
}

 <AudioTrack>.isStopped() → boolean

Returns whether playback of the track has been stopped.

History:

Parameters: none

Examples:

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.

History:

Parameters: none

Examples:

if (aTrack.isUnavailable()) {
	/* do something */
}

 <AudioTrack>.isUnloaded() → boolean

Returns whether the track's sources are currently unloaded.

History:

Parameters: none

Examples:

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.

History:

Parameters: none

Examples:

aTrack.load();

 <AudioTrack>.loop([state]) → get: boolean | set: AudioTrack

Gets or sets the track's repeating playback state (default: false). When used to set the loop state, returns a reference to the current AudioTrack instance for chaining.

History:

Parameters:

Examples:

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

Gets or sets the track's volume mute state (default: false). When used to set the mute state, returns a reference to the current AudioTrack instance for chaining.

History:

Parameters:

Examples:

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

Removes event handlers from the track. Returns a reference to the current AudioTrack instance for chaining.

Note: Shorthand for jQuery's .off() method applied to the audio element.

Warning: The SimpleAudio 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., .myEvents—when attaching your own handlers. It is further strongly suggested that you provide that same custom user namespace when removing them.

History:

Parameters:

See: <jQuery>.off() in the jQuery API docs for more information.

Examples:

// Remove any handlers for the ended event.
aTrack.off('ended.myEvents');

 <AudioTrack>.on(...args) → AudioTrack

Attaches event handlers to the track. Returns a reference to the current AudioTrack instance for chaining.

Note: Shorthand for jQuery's .on() method applied to the audio element.

Warning: The SimpleAudio 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., .myEvents—when attaching your own handlers. It is further strongly suggested that you provide that same custom user namespace when removing them.

History:

Parameters:

See: <jQuery>.on() in the jQuery API docs for more information.

Examples:

// Add a handler for the ended event.
aTrack.on('ended.myEvents', function () {
	/* do something */
});

 <AudioTrack>.one(...args) → AudioTrack

Attaches single-use event handlers to the track. Returns a reference to the current AudioTrack instance for chaining.

Note: Shorthand for jQuery's .one() method applied to the audio element.

Warning: The SimpleAudio 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., .myEvents—when attaching your own handlers. It is further strongly suggested that you provide that same custom user namespace when removing them.

History:

Parameters:

See: <jQuery>.one() in the jQuery API docs for more information.

Examples:

// Add a single-use handler for the ended event.
aTrack.one('ended.myEvents', function () {
	/* do something */
});

 <AudioTrack>.pause()

Pauses playback of the track.

History:

Parameters: none

Examples:

aTrack.pause();

 <AudioTrack>.play() → Promise

Begins playback of the track.

History:

Parameters: none

Examples:

Basic usage
aTrack.play();
Using the returned 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.

History:

Parameters: none

Examples:

aTrack.playWhenAllowed();

 <AudioTrack>.remaining() → number

Returns how much remains of the track's total playtime in seconds, Infinity for a stream, or NaN if no metadata exists.

History:

Parameters: none

Examples:

var trackRemains = aTrack.remaining();

 <AudioTrack>.stop()

Stops playback of the track.

History:

Parameters: none

Examples:

someTrack.stop();

 <AudioTrack>.time([seconds]) → get: number | set: AudioTrack

Gets or sets the track's current time in seconds. When used to set a value, returns a reference to the current AudioTrack instance for chaining.

History:

Parameters:

Examples:

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

History:

Parameters: none

Examples:

aTrack.unload();

 <AudioTrack>.volume([level]) → get: number | set: AudioTrack

Gets or sets the track's volume level (default: 1). When used to set the volume, returns a reference to the current AudioTrack instance for chaining.

History:

Parameters:

Examples:

// 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: true) determines whether the audio subsystem automatically pauses tracks that have been faded to 0 volume (silent).

History:

Parameters:

Examples:

// 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 1 (loudest) over the specified number of seconds.

History:

Parameters:

Examples:

// 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 0 (silent) over the specified number of seconds.

Note: The Config.audio.pauseOnFadeToZero setting (default: true) determines whether the audio subsystem automatically pauses tracks that have been faded to 0 volume (silent).

History:

Parameters:

Examples:

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

History:

Parameters: none

Examples:

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.

History:

Parameters: none

Examples:

someTracks.load();

 <AudioRunner>.loop(state) → AudioRunner object

Sets the selected tracks' repeating playback state (default: false). Returns a reference to the current AudioRunner instance for chaining.

History:

Parameters:

Examples:

// 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: false). Returns a reference to the current AudioRunner instance for chaining.

History:

Parameters:

Examples:

// 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 AudioRunner instance for chaining.

Note: Shorthand for jQuery's .off() method applied to each of the audio elements.

Warning: The SimpleAudio 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., .myEvents—when attaching your own handlers. It is further strongly suggested that you provide that same custom user namespace when removing them.

History:

Parameters:

See: <jQuery>.off() in the jQuery API docs for more information.

Examples:

// 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 AudioRunner instance for chaining.

Note: Shorthand for jQuery's .on() method applied to each of the audio elements.

Warning: The SimpleAudio 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., .myEvents—when attaching your own handlers. It is further strongly suggested that you provide that same custom user namespace when removing them.

History:

Parameters:

See: <jQuery>.on() in the jQuery API docs for more information.

Examples:

// 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 AudioRunner instance for chaining.

Note: Shorthand for jQuery's .one() method applied to each of the audio elements.

Warning: The SimpleAudio 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., .myEvents—when attaching your own handlers. It is further strongly suggested that you provide that same custom user namespace when removing them.

History:

Parameters:

See: <jQuery>.one() in the jQuery API docs for more information.

Examples:

// Add a single-use handler for the ended event.
someTracks.one('ended.myEvents', function () {
	/* do something */
});

 <AudioRunner>.pause()

Pauses playback of the selected tracks.

History:

Parameters: none

Examples:

someTracks.pause();

 <AudioRunner>.play()

Begins playback of the selected tracks.

History:

Parameters: none

Examples:

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.

History:

Parameters: none

Examples:

someTracks.playWhenAllowed();

 <AudioRunner>.stop()

Stops playback of the selected tracks.

History:

Parameters: none

Examples:

someTracks.stop();

 <AudioRunner>.time(seconds) → AudioRunner object

Sets the selected tracks' current time in seconds. Returns a reference to the current AudioRunner instance for chaining.

History:

Parameters:

Examples:

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

History:

Parameters: none

Examples:

someTracks.unload();

 <AudioRunner>.volume(level) → AudioRunner object

Sets the selected tracks' volume level (default: 1). Returns a reference to the current AudioRunner instance for chaining.

History:

Parameters:

Examples:

// 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, Infinity if it contains any streams, or NaN if no metadata exists.

History:

Parameters: none

Examples:

var listLength = aList.duration();

 <AudioList>.fade(duration , toVol [, fromVol]) → Promise

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: true) determines whether the audio subsystem automatically pauses tracks that have been faded to 0 volume (silent).

History:

Parameters:

Examples:

// Fade the playlist from volume 0 to 1 over 6 seconds.
aList.fade(6, 1, 0);

 <AudioList>.fadeIn(duration [, fromVol]) → Promise

Starts playback of the playlist and fades the currently playing track from the specified volume level to 1 (loudest) over the specified number of seconds.

History:

Parameters:

Examples:

// Fade the playlist in from volume 0 over 5 seconds.
aList.fadeIn(5, 0);

 <AudioList>.fadeOut(duration [, fromVol]) → Promise

Starts playback of the playlist and fades the currently playing track from the specified volume level to 0 (silent) over the specified number of seconds.

Note: The Config.audio.pauseOnFadeToZero setting (default: true) determines whether the audio subsystem automatically pauses tracks that have been faded to 0 volume (silent).

History:

Parameters:

Examples:

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

History:

Parameters: none

Examples:

aList.fadeStop();

 <AudioList>.isEnded() → boolean

Returns whether playback of the playlist has ended.

History:

Parameters: none

Examples:

if (aList.isEnded()) {
	/* do something */
}

 <AudioList>.isFading() → boolean

Returns whether a fade is in-progress on the currently playing track.

History:

Parameters: none

Examples:

if (aList.isFading()) {
	/* do something */
}

 <AudioList>.isPaused() → boolean

Returns whether playback of the playlist has been paused.

History:

Parameters: none

Examples:

if (aList.isPaused()) {
	/* do something */
}

 <AudioList>.isPlaying() → boolean

Returns whether the playlist is playing.

History:

Parameters: none

Examples:

if (aList.isPlaying()) {
	/* do something */
}

 <AudioList>.isStopped() → boolean

Returns whether playback of the playlist has been stopped.

History:

Parameters: none

Examples:

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.

History:

Parameters: none

Examples:

aList.load();

 <AudioList>.loop([state]) → get: boolean | set: AudioList

Gets or sets the playlist's repeating playback state (default: false). When used to set the loop state, returns a reference to the current AudioList instance for chaining.

History:

Parameters:

Examples:

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

Gets or sets the playlist's volume mute state (default: false). When used to set the mute state, returns a reference to the current AudioList instance for chaining.

History:

Parameters:

Examples:

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

History:

Parameters: none

Examples:

aList.pause();

 <AudioList>.play() → Promise

Begins playback of the playlist.

History:

Parameters: none

Examples:

Basic usage
aList.play();
Using the returned 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.

History:

Parameters: none

Examples:

aList.playWhenAllowed();

 <AudioList>.remaining() → number

Returns how much remains of the playlist's total playtime in seconds, Infinity if it contains any streams, or NaN if no metadata exists.

History:

Parameters: none

Examples:

var listRemains = aList.remaining();

 <AudioList>.shuffle([state]) → get: boolean | set: AudioList

Gets or sets the playlist's randomly shuffled playback state (default: false). When used to set the shuffle state, returns a reference to the current AudioList instance for chaining.

History:

Parameters:

Examples:

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

History:

Parameters: none

Examples:

someTrack.skip();

 <AudioList>.stop()

Stops playback of the playlist.

History:

Parameters: none

Examples:

someTrack.stop();

 <AudioList>.time() → number

Returns the playlist's current time in seconds, or NaN if no metadata exists.

History:

Parameters: none

Examples:

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.

History:

Parameters: none

Examples:

aList.unload();

 <AudioList>.volume([level]) → get: number | set: AudioList

Gets or sets the playlist's volume level (default: 1). When used to set the volume, returns a reference to the current AudioList instance for chaining.

History:

Parameters:

Examples:

// 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 State.active 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.

History:

Examples:

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

History:

Examples:

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: State.current is not a synonym for State.active. You will, very likely, never need to use State.current directly within your code.

History:

Examples:

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 number

Returns the number of moments within the past in-play history (past only).

History:

Examples:

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.

History:

Examples:

State.passage  → The passage title of the present moment

 State.size → integer number

Returns the number of moments within the full in-play history (past + future).

History:

Parameters: none

Examples:

if (State.size === 0) {
	/* No moments within the full in-play history. Egad! */
}

 State.temporary → Object

Returns the current temporary variables.

History:

Examples:

State.temporary  → The current temporary variables

 State.top → Object

Returns the topmost (most recent) moment from the full in-play history (past + future).

Warning: State.top is not a synonym for State.active. You will, very likely, never need to use State.top directly within your code.

History:

Examples:

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 number

Returns the total number (count) of played moments within the extended past history (expired + past).

History:

Examples:

if (State.turns === 1) {
	/* Initial turn.  The starting passage is displayed. */
}

 State.variables → Object

Returns the variables from the active (present) moment.

History:

Examples:

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.

History:

Parameters:

Examples:

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: State.has() 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.

History:

Parameters:

Examples:

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.

History:

Parameters:

Examples:

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.

History:

Parameters:

Examples:

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.

History:

Parameters: none

Examples:

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.

History:

Parameters:

Examples:

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 number

Returns the size of the story metadata store—i.e., the number of stored pairs.

History:

Examples:

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

History:

Parameters: none

Examples:

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

History:

Parameters:

Examples:

// 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 [key, value] arrays.

History:

Parameters: none

Examples:

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

History:

Parameters:

Examples:

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

History:

Parameters:

Examples:

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

History:

Parameters: none

Examples:

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

History:

Parameters:

Examples:

// 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: State.prng.init() must be called during story initialization, within either your project's JavaScript section (Twine 2: the Story JavaScript; Twine 1/Twee: a script-tagged passage) or the StoryInit special passage. Additionally, it is strongly recommended that you do not specify any arguments to State.prng.init() 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.

History:

Parameters:

Examples:

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.

History:

Examples:

State.prng.isEnabled()  → Returns whether the seedable PRNG is enabled

 State.prng.pull → integer number | 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.

History:

Examples:

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.

History:

Examples:

State.prng.seed  → Returns the PRNG seed

 State.random() → number

Returns a pseudo-random decimal number (floating-point) in the range 0 (inclusive) up to, but not including, 1 (exclusive).

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.

History:

Parameters: none

Examples:

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.

History:

Parameters:

Examples:

State.setVar("$charName", "Jane Doe")  → Assigns the string "Jane Doe" to $charName

 Story API

 Story.id → string

The DOM-compatible ID of the story.

History:

Value:

The string DOM-compatible ID of the story, created from the slugified story name.

 Story.ifId → string

The IFID (Interactive Fiction IDentifier) of the story.

History:

Value:

The string IFID of the story, or an empty string if no IFID exists. The Twine 2 ecosystem's IFIDs are v4 random UUIDs.

 Story.name → string

The name of the story.

History:

Value:

The string name of the story.

 Story.add(descriptor) → boolean

Adds the passage to the passage store.

Note: This method cannot add code passages or passages tagged with code tags.

History:

Parameters:

Passage Descriptor:

A passage descriptor object should have the following properties:

Returns:

Boolean true if the passage was added, elsewise false.

Examples:

// 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 Passage instance with the given name.

Note: This method cannot delete the starting passage, code passages, or passages tagged with code tags.

History:

Parameters:

Returns:

Boolean true if a Passage instance with the given name was deleted, elsewise false.

Examples:

// 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 Passage instances for those that pass the test implemented by the given predicate function.

Note: This method cannot retrieve passages tagged with code tags.

History:

Parameters:

Returns:

A new Array<Passage> filled with all instances that pass the test implemented by the given predicate function, or an empty Array if no instances pass.

Examples:

// 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 Passage instances for the first that passes the test implemented by the given predicate function.

Note: This method cannot retrieve passages tagged with code tags.

History:

Parameters:

Returns:

The first Passage instance that passed the test implemented by the given predicate function, or undefined if no instance passes.

Examples:

// 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);
});

 Story.get(name) → Passage

Gets the Passage instance with the given name.

Note: This method cannot retrieve passages tagged with code tags.

History:

Parameters:

Returns:

The Passage instance with the given name, or a new empty Passage instance if no such passage exists.

Examples:

// Get the Passage instance with the name "The Ducky"
const theDucky = Story.get("The Ducky");

 Story.has(name) → boolean

Determines whether a Passage instance with the given name exists.

Note: This method does not check passages tagged with code tags.

History:

Parameters:

Returns:

Boolean true if a Passage instance with the given name exists, elsewise false.

Examples:

// Returns whether a "The Ducky" Passage instance exists
if (Story.has("The Ducky")) {
	/* The "The Ducky" passage exists. */
}

 Story.domId → string

Deprecated: This setting has been deprecated and should no longer be used. See the Story.id setting for its replacement.

History:

 Story.title → string

Deprecated: This setting has been deprecated and should no longer be used. See the Story.name setting for its replacement.

History:

 Story.lookup(propertyName , searchValue [, sortProperty]) → Array<Passage>

Deprecated: This static method has been deprecated and should no longer be used. See the Story.filter() static method for its replacement.

History:

 Story.lookupWith(predicate [, sortProperty]) → Array<Passage>

Deprecated: This static method has been deprecated and should no longer be used. See the Story.filter() static method for its replacement.

History:

 Template API

 Template.size → number

Returns the number of existing templates.

History:

Examples:

if (Template.size === 0) {
	/* No templates exist. */
}

 Template.add(name , definition)

Add new template(s).

History:

Parameters:

Function templates:

Function templates should return a string, which may itself contain markup. They are called with no arguments, but with their this set to a template (execution) context object that contains the following data properties:

String templates:

String templates consist solely of a string, which may itself contain markup.

Examples:

Basic usage
/* Define a function template named ?yolo. */
Template.add('yolo', function () {
	return either('YOLO', 'You Only Live Once');
});

/* Define a string template named ?nolf. */
Template.add('nolf', 'No One Lives Forever');

/* Define an array of string templates named ?alsoYolo. */
Template.add('alsoYolo', ['YOLO', 'You Only Live Once']);

/* Define an array of mixed string and function templates named ?cmyk. */
Template.add('cmyk', [
	'Cyan',
	function () {
		return either('Magenta', 'Yellow');
	},
	'Black'
]);
Using the context object (this)
/* Define a function template with two names, ?color and ?Color, whose output changes based on its name. */
Template.add(['color', 'Color'], function () {
	var color = either('red', 'green', 'blue');
	return this.name === 'Color' ? color.toUpperFirst() : color;
});

 Template.delete(name)

Remove existing template(s).

History:

Parameters:

Examples:

/* Deletes the template ?yolo. */
Template.delete('yolo');

/* Deletes the templates ?yolo and ?nolf. */
Template.delete(['yolo', 'nolf']);

 Template.get(name) → Function | string | Array<Function | string>

Return the named template definition, or null on failure.

History:

Parameters:

Examples:

/* Returns the template ?yolo, or null if it doesn't exist. */
var yolo = Template.get('yolo');

 Template.has(name) → boolean

Returns whether the named template exists.

History:

Parameters:

Examples:

if (Template.has('yolo')) {
	/* A ?yolo template exists. */
}

 UI API

 UI.alert(message [, options [, closeFn]])

Opens the built-in alert dialog, displaying the given message to the player.

History:

Parameters:

Returns: none

Throws: none

Examples:

UI.alert("You smell of elderberries!");

 UI.restart([options [, closeFn]])

Opens the built-in restart dialog, prompting the player to restart the story.

History:

Parameters:

Returns: none

Throws: none

Examples:

UI.restart();

 UI.saves([options [, closeFn]])

Opens the built-in saves dialog.

History:

Parameters:

Returns: none

Throws: none

Examples:

UI.saves();

 UI.settings([options [, closeFn]])

Opens the built-in settings dialog, which is populated from the Setting API.

History:

Parameters:

Returns: none

Throws: none

Examples:

UI.settings();

 UI.update()

Triggers a :uiupdate event that causes the update of the dynamically updated sections built-in user interface—e.g., those populated by code passages, like StoryCaption and StoryMenu. Automatically invoked during passage navigation.

Warning:

As all dynamically updated sections of the built-in UI are updated, save for the main passage display, it is recommended that this method be used sparingly.

Ideally, if you need to update these sections of the built-in UI outside of the normal passage navigation update, then you should update only the specific areas you need to rather than the entire UI.

History:

Parameters: none

Returns: none

Throws: none

Examples:

UI.update();

 UI.jumpto([options [, closeFn]])

Deprecated: This method has been deprecated and should no longer be used.

History:

 UI.share([options [, closeFn]])

Deprecated: This method has been deprecated and should no longer be used.

History:

 UIBar API

 UIBar.destroy()

Completely removes the UI bar and all of its associated styles and event handlers.

History:

Parameters: none

Examples:

UIBar.destroy();

 UIBar.hide() → UIBar object

Hides the UI bar. Returns a reference to the UIBar object for chaining.

Note: This does not reclaim the space reserved for the UI bar. Thus, a call to UIBar.stow() may also be necessary. Alternatively, if you simply want the UI bar gone completely and permanently, either using UIBar.destroy() or the StoryInterface special passage may be a better choice.

History:

Parameters: none

Examples:

Basic usage
UIBar.hide();
With stow
UIBar.hide().stow();

 UIBar.isHidden() → boolean

Returns whether the UI bar is currently hidden.

History:

Parameters: none

Examples:

if (UIBar.isHidden()) {
	/* code to execute if the UI bar is hidden… */
}

if (!UIBar.isHidden()) {
	/* code to execute if the UI bar is not hidden… */
}

 UIBar.isStowed() → boolean

Returns whether the UI bar is currently stowed.

History:

Parameters: none

Examples:

if (UIBar.isStowed()) {
	/* code to execute if the UI bar is stowed… */
}

if (!UIBar.isStowed()) {
	/* code to execute if the UI bar is not stowed… */
}

 UIBar.show() → UIBar object

Shows the UI bar. Returns a reference to the UIBar object for chaining.

History:

Parameters: none

Examples:

Basic usage
UIBar.show();
With unstow
UIBar.unstow().show();

 UIBar.stow([noAnimation]) → UIBar object

Stows the UI bar, so that it takes up less space. Returns a reference to the UIBar object for chaining.

History:

Parameters:

Examples:

Basic usage
UIBar.stow();
With no animation
UIBar.stow(true);

 UIBar.unstow([noAnimation]) → UIBar object

Unstows the UI bar, so that it is fully accessible again. Returns a reference to the UIBar object for chaining.

History:

Parameters:

Examples:

Basic usage
UIBar.unstow();
With no animation
UIBar.unstow(true);

 UIBar.update()

Deprecated: This method has been deprecated and should no longer be used. See the UI.update() static method for its replacement.

History:

 Guide: State, Sessions, and Saving

SugarCube preserves the state of the story as it's being played in a number of ways to both prevent the loss of progress and allow players to save stories. This guide will detail how these features work.

 Story History

The story history is a collection of moments. A new moment is created whenever passage navigation occurs, and only when passage navigation occurs. Each moment contains data regarding the active passage and the state of all story variables—that is, the ones you use the $ sigil to interact with—as they exist when the moment is created. The history allows players to navigate through these moments.

The number of moments contained within the story history is, generally, limited, via the Config.history.maxStates setting. As new moments are added, older moments that exceed the maximum number are expired in order of age, oldest first. Expired moments are recorded in a separate expired collection and can no longer be navigated to. If you limit the moments within the history to 1, via setting Config.history.maxStates to 1, then there will only ever be one moment in the history, but passage navigation is still required for new moments to be created.

Note: All user functions and macros that check for the existence of moments within the history check both the story history and expired moments, so will work as expected even if the history is limited to a single moment as described above.

Saving the story records the story's state up until the last moment that was created. This is not necessarily the same as the current state of the story: because moment creation is tied to passage navigation, changes that occur between one passage navigation and the next are not part of the current moment and will not be preserved by a moment until the next navigation, when the next moment is created.

Consider the following:

:: one passage
<<set $var to 1>>

[[another passage]]

:: another passage
<<link "Click me!">>
	<<set $var to 2>>
<</link>>

In the above example, if you save the story after reaching the passage called another passage, the $var variable will be saved in the state as 1, as you would expect. If you click the link that sets the variable to 2, and then save the story, the $var variable will still be saved as 1, because a new moment has not yet been created.

 Playthrough Session

Note: Auto saves are occasionally confused with the playthrough session, but they are in fact distinct systems.

SugarCube automatically stores the current playthrough state to the browser's session storage whenever a new moment is created. This can be thought of as a special, temporary saved story, which is automatically deleted after the player's current browsing session ends. This temporary playthrough session is intended to prevent players from losing data. Some browsers, particularly mobile ones, will free up memory by unloading web pages that are running in the background. This functionally refreshes the webpage, and can cause users to lose their progress. When SugarCube is reloaded by the browser, it checks if a playthrough session exists and loads it to prevent any inadvertent loss of progress.

This feature also prevents players from losing progress if they try to use the browser back and forward buttons to navigate, or if they refresh their browser for any reason. The built-in Restart button, along with the methods UI.restart() and Engine.restart() are provided so that the story can be restarted without restoring a session.

To recap:

 Auto saves

Note: A playthrough session is occasionally confused with auto saves, but they are in fact distinct systems.

SugarCube features configurable auto saves. Auto saves are otherwise normal browser saves that automatically save either on every turn or only on certain turns, depending on how they're configured.

See: Config.saves.maxAutoSave setting, Config.saves.isAllowed setting, and Save.browser.auto API.

 What Happens When a Save is Loaded?

When a save is loaded, the state loaded from the save replaces the current state. This process is the same regardless of where the loaded state is coming from, be it a save or the playthrough session. The previous state is completely lost—the new state is not added to or combined with the current state, instead it replaces it in its entirety. The easiest way to understand this is to look at what happens when you make some changes to StoryInit and then load a save from before those changes were made. For example:

:: StoryInit
<<set $x to 0>>

:: Start
$$x is <<if def $x>> $x <<else>> undefined <</if>>

If you run the above, you'll see $x is 0. Create a save, then edit the code as follows:

:: StoryInit
<<set $x to 0>>
<<set $y to 1>>

:: Start
$$x is <<if def $x>> $x <<else>> undefined <</if>>
$$y is <<if def $y>> $y <<else>> undefined <</if>>

Running that, you'll see $x is 0 and $y is 1. Now, load the save from before the changes were made, and you'll see $y is undefined, since it doesn't exist at all in the loaded state.

 Refreshing and Restarting

Whenever your story is first started or, for any reason, restarted—e.g., the browser window/tab was refreshed/reloaded—it undergoes its startup sequence. Several things occur each and every time startup happens, regardless of whether or not a playthrough session will be restored or the starting passage run. First, the CSS, JavaScript, and Widget sections are processed. Next, any init-tagged passages and the StoryInit special passage are processed. Finally, one of two things happen (in order): the existing playthrough session is restored, if it exists, elsewise the starting passage is run.

Some users have the false impression that StoryInit is not run when the story is restarted when the playthrough session is restored or autosave is loaded. Code like <<set $y to 1>> seems to have no effect because the startup state is replaced by the of the incoming state, but they are still executed by the engine. You can see this effect by changing data outside the state. For example, let's return to the example above and change it again:

:: StoryInit
<<set $x to 0>>
<<set setup.y to 1>>

:: Start
$$x is <<if def $x>> $x <<else>> undefined <</if>>
setup.y is <<if def setup.y>> <<= setup.y>> <<else>> undefined <</if>>

You'll see that setup.y is being set to 1 and displayed properly regardless of whether you load a save or not, because it is not part of the state.

When the story is restarted by SugarCube rather than refreshed via the browser, the playthrough session, if any, is not loaded. The CSS, JavaScript, & Widget sections, any init-tagged passages, and the StoryInit special passage are processed, as usual, and then the starting passage is rendered.

 Guide: Non-generic object types (classes)

As a basic working definition, non-generic object types—i.e., classes—are instantiable objects whose own prototype is not Object—e.g., Array is a native non-generic object type.

Many of the commonly used native non-generic object types are already fully compatible with and supported for use within story variables—e.g., Array, Date, Map, and Set. All other non-generic object types, on the other hand, must be made compatible to be successfully stored within story variables.

Making custom non-generic object types fully compatible requires that two methods be added to their prototype, .clone() and .toJSON(), to support cloning—i.e., deep copying—instances of the type.

In both cases, since the end goal is roughly the same, this means creating a new instance of the base object type and populating it with clones of the original instance's data. There is no one size fits all example for either of these methods because an instance's properties, and the data contained therein, are what determine what you need to do.

See Also: The Serial.createReviver() method for additional information on implementing the .toJSON() method.

Examples: (not an exhaustive list)

 class-based syntax (newer, preferred)

Configuration object parameter constructor (w/ automatic copying of own data)

Here's a simple example whose constructor takes a single configuration object parameter:

window.Character = class Character {
	constructor(config) {
		// Set up our own data properties with some defaults.
		this.name = '(none)';
		this.race = '(none)';
		this.st   = 10;
		this.dx   = 10;
		this.iq   = 10;
		this.ht   = 10;
		this.hp   = 10;

		// Clone the given config object's own properties into our own properties.
		//
		// NOTE: We use the SugarCube built-in `clone()` function to make deep
		// copies of each of the properties' values.
		Object.keys(config).forEach((pn) => {
			this[pn] = clone(config[pn]);
		});
	}

	clone() {
		// Return a new instance containing our own data.
		return new this.constructor(this);
	}

	toJSON() {
		// Return a code string that will create a new instance containing our
		// own data.
		//
		// NOTE: Supplying `this` directly as the `reviveData` parameter to the
		// `Serial.createReviver()` call will trigger out of control recursion in
		// the serializer, so we must pass it a clone of our own data instead.
		const ownData = {};
		Object.keys(this).forEach((pn) => {
			ownData[pn] = clone(this[pn]);
		});
		return Serial.createReviver(`new ${this.constructor.name}($ReviveData$)`, ownData);
	}
};

Creating a new instance of this Character example would be something like:

<<set $Joe to new Character({
	name : 'Joe the Barbarian',
	race : 'human',
	st   : 20,
	dx   : 12,
	iq   : 9,
	ht   : 18,
	hp   : 18
})>>

Discrete parameters constructor (w/ manual copying of own data)

Here's a simple example whose constructor takes multiple discrete parameters:

window.Character = class Character {
	constructor(
		name,
		race,
		st,
		dx,
		iq,
		ht,
		hp
	) {
		// Set up our own data properties with the given values or defaults.
		this.name = name ?? '(none)';
		this.race = race ?? '(none)';
		this.st   = st ?? 10;
		this.dx   = dx ?? 10;
		this.iq   = iq ?? 10;
		this.ht   = ht ?? 10;
		this.hp   = hp ?? 10;
	}

	clone() {
		// Return a new instance containing our own data.
		return new this.constructor(
			this.name,
			this.race,
			this.st,
			this.dx,
			this.iq,
			this.ht,
			this.hp
		);
	}

	toJSON() {
		// Return a code string that will create a new instance containing our
		// own data.
		return Serial.createReviver(String.format(
			'new {0}({1},{2},{3},{4},{5},{6},{7})',
			this.constructor.name,
			JSON.stringify(this.name),
			JSON.stringify(this.race),
			JSON.stringify(this.st),
			JSON.stringify(this.dx),
			JSON.stringify(this.iq),
			JSON.stringify(this.ht),
			JSON.stringify(this.hp)
		));
	}
};

Creating a new instance of this Character example would be something like:

<<set $Joe to new Character(
	'Joe the Barbarian',
	'human',
	20,
	12,
	9,
	18,
	18
)>>

 function-based syntax (classic, not recommended)

Configuration object parameter constructor (w/ automatic copying of own data)

Here's a simple example whose constructor takes a single configuration object parameter:

window.Character = function Character(config) {
	// Set up our own data properties with some defaults.
	this.name = '(none)';
	this.race = '(none)';
	this.st   = 10;
	this.dx   = 10;
	this.iq   = 10;
	this.ht   = 10;
	this.hp   = 10;

	// Clone the given config object's own properties into our own properties.
	//
	// NOTE: We use the SugarCube built-in `clone()` function to make deep
	// copies of each of the properties' values.
	Object.keys(config).forEach(function (pn) {
		this[pn] = clone(config[pn]);
	}, this);
};

Character.prototype.clone = function () {
	// Return a new instance containing our own data.
	return new Character(this);
};

Character.prototype.toJSON = function () {
	// Return a code string that will create a new instance containing our
	// own data.
	//
	// NOTE: Supplying `this` directly as the `reviveData` parameter to the
	// `Serial.createReviver()` call will trigger out of control recursion in
	// the serializer, so we must pass it a clone of our own data instead.
	var ownData = {};
	Object.keys(this).forEach(function (pn) {
		ownData[pn] = clone(this[pn]);
	}, this);
	return Serial.createReviver('new Character($ReviveData$)', ownData);
};

Creating a new instance of this Character example would be something like:

<<set $Joe to new Character({
	name : 'Joe the Barbarian',
	race : 'human',
	st   : 20,
	dx   : 12,
	iq   : 9,
	ht   : 18,
	hp   : 18
})>>

Discrete parameters constructor (w/ manual copying of own data)

Here's a simple example whose constructor takes multiple discrete parameters:

window.Character = function (
	name,
	race,
	st,
	dx,
	iq,
	ht,
	hp
) {
	// Set up our own data properties with the given values or defaults.
	this.name = name || '(none)';
	this.race = race || '(none)';
	this.st   = st || 10;
	this.dx   = dx || 10;
	this.iq   = iq || 10;
	this.ht   = ht || 10;
	this.hp   = hp || 10;
};

Character.prototype.clone = function () {
	// Return a new instance containing our own data.
	return new Character(
		this.name,
		this.race,
		this.st,
		this.dx,
		this.iq,
		this.ht,
		this.hp
	);
};

Character.prototype.toJSON = function () {
	// Return a code string that will create a new instance containing our
	// own data.
	return Serial.createReviver(String.format(
		'new Character({0},{1},{2},{3},{4},{5},{6})',
		JSON.stringify(this.name),
		JSON.stringify(this.race),
		JSON.stringify(this.st),
		JSON.stringify(this.dx),
		JSON.stringify(this.iq),
		JSON.stringify(this.ht),
		JSON.stringify(this.hp)
	));
};

Creating a new instance of this Character example would be something like:

<<set $Joe to new Character(
	'Joe the Barbarian',
	'human',
	20,
	12,
	9,
	18,
	18
)>>

 Guide: Tips

This is a collection of tips, from how-tos to best practices.

Suggestions for new entries may be submitted by creating a new issue at SugarCube's source code repository.

 Arbitrarily long return

Warning: Navigating back to a previous passage, for whatever reason, can be problematic. There's no way for the system to know ahead of time whether it's safe to re-execute a passage's contents. Even if it did know that, there's no way for it to know which operations may or may not have side-effects—e.g., changing variables. Thus, if you allow players to return to passages, then you should either: ensure the passages contain no code that has side-effects or wrap that code in something to prevent re-execution—e.g., <<if visited() is 1>>side-effects<</if>>.

Note: An alternative to navigating to passages to create menus, inventories, and the like would be to use the Dialog API.

When you have a situation where you're using a set of passages as some kind of menu/inventory/etc and it's possible for the player to interact with several of those passages, or even simply the same one multiple times, then returning them to the passage they were at before entering the menu can be problematic as they're possibly several passages removed from that originating passage—thus, the <<return>> macro and link constructs like [[Return|previous()]] will not work.

The most common way to resolve this arbitrarily long return issue is to use a bit of JavaScript to record the last non-menu passage the player visited into a story variable and then to create a link with that.

For instance, you may use one of the following examples—they both do the same thing—to record the last non-menu passage into the $return story variable.

Via JavaScript (Twine 2: the Story JavaScript, Twine 1/Twee: a script-tagged passage)

$(document).on(':passagestart', function (ev) {
	if (!ev.passage.tags.includes('noreturn')) {
		State.variables.return = ev.passage.name;
	}
});

Via macros (best used in the PassageReady special passage)

<<if not tags().includes("noreturn")>>
	<<set $return to passage()>>
<</if>>

You'll need to tag each and every one of your menu passages with noreturn—you may use any tag you wish (e.g., menu, inventory), just ensure you change the name in the code if you decide upon another. If necessary, you may also use multiple tags by switching from <Array>.includes() to <Array>.includesAny() in whichever of the above examples you choose to use.

In your menu passages, your long return links will simply reference the $return story variable, like so:

→ Using link markup
[[Return|$return]]

→ Using <<link>> macro (separate argument form)
<<link "Return" $return>><</link>>

Warning (Twine 2): Due to how the Twine 2 automatic passage creation feature currently works, using the link markup form will cause a passage named $return 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—as shown above.

 Guide: Media Passages

Media passages are simply a way to embed media into your project—specially tagged passages that contain the data URI of a Base64-encoded media source. Audio, image, video, and VTT passages are supported.

For example, the following is the data URI of a Base64-encoded PNG image of a red dot (Red dot):

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHE
lEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==

History:

 Creation

Generally, it's expected that you will use a compiler that supports the automatic creation of media passages, however, they may be created manually.

Automatically

Compilers supporting automatic creation of media passages:

Manually

Warning (Twine 2): Due to various limitations in its design, if you're using Twine 2 as your IDE/compiler, then it is strongly recommended that you do not create more than a few media passages and definitely do not use large sources.

To manually create a media passage:

  1. Create a new passage, which will only be used as a media passage—one per media source.
  2. Tag it with the appropriate media passage special tag, and only that tag—see below.
  3. Paste in the Base64-encoded media source as the passage's content.

See the MDN article Media formats for HTML audio and video for more information on formats commonly supported in browsers—pay special attention to the Browser compatibility section.

Media passage special tags

Note: As with all special tags, media passage tags are case sensitive, so their spelling and capitalization must be exactly as shown.

Passage type Tag
Audio passage Twine.audio
Image passage Twine.image
Video passage Twine.video
VTT passage Twine.vtt

 Guide: Icon Font

This guide is a reference to the icon font used by SugarCube, sc-icons, which is a subset of Font Awesome Free 6.7.2.

Font Awesome Free 6.7.2 by @fontawesome - https://fontawesome.com
License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License)
Copyright 2024 Fonticons, Inc.

 Icon Styling

The following CSS properties should be used with any icon style rule.

cursor: pointer;
display: inline-block;
font-family: sc-icons !important;
font-size: 1em;
font-style: normal;
font-variant: normal;
font-weight: 900;
line-height: 1;
speak: never;
text-decoration: none;
text-rendering: auto;
text-transform: none;
user-select: none;
/* vendor-prefixed properties */
-moz-osx-font-smoothing: grayscale;
-webkit-font-smoothing: antialiased;

 Icon Reference

Each icon's hexadecimal reference ID is listed below it. How to use the reference IDs varies based on where you're using them.

e0b7
e2ca
e447
e490
e68f
f002
f004
f005
f007
f00c
f00d
f00e
f010
f011
f013
f015
f019
f01e
f021
f023
f026
f027
f028
f02b
f02c
f02e
f031
f032
f033
f034
f035
f036
f037
f038
f039
f03a
f03b
f03c
f03d
f03e
f042
f047
f048
f049
f04a
f04b
f04c
f04d
f04e
f050
f051
f052
f053
f054
f055
f056
f057
f058
f059
f05a
f05e
f060
f061
f062
f063
f065
f066
f067
f068
f06a
f06e
f070
f071
f074
f076
f077
f078
f079
f07d
f07e
f089
f08b
f08d
f08e
f090
f093
f09c
f09e
f0a0
f0a8
f0a9
f0aa
f0ab
f0ad
f0b2
f0c1
f0c2
f0c4
f0c5
f0c7
f0c9
f0ca
f0cb
f0cc
f0cd
f0d0
f0d7
f0d8
f0d9
f0da
f0dc
f0dd
f0de
f0e2
f0e7
f0ea
f0eb
f0ec
f0ed
f0ee
f0f3
f0fe
f100
f101
f102
f103
f104
f105
f106
f107
f10d
f10e
f110
f120
f121
f125
f127
f12b
f12c
f130
f131
f135
f137
f138
f139
f13a
f13e
f141
f142
f143
f144
f146
f148
f149
f14a
f14c
f150
f151
f152
f15d
f15e
f160
f161
f162
f163
f164
f165
f175
f176
f177
f178
f185
f186
f188
f191
f192
f1ab
f1c0
f1dc
f1dd
f1de
f1e0
f1f6
f1f8
f1fb
f204
f205
f20a
f240
f241
f242
f243
f244
f245
f246
f249
f24d
f28b
f28d
f29e
f2a2
f2a4
f2a8
f2d0
f2d1
f2d2
f2d3
f2ea
f2ed
f2f1
f2f5
f2f6
f2f9
f304
f309
f30a
f30b
f30c
f31e
f337
f338
f358
f359
f35a
f35b
f35d
f360
f362
f363
f3be
f3bf
f3c1
f3e0
f410
f422
f424
f4e2
f522
f534
f53f
f54a
f55a
f565
f56d
f56e
f56f
f574
f58f
f590
f5c0
f6a9
f715
f78c
f7a4
f7a5
f7a9
f7d9
f829
f82a
f84c
f850
f853
f87d
f881
f882
f884
f885
f886
f887
f891

 Guide: Harlowe to SugarCube

There are many differences between Harlowe and SugarCube, this guide will document some of the most critical you will need to account for if you're coming to SugarCube from a background in Harlowe.

 Macro Overview

Aside from general syntax, SugarCube macros do not use hooks, separate arguments differently, and don't allow other macros to be passed as arguments.

Macro Arguments

Like in Harlowe, some SugarCube macros accept expressions and others accept discreet arguments. In SugarCube, discreet arguments passed to a macro are separated by spaces instead of commas. To pass expressions or the results of functions to macros as an argument, you must wrap the expression in backquotes (`).

Additionally, macros in SugarCube do not return values, so macros cannot be used as arguments to other macros. SugarCube provides a variety of functions and methods that may be used instead, and standard JavaScript functions and methods may also be used.

Consider the following Harlowe code:

(link-goto: "Go somewhere else", (either: "this passage", "that passage", "the other passage"))

A version of the above code in SugarCube might look like this:

<<link "Go somewhere else" `either("this passage", "that passage", "the other passage")`>><</link>>

See: Macro Arguments.

Container Macros

Where Harlowe uses its hook syntax (square brackets) to associate a macro with its contents, SugarCube instead uses "container" macros—macros that can have content associated with them have opening and closing tags.

Consider the following Harlowe code:

(if: $var is 1)[
	The variable is 1.
]

In SugarCube, you instead open and close the <<if>> macro itself:

<<if $var is 1>>
	The variable is 1.
<</if>>

 Specific Macros

Some macros in Harlowe and SugarCube share a name but work a bit differently. We'll cover some of these differences below.

Link and Click Macros

SugarCube does not have any equivalents to Harlowe's (click:) family of macros. Additionally, SugarCube's normal <<link>> macro does not have an output element associated with it and is not, by default, a single-use link like its Harlowe equivalent. Both of these features can be constructed in SugarCube, however, using macros like <<linkreplace>> or by combining <<link>> macros with DOM macros. Additionally, SugarCube's link macro accepts a passage argument, that, if included, turns any <<link>> into something similar to Harlowe's (link-goto:) macro.

Consider the following Harlowe link macros:

(link: "Hey there.")[Hay is for horses.]
(link-repeat: "Get some money")[(set: $cash to it + 1)]
(link-goto: "Move on", "next passage")

The equivalent SugarCube code for each link might look something like this:

<<linkreplace "Hey there.">>Hay is for horses.<</linkreplace>>
<<link "Get some money">><<set $cash += 1>><</link>>
<<link "Move on" "next passage">><</link>>

SugarCube's <<link>> and <<button>> macros can also accept the link markup as an argument:

<<link [[Move on|next passage]]>><</link>>

DOM Macros

Note: Harlowe refers to these as "revision macros".

SugarCube's DOM macros can target any HTML element on the page, not just hooks, and unlike their Harlowe equivalents, they cannot target arbitrary strings. You can use custom style markup or HTML to create the elements, and then target them with a query selector.

Consider the following Harlowe code:

(set: _greetings to (a: "hi", "hello", "good day", "greetings"))\
The man says, "|target>[(either: ..._greetings)]."

{
(link-repeat: "Change")[
	(replace: ?target)[(either: ..._greetings)]
]
}

The equivalent SugarCube code to achieve a similar result would be:

<<set _greetings to ["hi", "hello", "good day", "greetings"]>>\
The man says, "@@#target;<<= _greetings.random()>>@@."

<<link "Change">>
	<<replace "#target">><<= _greetings.random()>><</replace>>
<</link>>

Note: The DOM macros do have a limitation that you should familiarize yourself with.

The Goto Macro

Harlowe's implementation of the (goto:) macro terminates the rendering passage. In SugarCube, the passage is not terminated, and anything in the code below the <<goto>> macro will have side effects.

Consider this Harlowe code:

:: some passage
(set: $count to 0)
(goto: "next")
(set: $count to it + 1)

:: next
$count <!-- 0 -->

In the above, the second (set:) macro is never run, and the $count variable remains at 0.

The equivalent SugarCube code works a bit differently:

:: some passage
<<set $count to 0>>
<<goto "next">>
<<set $count += 1>>

:: next
$count /* 1 */

SugarCube does not terminate the parsing of the calling passage, so some care is required when calling <<goto>>.

As with <<link>> and <<button>>, <<goto>> can accept link markup as its argument:

<<goto [[next]]>>

 User Input

SugarCube's user input macros, like <<textbox>>, cannot be nested inside a <<set>> macro, as you might do with a (prompt:) and a (set:) in Harlowe. Instead, the macro is passed a receiver variable which is set to the value input by the user.

For example, if you wanted to ask the user to enter a name, your code may look like this in Harlowe:

(set: $name to (prompt: "What is your name?", "Frank"))

In SugarCube, you would likely want to use the <<textbox>> macro instead, and pass $name in as the receiving variable:

<label>What is your name? <<textbox "$name" "Frank">></label>

Harlowe's newer input macros, like (dropdown:) and (cycling-link:) use "bound" variables, which are similar in concept to SugarCube's receiver variables.

 Data Types

Harlowe's implementation of data types differs significantly from SugarCube's. A data type refers to the "type" of data a variable is holding, such as a number, a string, an array, or anything else. Harlowe has stricter typing than SugarCube, requiring authors to call macros like (str:) or (num:) on variables to change their type. SugarCube, like JavaScript, uses dynamic typing.

Dynamic Typing

SugarCube, like JavaScript, will try to make sense of expressions passed to it by coercing their values if necessary:

<<set $number to 1>>
<<set $string to "2">>
<<= $string + $number>> /* "21" */

In the above case, since the string value "2" cannot be added to a number value, the number value is coerced into a string, and the two strings are then concatenated. In Harlowe, the same operation will yield an error:

(set: $number to 1)
(set: $string to "2")
(print: $string + $number) <!-- error! -->

You must convert the values to the same type in Harlowe. In SugarCube you can convert them if you need to.

In Harlowe:

(set: $number to 1)
(set: $string to "2")
(print: $string + $number) <!-- error! -->
(print: $string + (str: $number)) <!-- "21" -->
(print: (num: $string) + $number) <!-- 3 -->

In SugarCube:

<<set $number to 1>>
<<set $string to "2">>
<<= $string + $number>> /* "21" */
<<= $string + String($number)>> /* "21" */
<<= Number($string) + $number>> /* 3 */

Arrays, Datamaps, and Datasets

Harlowe's arrays, datamaps, and datasets are functionally similar to JavaScript Arrays, Maps, and Sets, but with a few key differences. SugarCube requires authors to define and work with these data types using the standard JavaScript methods rather than providing macros for them.

Using an array in Harlowe:

(set: $array to (a:))
(set: $array to it + (a: "something"))
(if: $array contains "something")[…]

In SugarCube:

<<set $array to []>>
<<run $array.push("something")>>
<<if $array.includes("something")>>…<</if>>

Using a datamap in Harlowe:

(set: $map to (dm: "key", "value"))
(set: $map's key to "another value")
(if: $map contains key)[…]

In SugarCube:

<<set $map to new Map([["key", "value"]])>>
<<run $map.set("key", "another value")>>
<<if $map.has("key")>>…<</if>>

SugarCube also allows the use of JavaScript generic objects, which may be better in some situations than a map:

<<set $object to { key : "value" }>>
<<set $object.key to "another value">>
<<if $object.hasOwnProperty("key")>>…<</if>>

Another important difference in the way Harlowe handles its non-primitive data types like arrays, datamaps, and datasets is that they are passed by value rather than passed by reference.

Consider the following Harlowe code:

(set: $player to (dm: "hp", 100, "mp", 50))
(set: $partyMember to $player)
(set: $partyMember's hp to it - 50)
(print: $player's hp) <!-- 100 -->
(print: $partyMember's hp) <!-- 50 -->

As you can see, Harlowe creates a deep copy/clone of its non-primitive data types each time they're modified.

In SugarCube, both variables would still point to the same underlying object—at least initially (see below):

<<set $player to { hp : 100, mp : 50 }>>
<<set $partyMember to $player>>
<<set $partyMember.hp -= 50>>
$player.hp /* 50 */
$partyMember.hp /* 50 */

SugarCube does eventually clone its non-primitive data types as well, but does at the start of passage navigation, rather than each time they're modified.

 Guide: Test Mode

History:

 Introduction

In test mode, SugarCube will wrap all macros, and some non-macro markup—e.g., link & image markup—within additional HTML elements, called "debug views" ("views" for short). Views make their associated code visible, thus providing onscreen feedback—they may also be hovered over which, generally, exposes additional information about the underlying code.

Warning: Because of the additional HTML elements added by the debug views, some nested markup and selectors may be broken. This only affects test mode.

Tip: In versions of SugarCube ≥v2.23.0, the debugging interface offers additional tools, namely variable watches and arbitrary history navigation.

 Enabling Test Mode

Automatically

In Tweego

To enable test mode, use the test option (-t, --test).

In Twine 2 (≥v2.2)

To enable test mode from the Stories screen, click on the story's gear menu and select the Test Story menu item.

To enable test mode from the story editor/map screen, click on the Test menu item (right side of the bottom bar).

To enable test mode from the story editor/map screen while starting at a specific passage, hover over a passage and select the menu item.

In Twine 2 (<v2.2)

To enable test mode from the Stories screen, click on the story's gear menu and select the Test Play menu item.

To enable test mode from the story editor/map screen, click on the Test menu item (right side of the bottom bar).

To enable test mode from the story editor/map screen while starting at a specific passage, hover over a passage and select the menu item.

In Twine 1

To enable test mode while starting at a specific passage, right-click on a passage and select the Test Play From Here context menu item.

Note: Unfortunately, due to limitations in the current release of Twine 1, the Build menu's Test Play menu item is not able to trigger test mode. You may, however, simply use the Test Play From Here context menu item on the Start passage to achieve the same result.

Manually

You may forcibly enable test mode manually by setting the Config object's debug property to true. For example:

Config.debug = true; // forcibly enable test mode

See: The Config.debug setting for more information.

 Debug Bar (≥v2.23.0)

The debug bar (bottom right corner of the page) allows you to: watch the values of story and temporary variables, toggle the debug views, and jump to any moment/turn within the history.

The variable watch panel may be toggled via the Watch  button. To add a watch for a variable, type its name into the Add field and then either press enter/return or click the button—n.b. depending on the age of your browser, you may also see a list of all current variables when interacting with the Add field. To delete a watch, click the button next to its name in the watch panel. To add watches for all current variables, click the button. To delete all current watches, click the button.

The debug views may be toggled via the Views  button.

To jump to any moment/turn within the available history, select the moment/turn from the Turn select field.

 Debug Views (≤v2.22.0)

The debug views themselves may be toggled on and off (default: on) via the Debug View button (top of the UI bar).

If you've removed/hidden the UI bar, a construct like the following will allow you to toggle the views on and off:

<<button "Toggle Debug Views">><<script>>DebugView.toggle()<</script>><</button>>

Note: That will only toggles the views, test mode must still be enabled first.

 Guide: TypeScript

TypeScript bindings for SugarCube APIs can found as the Definitely Typed package: @types/twine-sugarcube.

To install the package via NPM, use the following command:

npm install --save-dev @types/twine-sugarcube

 Guide: Installation

This is a reference on how to install SugarCube in Tweego, Twine 2, and Twine 1/Twee.

Note (Twine 2): Newer versions of Twine 2 come bundled with a version of SugarCube v2, so you only need to read these instructions if you want to install a newer version of SugarCube v2 than is bundled or a non-standard release.

 Local Install For Tweego

See Tweego's documentation for more information.

 Local Install For Twine 2

There are two primary branches of Twine 2 as far as SugarCube is concerned:

Regardless of the version of Twine 2 you're using, follow these instructions to install a local copy of SugarCube v2:

  1. Download the current version of SugarCube v2 for Twine 2—comes as a ZIP archive. NOTE: There are separate downloads for Twine ≥2.1 and Twine 2.0, so you must ensure that you download the one that matches your version of Twine 2 or you will likely run into issues.
  2. Extract the archive to a safe location on your computer and make note of the path to it. Make sure to keep the files together if you move them out of the included directory.
  3. Launch Twine 2.
  4. Click on the Formats link in the Twine 2 sidebar.
  5. In the dialog that opens, click on the Add a New Format tab.
  6. Finally, paste a file URL to the format.js file, based upon the path from step #2, into the textbox and click the +Add button (see below for examples).

UNIX (and similar) file URL examples

Note: If constructing the file URL from a shell path, ensure that either it does not contain escapes or you properly convert them into the correct URL percent-encoded form.

If the full path to the contents of the archive is something like:

/home/soandso/Twine/StoryFormats/SugarCube-2/format.js

Then the file URL to it would be:

file:///home/soandso/Twine/StoryFormats/SugarCube-2/format.js

Windows file URL examples

If the full path to the contents of the archive is something like:

C:\Users\soandso\Documents\Twine\StoryFormats\SugarCube-2\format.js

Then the file URL to it would be (note the changed slashes):

file:///C:/Users/soandso/Documents/Twine/StoryFormats/SugarCube-2/format.js

 Online Install For Twine 2

The online SugarCube install, delivered by the jsDelivr CDN, supports only versions of Twine 2 ≥2.1.

Copy the following URL and paste it into the Add a New Format tab of the Formats menu, from Twine 2's sidebar.

URL: https://cdn.jsdelivr.net/gh/tmedwards/sugarcube-2/dist/format.js

 Local Install For Twine 1/Twee

Follow these instructions to install a local copy of SugarCube v2:

  1. Download the current version of SugarCube v2 for Twine 1/Twee—comes as a ZIP archive.
  2. Go to your Twine 1/Twee installation directory and open the targets directory within.
  3. Move the downloaded archive into the targets directory and extract it, included directory and all.

If you followed the steps correctly, within Twine 1/Twee's targets directory you should now have a sugarcube-2 directory, which contains several files—e.g., header.html, sugarcube-2.py, etc.

Warning (Twine 1):

Due to a flaw in the current release of Twine 1/Twee (v1.4.2), if you rename the directory included in the archive (or simply copy its contents to your current SugarCube v2 install), then you must ensure that the file with the extension .py (the story format's custom Twine 1 Header class file) within is named the same as the directory—i.e., the name of the directory and .py file must match.

For example, if the name of SugarCube's directory is sugarcube, then the name of the .py file within must be sugarcube.py. Similarly, if the directory is sugarcube-2, then the name of the .py file within must be sugarcube-2.py. Etc.

The directory and .py file names within the archive available for download are already properly matched—as sugarcube-2 and sugarcube-2.py—and to avoid issues it recommended that you simply do not rename them.

 Guide: Code Updates

This is a reference on how to update existing SugarCube code to work with newer versions of SugarCube.

Note: The majority of newer SugarCube versions do not have any changes that would require an update. For those versions that do, the updates are normally completely elective and may be addressed at your leisure, or not at all. Sometimes there are breaking changes, however, and these must be addressed immediately.

 Updating to any version ≥2.37.0 from a lesser version

Warning: Some changes within this version are breaking changes that you must address immediately, while others are elective changes that you may address at your leisure. All breaking changes will be so noted.

Note: The removals herein are of features that have been deprecated for years. Most are v1 compatibility APIs that have always been deprecated in v2. Nothing of value has been lost.

Deprecated legacy APIs

API Change
browser BREAKING: This deprecated legacy API has been removed. Its replacement is Browser.
config BREAKING: This deprecated legacy API has been removed. Its replacement is Config.
has BREAKING: This deprecated legacy API has been removed. Its replacement is Has.
History BREAKING: This deprecated legacy API has been removed. Its replacement is State.
state BREAKING: This deprecated legacy API has been removed. Its replacement is State.
tale BREAKING: This deprecated legacy API has been removed. Its replacement is Story.
TempVariables BREAKING: This deprecated legacy API has been removed. Its replacement is State.temporary.

Array API

Method Change
Array.random() BREAKING: This deprecated static method has been removed. See the <Array>.random() instance method.
<Array>.contains() BREAKING: The polyfill for this instance method has been removed. See the <Array>.includes() instance method.
<Array>.containsAll() BREAKING: This instance method has been removed. See the <Array>.includesAll() instance method.
<Array>.containsAny() BREAKING: This instance method has been removed. See the <Array>.includesAny() instance method.
<Array>.flatten() BREAKING: This instance method has been removed. See the <Array>.flat() instance method while providing a depth parameter of Infinity.

Config API

Setting Change
Config.macros.ifAssignError This setting has been deprecated and should no longer be used. See the Config.enableOptionalDebugging setting for its replacement.
Config.passages.descriptions This setting has been deprecated and should no longer be used. See the Config.saves.descriptions setting for its replacement.
Config.saves.autoload 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.
Config.saves.autosave 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.
Config.saves.isAllowed This setting, to which you assign a function, has had the parameters provided to the assigned function changed. See its documentation entry for details.
Config.saves.slots This setting has been deprecated and should no longer be used. See the Config.saves.maxSlotSaves setting for its replacement.
Config.saves.tryDiskOnMobile This setting has been deprecated and should no longer be used. Saving to disk on mobile devices is now unconditionally enabled.

Dialog API

Method Change
Dialog.addClickHandler() BREAKING: This deprecated static method has been removed.
Dialog.setup() This static method has been deprecated in favor of the Dialog.create() static method.

JSON API

Method Change
JSON.reviveWrapper() This static method has been deprecated in favor of the Serial.createReviver() static method.

Macro library

Macro Change
<<actions>> This macro has been deprecated.
<<choice>> This macro has been deprecated.
<<click>> BREAKING: This deprecated macro has been removed. See the <<link>> macro.
<<display>> BREAKING: This deprecated macro has been removed. See the <<include>> macro.
<<forget>> BREAKING: This deprecated macro has been removed. See the forget() function.
<<remember>> BREAKING: This deprecated macro has been removed. See the memorize() and recall() functions.
<<setplaylist>> BREAKING: This deprecated macro has been removed. See the <<createplaylist>> macro.
<<stopallaudio>> BREAKING: This deprecated macro has been removed. See the <<masteraudio>> macro.

MacroContext API

Member Change
<MacroContext>.contextHas() This instance method has been deprecated in favor of the <MacroContext>.contextSome() instance method.
<MacroContext>.contextSelect() This instance method has been deprecated in favor of the <MacroContext>.contextFind() instance method.
<MacroContext>.contextSelectAll() This instance method has been deprecated in favor of the <MacroContext>.contextFilter() instance method.

Number API

Method Change
<Number>.clamp() This instance method has been deprecated. See the Math.clamp() static method.

Passage API

Member Change
<Passage>.domId This instance property has been deprecated in favor of the <Passage>.id instance property.
<Passage>.title This instance property has been deprecated in favor of the <Passage>.name instance property.
<Passage>.description() This instance method has been deprecated.

Save API

Method Change
Save.get() BREAKING: This static method has been removed. See the Save.browser.auto.entries() and Save.browser.slot.entries() static methods for its closest replacements.
Save.clear() This static method has been deprecated in favor of the Save.browser.clear() static method.
Save.ok() This static method has been deprecated in favor of the Save.browser.isEnabled() static method.
Save.autosave.delete() This static method has been deprecated in favor of the Save.browser.auto.delete() static method.
Save.autosave.get() This static method has been deprecated in favor of the Save.browser.auto.get() static method.
Save.autosave.has() This static method has been deprecated in favor of the Save.browser.auto.has() static method.
Save.autosave.load() This static method has been deprecated in favor of the Save.browser.auto.load() static method.
Save.autosave.ok() This static method has been deprecated in favor of the Save.browser.auto.isEnabled() static method.
Save.autosave.save() This static method has been deprecated in favor of the Save.browser.auto.save() static method.
Save.slots.length This static property has been deprecated in favor of the Config.saves.maxSlotSaves setting.
Save.slots.count() This static method has been deprecated in favor of the Save.browser.slot.size static getter.
Save.slots.delete() This static method has been deprecated in favor of the Save.browser.slot.delete() static method.
Save.slots.get() This static method has been deprecated in favor of the Save.browser.slot.get() static method.
Save.slots.has() This static method has been deprecated in favor of the Save.browser.slot.has() static method.
Save.slots.isEmpty() This static method has been deprecated in favor of the Save.browser.slot.size static getter.
Save.slots.load() This static method has been deprecated in favor of the Save.browser.slot.load() static method.
Save.slots.ok() This static method has been deprecated in favor of the Save.browser.slot.isEnabled() static method.
Save.slots.save() This static method has been deprecated in favor of the Save.browser.slot.save() static method.
Save.export() This static method has been deprecated in favor of the Save.disk.save() static method.
Save.import() This static method has been deprecated in favor of the Save.disk.load() static method.
Save.deserialize() This static method has been deprecated in favor of the Save.base64.load() static method.
Save.serialize() This static method has been deprecated in favor of the Save.base64.save() static method.

Scripting API

Method Change
Scripting.desugar() BREAKING: The undocumented is not to isnot operator mapping has been removed.
Scripting.parse() This static method has been deprecated in favor of the Scripting.desugar() static method.

State API

Method Change
State.backward() BREAKING: This deprecated static method has been removed.
State.display() BREAKING: This deprecated static method has been removed.
State.forward() BREAKING: This deprecated static method has been removed.
State.initPRNG() BREAKING: This deprecated static method has been removed.
State.play() BREAKING: This deprecated static method has been removed.
State.restart() BREAKING: This deprecated static method has been removed.
State.show() BREAKING: This deprecated static method has been removed.

Story API

Member Change
Story.domId This static property has been deprecated in favor of the Story.id static property.
Story.title This static property has been deprecated in favor of the Story.name static property.

StoryInterface special passage

POSSIBLY BREAKING: The default UI's <div id="story" role="main"> container has been made a core part of the base UI, for both native and custom end user markup. As a consequence, this means that the custom markup generated by using the StoryInterface special passage may no longer itself contain a #story element and will be added to the core #story container, rather than <body>.

An example of the new hierarchy: 

<body>
	<div id="story" role="main">
		<!-- StoryInterface elements added here -->
	</div>
</body>

It is strongly recommended that you review your selectors related to the generated markup, both for DOM manipulation and CSS styling, to ensure that they're still functional. Primarily this will affect selectors that use the child combinator (>) with a body parent—e.g., body > … where … is one the elements within your custom markup.

This change was required to fix a bug related to the interaction between open dialogs and <body>.

String API

Method Change
<String>.readBracketedList() BREAKING: This deprecated instance method has been removed.

UI API

Method Change
UI.buildAutoload() This static method has been deprecated.
UI.addClickHandler() BREAKING: This deprecated static method has been removed.
UI.body() BREAKING: This deprecated static method has been removed.
UI.close() BREAKING: This deprecated static method has been removed.
UI.isOpen() BREAKING: This deprecated static method has been removed.
UI.open() BREAKING: This deprecated static method has been removed.
UI.resize() BREAKING: This deprecated static method has been removed.
UI.setStoryElements() BREAKING: This deprecated static method has been removed.
UI.setup() BREAKING: This deprecated static method has been removed.
UI.stow() BREAKING: This deprecated static method has been removed.
UI.unstow() BREAKING: This deprecated static method has been removed.

UIBar toggle and history button markup & styles

The icons of the UI bar history control buttons have been changed from being text content in their markup to a part of their styles, as with most native SugarCube icon bearing buttons.

The styles of the UI bar toggle and history control buttons have been simplified. If you've customized the styling of any of these buttons, then it is strongly recommended that you review the ui-bar.css file for exact details.

 Updating to any version ≥2.36.0 from a lesser version

All changes within this version are elective changes that you may address at your leisure.

Config API

Property Change
Config.history.maxStates This setting property has been updated to disallow unlimited states.
Config.saves.onLoad This setting property has been deprecated in favor of the Save Events API, specifically the Save.onLoad.add static method.
Config.saves.onSave This setting property has been deprecated in favor of the Save Events API, specifically the Save.onSave.add static method.

Macro library

Macro Change
<<widget>> The special $args story variable has been deprecated in favor of the _args_ temporary variable.

 Updating to any version ≥2.31.0 from a lesser version

Warning: All changes within this version are breaking changes that you must address immediately.

Parser library

Parser Change
HTML tag The parser has been updated to disallow use of the evaluation attribute directive on the data-setter content attribute. They were never supposed to be combined.

 Updating to any version ≥2.30.0 from a lesser version

All changes within this version are elective changes that you may address at your leisure.

Config API

Property Change
Config.saves.autosave This setting property has been updated to accept function values and its acceptance of string values has been deprecated. String values will still be accepted for further releases of v2, however, switching to an array is recommended—e.g., the string value "autosave" would become the array ["autosave"]. See the Config.saves.autosave property for more information.

 Updating to any version ≥2.29.0 from a lesser version

All changes within this version are elective changes that you may address at your leisure.

Dialog API

Method Change
Dialog.addClickHandler() This method has been deprecated and should no longer be used. The core of what it does is simply to wrap a call to Dialog.open() within a call to <jQuery>.ariaClick(), which can be done directly and with greater flexibility.

Macro library

Macro Change
<<track>> (of: <<createplaylist>>) The <<createplaylist>> macro's <<track>> child macro has had its copy keyword deprecated in favor of own. See the <<createplaylist>> macro for more information.
<<forget>> The <<forget>> macro has been deprecated in favor of the forget() function.
<<remember>> The <<remember>> macro has been deprecated in favor of the memorize() and recall() functions.

Method library

Method Change
<Array>.flatten() This method has been deprecated in favor of the <Array>.flat() method.

State API

Method Change
State.initPRNG() This method has been deprecated in favor of the State.prng.init() method.

 Updating to any version ≥2.28.0 from a lesser version

All changes within this version are elective changes that you may address at your leisure.

Macro library

Macro Change
<<cacheaudio>> The <<cacheaudio>> macro's original optional format specifier syntax, format:formatId;…, has been deprecated in favor of the new syntax, formatId|…..

 Updating to any version ≥2.20.0 from a lesser version

All changes within this version are elective changes that you may address at your leisure.

Method library

Method Change
Array.random() This method has been deprecated and should no longer be used. In general, look to the <Array>.random() method instead. If you need a random member from an array-like object or iterable, use the Array.from() method to convert it to an array, then use <Array>.random()—e.g., Array.from(something).random().

 Updating to any version ≥2.15.0 from a lesser version

All changes within this version are elective changes that you may address at your leisure.

Macro library

Macro Change
<<display>> The <<display>> macro has been deprecated in favor of the <<include>> macro.

 Updating to any version ≥2.10.0 from a lesser version

All changes within this version are elective changes that you may address at your leisure.

Method library

Method Change
<Array>.contains() The <Array>.contains() method has been deprecated in favor of the <Array>.includes() method.
<Array>.containsAll() The <Array>.containsAll() method has been deprecated in favor of the <Array>.includesAll() method.
<Array>.containsAny() The <Array>.containsAny() method has been deprecated in favor of the <Array>.includesAny() method.

strings object

The strings API object has been replaced by the l10nStrings object. See the Localization guide for more information.

 Updating to any version ≥2.8.0 from a lesser version

All changes within this version are elective changes that you may address at your leisure.

Macro library

Macro Change
<<click>> The <<click>> macro has been deprecated in favor of the <<link>> macro.
<<playlist>> The <<playlist>> macro has had its argument list changed, for compatibility with <<createplaylist>>. See the <<playlist>> macro for more information.
<<setplaylist>> The <<setplaylist>> macro has been deprecated in favor of the <<createplaylist>> macro.
<<stopallaudio>> The <<stopallaudio>> macro has been deprecated in favor of <<audio ":all" stop>>. See the <<audio>> macro for more information.

 Updating to any version ≥2.5.0 from a lesser version

All changes within this version are elective changes that you may address at your leisure.

config API

The config API has been renamed Config for better consistency with the other APIs.

State API

Several State API methods have moved to the new Engine API. See the Engine API docs for more information.

Old State method New Engine method
State.backward() Engine.backward()
State.display() Engine.display()1
State.forward() Engine.forward()
State.play() Engine.play()
State.restart() Engine.restart()
State.show() Engine.show()
  1. While the Engine.display() static methods exists, it, like State.display() before it, is deprecated. See the Engine.play() static method for the replacement. NOTE: Their parameters differ, so read the description of Engine.play() carefully.

UI API

Several UI API methods have moved to the new Dialog API. See the Dialog API docs for more information.

Old UI method New Dialog method
UI.addClickHandler() Dialog.addClickHandler()
UI.body() Dialog.body()
UI.close() Dialog.close()
UI.isOpen() Dialog.isOpen()
UI.open() Dialog.open()
UI.setup() Dialog.setup()

 Updating to any version ≥2.0.0 from a lesser version

Warning: All changes within this version are breaking changes that you must address immediately.

HTML & CSS

The HTML & CSS have undergone significant changes. See the HTML and CSS docs for more information.

Special passages

Passage Change
MenuOptions The MenuOptions special passage has been removed. See the Options system section for more information.
MenuShare The MenuShare special passage has been removed. See the StoryShare special passage.
MenuStory The MenuStory special passage has been removed. See the StoryMenu special passage.

config object

The config object has been renamed to Config and some of its properties have also changed. See the Config API docs for more information.

Property Change
config.altPassageDescription Changed the config.altPassageDescription property to Config.passages.descriptions.
config.disableHistoryControls Changed the config.disableHistoryControls property to Config.history.controls. This change also inverted the meaning of the property, so take note of that.
config.disableHistoryTracking Replaced the config.disableHistoryTracking property with Config.history.maxStates. The new property works differently, so take note of that.
config.displayPassageTitles Changed the config.displayPassageTitles property to Config.passages.displayTitles.
config.historyMode Removed the config.historyMode property. It's unnecessary since there's now only one history mode in the engine.
config.macros.disableIfAssignmentError Changed the config.macros.disableIfAssignmentError property to Config.macros.ifAssignmentError. This change also inverted the meaning of the property, so take note of that.
config.passageTransitionOut Changed the config.passageTransitionOut property to Config.passages.transitionOut. Additionally, it no longer accepts a boolean value, which has been replaced by the name of the animating property (necessitated by changes to browser handling of transition animations).
config.startPassage Changed the config.startPassage property to Config.passages.start.
config.updatePageElements Changed the config.updatePageElements property to Config.ui.updateStoryElements.

History object & prototype (instance: state)

The History API object has been renamed to State and some of its methods have also changed. Furthermore, it is no longer instantiated into the legacy state object—which still exists, so legacy code will continue to work. See the State API docs for more information.

The State.display() method—formerly state.display()—is no longer overridable, meaning it cannot be wrapped—e.g., the "StoryRegions" 3rd-party add-ons do this. See Navigation Events or Tasks.

Calling the State.prng.init() method—formerly History.initPRNG()—outside of story initialization will now throw an error. It has always been required that the call happen during story initialization, the only change is the throwing of the error.

Seedable pseudo-random number generator (PRNG)

Math.random() is no longer replaced by the integrated seedable PRNG when State.prng.init() is called. See either the built-in functions random() & randomFloat() or the State.random() method, if you need direct access to the PRNG—since it returns a call to either Math.random() or the seedable PRNG, as appropriate.

Macro system

The Macros API object has been renamed to Macro and several of its methods have also changed, for better consistency with the other APIs. Furthermore, it is no longer instantiated into the legacy macros object—which still exists, so SugarCube-compatible legacy macros will continue to work. See the Macro API docs for more information.

Macro library

Macro Change
<<back>> & <<return>> Replaced the ungainly link text syntax—<<back::linktext "…">>/<<return::linktext "…">>—with l10nStrings object properties—l10nStrings.macroBackText and l10nStrings.macroReturnText.
<<if>> & <<elseif>> The <<if>> macro will now, optionally, return an error if the JavaScript = assignment operator is used (default: enabled). Configured via the Config.macros.ifAssignmentError config property.
Options macros The various Options macros have been removed. See the Options system section for more information.

Options system

The entire Options system—MenuOptions special passage, options special variable, and associated macros—has been scrapped for numerous reasons—it was always a hack, required copious amounts of boilerplate code to be useful, etc. It is replaced by the Setting API and settings special variable. See the Setting API docs for more information.

Save system

The SaveSystem API object has been renamed to Save and several of its methods have also changed, for better consistency with the other APIs. See the Save API docs for more information.

UI system

The UISystem API object has been split into two APIs Dialog and UI, and some of its methods have also changed. In particular, the parameter list for the Dialog.setup() method has changed. See the Dialog API and UI API docs for more information.

 Guide: Localization

This is a reference for localizing SugarCube's default UI text, in general, and its l10nStrings object specifically.

Note: If you're simply looking to download ready-to-use localizations, see the locale directory for files in the format xx-YY.js—where xx is the primary code that identifies the language (e.g., en) and YY is the secondary code, in capital letters, that specifies the national variety (e.g., GB or US).

History:

A note about strings vs. l10nStrings

Prior to SugarCube v2.10.0, the strings localization object was named strings. The new l10nStrings object has a simpler, flatter, set of properties and better support for replacement strings. Unfortunately, this means that the two objects are incompatible.

To ensure backwards compatibility of existing strings objects, if one exists within a project's scripts, the older object is mapped to the new l10nStrings object.

 Translation Notes

The capitalization and punctuation used within the default replacement strings is deliberate, especially within the error and warning strings. You would do well to keep your translations similar when possible.

Replacement patterns have the format {NAME}—e.g., {textIdentity}—where NAME is the name of a property within either the l10nStrings object or, in a few cases, an object supplied locally where the string is used—these instances will be commented.

By convention, properties starting with an underscore—e.g., _warningOutroDegraded—are used as templates, only being included within other localized strings. Feel free to add your own if that makes localization easier—e.g., for gender, plurals, and whatnot. As an example, the default replacement strings make use of this to handle various warning intros and outros.

In use, replacement patterns are replaced recursively, so replacement strings may contain patterns whose replacements contain other patterns. Because replacement is recursive, care must be taken to ensure infinite loops are not created—the system will detect an infinite loop and throw an error.

 Usage

Properties on the strings localization object (l10nStrings) should be set within your project's JavaScript section (Twine 2: the Story JavaScript; Twine 1/Twee: a script-tagged passage) to override the defaults.

For the template that should be used as the basis of localizations, see the locale/TEMPLATE.js file @github.com.

Examples

// Changing the project's reported identity to 'story' (default: 'game')
l10nStrings.textIdentity = 'story';

// Changing the text of all dialog OK buttons to 'Eeyup' (default: 'OK')
l10nStrings.ok = 'Eeyup';

// Localizing the title of the Restart dialog (n.b., machine translations)
l10nStrings.restartTitle = 'Neustart';  // German (de)
l10nStrings.restartTitle = 'Reiniciar'; // Spanish (es)