The 100% Good Twine SugarCube Guide is a coding guide for the SugarCube format of Twine. It is meant as an alternative to the SugarCube documentation, with further explanations, interactive examples, and organised by difficulty. The goal of this guide is to make the learning curve for new SugarCube user less steep, and provide a comprehensive and wide look over the format.
VIEW / DOWNLOAD THE GUIDE!!!!
The Guide is compartmentalised in (currently) four categories:
THE BASICS
or the absolute basics to start with SugarCube.
No need for extra knowledge. Just the base needed to make something.
THE BASICS +
adding interactivity, and creating a fully rounded IF game
May require a bit of CSS knowledge (formatting rules)
INTERMEDIATE MODE
adding more customisation and complex code
Will probably require some CSS knowledge, and maybe some JavaScript
ADVANCE USE
the most complex macros and APIs
Will surely require some JavaScript/jQuery knowledge
Note: The Advanced Use includes all the APIs, macros, and methods not covered by the previous categories. This includes code requiring very advance knowledge of JavaScript/jQuery to be used properly.
Each category explains many aspects of the format, tailored to a specific level of the user. More simpler explanations and examples are available in earlier chapters, compared to the later ones.
If something is unclear, you found a mistake, you would like more examples in the guide, or would like a feature covered, let me know!
The Guide currently covers all macros (as of SugarCube v.2.37.3), all functions and methods, and APIs. It touches upon the use of HTML, CSS, JavaScript and jQuery, when relevant. It also discusses aspects of accessibility.
The Guides also provides a list of further resources, for the different coding languages.
The Guide is available in a downloadable form for offline view:
HTML file that can be opened in Twine
.tw file that can be opened in Twine
source code, separating the chapters, .js and .css files
Twine® is an “an open-source tool for telling interactive, non-linear stories” originally created by Chris Klimas maintained in several different repositories (Twinery.org). Twine is also a registered trademark of the Interactive Fiction Technology Foundation.
SugarCube is a free (gratis and libre) coding format for Twine/Twee created and maintained by TME.
VIEW / DOWNLOAD THE GUIDE!!!!
As of this release (v2.0.0), it is up to date with the version 2.37.3. If you are looking for the guide covering SugarCube 2.36.1, you can find it on my GitHub.
Note: the Guide is now complete. There won't be further substantial updates.
When would be an appropriate point to open a blog for my story? I plotted my whole story, got the story down, finished 95 percent of the code, started writing a little, and now I just need to fully figure out the rest of my cast (procrastination 😬). I'm a little confused when and tbh... how lol. Been questioning myself a lot. I want to start early to build a fanbase, but I also don't want to lead anyone on. You've been around a while, so I feel like you know your stuff.
So, there's really no right or wrong answer to this kind of thing.
But I think the most important thing is that you need a substantial demo and to know exactly what your vision is for your game before you start to build an audience. Don't build a fandom before you have something for them to be a fan of—story summaries, character introductions, and all that kind of stuff is well and good, but if players don't have something to play, you're setting them (and yourself) up for disappointment.
You need to have a demo that is functional, substantial, and gives the player a solid idea of what your game is about and how it is going to play. You need enough material that what they can play is satisfying and leaves them wanting more.
I think you also can't underestimate the impact a growing audience has on your work, and how excitement over in-development ideas can influence you in ways that will ultimately harm your game. The audience doesn't know what you want or what your vision is, only you do. Know exactly what you're creating so you can stand firm on your ideas.
My one regret in starting my blog when I did (which albeit was for a completely different game, Wayfarer as it is conceptualized now didn't exist when I made this blog) is that I announced too many characters too soon. If I was doing this over again, I would keep my mouth shut about any upcoming characters, especially companions, until they were actually in the game—even if it meant that no one knows who they can and cannot romance.
Companion/RO lists are the number one marketing tool for IF games on tumblr, but in practice this only works for a small number of games with a very specific structure. If these characters are not in the game from the first chapter, don't say anything about them. Don't hint. Don't announce. Don't offer information. Keep it blind.
Development is always, always, always going to take longer than you expect.
Trust your gut instinct. Keep more things to yourself than you think you need to. It's better to let future updates surprise your playerbase than to let hype for a future character or moment lead to disappointment when it ends up taking you a while to get there.
Glucosify's Quick Start Guide to Twine's Sugarcube for Interactive Fiction
Or GQSGTSIF for short.
Very simplified guide to making interactive fiction on Twine, using Sugarcube. This won't cover how to change the UI or anything like that, it's really the bare bones on how to make passages, variables, choices etc. There are multiple ways and syntaxes to do these things, I'm covering the ones I use but it's really not the only way to write code and to do these things ^^
This is not a replacement to the documentation, I'll link relevant parts of the documentations throughout the guide but it's really going to be your best source of information
Let me know if there's anything else you think I should add in there ~
1. Passages & StoryInit
2. Variables
3. If statements
4. StoryMenu (bonus)
First of all, assuming you've already downloaded Twine and opened a new project, make sure that your default story format is Sugarcube (in the top left of the window, go to Twine -> Story Formats and click on Sugarcube then at the top left 'use as default format')
Now, go back to your project. In the top left, click on Passage -> New : this is how you'll create new passages.
Passages are what makes the game essentially, it's where you write your story. Whenever you play an if and you click on a choice and it progresses to a new passage of text, that's how it's done. Make sure to name your passages in a way that makes sense to you, two passages can't have the same name. It's probably best the names aren't super long either considering the names are what you'll type in your code to make the player go to this or that passage.
Special passages :
there are some passages that have special functions. Create a passage and name it StoryInit : this passage is used to store variables. Whenever a new game is started, it will load up the variables states as they are in the StoryInit passage. This is essentially a default state where no progress has been made in the story so for example : all stats would be at 0, all relationships points would be at 0, the MC wouldn't have a name yet etc.
We'll store our variables there. Variables are attached to values, these values change as the player goes through the story. A variable's value can be many things, it could be a string which is anything that you'd write inside double quotes "" and would be printed as is in the string.
For example :
<<set $mcName to "">>
$mcName is a variable. Its value changes to whatever the player chooses for the MC name. As you write your code, you just have to type $mcName and it will be changed to whatever name the player has set it to.
A variable's value can also be a number, in this case, you wouldn't write it in double quotes.
<<set $confidence to 50, $maxConfidence to 100>>
It can also be a true or false statement.
<<set $IrisRomance to false>>
Figure out what needs to be a variable in your story and add them accordingly in your StoryInit passage, you'll add more variables as you go. Remember to give them a value, even if the value is 0 or "". Common variables would be for the MC's name and different physical traits, personality stats, pronouns, character's relationships stats etc. For this tutorial, write in your StoryInit :
<<set $mcName to "">>
Now, let's test our variable. Create another passage, call it start. In the top left bar, select Start Story Here : you should now see a little green rocket attached to your start passage. This is the passage the players will first see when they launch your game.
Inside the "start" passage, let's make a way to enter your own name with a simple text box.
<<textbox "$mcName" "Enter your name">>
Under it but still inside the "start" passage, let's write a simple link that will let us go to the next passage when we click on it.
<<link 'click here to confirm your name' 'next'>><</link>>
((the first string in the single quote is what will be displayed on the screen as the link, the second word in quotes, in this case 'next' is the name of the passage this link should direct you to))
Now make a second passage and call it next.
Inside that passage, write this :
My name is $mcName.
Let's see if it works : in the top left, go to build -> play.
It will open an html file in your default browser. Considering we haven't touched the UI, it will have the default Sugarcube UI. You should have a textbox on the screen and a link under it in blue. If your link is red or if you have an error, go back to your code and check for misspellings or make sure you have the right amount of quotes etc.
Type whatever name you want inside that text box then click on the 'click here to confirm your name' link. It should now have changed the $mcName we wrote in the next passage into the name you input in the box.
Congrats, you've learned how to set, change and display a variable :^)
Now, let's say you want personality (or relationship) stats that change when you select a choice. Back in your StoryInit :
<<set $confidence to 50, $maxConfidence to 100>>
If you want to have a visual elements like actual bars and meters, I would suggest making it easy on you and just getting Chapel's meter macro. You just copy the minified code inside your Javascript file (top left -> story -> Javascript) and then write in your StoryInit and in your relationships / stats / profile page as explained on his demo.
Go back to your "next" passage. Under the first sentence, let's write two choices link, one that will lead to an increase in confidence and one that lowers it.
<<link 'You are not confident. Life is hard.' 'sadface'>><<set $confidence to Math.clamp($confidence - 10, 0, $maxConfidence)>><</link>>
<<link 'You are very confident. Life is great.' 'happyface'>><<set $confidence to Math.clamp($confidence + 10, 0, $maxConfidence)>><</link>>
((Math.clamp might look intimidating but don't worry too much, it's just to make sure your variable's value doesn't go over the min and max allowed so you can't go below 0 or above 100 in this case. You write the variable you want to change then a + or a - followed by how many points you want to remove / add - in this case, 10. Then the 0 is the minimum and the $maxConfidence is the maximum value.))
Now create two new passages, one called sadface and one called happyface. To make sure your variable changed, type $confidence in both of the new passages and play your game.
On one of the statement, it should now say 40 instead of 50 and 60 in the other one. Congrats you've learned how to change a stat. :^)
But what if you want two choices to lead to the same passage but to display different informations depending on how high / low a stat is? Welcome to the world of if statements.
Back in StoryInit, you know the drill :
<<set $idiotLove to 0, $idiotMaxLove to 100>>
<<set $idiotRomance to false>>
New passage, call it LoveCheck. Go back to your "next" passage :
<<link 'Click here to get 25 love points with the idiot.' 'LoveCheck'>><<set $idiotLove to Math.clamp($idiotLove + 25, 0, $idiotMaxLove)>><</link>>
<<link 'Click here to get 50 love points with the idiot.' 'LoveCheck'>><<set $idiotLove to Math.clamp($idiotLove + 50, 0, $idiotMaxLove)>><</link>>
<<link 'Click here to get 100 love points with the idiot.' 'LoveCheck'>><<set $idiotLove to Math.clamp($idiotLove + 100, 0, $idiotMaxLove)>><</link>>
<<link 'I\'m allergic to idiots.' 'LoveCheck'>><</link>>
((you need to add a \ before your apostrophe when it's supposed to be part of the string, otherwise, the program will just think that's a closing single quote and not an apostrophe))
Alright, so now go to your newly created LoveCheck passage and let's write your first if statement. An if statement is basically a condition that you set, if the statement is 'valid' so like if it's a match then the program will ignore every other 'if' possibility. This is important because it means the order of your if statements matters. An if statement can be as simple as :
You are a person. <<if $idiotRomance is false>>You are not in love with an idiot.<</if>>
((this means that if the variable is false, then the second sentence will be displayed but if the variable is true, then the second sentence wouldn't be displayed to the player.))
An if statement can have an else :
You are a person. <<if $idiotRomance is false>>You are not in love with an idiot. <<else>> You love an idiot, I'm sorry. <</if>>
Note that this is the same as this, using elseif :
You are a person. <<if $idiotRomance is false>>You are not in love with an idiot. <<elseif $idiotRomance is true>> You love an idiot, I'm sorry. <</if>>
What this does is, if the variable is true, it will show the third sentence and not the second one and vice versa if the variable is false - because an if statement will only display the first statement that matches, if the variable is true then it will ignore any statement that require the variable to be false. As I said earlier, the order of your statement matter especially with variables tied to numerical values.
You'll understand better once you try it - let's do it in the wrong order first (still in your LoveCheck passage), we'll print the $idiotLove variable to see its value :
$idiotLove
<<if $idiotLove gte 25>> You like the idiot a little.
<<elseif $idiotLove gte 50>>You like the idiot quite a bit.
<<elseif $idiotLove gte 100>>You've fallen for the idiot, it's too late to save you.
<<else>> You don't even know who the idiot is, good for you.<</if>>
Click play and let's look at the problem. If you click on all the links, the number will be different but the sentence will still say that you like the idiot a little, even if you have 100 points. That's because gte stands for greater than or equal to, 100 is greater than 25 so the first statement is always valid so long as you have at least 25 points. The program sees the first statement matches and is valid so it has no need to read the rest of the if statements. To remedy this, we just change the order :
$idiotLove
<<if $idiotLove gte 100>>You've fallen for the idiot, it's too late to save you.
<<elseif $idiotLove gte 50>>You like the idiot quite a bit.
<<elseif $idiotLove gte 25>>You like the idiot a little.
<<else>> You don't even know who the idiot is, good for you.<</if>>
Now it works. If statements will be your most used tool I imagine, especially if there's a lot of variations in your story. You can use if statements for pronouns, for stat checks, romance checks etc.
I can always make another guide for the UI but for now, I'll just show you how to add another link in the sidebar of the default UI, using StoryMenu.
Make two new passages called relationships and stats. Write whatever you want in them, if you're using Chapel's meters, you could use the <<showmeter>> macro here to display your stat bars.
I've been making progress on my IF... gotta say though, the more I write the more it seems it won't be exactly a short story. I'm writing quite a few branches, and idk if I should tone it down or keep going
hi im truly sorry to ask you this, but i have a coding question if you dont mind
Ive been looking around to see how you can put music into twine, and i just cant seem to find how to do it?
Any help is greatly appreciated, just a link to another site to show me how would be enough. Again, please feel free to ignore as i feel I'm asking for to much.
hello! here it's pretty heavily explained how to add the music/add audio macros -> CLICK
Spiritual ability: Can see, hear and speak with spirits without any rituals
Character traits: Compassionate, Sensitive, Caring, Erudite, Careful
Bio: A promising new member of the island's coven and put in charge of the care of your mca and training in everything spiritual.
[ Valeria / Valerio ]
Names meaning: Valeria - strong, brave, and healthy || Valerio - to be strong
Age: 30
Height: 1.95 cm / 6'5"
Build: Muscular, broad build overall
Eye color: Green
Hair color: Black
Skin color: Olive Brown
Notable attributes: A pale horizontal scar running across their stomach
Default expression: Slight Smirk
Spiritual ability: None beyond a slight sense
Character traits: Passionate, Bold, Fearless, Charismatic, Affectionate
Bio: Once a peerless ocēlōtl in the Aztec Army, but died before being promoted and returning home. Their unrivaled fearlessness and exceptional strength always land them on the winning side of fights.
So like, you were the first IF game I’ve played of this quality, and I’m working on an IF game myself so I wanted to ask
1: how do you go about story boarding, do you have the entire thing planned out or do you write as you go
2: how do I decide what to create the game in, the two I’ve see have been twine and choice script but choice seems to have to be downloaded on GitHub or something and that seems complicated
3: how much coding knowledge or experience do I need to actually make an IF game
Also, I love the game can’t wait for more
Hello!
These are all good questions. I'll answer in brief:
I have a full game outline called a story bible that goes over the structure of the whole game in broad strokes. When I am actually working on an episode, I make an episode outline to cover the details I need to know (specifically gameplay structure). I will often break the episode into smaller parts which all have their own individual outlines. I am constantly outlining and refining outlines; this allows me to accommodate for new ideas that crop up organically during the writing process.
You need to check out available engines and play around with them. You don't have to build a full prototype if you don't want to, but it can help. Get in there, familiarize yourself with the language, figure out the basic building blocks. Familiarize yourself with the documentation so you can troubleshoot problems on your own. When I started with Twine/SugarCube I spent a lot of time in the editor with placeholder text learning how to move the player forward while adjusting stats, etc. You can't accurately make a decision about which engine you want to use until you see how they work and have done some groundwork.
It depends on the kind of game you want to make. But ultimately you can start from scratch and learn as you go. Designing your game structures (i.e. your mechanics, your stats, etc) will put you in a position where you have an idea and now you have to figure out how to make it work, which is the best way to learn something.
