aka "The Messy Learning Process"

Programs change over time, so this is all being done with Twine 2.1.3 Sugarcube 2.18.0 around July 2017, for version tracking.

It was a strange combination of thinking about things and reading a few different websites that led me to my project: to port the “Lone Wolf” adventure book by Joe Dever into Twine. I loved all of the “choose your own adventure” books as a kid, and I had a lot of them (wish I still did, youth never appreciates what it's got). Recently I found Project Aon, a group that received permission from Joe Dever, author of the Lone Wolf series, to put his books online. You can read the books in a web browser, merrily hyperlinking from passage to passage.
    But, Lone Wolf does have something of an RPG-like ruleset, you have stats and skills/abilities and inventory - all of which is kind of tricky to do in plain HTML and JavaScript - which the Project Aon books are in. There is a flash-based “Statskeeper,” which looks pretty cool - but at the same time I heard about a program called Twine, which was made for creating interactive fiction in HTML/JavaScript, and is pretty robust.
    For some reason, I decided to port over the first Lone Wolf book, Flight From The Dark, into Twine and learn about how the program worked. With the material already written, I would save myself that longest part and just focus on the programming and mechanics. After getting a little ways into it, and finding just how few good tutorials there are for Twine/Sugar Cube I decided to write down my experiences. Thus, here we are.

    Now, am I a Twine expert? Do I know what I'm doing? Well, no. Again, I'm writing my experiences, so I'm sure that there are better/ more efficient/ more logical ways to do the same things. This advise is worth exactly what you paid for it.

    So far, I managed to get just about every passage from the book into Twine (I'm sure I missed a few, there are several hundred) - so now I have the framework of what needs to happen. Next, I'm going to start a new story and just focus on getting the mechanics to work. I'm going to screenshot everything and post my code as I go. Project Aon's licensing agreement includes you not redistributing or altering their work - so I'm not going to post or show the whole story; I'm just going to put some snippets here to show how Twine handles this kind of book. So, let's open Twine (downloaded from their website here). You could even write everything online from their website, but your work will be stored in your browser, so if you clear your browser's cache or switch to another browser (or another computer), you'll loose your work. So I recommend downloading it like I did.

You can see the story I started, and the whole-buncha' passages in it (all the red dots). Let me start a new story for this ‘tutorial’/journal. First, Twine does come with several formats for the interactive elements, so a reminder that I'm using SugarCube (since the code I'm going to share won't work in the others, of course). On the front page if you click on the right side where it says "Formats" you'll see the available formats and which one you're using...

Let's give our new story a title...

And now we have our blank story. The green rocket says that passage is the starting point.

By double-clicking on it we can edit it...

   We can name passages whatever we want, spaces are okay but case matters. Tags are something I didn't think about using at first, but now I've started tagging passages that have interactive elements (like skill checks or inventory items) since I do believe I can do a search for them to make it easier to keep track of which passages will need code. All of this is really HTML and JavaScript, so tags can also be used to target CSS or scripting or such (which I'll talk about more later).

     Okay, I'm not going to do a full interduction/ walkthrough right now - I'll highlight some things while I'm working - so let's jump into what we need to do.

     Lone Wolf is really a mini-RPG, and my challenge is to replicate all that here in Twine. So what all do we need to code?

• Attributes - there is Combat Skill and Endurance. Both start with a fixed number with a random bonus, and they'll need to be tracked throughout the story.

• Skills/abilities - there are 10 special skills, and the player chooses 5. Some passages will call for a skill, and other times they'll be in the background or a part of combat.

• Inventory - there is actually quite a bit of ‘stuff’ in the book. You can have up to 2 weapons (one in each hand), there is some armor (head and body slots), most items go in the Backpack (which only holds 8 max), there's a coin pouch, and a few special items that don't take up any space. And all items do something, of course, sometimes chosen by the player and otherwise by the story.

• Combat - is thankfully simple, there are just the two stats and a table to reference, but can be modified by items and the story; there are times when the player can try to escape, and I'll need to figure out how to 'rewind' on death if the player doesn't want to roll a new character.

     It's not a huge list, which is a big part of why I chose this story to covert to Twine, but it should require some quick-thinking and a few lines of code. Okay, so where to start? Well, let's go with the story itself and work alongside it.

Setting The Character Attributes / Stats

Here's my first section, and the mechanics I'm implementing from the book.

The Game Rules
    You keep a record of your adventure on the Action Chart.
    During your training as a Kai Lord you have developed fighting prowess—COMBAT SKILL and physical stamina—ENDURANCE. Before you set off on your adventure you need to measure how effective your training has been. To do this take a pencil and, with your eyes closed, point with the blunt end of it onto the Random Number Table. If you pick 0 it counts as zero.
    The first number that you pick from the Random Number Table in this way represents your COMBAT SKILL. Add 10 to the number you picked and write the total in the COMBAT SKILL section of your Action Chart (i.e. if your pencil fell on the number 4 in the Random Number Table you would write in a COMBAT SKILL of 14). When you fight, your COMBAT SKILL will be pitted against that of your enemy. A high score in this section is therefore very desirable.
    The second number that you pick from the Random Number Table represents your powers of ENDURANCE. Add 20 to this number and write the total in the ENDURANCE section of your Action Chart (i.e. if your pencil fell on the number 6 on the Random Number Table you would have 26 ENDURANCE points).
    If you are wounded in combat you will lose ENDURANCE points. If at any time your ENDURANCE points fall to zero or below, you are dead and the adventure is over. Lost ENDURANCE points can be regained during the course of the adventure, but your number of ENDURANCE points can never go above the number with which you start your adventure.

Okay, so we need 2 main stats - Combat Skill and Endurance. Combat Skill starts at 10 and Endurance starts at 20, both get a bonus between 0 and 9. Let's start by setting the variables to their default state...

<<set $CombatSkill to 10>>
<<set $Endurance to 20>>

Now, I could abbreviate the names, so I don't have to type so much- but I'm going to keep the full names to remind me what is what, and make it as easy as possible for others to read. I am going to copy and paste them to make sure I don't goof up the spelling and cause an error down the road. I could also set the values with '=' instead of ‘to’, potato potahto ;)
Next, I need to add the random numbers to the bases...

<<set $CombatSkill to $CombatSkill + random (0, 9)>>
<<set $Endurance to $Endurance + random (0, 9)>>

     The ‘random’ macro will default to a minimum of 0, so I could have used random (9) and gotten the same results, but again I want to be as explicit as possible.
     Now, I need a button or link for the player to click on to set the final scores, and I want to print out those scores for the player to see - plus I might want to keep those visible somewhere. I'm not sure yet, somehow I want the player to be able to see their character sheet - I just don't know if I want it always visible in some way or a link to call up. Thinking about that.
     Let's just worry about getting the numbers working, after I look at the whole character I'll decide how I want to display everything (after all, having working code means I can just cut-and-paste stuff into the right look/format later). I'm going to create a new Passage and throw in some descriptions.

Your training has covered two broad areas, your ability to fight (Combat Skill) and your physical strength and toughness (Endurance).

Combat Skill is used to determine who has the edge in a fight; the higher your skill compared to your foe, the more likely that you will damage them without taking damage yourself.

Endurance is your health, when it reaches 0 you are dead.

Now, what I want is to write some text, then have the player click on that text and it will generate the numbers. So I'm going to use the <<click>> macro, which does something on a click. Okay, first my text:

Let's find out how your training has progressed.

I'm going to make the word “training” the thing to click on, set the final values (base + rand), and display those values at the bottom. I'm going to put a lot of whitespace in my code so I can read it easily (and make sure I get all my closing tags in the right places).

Let's find out how your
<<click "training">>
<<set $CombatSkill to $CombatSkill + random (0, 9)>>
<<set $Endurance to $Endurance + random (0, 9)>>
<<replace #start_att_show>>
Your Combat Skill is $CombatSkill. Your Endurance is $Endurance.
<</replace>>
<</click>>
has progressed.

<<Click>> is kind of funny, what you want to be clicked on is in “ ” in the macro. So <<click “training”>> makes the word ‘training’ click-able, I don't need to write it within the sentence. I add my randoms to my already-declared variables, then I trigger the <<replace>>. This will, duh, replace something. My target is #start_att_show, which is the ‘id’ to the below. That is blank, so the blankness is what will be replaced with my text and values. I could call the <<print>> macro to show the values (ie, Your Combat Skill is <<print $CombatSkill>>. Your Endurance is <<print $Endurance>>.) but that is pretty cumbersome.

Also, is HTML, <<click>> is a macro, note the single vs double greater/less-than-signs.

Let's see what we get:

Here's the starting page.

Then, after we click on training.

Cool. We got the line to show up. But, something else could happen...

Woah, Combat Skill and Endurance of 44 are a bit higher than the rules state. Problem is that the link keeps working even after you click on it, so you can keep clicking and adding to your values. We should fix that. What I need is for the word ‘training’ to go from the thing to click on to start the macro to just plain text. How? Well, with another <<replace>>.

This one's a bit tricky though. The <<click>> macro has the word ‘training’ in it, so I'm going to have to wrap that entire macro in another like I did for the output. Here's the updated code.

Let's find out how your

<<click "training">>
<<replace #training>>training<</replace>>
<<set $CombatSkill to $CombatSkill + random (0, 9)>>
<<set $Endurance to $Endurance + random (0, 9)>>
<<replace #start_att_show>>
Your Combat Skill is $CombatSkill. Your Endurance is $Endurance.
<</replace>>
<</click>>

has progressed.

Okay, so the bracket soup tripped me up a few times, I kept forgetting to double them. Each time I ran and got an error I had to look carefully at the number of 'than-signs.' Finally got it written right though, now after the click...

...'training' turns into text and no more runaway ability scores. Okay, so everything is now working the way I want, last step is the cleanup. All the blank spaces are pretty ugly, so we need to tighten that up. I could just delete the spaces and make one run-on block of text and code, which would be fine (it's not like the computer cares). I do want to keep this as a reference and release it for others to learn from though, so I want to keep the spacing to try to make things more human-readable. Which means I'm going to use the <> macro, which will remove the line breaks around the code when the page gets displayed. That makes my final code (for the whole page) this...

<<set $CombatSkill to 10>>
<<set $Endurance to 20>>

Your training has covered two broad areas, your ability to fight (Combat Skill) and your physical strength and toughness (Endurance).

Combat Skill is used to determine who has the edge in a fight; the higher your skill compared to your foe, the more likely that you will damage them without taking damage yourself.

Endurance is your health, when it reaches 0 you are dead.

<>
Let's find out how your

<<click "training">>
<<replace #training>>training<</replace>>
<<set $CombatSkill to $CombatSkill + random (0, 9)>>
<<set $Endurance to $Endurance + random (0, 9)>>
<<replace #start_att_show>>
Your Combat Skill is $CombatSkill. Your Endurance is $Endurance.
<</replace>>
<</click>>

has progressed.
<>

And the pre- and post-clicks look like this...