Gone to Hell in a Handbasket - by glucosify

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 a new passage, call it StoryMenu :

<<link 'relationships' 'relationships'>><</link>> <<link 'stats' 'stats'>><</link>>

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.