# Text Adventure 1: Twine

Welcome! Over the course of the next 3 workshops, you'll be creating your very own text adventure. You'll be starting here, by using a text adventure framework called [Twine](http://twinery.org). It uses an easy-to-follow interface to lay out your story, but you'll also be using some very basic functions called "macros," which we'll be discussing later. [Here's an example of what you'll have created by the end of this workshop.](https://bruggie.com/twine)

A text adventure is like any sort of adventure game today, but everything is described through, as the name suggests, text. These were popular in the early days of computing, before every computer had the power to render "complex" graphics, even though many early graphics were only pixel art! Because they are simple in this way, they're a great platform for us to target when starting out. However, just because they only display text doesn't mean they can't be complex in their own rights. Here are some examples of very complex text adventures:

* [Zork](https://en.wikipedia.org/wiki/Zork) - One of the earliest text adventures created, it was essentially the definition of the genre, as it was able to understand more complex commands, through the usage of prepositions and conjunctions.
* [The Hitchhiker's Guide to the Galaxy](http://www.bbc.co.uk/programmes/articles/1g84m0sXpnNCv84GpN2PLZG/the-hitchhikers-guide-to-the-galaxy-game-30th-anniversary-edition) - Based on the book of the same title, this is one of the most complicated text adventures created. It's known for its extreme user-unfriendliness. If you try it... expect to die! A lot!

You'll be creating something a bit less complex than those examples, but still with its own interesting functionality. [Here's an example of one made by a staff member.](https://hire.bruggie.com) This one has multiple endings, and some interactive functionality. These are somewhat advanced concepts, but nothing outside of what you can do with Twine. If you're ever stuck, you can take a look at this for an idea of the format of a text adventure. Let's get started!

## Creating your story

We'll be using the online Twine editor to create our text adventure. [You can find it by clicking here.](http://twinery.org/2)

![Empty Twine dashboard](https://gist.githubusercontent.com/remixz/7d82c3bf1c113fbad0f7/raw/94a6a0d480eca9da958a7e7b94f4f69012810831/dashboard-1.png)

This is the Twine dashboard. For now, we just want to focus on one thing: creating our story! Click on the big green "+ Story" button, and choose a name for your story. As it mentions, you can change this later.

![Story overview with one default passage](https://gist.githubusercontent.com/remixz/7d82c3bf1c113fbad0f7/raw/94a6a0d480eca9da958a7e7b94f4f69012810831/overview-1.png)

After you entered the name, you'll notice that the story overview has launched. Towards the middle, you'll notice a box that says "Untitled passage." A passage can be seen like a page of a book, as you'll write your story in these passages. As well, you'll be adding links to other passages from a passage. For now, let's just change the text. Double click on the passage to open the passage editor, and enter something to start your story with. In general, a text adventure will describe the reader's current surroundings, any actions that may have just happened, and what the user can do next. Since the adventure just started, just a brief description will do.

![Passage editor with initial writing](https://gist.githubusercontent.com/remixz/7d82c3bf1c113fbad0f7/raw/94a6a0d480eca9da958a7e7b94f4f69012810831/editor-1.png)

You'll also likely want to change the title of the passage. Once you're done, just click the little X on the popup, and it'll automatically save what you wrote. We're now back in the story overview. You can drag around the passage boxes to organize them in a way that makes most sense to you.

Now, let's make sure this works. In the bottom right, click on the "Test" button. This should open a new tab with your story.

![Story preview of first passage](https://gist.githubusercontent.com/remixz/7d82c3bf1c113fbad0f7/raw/94a6a0d480eca9da958a7e7b94f4f69012810831/preview-1.png)

Awesome! You should see what you wrote in that first passage. As well, you'll notice a "Debug View" button in the bottom right. We'll be using that later. You can close this tab for now if you want, but whenever you want to test out your story, you should press the "Test" button in the bottom right of the story overview.

## Adding new passages

So far, our story is pretty simple: It's just one passage! For this to be an adventure, we're probably going to want a bit more. Thankfully, this is pretty easy to do in Twine. This is also going to be the first we use what's called "syntax", which refers to special instructions that computer programs use to understand what you want to do.

Let's open up our first passage again by double clicking on it. So far, we've wrote about the #meta channel on Slack. Let's add a link to the #random channel. To create a new passage, it's pretty simple: With a special syntax, we tell Twine what the title of our new passage is. Our new passage is going to be called "random". We'll create a couple of blank lines in the editor, and then enter this: `[[random]]`.

![Passage editor with new link syntax](https://gist.githubusercontent.com/remixz/7d82c3bf1c113fbad0f7/raw/94a6a0d480eca9da958a7e7b94f4f69012810831/editor-2.png)

That syntax of wrapping the title in two square brackets tells Twine that we want to create a clickable link, and when clicked, show the contents of the passage with the title we gave it. Close out of the passage editor, and you'll notice something...

![Story overview with two passage boxes](https://gist.githubusercontent.com/remixz/7d82c3bf1c113fbad0f7/raw/94a6a0d480eca9da958a7e7b94f4f69012810831/overview-2.png)

Twine recognized that the passage we specified didn't exist, so it made it for us. How convenient! You'll also notice there's an arrow going between the first passage and this new passage. This is Twine letting us know that the link is functional. In other terms, it parsed the syntax we wrote correctly. Let's add something to our new passage the same way we did with our first, by double clicking it. We'll also add a link back to our first passage, just to show again how we create links.

![Passage editor with link syntax again](https://gist.githubusercontent.com/remixz/7d82c3bf1c113fbad0f7/raw/94a6a0d480eca9da958a7e7b94f4f69012810831/editor-3.png)

You'll have noticed that if you started typing out a link to your previous passage, Twine auto-suggested the name. This is a good way to ensure you're linking to the right passage. When you close out of the editor again, you'll notice the arrow now runs two-ways, letting us know that the link is functional both ways. Let's hit "Test" again at the bottom right, and try out our new links.

![Animation of going between passages](https://gist.githubusercontent.com/remixz/7d82c3bf1c113fbad0f7/raw/94a6a0d480eca9da958a7e7b94f4f69012810831/link-demo.gif)

Radical! At this point, you now know the basics of Twine: You create passages with a special syntax, and link them together. You might want to take some time now to write out more of your story. Before you do though, let's learn one more helpful piece of syntax.

## Customizing link text

So far, when the links are shown in our story, they've just been the name of the passage. Although you could make the names of the rooms whatever you want to be shown in the story, this could lead to problems later. For example, you might want to have the same text in multiple places, but not have them link to the same passage. As well, this overall might become disorganized, since the sentences may be out of context, and it'll be confusing to go through in the story overview.

Instead, we can use some syntax to specify what the links says when shown in the story. If we wanted our link to the `random` passage to say "Go to the #random channel", we would replace `[[random]]` with `[[Go to the #random channel->random]]` You'll notice we added an arrow, with `->`.

![Passage editor with new display text syntax](https://gist.githubusercontent.com/remixz/7d82c3bf1c113fbad0f7/raw/94a6a0d480eca9da958a7e7b94f4f69012810831/editor-4.png)

Anything that comes after the `->` arrow will display as the text when going through our story. Make sure to write it exactly like our example, where there's no space between the passage title and arrow, and the arrow and display text.

Equipped with these two pieces of syntax, you can start making some real progress on your text adventure. When you've written something fun, you can start on the next sections, which will talk about formatting your text with new syntax, and how to use a macro to generate content dynamically.

If you're stuck on your story, feel free to work with others! Collaboration is super important in computer science, and can lead to some great results. Don't worry: there's no cheating in this club.

## Formatting your story

Through things like **bolding** and *italicizing*, you can help to convey different types of tone throughout your story. You can see [a full reference of the types of text styling here](http://twine2.neocities.org/#markup_style), but here's a quick cheatsheet:

* `*Italics*` -> Creates *Italics*
* `**Bolding**` -> Creates **Bolding**
* `***Bold italics***` -> Creates ***Bold italics***
* `~~Crossed out~~` -> Creates ~~Crossed out~~

You'll also notice on that page it mentions that macros can be used to format your text. Let's talk about what a macro is, and how you can use them.

## Adding macros to your story

As mentioned in the formatting documentation linked previously, Twine has macros that can be used to do a variety of functions. [Twine defines them as so](http://twine2.neocities.org/#markup_macro):

> A macro is a piece of code that is inserted into passage text. Macros are used to accomplish many effects, such as altering the game's state, displaying different text depending on the game's state, and altering the manner in which text is displayed.

In other words: A macro is another piece of Twine's syntax that can be used for content that is not pre-defined, or "dynamically generated." In general, macros return some sort of result. Macros are also very similar to what's known as a "function" in other programming languages. They technically have some differences, but for our purposes, they are equivalent.

Twine's macros generally return text. However, the text may be altered, such as being a different colour, or or it may be dynamically generated, such as showing the current time. As you can see from [this list of macros](http://twine2.neocities.org/#macro_set), there are a lot of macros that you can use, and some of them are quite advanced. We're going to try using a pretty simple one, that changes the colour of the text. [Here's the documentation on this macro.](http://twine2.neocities.org/#macro_text-colour) It's called `text-colour`, but it's also called just `colour` for ease of use. Here's their example usage:

```
(colour: red + white)[Pink]
```

 Let's break down this syntax into two parts:

 * `(colour: red + white)` - We start with a regular bracket, and then type out the word `colour`, followed the colon. This is the macro call, which tells Twine that we want to do. After the colon, we put our colour. In their case, they've highlighted that Twine will combine colours if you use a `+` symbol in between colour names, so you can have a wide range of colours. We'll experiment with that in a second. After the last colour, we put a closing bracket, to show we've finished the macro call.

 * `[Pink]` After that, there's a single square bracket, followed by the word "Pink," and then a closing square bracket. This is the text we want Twine to colour, which in this case is `red + white`, which makes pink. Any amount of text can go in-between the opening and closing square brackets. Let's add this to our story:

 ![Passage editor with colour macro](https://gist.githubusercontent.com/remixz/7d82c3bf1c113fbad0f7/raw/94a6a0d480eca9da958a7e7b94f4f69012810831/editor-5.png)

In our case, we made the text just plain red. However, you can try experimenting with colours. Try combining a couple different colours to see what you get.

If you looked at the documentation previously, you'll also noticed it mentioned we can use a "CSS-style colour" instead. We'll be talking about CSS in a later workshop, but for now, you can use a [colour picker like this one](https://gist.githubusercontent.com/remixz/7d82c3bf1c113fbad0f7/raw/94a6a0d480eca9da958a7e7b94f4f69012810831/http://www.colorpicker.com/), pick out a colour, copy the letters and numbers above the colour picker next to the hashtag, and put it in the colour like this: `(colour: "#90C3D4")(My custom colour!)` Notice that we had to add double-quotes around the letters and numbers, and also add the `#` symbol (also known as an "octothorpe") before it. Again, we'll be talking more about why this is later, but just note that you'll need to do this.

Before we finish up, let's test our story again, to make sure we got the syntax right. If everything loads correctly, let's also do one more thing: Press the "Debug View" button in the bottom right of your story preview.

![Story preview with debug view on](https://gist.githubusercontent.com/remixz/7d82c3bf1c113fbad0f7/raw/94a6a0d480eca9da958a7e7b94f4f69012810831/preview-2.png)

The debug view will show where you're using macros, amongst other things. You'll notice your coloured text now shows the macro next to it. However, you'll also notice your link has a macro next to it, that says `(link-goto:)`. What does this mean? Well, when you use the double square bracket syntax to define a link to another passage, you're actually using the shorthand for the `link-goto` macro!

You could create all of your links by typing `(link-goto: "Display text", "Passage title")`, but we used the shorthand with the double square brackets and `->` arrow because it's a lot quicker to do. The Twine passage editor also doesn't automatically create a new passage if you use the full macro syntax. In general, many things in programming have shortcuts to make them easier. These are sometimes called "abstractions", as they mask over what might take a lot of code with something much simpler.

## Saving your story to your computer

To finish up, we need to do one last thing: Save our stories! Twine does automatically save your story as you go, but this is only within your browser. Some computers may not remember this data when the browser is closed, or when the computer is logged out of. Thankfully, Twine has us covered here. First, click on the Home button in the bottom left of the story overview. You should be back on your Twine dashboard. You'll see that your story now has a place on the dashboard. Click the gear icon on your story, and choose "Publish to file" in the menu that pops up.

![Twine dashboard with options menu open on story created](https://gist.githubusercontent.com/remixz/7d82c3bf1c113fbad0f7/raw/94a6a0d480eca9da958a7e7b94f4f69012810831/dashboard-2.png)

Twine will automatically download your story into a .html file. You'll want to move this somewhere safe, such as your Documents on a network drive at school, onto a service like Dropbox or Google Drive, or onto a USB flash drive. You can also open this .html file anywhere, whether you're online or offline, and you can play through your story. If you wish to edit this story again at a later date, simply go to the Twine dashboard, and click the "Import From File" button underneath the "+ Story" button. Then, find the .html file that Twine saved for you, and upload it. Twine will recognize it, and add it back to your dashboard. You'll want to save your story to your computer whenever you're done editing it, such as at the end of a meeting. Your computer may save your progress automatically without doing this, but to err on the side of caution, always save the story to a local file.

## Wrap-up

Great work! You've made your first computer science creation. It may not have seemed like you did a lot of programming, but through this workshop, you were introduced to some fundamental basics, such as the idea of using syntax to tell a computer to something, or using macros to return a result from an input. Here are some ideas for how you could expand your story:

* Try using some different macros! [There's a full list of them here](http://twine2.neocities.org/#macro_set), all with explanations and example usages. Some of the terminology may be new to you, but try researching what you don't know.
* The documentation linked to in the last point also has some other text formatting that we didn't go over here. Try experimenting with those.

Overall, by the end of this meeting, you should have a solid story written. It doesn't have to be super long or complicated, but you should be proud of it! In our next workshop, we'll be using the stories we wrote, and coding the basic functionality of Twine ourselves using HTML. Until next time!
