# A Deep Dive into Twine (and Coding Branching Scenarios)
## Useful Coding to Know When Making a Story in Twine
Depending on the style of Twine that you've chosen (see the [Cookbook](https://twinery.org/cookbook/index.html) for more information or [this helpful article](http://www.adamhammond.com/twineguide/)) there is a certain amount of control that you have over the appearance and behavior of each passage. This is done with 4(*ish*)components: Markup, Javascript/JQuery, Twine's language, and CSS.

For the purpose of simplicity, we'll stick to the default (Harlowe). Harlowe uses Markup language for in-text formatting. [Here's a quick start guide for that language](https://hackmd.io/c/codimd-documentation/%2F%40codimd%2Fmarkdown-syntax) (taken from HackMD...which is where this tutorial is hosted) Not all of the elements are allowed, but the section below covers the basics.

:::info
# # is h1
## ## is h2
### ### is h3
#### #### is h4
*`*` makes an item italicized*
**`**` makes an item bold**
***`***` makes an item bold and italicized***
~~crossthrough~~
:::

All of these markup syntax elements also work within Twine and are generally how you are going to edit your text elements. I recommend playing around and seeing what you like in order to craft the correct reading experience.

***The Most Important thing*** that separates Twine and regular Markup is that Twine relys on links to create the branching scenarios. To do this, surround the text that you want to link with square brackets.

:::info
[[The words that you want to link]] or The words that you [[want to link]]
:::

Twine will take that information and create a new passage with the same title as what is listed in the brackets. You can, however, also adjust this to make it so the choice links to an existing passage or to make it so that you can have the passage be called something different from the choice.

:::info
[[The words of your choice -> The Passage you want to link to]]
[[The Passage that you want to link to <- The words of your choice]]
[[The words of your choice | PassageName]]

:::

**Note:** You can also create very custom experiences by changing the Javascript associated with your story directly, but that is more advanced than is necessary for this exploration.

### Images, Links, Videos, Oh My!
Markdown and Twine diverge regarding embedding media content in the stories. To do this on Twine you have to use good old-fashioned HTML.

The good news with how it has been included, however, is that all of the HTML can be inserted in-line (you don't have to navigate to another page to do any editing...which is very nice).

:::success
Image: `<img src="imageurl.jpg" alt="alt text">`
Video/Web app: `<iframe src="videofileURL" width="" height="" alt=""></iframe>`
Link: `<a href="url">Placeholder Text</a>`
Center on page: `<center>element</center>`
:::

### An Aside on Variables
Variables are where Twine connects with Javascript/JQuery for the average user. They are the ways that you can truly shape the experience of the player. Using a variable allows you to determine which areas the player can access or what will show up depending on their past choices.

To define a variable, you have to initialize it. This doesn't necessarily have to be at the beginning of the story, but it's pretty good practice to do so. I have an unseen passage with the tag startup that does this purpose for any variables used

Define a variable like this:

{
(set: $fear to 0)
}

For any event that would affect that variable, you can call and change it on that passage.

{(set: $fear to it + 1)} 
Rest of the passage

And you can also use it to change what is visible to the player depending on the level of your variable (or if it is present, what its value is, etc.) using a bit of Javascript

{
(if: $fear > 2)[what you want to show up [[link to the next page]]]
(elseif: $fear >=1) [what you want to show up with this [[link to another page]]]
(else:)[remaining option [[link to still another page]]]
}

There are so many more things that you can do with the variables that are really only limited to what you could imagine/figure out how to create.

### [CSS](http://www.dhs.state.il.us/accessibility/references/css-quick-reference.html)
Depending on the style that you have chosen, you have to investigate exactly which elements to target within your story. For Harlowe, if you want to adjust globally, you have to use **tw-story** as your selector.

tw-story {
background-color: # HEXCODE;
color: # HEXCODE;
font-family: example;
}

Other styles of Twine (specifically SugarCube) allow you to select pages based on their tag that can be specified on the passage page. This sets their class that you can then use as the selector.

## Overview of Branching Scenarios
Branching Scenarios became popular in media starting with the Choose Your Own Adventure series (1979-1998) and then extending through the influence of tabletop role-playing games such as Dungeons and Dragons. This then evolved (co-currently) with the popularity of [DOS video games](https://classicreload.com/) such as ZORK, Oregon Trail, etc. More modern examples of games/media that rely on the same sort of input are: *Beyond Two Worlds*, *Mass Effect*, any game by Telltale studios (such as *The Walking Dead* or *Tales from the Borderlands*), and *Black Mirror: Bandersnatch*

:::info
Most board games are better at this sort of thing but require multiple people - *Betrayal on the House on the Hill*, *Fog of Love*, or any of the Legacy games (*Pandemic Legacy, Risk Legacy, One Night Ultimate Warewolf Legacy*) for example.
:::

Branching scenarios are occasions where the user is allowed to give input in the direction that the story takes. In practice, it means that the player/reader *feels* that the choices that they make have an outcome on the end story. The important thing to note, however, is that none of these games actually allow the player/reader to have full control of the story.

I like to imagine it like a parallel world theory - each choice produces a copy of the world that branches away from the original. Importantly, this means that the rest of the story can (and usually does) run parallel in the exact same way regardless of the choice. The more of this type of media you consume, the more you realize that your choices don't actually matter that much, as the stories almost always converge at the end for the sake of storytelling. Usually the choices are pretty much irrelevant to the greater plot but have some sort of an emotional component attached to them to make them *feel* important to the player (i.e. which character remains alive).

Preserving the integrity of the story is the most important thing to note regarding creating for Branching Scenarios. You must make sure that every branch leads to a satisfying conclusion and that the arcs that the character follows makes sense *for each scenario*.

## Basics of Coding Branching Scenarios
Coding Branching Scenarios relies largely on the if...then... type of logic. Basically, you create a series of scenes or scenarios and them link them together in a way similar to adaptive release.

For Example, lets say you have 5 different scenes:

* Scene 1
* Scene 2
* Scene 3
* Scene 4
* Scene 5

In an ordinary story, these would progress in a linear fashion

s1=>start: Scene 1
s2=>operation: Scene 2
s3=>operation: Scene 3
s4=>operation: Scene 4
s5=>end: Scene 5

s1->s2->s3->s4->s5

In a story with branching scenarios, you would see something more like this:

s1=>start: Scene 1
s2=>operation: Scene 2
s3=>operation: Scene 3
s4=>operation: Scene 4
s5=>operation: Scene 5
cond=>condition: Did you Pick Scene 2?
e=>end: End A
e2=>end: End B

s1->cond
cond(yes)->s2->s5->e
cond(no)->s3->s4->e2

Thus making the choice that you made in Scene 1 affect the path that the story heads to next.

When a user goes through, for example, a Twine story their path could be

OR 

as long as each of the scenes makes sense in where they are placed.

As you can guess, this leads to a LOT of scenes to sort through and organize. Twine does this in a couple of ways.

The first is through Arrays. Arrays are coding language for an object that holds a series of objects (folders within folders, if you will). It creates a database of sorts that you can then make a command to parse through in order to find and retrieve a specific element.

So, here is our new array (in Javascript):

var scenes = 
[
"Scene 1", 
"Scene 2", 
"Scene 3", 
"Scene 4", 
"Scene 5"
];

Using this, if we have a selectable element in our HTML, we can create a function to find and produce one of our scenes from that array:

function findScene(){
if (elementClicked.value === "Scene 2") {
document.getElementById(scenes[1]).style.display = 'block';
} 
}

This function basically tells the computer to find the value of whatever element that was clicked, and, if it is exactly "Scene 2", to then find the element with the matching id (in HTML) and display that.

To make this work on a more universal level, we have to add a lot more information to our array, our html (not shown), and our function.

var scenes = 
[
{name: "Scene 1",
id: "sceneOne",
links: "Scene 2", "Scene 3"},
{name: "Scene 2",
id: "sceneTwo",
links: "Scene 1", "Scene 4", "Scene 5"},
{name: "Scene 3",
id: "sceneThree",
links: "Scene 1", "Scene 5", "Scene 6"},
{name: "Scene 4",
id: "sceneFour",
links: "Scene 6", "Scene 7"},
{name: "Scene 5",
id: "sceneFive",
links: "Scene 7", "Scene 10"},
...
{name: "End",
id: "end",
links: "Scene 1"}
];

function findScene(){
for (i=0; i < scenes.length; i++)
if (elementClicked.value === scenes[i].name) {
document.getElementById(scenes[i].id).style.display = 'block';
} else {
document.getElementById(scenes[i].id).style.display = 'none';
}
}

This is a ***very*** simplified version of what is going on behind the scenes in Twine, but the logic follows. For this example, each of the scenes is a HTML element on the page that gets shown depending on which choice is clicked by the user. (not the way that Twine does it...see below for explanation on that) Here's a working version of it for reference.

The section of code called a for loop is what parses through the array to find the exact element that fulfills the if...then...logic as written below it.

In Twine, these elements are a lot more complicated and a lot more elegant. Each of the scenes that you create has its own page that is called forth (with an animation no less) based on the selection that you make. So the arrays for the scenes on a sample Twine look like this:

nav = new SceneNavigator(
[
 "startup",
 "self-choice",
 "day1-arrival",
 "day1-lunch",
 "day1-luggage",
 "day1-afternoon",
 "day1-dinner",
 "creatures",
 "day2-breakfast",
 "day2-moonwalk",
 "creatures-act2",
 "day2-lunch",
 "day2-exercise",
 "path-evacuate",
 "finale",
 "newending"
]
);

;hashes = {
 "scenes": {
  "choicescript_description.txt.json": "a6c098bddb0a5bf4a1522956bf54ebd8",
  "choicescript_stats.txt.json": "43f2483a68d1f6dba0bac9601cb4530c",
  "choicescript_upgrade.txt.json": "9bc9ef65ba0957d5f777cd107cbf144f",
  "creatures-act2.txt.json": "a76fd15369418b532418a8753ca6ec69",
  "creatures.txt.json": "fce4c5d22634725ec293715960a90603",
  "day1-afternoon.txt.json": "55f5ebe2fba3d9e982583c02011998b9",
  "day1-arrival.txt.json": "7575ef475f0ae339efe43b054d10560e",
  "day1-dinner.txt.json": "207736c2db3103e4ff038e78d22e3890",
  "day1-luggage.txt.json": "b8bb85ac15a9f4073177c46c41a2c55c",
  "day1-lunch.txt.json": "ef5feb74ee7581005e52bc3c3e7c027f",
  "day2-breakfast.txt.json": "267f3ee2e12c72c509f5a9e5d1b7a5ec",
  "day2-exercise.txt.json": "7e03f04751221747cfac0e32541f91b2",
  "day2-lunch.txt.json": "704a7222d6562f8fa736341b14847feb",
  "day2-moonwalk.txt.json": "2b07b35d4b14c9620881fb00b340a986",
  "finale.txt.json": "515d63e8b49020bdbc941285710520ce",
  "newending.txt.json": "52537580c93f0a4316bb22c60ffadab1",
  "path-evacuate.txt.json": "603e2841ee6bb6bbbadb37e96e2ceb97",
  "self-choice.txt.json": "e7a02b6d73a0200d04e373506c6ce5f5",
  "startup.txt.json": "2ebd92d5985c42f36a56fbd676e8fe71"
 },
 "icon.jpg": "7414c23b8f4e7e86feda73dd1c274756",
 "icon.png": "30d0a781d5b6bc3099ef13ee8b9b6338",
 "spacejoy.jpg": "fc0b73fd9fbde26876574f8e5dd083ce"
}

The first array is the list of the scene names, and the second one is the list of the "hash" that gets replaced in the URL to load the specfic page for that scene. The way that they do that is similar to a very easy to use javascript tool called Riot.js.

The functions that they have as the base navigation functions are these:

function SceneNavigator(sceneList) {
    this.setSceneList(sceneList);
    this.startingStats = {implicit_control_flow:false};
}

SceneNavigator.prototype.setSceneList = function setSceneList(sceneList) {
    this._sceneList = sceneList;
    this._sceneMap = {};
    for (var i = 0; i < sceneList.length-1; i++) {
        var scene1 = sceneList[i];
        var scene2 = sceneList[i+1];
        this._sceneMap[scene1] = scene2;
    }
    this._startupScene = sceneList[0];
};

SceneNavigator.prototype.nextSceneName = function nextSceneName(currentSceneName) {
    var nextScene = this._sceneMap[currentSceneName];
    //if (!nextScene) throw new Error("No scene follows " + currentSceneName);
    return nextScene;
};

SceneNavigator.prototype.getStartupScene = function getStartupScene() {
    return this._startupScene;
};

If you read through both, you can see how the little function we created works in a similar was (though very much less elegant and messier in the HTML).