#TwineTuesday, Twine Tuesday

#TwineTuesday: Twine 2 Basics (SugarCube)

Note: While I show common macros and markup in the examples below, Thomas Michael Edwards has done a great job documenting the full set of macros and functionality available to SugarCube users.

Table of Contents

 


 

Headers

Just like in the underlining HTML, Twine also supports all five different levels of headers. To create a header, you include the exclamation point (“!”) in front of some selection of text and match the number with the level wanted. For example, a single hash is for <h1> element, but five would be for a <h5> element.

Markup

SugarCube Headers Markup

Result

SugarCube Headers Result

 


 

Text Elements

To mark some selection of text to be emphasis (italicized), bolded, or otherwise set apart requires some special markup symbols in Twine.

Markup

SugarCube Text Elements Markup

Result

SugarCube Text Elements Result

 


 

Bulleted and Numbered items

To have Twine produce bulleted or numbered items, some selection of text needs to have a single asterisk (“*“) before them for top-level and two or more asterisks for indented items. For numbered items, use a hash (“#”) for top-level and two or more hashes for indented items.

Markup

SugarCube Bulleted Markup

Result

SugarCube Bulleted Result

 

 


 

Using the <<set>> macro

The Set Macro is one of the most powerful and common macros found in Twine. In order to save (“set”) some value, the Set Macro is used.

Markup

SugarCube Set Macro

Result

SugarCube Set Macro Result


 

Combining the <<set> and <<if> macros

In most cases of using variables in Twine, you will want to first “set” some value and then, at some later point, conditionally act from testing the value. In Twine, you can combine the Set Macro with an If Macro to test is some condition is “true.” For example, if a value “is” strictly the same as another or if some other comparison results in a “true” statement. (See the extended list of SugarCube comparison keywords for greater detail of what can be used in conditional statements.)

Markup

SugarCube Set and If Macros

Result

SugarCube Set and If Macros Result


 

Using either() and random() functions

In some cases, you will want Twine to choose some value for you. If you want Twine to pick a single value between some fixed, existing set, the Either Macro will work. For those times when you want Twine to pick a random value between two positive numbers, the Random Macro will work.

Markup

SugarCube Either and Random Functions

Result

 

SugarCube Either and Random Functions Result


 

Using a dataset (object literal)

When using the Harlowe Story Format, there is a (dataset: ) macro for directly creating a set of data. SugarCube does not have this layer of abstraction. Instead, it allows you to use JavaScript directly to achieve the same effect of having a container of different data by creating an object literal and adding properties to it as needed.

In the following example, we can replicate the “is in” functionality from Harlowe through adding properties to an object and setting their value to “true”. When adding items to the bag, we set them to “true”; if we need to remove them, we could set their value to “false” (or “undefined”).

Markup

SugarCube Dataset

Result

SugarCube Dataset Result


 

Using a datamap (object literal with properties)

When using the Harlowe Story Format, there is a (datamap: ) macro for directly creating a map of key-value pairs. SugarCube does not have this layer of abstraction. Instead, it allows you to use JavaScript directly to achieve the same effect of having a container of different data by creating an object literal and adding properties to it as needed.

In the following example, we set an object literal to have the properties of “strength”, “wisdom”, and “will” to initial values. Then, we test one of those values and, finally, increase one using a secondary Set Macro statement.

Markup

SugarCube Datamap

Result

SugarCube Datamap Result


 

Using <<print>>

While variables can be used directly in any passage, sometimes you may want Twine to dynamically display some content that contains other markup. For those cases, you can use the Print Macro to have Twine “print” the result of some combination of macro calls, expressions, or JavaScript.

Markup

SugarCube Print Macro

Result

SugarCube Print Macro Result