-
Notifications
You must be signed in to change notification settings - Fork 3
SugarCube Basics
New to Programming? Check out JavaScript Fundamentals!
Setting and Updating Variables
Variables let you keep track of things as the story progresses such as health or energy.
SugarCube has two types of variables:
- Story Variables - start with
$(e.g.$health) - Temporary Variables - start with
_(e.g._healthAfterDamage)
To set variables we use the built-in <<set>> macro:
<<set $maxHealth to 100>> <!-- Numbers -->
<<set $name to "John">> <!-- String -->
<<set $awake to false>> <!-- Booleans -->
<<set $health to $maxHealth>> <!-- Assignment -->
<<set $health to $health - 5>> <!-- Subtraction -->
<<set $health to $health + 5>> <!-- Addition -->
<<set $health to $health * 2>> <!-- Multiplication -->
<<set $health to $health % 2>> <!-- Division (Remainder) -->
<<set $health to $health / 2>> <!-- Division (Result) -->
<<set $health to $health ** 2>> <!-- Exponent -->
<<set $health++>> <!-- Increase By One -->
<<set $health-->> <!-- Decrease By One -->
<!-- Advanced Assignments -->
<<set $health to $health ^ 2>> <!-- XOR -->
<!-- Temporary Assignment is the same -->
<<set _healthAfterDamage to $health - 10>>If you're familiar with JavaScript you can use JavaScript notation:
<<set $maxHealth = 100>> <!-- Numbers -->
<<set $name = "John">> <!-- String -->
<<set $awake = false>> <!-- Booleans -->
<<set $health = $maxHealth>> <!-- Assignment -->
<<set $health -= 5>> <!-- Subtraction -->
<<set $health += 5>> <!-- Addition -->
<<set $health *= 2>> <!-- Multiplication -->
<<set $health %= 2>> <!-- Division (Remainder) -->
<<set $health /= 2>> <!-- Division (Result) -->
<<set $health **= 2>> <!-- Exponent -->
<<set $health++>> <!-- Increase By One -->
<<set $health-->> <!-- Decrease By One -->
<!-- Advanced Assignments -->
<<set $health ^= 2>> <!-- Bitwise XOR -->
<<set $health &= 2>> <!-- Bitwise AND -->
<<set $health |= 2>> <!-- Bitwise OR -->
<<set $health <<= 2>> <!-- Left Shift -->
<<set $health >>= 2>> <!-- Right Shift -->
<<set $health >>>= 2>> <!-- Unsigned Right Shift -->
<<set $health &&= 2>> <!-- Logical AND -->
<<set $health ||= 2>> <!-- Logical OR -->
<<set $health ??= 2>> <!-- Logical Nullish -->
<!-- Assignments with Other Variables work too -->
<<set $health /= $maxHealth>>
<<set $health = $maxHealth / 2>>
<!-- Temporary Assignment is the same -->
<<set _healthAfterDamage = $health - 10>>Going forward we will be using JavaScript notation.
Unsetting Variables
Sometimes you want to remove or clear out temporary variables that you've used.
To unset variables we use the built-in <<unset>> macro:
<<unset $health, $maxHealth>> <!-- Unset Multiple Variables -->
<<unset _someTempVar>> <!-- Unset Single Variable -->Printing Variables
Now that we know how to set variables, what about displaying their value?
We call this printing, in SugarCube you can print variables in many different ways.
Using the built-in <<print>> macro:
<<set $health = 95>>
<<set $maxHealth = 100>>
HP: <<print $health>> / <<print $maxHealth>> <!-- HP: 95/100 -->Using the built-in print shorthand <<=>> macro:
<<set $health = 95>>
<<set $maxHealth = 100>>
HP: <<= $health>> / <<= $maxHealth>> <!-- HP: 95/100 -->Have special characters you want encoded?
Use the built-in <<->> macro:
<<set $code = "<p>Hello World!</p>">>
<pre><<- $code>></pre> <!-- <p>Hello World!</p> -->Working with Strings
SugarCube provides some built-in methods for strings that can be of help:
<<set $sentence = "The brown fox jumped over the lazy dog">>
<<set $name = "john">>
<<set $welcomeMessage = "Hello {0}!">>
<<print $sentence.count("z")>> <!-- 1 -->
<<print $sentence.first()>> <!-- T -->
<<print $sentence.last()>> <!-- g -->
<<print $sentence.includes("dog")>> <!-- true -->
<<print String.format($welcomeMessage, $name)>> <!-- Hello john! -->
<<print $name.toUpperFirst()>> <!-- John -->Working with Numbers
To generate random numbers you can use the built-in random method:
<<set $roll = random(1, 6)>> <!-- random between 1, 6 -->SugarCube provides some built-in methods for numbers:
<<set $health = 300>>
<<set $minHealth = 0>>
<<set $maxHealth = 100>>
<<print $health.clamp($minHealth, $maxHealth)>> <!-- 100 -->Working with Objects and Arrays
SugarCube also supports using Objects and Arrays.
To set Objects and Arrays we use the built-in <<set>> macro:
<<set $player = { name: "John", health: 100 }>> <!-- Object -->
<<set $nameChoices = ["John", "David", "Mike"]>> <!-- Array -->We can then access the properties like we would in JavaScript.
So using what we've learned we would be able to use them like so:
Hello <<print $player.name>>! <!-- Hello John! -->
<<set $player.name = $nameChoices[1]>> <!-- Set player name to "David" -->
Hello <<print $player.name>>! <!-- Hello David! -->You can also modify an array by using the built-in <<run>> macro:
<<set $inv = []>> <!-- Create an empty array -->
<<run $inv.push("Map")>> <!-- Add "Map" to our inventory -->
<<run $inv.push("Water")>> <!-- Add "Water" to our inventory -->
<<run $inv.push("Torch")>> <!-- Add "Torch" to our inventory -->
<<run $inv.push("Hat")>> <!-- Add "Hat" to our inventory -->
<<run $inv.push("Key", "Key")>> <!-- Add two "Key"(s) to our inventory -->
<<run $inv.concat(["Sword","Shield"])>> <!-- Add Sword and Shield to our inventory -->
<<print $inv.length>> <!-- 8 -->
<<print $inv.indexOf(1)>> <!-- Water -->
<<print $inv.contains("Map")>> <!-- true (list includes map) -->SugarCube adds a few custom methods to Arrays:
<<print $inv.first()>> <!-- Map -->
<<print $inv.last()>> <!-- Key -->
<<print $inv.random()>> <!-- Random Item -->
<<print $inv.includes("Water")>> <!-- true (list includes water) -->
<<print $inv.includes("Water", 1)>> <!-- true (list includes water at position 0) -->
<<print $inv.pluck()>> <!-- Remove random item and returns the value -->
<<print $inv.pluckMany(2)>> <!-- Remove random item and returns the value -->
<<print $inv.delete("Key")>> <!-- Remove "Key"(s) and returns list of items removed -->This is just scratching the surface. There is much more you can do with Arrays and Objecs!
Displaying Images
Now that we know how to show variables, how do we display images in our story?
Using the built-in Image markup:
[img[media/favicon.png]]We can also make it so that when a user clicks on the image they are taken to another passage (Link):
[img[media/favicon.png][Home]]You can also add a title to the image that shows on hover (Title):
[img[Go Home|media/favicon.png][Home]]And you can update variables when a user clicks on the image (Setter):
[img[Go Home|media/favicon.png][Home][$location = "Home"]]You can optionally use variables for all parts:
<<set $goHomeImage = "media/favicon.png">>
<<set $goHomeText = "Go Home">>
<<set $goHomePassage = "Home">>
<<set $location = "Bathroom">>
[img[$goHomeText|$goHomeImage][$goHomePassage][$location = $goHomePassage]]Using HTML
<img src="media/favicon.png" data-passage="Home" data-setter="$location = 'Home'" />Creating Passages
Passages are denoted by Passage Names that look like:
:: Passage Name
Passage Contentℹ Using SugarCube Starter Kit?
Passages are stored under src/story.
You can create new passages by creating new .twee files and adding passages like displayed in this section.
Navigating Between Passages
You can link to other passages by using the Link Markup:
[[Passage Name]]Example
:: Start
<<set $var to 1>>
Welcome! Check out this other passage:
[[Another Passage]]
:: Another Passage
<<link "Click me!">><<set $var += 1>><</link>>
<<print $var>>
[[Go Home|Start]]
ℹ Using SugarCube Starter Kit?
Passages are stored under src/story.
You can create new passages by creating new .twee files and adding passages like displayed in this section.
Tagging Passages
SugarCube contains special tags that tell SugarCube to do special things with that passage like the [script] tag:
:: SpecialCode [script]
console.log('hello world!')Causes SugarCube to process the passage as a script. Multiple tags are space separated. [widget nobr]
Avoiding Whitespace
By default newlines create whitespace inside passages:
:: Start
Hello
WorldTo avoid this you can use the built-in <<nobr>> macro:
Example
:: Start
<<nobr>>
Hello
World
<</nobr>>This is useful when setting variables up inside passages to be later used to avoid large blocks of whitespace at the top of your passages.
Start building today with the Sugarcube Starter Kit!