#twine tutorial

Setting Up Git With VSCode

Lucky for you, VSCode has built in integration with GitHub, which means you don't have to download any new programs other than git itself. You'll just have to set it up. A note- I'm not sure at what point exactly in this process VSCode prompts you to install git, because I'm not going to install it on another computer just for this tutorial haha. VSCode will provide the installation, just go along with the default settings and you'll be fine.

So first, make a Github account. It's free!

Now, open VSCode. Here's our project! You're going to want to click on that third button down in the side menu, the Source Control tab.

Under source control, you'll see this option. Click it.

Aaaaand it's done! That was easy, right? Now your folder is a git repository. Crazy!

Before you can put all of this up in GitHub, you'll need to push all of your files. Type a brief message (try "Initializing" to feel like a real cool coder), press commit, and VSCode will ask if you want to skip staging and just commit everything. Yes! Yes you do!

Now that all of your "changes" have been committed, let's publish your new repository to GitHub. Click on the new button that says "publish branch." When the popup appears, click "Allow" to give VSCode access to your GitHub account and sign in. Back in VSCode, you'll see this:

You're probably going to want it to be private, otherwise anyone on the internet could see all of your writing! Which is cool if it's a public coding project that people might want to download and use for their own projects, but if you're not a fan of code diving, leave it private.

Using Git To Help You Write

Now that you've got your folder set up as a git repository, it'll change the way VSCode looks. VSCode is using git's info to know where you've made changes, and it'll represent those changes in the UI. Here's what those look like:

If you click on those lines, you'll get to see this fancy new panel that highlights all of your changes:

So let's say we have a scene, and we aren't happy with how it's looking, but we aren't sure if we want to make one change or a different change. Instead of backing up all of your stuff or copy and pasting it to test it, you can just make whatever change you want and click that backwards facing arrow to revert it back if you aren't happy with it. You can do the same for things like CSS- when you've made some good progress and want to save your changes, commit them. Then any more changes you make will be easy to revert back if they don't look right. Groovy!

Now that everything's set up, it's as easy as committing your changes when you're satisfied with them and pushing those commits to back up your work.

Pat yourself on the back! You just learned (the very basics of) how to use git! You absolute genius!

What Is An Approval System?

An approval system is the mechanic that tracks how one character feels about another. This is typically the player character (PC) and the main NPCs. Most of the time these NPCs are romance options (ROs), but they could also be friends or party members. The higher the approval, the closer the PC and NPC become.

Choosing which characters will have an approval system and which ones do not is important. Unless you’re making a very small game (i.e. six or seven characters max, with no other characters involved in the story), not every character needs to have their approval tracked. These should be the characters whose relationship to the PC directly impacts the narrative and opens up different paths, routes, and outcomes.

How you build your approval system will depend on the scope and style of your game. A romance game where the PC follows the story route of their desired love interest will have different needs than an action/adventure game where the PC’s best friends can turn on them.

Before you design your approval system, there’s a few things you’ll want to think about:

Which characters will be affected by the approval system? How many? Keep in mind that every character who has a relationship/approval stat will need their own relationship/approval variable.

Do you want the approval system be linear? The approval system only ever moves forwards, with the player taking certain actions/dialogue options to gain approval points with an NPC, and they can never lose that progress.

Do you want the approval system to be bi-directional? The approval system can progress and regress. The player can take certain actions/dialogue to gain approval points with an NPC, but they can also take other actions/dialogue to lose points.

What is the impact your approval system will have on the game’s narrative? What types of things do you want it to lock or unlock? How will it shape the player’s experience?

What does your approval system measure? Friendship? Romance and friendship? Friendship and rivalry? Depending on your game’s needs, you may want to have more than one approval system to track different relationship names (for example, a separate system for friendship and one for romance, one for friendship and one for rivalry). You’ll want to think very carefully about using multiple relationship systems. If all of your desired outcomes can be controlled through one approval bar, then you probably don’t need more than one. However, if you want to do something like having a romance between a PC and an NPC who hate each other, you may want to split romance and friendship into two separate functions.

Linear Approval Systems

Linear approval systems measure the PC/NPC relationship in sequential order. The player can only ever gain approval points with an NPC. One gained, points cannot be lost. Usually with linear systems, the player needs to select the right dialogue and action options in order to progress the relationship, but they are not punished for selecting the wrong ones. Once the player achieves the right amount of points with the desired NPC, a special romance or friendship scene will unlock or they will attain some kind of additional content or flavour text.

When creating a linear system, you will want to decide how numerical values (the approval points) define the PC/NPC relationship. Here’s an example of a combined friendship/romance system, using units of 10:

0 – 9 – the characters have just met each other. They’re getting to know each other, but they’re not friends yet.

10 – 19 – The characters are warming up to each other. They are more friends than acquaintances and they are starting to flirt with each other.

20 – 29 – The characters know each other quite well. They are openly flirtatious; maybe they have started dating.

30 – 39 – The characters care a lot about each other. They have officially become a couple.

40 – 50+ – The characters know everything about each other. They are deeply in love and trust each other completely.

Here, the ranges are the same for every approval “level”, but they don’t have to be. Some levels could require fewer amounts of points (i.e. the “getting to know each other” range could be accomplished in 5 points, and the “caring a lot about each other” range could take 20 points). It could also change depending on the character, with some NPCs being more open to the player character right away and others taking more time to warm up to them.

How large your ranges are will depend on how many opportunities you plan to give the player to raise their approval level. If you only intend to provide a handful of opportunities to raise approval, then you won’t need ranges quite as large as this one.

Consider the scale of your game and what the long-term progression of the PC/NPC is; that will help you determine how many approval points you are working with. You should always know where the end point is.

Bi-Directional Approval Systems

Bi-directional approval systems are more difficult to implement than linear ones, but they are much more flexible. If you intend your PC and NPCs relationships to have any kind of rivalry, for them to fall in and out of love, or for them to end up hating each other over the course of your game, a bi-directional approval system may be better. This system creates a scale. The player can gain and lose approval over the course of the game, and depending on their actions, the PC/NPC relationship will either increase or decrease.

For this kind of system, you will want to think about your minimum point and maximum point for your scale (i.e. where does it start and where does it finish?). While you can set 0 as the neutral point and work with positive and negative numbers (anything above 0 being in the “like” range, anything below 0 being in the “dislike” range), this can be difficult to indicate visually later on if you want to use a meter or a progress bar.

I like to use 0 and 100 as my min and max points for sake of ease, but you can really set it to whatever you want.

Similarly to the linear approval system, you will want to define the numerical ranges that your PC/NPC relationship falls into. Here, it’s important to know where the where the mid point is—what value indicates the neutral ground between like and dislike.

It could look something like this:

0 - 19 — Extreme dislike

20 - 39 — Dislike

40 - 59 — Neutral feelings

60 - 79 — Friendly

80 - 100 — Loving/close friends

Here, I’ve divided the approval stat (0-100) into 5 approval ranges that increase in units of 20 points. 50 is the center—it is the mid point of the approval bar and the mid point of the neutral range.

Just like the linear system, how big your ranges are will depend on how many opportunities you plan to give the player to increase/decrease their approval stat.

Why Work in Ranges?

Having ranges in your approval system allows for more flexibility and control over the approval stat. It increases the amount of opportunities the player will have to change the course of their relationships, which makes for a more satisfying roleplaying experience.

For example, here’s a ten point approval system:

1 – We hate each other

2 – I can’t stand you

3 – I dislike you

4 – You bother me

5 – Neutral

6 – You’re okay

7 – I like you

8 – We’re good friends

9 – We’re close friends

10 – We unconditionally love each other

If gaining nine approval points is all it takes to go from “we hate each other” to “we unconditionally love each other”, then it only takes the player nine interactions for that growth to happen. The pacing of the relationship is going to feel off. When there’s less room for growth, growth between these extremes will happen very rapidly.

Working in ranges let’s the PC sit in different stages of the relationship for a longer amount of time. Because it takes more points (and therefore more time), any relationship progress or regression will feel more natural. At the same time, you don’t want the ranges to be too big, otherwise it will feel like no progress is happening. This will, of course, depend on how many points you are adding/subtracting with each approval gain and loss.

Adding/Subtracting Approval and Using Conditional Statements to Control Flavour Text, Dialogue, Choices & NPC Behaviour

Once you have your system established and you know your ranges, approval stats work very similarity to any other stat. You can use conditional statements that check the numerical value of the approval stat to show different flavour text, dialogue, choices and options.

I’m going to use the bi-directional system as an example here, with a range of 0-100.

Let’s say we have a character named Eliza and her approval is stored in a variable called $eliza_approval. Because she has just met the PC, let’s set her approval to 50, so she is in the exact centre of the neutral approval range.

<<set $eliza_approval to 50>>

If the player selects an option that coincides with something she approves of, you can add approval to her approval stat with:

<<set $eliza_approval +=1>>

(This adds +1 to her approval stat.)

<<set $eliza_approval -=1>>

(This subtracts -1 from her approval stat.)

You can accomplish the same thing inside a link, using SugarCube’s link markup:

[[1. Nice choice.|Next Named Passage][$eliza_approval +=1]]

[[2. Mean choice.|Next Named Passage][$eliza_approval -=1]]

In the text of your game, you can control what options and flavour text the player sees depending on Eliza’s approval stat by using conditional statements.

<<if $eliza_approval >=80>> Shows text/options for a loving/close friends relationship.

<<elseif $eliza_approval >=60 && $eliza_approval <=79>> Shows text/options for a friendly relationship.

<<elseif $eliza_approval >=40 && $eliza_approval <=59>> Shows text/options for a neutral relationship.

<<elseif $eliza_approval >=20 && $eliza_approval <=39>> Shows text/options for a relationship where they dislike each other.

<<elseif $eliza_approval >=0 && $eliza_approval <=19>> Shows text/options for a relationship where they hate each other.<</if>>

You could also close the statement with an <<else>> instead of the last <<elseif>>.

Depending on the context of the scene and options, you may not need flavour text or choices for all of your available ranges. Often when working with a bi-directional system, you may only need to have two options (one for low approval, one for high approval). What counts as “low” and what counts as “high” may change depending on where you are in the game, the current tensions, and what’s at stake.

To divide your ranges into low approval and high approval, you could do something like this:

<<if $eliza_approval >=60>> Shows the high approval option.

<<else>>Shows the low approval option.<</if>>

Here, high approval counts as anything that is 60 or over (the “friendly” range and above).

Later on, I may run into a situation where I want “high” approval to count anything in the neutral range. So I may change the code to this:

<<if $eliza_approval >=40>> Shows the high approval option.

<<else>>Shows the low approval option.<</if>>

How much differing flavour text and options will depend on the context of each individual moment in your game. Sometimes you will want to have more restrictions and more flavour text; other times, you’ll want to simplify.

A basic rule of thumb is that if the flavour text for a neutral relationship and a friendly relationship in a given scenario is basically the same, then you probably don’t need to separate them out (for that scenario). Even if you have your relationship stats divided into five ranges, you don’t always need to come up with text and options for all five.

Clamping Approval

I think the most important part of creating a relationship system that feels organic is pacing and offering a broad selection of player choice. One of the challenges with approval systems is crafting a system that allows the player to feel like they’re roleplaying their character. Sometimes, the choices that gain approval are out-of-character for the player and they won’t want to select them, even if they want to form a relationship with that NPC.

This can be frustrating for the player in games that have romance. Systems that don’t have enough varied opportunities for the player to gain approval can significantly hinder roleplaying and cause players to take out-of-character actions to get the RO they want.

However, developers may not want to offer a lot of opportunities for approval gain because players could max out (or deplete) their relationship stats too early. To circumvent this, I highly recommend clamping your approval.

Clamping keeps your relationship stats between a min/max range and prevents it from exceeding the limit. SugarCube can clamp numerical variables with a function called Math.clamp.

If we take Eliza’s approval variable from earlier and clamp it, it will look something like this:

<<set $eliza_approval to Math.clamp($eliza_approval + 5, 0, 100)>>

<<set $eliza_approval to Math.clamp($eliza_approval - 5, 0, 100)>>

The first code adds +5 to $eliza_approval, the second subtracts -5. Both clamp it between the range of 0 and 100.

This means that if $eliza_approval was at 98 and the game added +5 to it, it would max out at 100. And if $eliza_approval was at 3 and the game subtracted -5, it would only decrease to 0.

To clamp inside SugarCube’s link markup, you can do it like this:

[[1. Nice choice.|Next Passage][$eliza_approval to Math.clamp($eliza_approval + 5, 0, 100)]]

[[2. Mean choice.|Next Passage][$eliza_approval to Math.clamp($eliza_approval - 5, 0, 100)]]

You can use clamping to manipulate approval gains and loses at different stages of your game.

For example, in Wayfarer, the player has the opportunity to set the approval level of a major character with whom they have a pre-established relationship. If the player sets Aeran’s approval level to 80, then the game treats them as very close friends.

Because there are multiple opportunities to raise that approval level throughout Chapter 1, Aeran’s approval is clamped between 5 (as the minimum) and 90 (as the maximum) as I did not want players to fully deplete or max out his approval bar in the first chapter of a 14-chapter game.

It doesn’t matter if the player hits all of the possible approval gains available in the chapter, Aeran’s approval will always stop at 90 in Chapter 1.

Clamping approval gains and loses at different points in the game can be helpful for allowing more opportunities to affect approval. Instead of preventing players from maxing out their stats too soon by offering fewer choices, you can offer more choices and let the engine do the work for you to keep the player’s relationships within the desired range.

How Many Points to Add?

How many approval points you add or subtract will depend on your system’s range and your game’s needs. Approval gain/loss can always be static (+1 or -1), or it could depend on the action taken.

If the PC does something an NPC really likes, it could garner more approval points – +5, +10, or even enough to put them into the next range. Likewise, if the PC does something the NPC despises, it could net greater loses.

If the PC does something the NPC believes is unforgiveable, sometimes an approval loss is not enough because the PC could gain those relationship points back. You may want to add an additional check to control the NPC’s behaviour in regards to the Unforgiveable Event that supersedes the approval, or block the PC off from gaining approval with the NPC all together.

In SugarCube, this bit of code could look like this:

<<if $UnforgiveableEvent is true>>Unique flavour text that shows that Eliza is upset with the PC

<<elseif $eliza_approval <= 39>>Unique flavour text for a generic low approval interaction with Eliza

<<else>>Flavour text that isn’t covered by the above two situations (so, in this case, unique flavour text for a generic medium/high approval interaction with Eliza).<</if>>

Relationship Bars

If relationships are a crucial element of your game, you may want the player to access that information so they can track where their approval level is at.

There are multiple ways to do this, so it all depends on the design of your game and how much time you want to spend on it.

You can use conditional statements show relationship status through words, with no visuals. Something like this:

Eliza <<if $eliza_approval >=80>><b>loves</b> you.

<<elseif $eliza_approval >=60 && $eliza_approval <=79>>is a <b>close friend</b>.

<<elseif $eliza_approval >=40 && $eliza_approval <=59>>is <b>indifferent</b> towards you.

<<elseif $eliza_approval >=20 && $eliza_approval <=39>><b>dislikes</b> you.

<<elseif $eliza_approval >=0 && $eliza_approval <=19>><b>hates</b> you.<</if>>

You could also create an approval bar that visually indicates approval level. I prefer using the progress element for this (explained here), but you could also use Chapel’s Meter Macro to accomplish the same thing.

Th progress element and meters cannot show negative values, which is why I recommended having 0 as your lowest value on any given relationship stat.

You could do a combination of the two, or even use image assets (controlled by conditional statements) to indicate approval. Visually indicated approval level can be as complicated or as simple as you want it to be.

Using Multiple Relationship Stats

Depending on the complexity of your relationship system, you may end up splitting your approval systems into multiple parts. For example, you could have separate variables for:

Friendship

Romance

Rivalry

This would allow you to have greater control over a wider arrange of combinations. A relationship that is high friendship and low romance would be different from a relationship that is high friendship and high romance. A relationship that is low friendship, high romance and high rivalry would again be different from a relationship that is low friendship, but high romance and high rivalry.

All of this can be controlled with effective use of conditional statements. For example, if you were working with separate friendship and romance systems, you would need to set two stats: one for friendship and one for romance.

Conditional statements would then look something like this:

<<if $eliza_approval >=40 and $eliza_romance >=80>>Options for a neutral or friendly Eliza who is romanced.

<<elseif $eliza_approval <=39 and $eliza_romance >=80>>Options for a hostile Eliza who still has feelings for the PC.

<<elseif $eliza_approval >=40 and $eliza_romance <=79>>Options for a neutral or friendly Eliza who is not romancing the PC.

<<elseif $eliza_approval <=39 and $eliza_romance <=79>>Options for a hostile Eliza who is not romancing the PC.

<<else>>Options for if none of the above is true.<</if>>

So, Twine has two types of variables, a temporary variable and a story variable. Temporary variables are declared with an _, and can only be used within one single passage to store information, so if you attempt to use a temporary variable in another passage, Twine will no longer remember the information you put in it.

So you'll mostly be using the story variables in Twine, which are declared using the $, as Twine carries the information in those throughout the entire story. And for characteristics for MC, you'll obviously want to use those as well.

There are several ways of setting variables in Twine using various Macros, so I'll try to cover some of the most regular ones. You can use any of these ways to set variables for anything.

Name:

So for setting names, most games have a list of suggestions, as well as the option to type in your own name, like this:

For suggestions, you only need to have a regular link that sets a variable, which can be done either by using the [[]] link syntax or the <<link>><</link>> macro, like I have done here:

So for the first four names above, I've used the [[]] syntax to set the $firstname variable:

In the first part of the syntax, I write what I want to display in my link, which in the first example is the name Emma, then after the | I have the name of the passage that I want the link to take the player to next, which most logically would be the passage to set the last name (just an example, of course). Then I tell the syntax which variable to set whenever the player clicks on Emma, which is $firstname, as well as what information to store in that variable, which is Emma. So we're basically telling Twine to set $firstname to "Emma", so that whenever we write $firstname in our story, it will show up as Emma after this.

-

For the next four names, I've done the exact same as above, just by using the <<link>><</link>> syntax. These two are legitimately the same, but sometimes it's better to use one over the other for coding purposes.

in <<link>> between the first two "" I've again put the name I want the link to display for the user, then in the next "" I've put the next passage, but this time we have to use the <<set>> macro between the <<link>> and the <</link>> to set the variable. So we're doing exactly the same thing as above, telling Twine to set $firstname to "Tobias" if the user clicks Tobias.

Sidenote: Whether you use the = sign to set variables or the word to, doesn't matter. It's all preference, they do the exact same thing. Also the * that I have in front of the links is simply to make the name suggestions an unordered list with list items, for styling purposes.

-

Now for the player to type in their own name, you will use the <<textbox>> macro and do basically the same as above:

Inside the first "" we'll tell Twine which variable we want to set, which is $firstname, then in the next "" we tell Twine what value the textbox should hold by default. You can use this to tell the player what the textbox is for, ie. "Type your own name here", or you can put a name suggestion in there if you want. Then in the last "" we're telling Twine which passage to take the player to next, as soon as the enter button is hit. You don't have to include this if you'd rather the user had to navigate to the passage some other way, like a button.

When the player goes to the next passage, Twine will fetch the value inside the textbox and save it inside the $firstname variable.

Other ways to set variables

Generally, you can the [[]] syntax or the <<link>><</link>> macro to set any variables, whether it be name, gender, pronouns or appearance, like I have used it here to set the $gender variable:

I basically just use one of those for setting most variable, and I think most games do too, but I'll still cover some other ways of setting variables to show you how they work..

Radiobutton / <<radiobutton>>

Let's say we want to use Radio Buttons to set $gender like we did above. This will will look like this in Twine:

This result is achieved by this code:

Again, in between the first "" we're telling Twine which variable to set, which is $gender, then which information we want that variable to store, depending on which radio button is selected, then you have the option to tell Twine if you want a button to be autocheck-ed, which means that Twine will automatically check which value $gender currently holds and check that option, but in our case $gender has no value, so none is checked. The other option is to set one radio button to checked by default.

So, if the player checks of the Woman option, whenever they click through to the next passage, the $gender variable will set to "Woman".

Listbox / <<listbox>>

Let's say we're setting $haircolour by using Listbox. How it will look in game + code:

Inside of <<listbox>>'s first "" we're telling Twine which variable to set, in this case it's $hairColour.

Then we have a selection of <<options>> where the first "" will be the text that is displayed to the player, and the second "" is the value that the variable will actually hold. So in the first example, the player will see Blonde hair in the selection menu, and when selected, $hairColour will be set to "blonde".

Cycle link / <<cycle>>

This one is quite popular to use in Twine, it's the link that will function like this:

And is achieved by this code:

We use the <<cycle>> macro, and inside <<cycle>>'s "" we'll tell Twine which variable we want to set, in this case it will be $eyeColour, then between <<cycle>> and <</cycle>> we will once again use the <<option>> macro to set the selection of options the player can chose from, like we did above with the <<listbox>>

Protip:

If you wanted to set more than one variable with one single link, there's a simple way to do so. Let's use pronouns as an example, since you specifically asked for that. How it looks in game + code:

So above, we're doing the exact same thing as we did in the first example at the top of this post using the [[]] link or the <<link>><</link>> to set variables with a link, except we're setting several variables at the same time simply by separating them with a ;

So in the first example, if She/Her is clicked, we're setting $they to "she", $them to "her", $their to "her", etc. — all within the same link.

-

I think that covers the most basic and most popular ways of setting variables in Twine. I've linked all the macros as well, if you want to read more about them.