Twine SugarCube Cheatsheet

Versions
Twine 2.7.0

SugarCube 2.36.1

An all-in-one Twine SugarCube cheatsheet for easy navigation, CTRL + F, and copy-paste,
containing reference links and condensed tips to get interactive functionality and UI/UX started.

This is not an exhaustive list, but rather an overview of some common and useful syntax and
functions, with quick access to various forms of documentation. A few sources of custom macros
are included for ease of access.

Put this together for myself, because making giant lists helps me, but cleaned it up to share in case
anyone else might find it useful.

Websites & Documentation

Twine

Twine Main Site

Twine Reference Guide

Twine Cookbook

SugarCube

SugarCube 2 Main Site

SugarCube 2 Documentation

SugarCube Documentation: CSS

SugarCube Documentation: Built-In CSS Stylesheets

SugarCube Documentation: HTML

SugarCube 2 Source Code Repo on GitHub

Basic Web Design Help

MDN Web Docs

Learn Web Development

HTML

CSS

JavaScript

W3 Schools

HTML

CSS

JavaScript
Quick Code Generators & Templates
HTML-CSS-JS.com

Web Code Tools

CSS Portal

Toptal: Utilities

Twine Interface
Twinery: Story Format - Terms
Twinery: Story Formats - Editor
Twinery: Passages View
Twinery: Passages

All code and macros are meant to be used with the SugarCube story format and will go into one or
more of the following:

the story passages, both special and regular;

the CSS stylesheet;

the Story JavaScript.

Passages
Twinery: Passages View
Twinery: Passages

Special Passages

SugarCube Documentation: Special Names

StoryAuthor

StoryBanner

StoryCaption

StoryDisplayTitle

StoryInit

StoryInterface

StoryMenu

StoryShare

StorySubtitle

Passage Links

SugarCube Documentation: Links

Twinery: Links

Uses wikilinks:

[[This is the text that will appear.|Name Of Passage]]

Formatting

SugarCube Documentation: Markup

SugarCube Documentation: Style
SugarCube Documentation: List
Twinery: Style Markup

Strong and emphasis:

''Bolded text.''
//Italicized text.//

Can use HTML for lists:

<ul>
<li>This is text</li>
<li>in a list.</li></ul>

Headers

SugarCube Documentation: Heading

Markdown with ! instead of hashes:

!This is an H1 header.
!!!!!This is an H5 header.

Positioning

Can use HTML for centering:

<center>This is centered text.</center>

Button Macro

SugarCube Documentation: Interactive Macros

Create a button within one passage that links to another passage:

<<button>>[[Put link text here.|Name Of Passage]]<</button>>

--and example button styling for the stylesheet:

 .passage button {
cursor: pointer;
background-color: rgba(255, 204, 0, 0.3);
border-radius: 5px;
border-style: none;
box-shadow: 0 8px 20px 0 rgba(0,0,0,0.1), 0 6px 20px 0 rgba(0,0,0,0.1);
padding: 20px;
color: var(--body-color);
text-decoration: none;
font-weight: bold; }
.passage button:hover {
border-radius: 6px; }

Timed Macro

SugarCube Documentation: Timed Macro

Insert text after desired number of seconds with a transition:

Your name is <<timed 5s t8n>>gone<</timed>>.

Automatic Forwarding

SugarCube Documentation: Engine API

Send player to another passage automatically:

<<run Engine.play("Name of Passage")>>

--with delay:

<<timed 10s>><<run Engine.play("Name of Passage")>><</timed>>

Textbox Macro

SugarCube Documentation: Textbox

SugarCube Documentation: Variables Macros
Twinery: Setting and Showing Variables

Can be used to enter a variable (see "Narrative Options" below for more on variables):

--no prefill:

Your name is <<textbox "$name" "" "Name Of Passage" autofocus>>.

--prefill:

Your name is <<textbox "$name" "Ashley" autofocus>>.

--and example textbox styling for the stylesheet:

#textbox-player-name {
border-style: inset; }
Creating a textbox that enters a predetermined variable regardless of what is typed:
--see the "Typing Simulation" custom macro.

Fine-Tuning Line Breaks and Whitespace Formatting

SugarCube Documentation: Line Continuation

SugarCube Documentation: Silent Macro
SugarCube Documentation: Nobr Macro
SugarCube Documentation: Config.passages.nobr
SugarCube Documentation: Nobr Special Tag

Various methods to fine-tune the appearance and configuration of line breaks and whitespace
within passages.

Backslashes will remove line breaks:

This is\
an example text.

This is
\example text.

--Both will render like:

This is example text.

The "silently" macro will discard any output between its tags:

<<silently>>/*--- none of this

will appear in the rendered passage ---*/<</silently>>

--Can be used to enclose comments or macros that don't produce any visible output, so as to
format them for readability.

The "nobr" macro will remove line breaks but render output:

<<nobr>>You listen to the

<<if $radio is true>>
radio
<<else>>
silence
<</if>>
<</nobr>>

--Can be used to format macros for readability.

Tag a passage with nobr to configure that passage to render with single line breaks.

Put the "nobr" API within your JavaScript to render all passages with single line breaks by default:

Config.passages.nobr = true;
UI Bar In Passages

SugarCube Documentation: UIBar API

Within passage, stow UI bar + hide UI bar at the same time:

<<run UIBar.stow(true)>> <<run UIBar.hide();>>

--Otherwise, hiding the UI bar still takes up space.

--Place within the StoryInit special passage to automatically stow + hide UI bar on first page.

Within passage, unstow UI bar + show UI bar at the same time:

<<run UIBar.unstow();>> <<run UIBar.show();>>

--to fully restore visibility and space.

UI Bar Menu Passage

Twinery: Left Sidebar

SugarCube Documentation: StoryMenu
SugarCube Documentation: Scripting Macros

Place custom menu items in the StoryMenu special passage:

<<link "SAVES">><<run SugarCube.UI.saves();>><</link>>

<<link "RESTART">><<run SugarCube.UI.restart();>><</link>>
<<link "SETTINGS">><<run SugarCube.UI.settings();>><</link>>
<<link "FULL SCREEN">><<run Fullscreen.toggle();>><</link>>
<a href="https://yoursite.here" target="_blank" rel="noopener noreferrer">RETURN
TO YOUR SITE</a>

--Can include external HTML links.

Images & Audio

Images

SugarCube Documentation: Images

Twinery: Images

To properly load images for playtesting, save the story via "Publish To File" in game's folder, then
open the .html file from the game folder into a browser to see changes.

Place this in the StoryInit special passage:

<<set $imgPath to "./images/">>

--Have an /images folder within your story folder to create the image path.

Place this in any story passage that requires an image:

<span id="image-example">[img[$imgPath + "exampleimage.jpg"]]</span>

--Use the stylesheet to adjust appearance.

Audio

SugarCube Documentation: Audio Macro

Twinery: Audio

To properly load audio for playtesting, save the story via "Publish To File" in game's folder, then
open the .html file from the game folder into a browser to hear changes.

Place this in the StoryInit special passage for each track:

<<cacheaudio "Name Of Track" "audio/Name Of Track.wav">>

--Have an /audio folder within your story folder to create the audio path.

Place this in any story passage that requires audio:

<<audio "carstart" play>>

To loop:

<<audio "static" loop play>>

To pause or stop:

<<audio ":playing" pause>>

<<audio ":all" stop>>
<<audio ":playing" stop>>

To resume:

<<audio ":paused" play>>

To reduce volume:

<<audio "static" volume 0.5 play>>

To play audio only if it is toggled 'on' in the settings:

<<if settings.audioEnabled>><<audio "static1" loop play>><</if>>

JavaScript
UI Bar & Settings

SugarCube Documentation: Setting API

SugarCube Documentation: UI API
SugarCube Documentation: ui-bar.css
SugarCube Documentation: Stow
SugarCube Documentation: Story Interface
Remove UI bar completely:

UIBar.destroy()

--and replace it with a custom UI using the StoryInterface special passage.

Stow UI bar upon initially loading the game:

Config.ui.stowBarInitially = true;

Settings

SugarCube Documentation: Setting API

Add a "settings" button to the UI bar:

Setting.addHeader("Settings");

Change In-Built UI Text

SugarCube Documentation: Localization

SugarCube Localization Template on GitHub

Change text that is built into the UI, for localization purposes or personal preferences:

l10nStrings.savesTitle = "Checkpoints";

l10nStrings.restartTitle = "Redo";

Font Size

SugarCube Documentation: Setting API

Add "font size" options to the UI bar settings:

var settingFontSizeNames = ["Default", "Large"]; /*--- these are the names that
will show up in the settings menu; change or add extra font options here between
"[ ]" ---*/
var settingFontSizeHandler = function () {
var $html = $("html");

$html.removeClass("fontsize-default fontsize-large"); /*--- if adding or

changing extra themes, include or change all "theme-[name]" here ---*/

/*--- copy-paste to add more font sizes; remember to match the cnames in quotes
according to how they appear above and in the stylesheet ---*/
switch (settings.fontsize) {
case "Default":
$html.addClass("fontsize-default");
break; }
switch (settings.fontsize) {
case "Large":
$html.addClass("fontsize-large");
break; } };
 Setting.addList("fontsize", {
label : "Change the font size.", /*--- "change the font size" can be
changed to desired text ---*/
list : settingFontSizeNames,
onInit : settingFontSizeHandler,
onChange : settingFontSizeHandler });

--and set the values in the stylesheet:

html.fontsize-default .passage {
font-size: 0.95em; }

html.fontsize-large .passage {
font-size: 1.2em; }

Audio Toggle

SugarCube Documentation: Setting API

SugarCube Documentation: Add Toggle

Add an audio toggle option to the UI bar settings:

var audioEnabledHandler = function () {

if (!settings.audioEnabled) {
new Wikifier(null, "<<stopallaudio>>"); } };
Setting.addToggle("audioEnabled", {
label : "Toggle audio on/off.", /*--- "toggle audio on/off" can be changed
to desired text ---*/
default : true,
onInit : audioEnabledHandler,
onChange : audioEnabledHandler });

Fullscreen

SugarCube Documentation: Setting API

SugarCube Documentation: Add Toggle

Add a fullscreen toggle to the UI bar settings:

var settingFullscreenHandler = function () {

if (settings.fullscreen) { Fullscreen.request(); }
else { Fullscreen.exit(); } };
Setting.addToggle("fullscreen", {
label : "Toggle fullscreen.", /*--- "toggle fullscreen" can be changed to
desired text ---*/
default : false,
onInit : settingFullscreenHandler,
onChange : settingFullscreenHandler });
Saves

Twinery: Saving Games

SugarCube Documentation: Autosave Config
SugarCube Documentation: OnSave

Set up autosave:

Config.saves.autosave = ["autosave"]; /*--- "autosave" corresponds with passage

tags; can be changed to desired text ---*/

--to automatically save on passages tagged with "autosave" or another desired tag.

Enable and add custom player saves to the UI bar settings:

Save.onSave.add(function (save, details) {

switch (details.type) {
case 'null': { save.title = title;
break; }
default: { var title = prompt("Name your save.", save.title); /*--- "name
your save" can be changed to desired text ---*/
break; } } });

Themes

SugarCube Documentation: Setting API

SugarCube Documentation: Add Toggle

Add theme options to the UI bar:

var settingThemeNames = ["Light", "Dark"]; /*--- these are the names that will
show up in the settings menu; change or add extra theme options here between "[
]" ---*/
var settingThemeHandler = function () {
var $html = $("html");

/*--- make sure to hyphenate in all instances of "theme-[name]"; example: "theme-

dark-mode" ---*/
$html.removeClass("theme-light theme-dark"); /*--- if adding or changing
extra themes, include or change all "theme-[name]" here ---*/

/*--- copy-paste to add more themes; remember to match the cnames in quotes
according to how they appear above and in the stylesheet ---*/
switch (settings.theme) {
case "Light":
$html.addClass("theme-light");
break;
case "Dark":
$html.addClass("theme-dark");
break; } };

Setting.addList("theme", {
label : "Choose a theme.", /*--- "choose a theme" can be changed to
desired text ---*/
list : settingThemeNames,
 onInit : settingThemeHandler,
onChange : settingThemeHandler });

/*--- make sure all theme names across your JavaScript and stylesheet match
exactly ---*

CSS Stylesheet
Themes

To style theme options:

/*--- prepend `html.theme-name` before each element (body { }, img { }, etc),

class (.passage, etc), and ID (#passages, etc) to add theme options ---*/

html.theme-one body {
attributes-here: attribute; }

html.theme-two body {
attributes-here: attribute; }

Use the root selector to standardize colors and styles for ease of editing:

:root {
--title-font: "Garamond", serif;
--body-font: "Arial", sans-serif;
--subtitle-font: "Georgia", serif;
--font-size-regular: 0.95em;
--font-size-title: 2em;
--font-size-subtitle: 1.1em;
--body-color: #f5f5f5;
--accent1: #ffcc00;
--accent2: #cc9900;
--fallback-color: #0f0c00;}

--and use accordingly with the var() function:

/*--- set default font styles ---*/

html.theme-name body {
font-family: var(--body-font);
font-size: var(--font-size-regular); }

/*--- set main text color ---*/

html.theme-name .passage {
color: var(--body-color); }

Background

Gradient background:
 /*--- remove html.theme-name if not using themes; adjust the style of the
gradient (top right, bottom left, 45deg, etc) as desired ---*/
html.theme-name body {
background-attachment: fixed;
background-image: -webkit-linear-gradient(top right, #0f2027, #203a43,
#2c5364);
background-image: linear-gradient(top right, #0f2027, #203a43, #2c5364);
background-color: var(--color-name);

UI Bar CSS Adjustments

SugarCube Documentation: ui-bar.css

Remove the UI bar completely:

#ui-bar {
display: none; }

Remove the "forward" and "back" arrows in the UI bar:

html.theme-name #ui-bar-history {
display: none; }

Responsive Styling For Different Screen Sizes

@media screen and (max-width: 960px) {

.passage { font-size: 90%; }
#passages { width: 70%; } }
@media screen and (max-width: 840px) {
.passage { font-size: 87.5%; }
#passages { width: 80%; } }
@media screen and (max-width: 720px) {
.passage { font-size: 75%; }
#passages { width: 90%; } }

Other Styling

Change list appearance:

ul {
list-style-type: square; }

Narrative Options
Choice Tracking With Conditional Variables

SugarCube Documentation: Variables Macros

SugarCube Documentation: Control Macros
Twinery: Setting and Showing Variables
Twinery: Conditional Statements

Use $ to set variables. Set tracked variables in the StoryInit special passage or relevant story
passage.
If placing within StoryInit , set them as false initially:

<<set $radio to false>>

If placing within a story passage, set them as true when and where the variable option is chosen:

<<set $radio to true>>

Activate the variable to track choices:

[[Turn on the radio.|Static][$radio to true]]

[[Travel in silence.|Silence]]

Show the result of choices with the "if" macro:

<<nobr>>
You listen to the
<<if $radio>>radio
<<else>>silence
<</if>>.
<</nobr>>

Use variables to open potential choices:

/*--- without hidden text ---*/

[[You hear the silence.|Name Of Passage]]

/*--- with hidden text ---*/

<<if $radio is true>>[[You hear the static.|Name Of Passage]]
<<else>>[[You hear the silence.|Name Of Passage]]
<</if>>

If the variable is no longer needed:

<<unset $radio>>

Choice Tracking With Passage Visits

SugarCube Documentation: hasVisited Function

Use passage names and the "if" macro to track visits:

You <<if hasVisited("The Field")>>have been to the field.<</if>>

You <<if not hasVisited("The Field")>>have never been to the field.<</if>>
You <<if hasVisited("The Field", "The River")>>have been to both the field and
the river.<</if>>
You <<if not hasVisited("The Field", "The River")>>have never been to field or
the river.<</if>>
Cycling Options

SugarCube Documentation: Cycling Macro

Reddit: Cycling Links and Accessibility

Click on a link to cycle through and set variables:

<<nobr>>
What is your favorite fruit?
<<cycle "$fruit" autoselect>>
<<option "Strawberries">>
<<option "Apples">
<<option "Grapes">>
<<option "Bananas">>
<</cycle>>.
<</nobr>>

Add screen reader accessibility for cycling links in JavaScript:

Config.cleanupWikifierOutput = true; $(document).on(":passagerender", function

(event) { var clinks = $(event.content).find(".macro-cycle"); if (clinks.length)
{ clinks.attr("aria-label", function (event) { return "(click to change) " +
$(this).text(); }); clinks.on("click", function (evnt) {
$(this).find("p").contents().unwrap(); // Fix SugarCube bug with
<<cycle>>+Config.cleanupWikifierOutput $(this).attr("aria-label", "(click to
change) " + $(this).text()); }); } });

Custom Macros & Sample Code

Usually pasted into the JavaScript section, often accompanied by macros that can then be used
within story passages.

Chapel's Custom Macros

Twinelab / GitHub
Demos: Twinelab

The Fading Macro Set: A simple macro set that causes the text between its tags to fade in or
out over a period of time specified by the user, with an optional delay.

The Event Macro: This macro be used to handle events in your game; things like keyboard
hotkeys, controls, clickable non-link elements, and more. Note that the element the event is
tied to does not need to be rendered (or currently on the page or in the passage) in order to
attach an event to it.

The Continue Macro Set: Used to create basic "press any key" or "click anywhere to continue"
style interactions.

The First Macro: Creates code or text that is shown based on how many times the player has
visited a particular passage.

The Typing Simulation Macro: Creates a text area. When focused, the user's keystrokes
generate a predefined message one letter at a time, simulating typing but ignoring the actual
input. After the message is finished, any text or code between the macro tags is displayed /
run.
Hiev's Sample Code

Patreon / Other

Favicon

Combining Story Passages: Combine multiple linear (non-branching) story passages into a
single passage.

Replace Macro Sample Code: Replace text based on link clicked.

Textbox Plus Widget: Adds additional options for textboxes.

Loading External Scripts: For loading external CSS or JS files.

Cycy's Custom Macros

GitHub

Click To Proceed: Aims to provide an easy way to set up content that is revealed bit-by-bit via
user interaction.

Live Update: Used to show a change in a variable value without a passage transition.

Crossfade: Easy crossfading between images.

More

Hogart on GitHub

Mikewesthad on GitHub

SugarCube Validator on Github: Validates SugarCube games, and finds bugs quickly and
easily.