Using Variables in Twine

### What is a Variable?

Variables are pieces of data that are used to hold specific values in your game. For example, let's say you were writing a text RPG game and wanted a way to keep track of skill points. To do this, you would declare a variable for each skill type such as "strength". You'd then assign a value to your new "strength" variable so now, if you ever want to reference your current skill points to view them, add/remove points, or anything else, you would access the variable to do so.

### Variables in Twine

In Twine, variables can be created programmatically using Twine macros. Macros are simply Twine's coding syntax to allow users to make more specific and powerful changes to your game. These macros are written directly in the same space you will write your text and are generally enclosed by parentheses to denote that it is a macro. I will only be covering the macros you will need for working with variables but you will find (or already find) that macros have much more capabilities and functionalities beyond this.

Here is the syntax for creating a basic variable in Twine. The portions enclosed by <> should contain the content you want depending on the variable you want to make.

```
(set: $<name> to <value>)
```
Let's break down each component.

* set:
	+ This indicates to Twine that the macro you're using will be to declare or "set" a variable
* $<name>
	+ This is the name of the variable you are setting in Twine. The name is prefixed with $ as a signifier to Twine that this is a variable as oppose to the word itself. Later when you want to reference this variable, you will also use the $ symbol.
* <value>
	+ This is the value that you will be assigning to your variable.

For example, if I wanted to create a variable named "strength" and assign it the value 2, the syntax should look like this.

```
(set: $strength to 2)
```

#### Variable Types

When you assign a <value> over to a variable, that value can take the form of multiple types. The simplest two are **strings** and **numbers**. If you are a familiar with coding, this concept will be fairly routine.

Strings are just text as you know it but requires a special identifier to signal to Twine that you want the variable value to be text. Text are surrounded by quotes as below.

```
(set: $name to "Sam")
```
On the other hand, numbers are indicated by just writing the value as it is without any quotes.

```
(set: $strength to 2)
```

#### What's the point of types?

You may be wondering, why even bother caring about what type your values are? Can't we just treat everything as strings so we can just use a single unified syntax?

Let's say you've declared a variable for represent a health bar and you've assigned it the value 100 as a string.

```
(set: $health to "100")
```
Later on, what if we want to perform arithmetic on it (Look to the next section for how we change variables)? We would write something like...

```
(set: $health to it - 1)
```
If we run this, we will be greeted by the following error.

Twine will fail to perform operations on the health variable because it's value is being treated as text as oppose to a number.

There are many other datatypes that Twine supports that won't be covered in this tutorial but in the next section, you can take a look at the available data types Twine variables support through the **Variable Creator.**

#### Twines Variable Creator (Beginner Option)

While variables can just be written manually within the passage contents, Twine offers an alternative option to generate the Macro syntax for you automatically.

Click **Var...** to access this option.

From here, you can fill in the fields with the desired name and value. Twine will also offer some helpful tooltips on your variable. Once you're ready, click **Add** at the bottom right to add the code into your passage contents.

### Working with Variables

Now that you are able to create variables, let's look at ways we can make use of these variables in our story.

#### Referencing Variables

Let's say we've asked the player for their name and have stored their name inside a variable aptly named "name". If we later want to reuse the name variable, you can call the variable using it's name (including the $ identifier) at any point throughout your passage.

```
(set: $name to (prompt: "What is your name?", ""))

My name is $name
```
You can see that the passage text will now use the same name that is given by the player.

Additionally, if we want to use this variable later on in other passages, we can freely use the same variable that we've set in the previous passage and it will be able to preserve the same value in the output

#### Mutating Variables

Ofttimes, variables won't be as simple as the name example given above. You will have variables that not only have to be set, but also need to be changed later down the line. Like the skill points example given before, if your player gains skill points at any point throughout the story, the corresponding skill variable will need to have it's value updated.

The first way we can update is just by reassigning the variable name a new value. In this case, the syntax will be identical as the one you had used to create the variable. You can think of this as overwriting the previous variable you had made by creating one with a same name but different value

```
(set: $name to "Tim")

My name is $name

(set: $name to "John")

My name is now $name
```

Similarly, variables can be updated across different passages meaning you can declare a name variable in the beginning, and then later down the line, you can update that previously declared variable as desired.

Another way you can update variables is using arithmetic. Specifically, if your variable has a number value, then it can be helpful to alter it by a numerical amount, as oppose to just reassigning it to a whole new number. In the case of a health bar, if your player takes 5 damage, you may not be certain of your characters starting health—it may be full, half, exactly 42. You can't blindly assign a new value without taking in consideration the current value. This is a good place to instead use some simple arithmetic to subtract 5 from the current value. Let's try this.

```
(set: $health to 100)

Your health is $health

You took 5 damage (set: $health to it - 5)
Your health is now $health
```

Notice the syntax is actually quite similar to how we were reassigning variables. The key difference is that we use the keyword "it" to reference the current value of the variable. From there, we can freely perform arithmetic operations on that value and the output will get assigned to the variable name.

### Conclusion

Variables are an extremely powerful tool in Twine to keep track of certain information important to your story. It's use cases extend across many other of Twine's feature set, particularly in conjunction with another macros. I hope with this tutorial you have a better understanding of how variables function in Twine and some ways you can use them.

### References

1. https://www.youtube.com/watch?v=SYEtItd4rXs
2. https://twinery.org/cookbook/terms/terms\_variables.html
3. https://damonwakes.wordpress.com/2018/01/24/twine-for-beginners-using-variables/
4. http://www.adamhammond.com/twineguide/