I made the offer to write some exercises to teach python programming at OSCON, specifically in the form of being able to create a "choose your own adventure" style game using python. So, here we start! By the end of this first entry, you will be able to write a basic "choose your own adventure" computer game, even if you've never written a line of code before.

OK, there's dozens of ways of doing this, so we have to pick one. One place to start is to look at what the thing you're trying to emulate looks like.

What does a choose your own adventure look like?

Well, it's essentially a book, divided into lots of micro-chapters - at most 1.5 pages long, normally 1-3 paragraphs in length. Each paragraph has the following:

• It is typically numbered and you start at section "1"
• The section says where you are, tells a microstory, that ends with a choice point.
• That choice point then allows you to move on to another part of the story

So, let's begin.

As a word of warning, this will start out gently, perhaps a little patronising, but hopefully with enough humour or bizarreness to offset that. The reason it might seem patronising is because I really want to point out some really important points, and without understanding those, everything else falters. However at the end of this first tutorial you will write your first adventure game, and don't worry, it will be simple.

The tutorial for sake of getting into the spirit of things, the tutorial is in the second person. This is YOUR adventure!

Prologue

You are sitting at the computer looking dumbly at the screen. You ponder your decision to decide to learn to code wryly, and realise that it might not've been such a bad idea after all. You decide to download python, and give it a go.

You go to http://www.python.org/download/ and grab a version suitable for your OS (unless you already have it installed because you have a recent Mac, or a modern Linux install) and install it.

The first program you are asked to run looks like this:

print "Hello, you are in a small dark room"

Unimpressed, but determined to follow the instructions, you open up a Terminal window, then load up the python interpreter:

~> python
Python 2.4.2 (#1, May 2 2006, 08:13:46)
[GCC 4.1.0 (SUSE Linux)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>>

You type the code in, and press return, and are singularly unimpressed by the result:

>>> print "Hello, you are in a small dark room"
Hello, you are in a small dark room

That said, your lack of awe with regard to this fills you with hope. You realise that this programming lark might not be as difficult as some people make out.

The Lobby Scene Begins....

"AAARRRGGGHHH!", you think, "I'm late!" - as you remember that this is your first day at yet another job of the kind that you're hoping to use your hoped to gain programming skills to get out of. You're starting a new day as a receptionist at the local hotel, though thankfully only for postal & messages tasks. You remember the hassle you got last time when you were on the front desk and all those people from that open source conference were visiting - what a nightmare that'd been - everyone complaining about the wireless!

You arrive at work, some 10 minutes later, and after 20 minutes of waiting are thrown straight in.

In front of you is a large collection of old style pigeon holes on the wall. All 256 are numbered, though oddly starting from 0 all the way to 255. Puzzled by that you pass it by. Next to the collection of pigeon holes is a register which should contain a list of the surnames of the people staying in which rooms. You note that some rooms have multiple surnames associated with them. Since it's not the 1900's you're not particularly surprised by this!

You do for a moment wonder though - why's the story taken a turn for the moment towards hotels, pigeon holes, and surreptitious weekends away when the story should be related to teaching programming through adventures...

"WHAT ARE YOU DOING DAYDREAMING", shouts the concierge at you. "HAVE YOU FORGOTTEN WHY YOU'RE HERE?"

Suddenly you realise you have forgotten what you're doing. You decide to make a note on the notebook in front of you to remember what you're doing - you're taking messages and giving them back when requested.

Your First Assignment

A customer comes up.

"Ahh, your first assignment", says the concierge.

"Hi! I'd like to leave a message for Mr Message", says the customer.

You think this is a very odd name for a person, but reply "OK, sure, let me just check his room number". You consult the register and find that he's staying in room 5. You grab the slate board from pigeon hole 5, whilst thinking briefly how strange it is to be writing notes on slate boards, but hey, maybe the hotel management isn't really that bright, or just stick to simple things they trust.

"OK, ready, what's the message", you say.

"OK, the message is 'Hello, you are in a small dark room' ", the customer replies.

You pause for a moment thinking how strange this is - after all this was the message the tutorial you were reading suggested.

Undeterred, you say "sure, no problem", and write "Hello, you are in a small dark room" on the slate for the room that Mr Message is staying in, and store the message "Hello, you are in a small dark room" back in Mr Message's pigeon hole.

Strangely, the mysterious glyphs ...

>>> message = "Hello, you are in a small dark room"
>>>

... appear in mid air, burning like fire, but as cold as stone. There is a clarity about the phrase. It is trying to get you to understand something. Something about what you are doing in the hotel lobby storing a message, and what looks mysteriously like something you'd see on a python prompt.

You ponder for a moment what could possibly be similar between the code ...

message = "Hello, you are in a small dark room"

... and putting the text "Hello, you are in a small dark room", in a pigeon hole associated with a Mr Message?

A wry observer sitting the hallway nods sagely and realises that whilst such a description may be patronising, he's seen many a novice stumble over this initial step.

He walks forward and says: "Think like Daniel - the Karate Kid. How many times did he wax on, wax off, on those cars? When did he learn Karate? Was he merely polishing when he was hitting his opponents? or was he fighting those cars instead of polishing them? Sometimes realising that you already understand something is merely a matter of recognising that it is really no different from something you already know."

You pause. Pop reference. Telling you something you already know, but telling it to you in a way you hadn't expected. Australian accent. Hmm. Nah. You move on.

Then you realise - the old man was right. If taking a message for a man named "message" and placing it in a pigeon hole was an easy and obvious thing to do, something you'd seen a 100 times, then that was precisely what ...

message = "Hello, you are in a small dark room"

... means. It means taking a piece of information, storing it away somewhere, merely referenced by the name message.

Access All Areas

"PAY ATTENTION", shouts the concierge again. "DON'T YOU SEE THAT SOMEONE IS HERE?"

"Oh, sorry", you reply.

"Yes, I'd like to access my messages"

"Access my messages", you think, "how strangely these people in silicon valley speak. Maybe they've spent too long near their computers". However, you reply "Of course sir, name?"

"Message", he replies

For a moment you pause, you were about to ask "yes, but I need your name". However you realise that this is actually Mr Message - you remember that he does actually have a message.

You glance at the register, looking for the name "message", finding again that he's in room 5. "How could I forget that? That was like just a moment ago?". Shrugging, you grab the slate from pigeon hole 5 - and find "message" has the message (hmm, that's a bad turn of phrase you think) - that "message" has the value "Hello, you are in a small dark room".

You declare to Mr Message, "Your message reads, 'Hello, you are in a small dark room'".

As you do so, again those firey, cold, and compelling letters come into the fore again, but this time it's different:

>>> message
'Hello, you are in a small dark room'

Mr Message seems happy with this news, and wanders off. Presumably he just wanted to hear what was left in his box, and didn't actually want to do anything with it.

At this point in your thoughts you see the old australian again look up at you, give you a piecing look, and a smile that suggests that there is something here again. However all he says is, "Look at you figuring it out! You snake!".

Realisation - Revelations in a Lobby

More puzzled than before you wonder, what can he mean? Snake? What can be the relationship between a man coming up to you, saying "message", and you replying " 'Hello, you are in a small dark room' ", and the interaction on the python interpreter of:

>>> message
'Hello, you are in a small dark room'

You pause.

You think.

Then you smile.

The old man is trying to draw your attention to the fact that your role in the hotel lobby has been akin to that of the python interpreter. You have been the python - you have been the snake. Once you have been the snake there is no going back. From now on when ever you see the following on the python interpreter

>>> message = "Hello, you are in a small dark room"

You will think of the lobby. You will think of the pigeon holes, each with a slate that can hold only one message - only one value. You will remember the register on the desk beside the pigeon holes, and remember that it allows you to look up a pigeon hole from the name you're given. You'll remember that when you see:

>>> message = "Hello, you are in a small dark room"

That you will look up the room "message" is staying, grab the slate from the pigeon hole for "message", write the value "Hello, you are in a small dark room" on the slate, and then put the slate back.

Furthermore, you'll also remember that if someone merely requests the value associated with message, that is if you see:

>>> message

That they're not necessarily interested in doing anything with the value, they're just after the value.

You'll remember it's like someone coming up to the counter and saying "message" (or rather messages for Mr Message, but you filter out the boring parts), and that when they do that you look up which pigeon hole contains what they're after. You'll remember that you simply reply with the value in their pigeon hole.

Indeed, so patronising do you find the whole idea, you realise that the person behind the counter could be replaced with a little robot instead who merely sits there storing values for names, and when asked for values by name it replies with those values.

As a result, by this stage you think that the following is now painfully obvious to you:

>>> message = "Hello, you are in a small dark room"
>>> message
'Hello, you are in a small dark room'

You realise that "=" has nothing to do with mathematical equality (mind you, neither does gender equality!) as you learnt in school, and whilst there is a link, the reality is that what this...

>>> something_memorable = "some thing"

... really means is take the value "some thing", and store it in a location for safe keeping that we can come back to later and label that place "something_memorable". When asked for the value "something_memorable", by simply mentioing it's name:

>>> something_memorable

... we'll look at the location assocaited with "something_memorable", find the value "some thing" and merely return the value.

Your First Adventure

Excited, you realise that this actually is enough for you to get started with your first adventure!

OK, maybe it'll be a bit manual right now, and lets face it this will be a bit un-exciting as a first version, but hey, we need to learn to crawl before we can run right? And heck, we'll be able to translate all those old choose your own adventure books at this stage (but not those more fun Fighting Fantasy ones perhaps ! ;-).

You figure that surely the later steps in the tutorial will be about making this less manual, so you give the person writing this tutorial a break - after all this is about getting started as quickly as possible.

You do cut them a break, don't you? ;-)

So without further ado, we revisit what a choose your own adventure is - it's a collection of sections - all numbered - much like the rooms. Each section is a passage of prose, finishing with a little statement of where to go next.

Get a room!

You then figure. "Hmm. I can do that already. What would the first room look like. You excitedly open up your python interpretor and bash out your first section excitedly:

>>> one = "You are in a small dark room. You can see a dim light coming from the north and south exits. Type two to go south, and three to go north"

You sit back and think "It can't be that simple can it? There's all that choice stuff in those books?! They seem so complex? So rich? It can't be as simple as this". However your next step is to try it. What does it look like, can it really be this easy?

>>> one
'You are in a small dark room. You can see a dim light coming from the north and south exits. Type two to go south, and three to go north'

You sit back, stunned.

This is exactly what you wanted! (or said you wanted :-) OK you think, let's go north, I wonder what is north. You see that the instructions are "to go north, type three". So you do just that.

>>> three
Traceback (most recent call last):
File "" line 1, in ?
NameError: name 'three' is not defined

Oddly however, you notice that your computer is also shouting this at the top of it's lungs in a voice that sounds remarkably similar to that of the concierge. At this point, you remember the hotel lobby. What if someone had come up to the desk earlier today and asked for messages for "Mr Three". There were no messages for "Mr Three", and furthermore, no "Mr Three" had ever checked in.

You realise that you're being unfair - the computer is a poor little dumb beast - it can't take a single value and create a whole adventure, it's just not that good. You need to provide it the adventure yourself. You take a heavy sigh, computers are dumb. They're very good at remembering things if you tell them things and something to remember them by, but you have to remember what you called those things.

Write your own Adventure

Expectantly, you sit back for a moment wondering what the author of this tutorial is thinking. Are they really expecting you to fill in the rest of the adventure yourself?

Suddenly, as if by magic some hints fall from the sky in the form of more activity on the python prompt:

>>> two = "You have entered a clearing. It is a warm and sunny clearing, and you hear birds chirriping, and children playing in the south. You smell the strong familiar scent of coffee to the east. To go east, type four. To go south type five. To return north, type one"

>>> three = "You are in a maze of twisty passages all alike. You continue on for a while and the passageway branches to the right. To continue straight on type three. To turn right type six. To turn back, type one"

Now seeing what the idea is, you copy the text out, into a text editor, and format it over 3 lines to look like this:

one = "You are in a small dark room. You can see a dim light coming from the north and south exits. Type two to go south, and three to go north"

two = "You have entered a clearing. It is a warm and sunny clearing, and you hear birds chirriping, and children playing in the south. You smell the strong familiar scent of coffee to the east. To go east, type four. To go south type five. To return north, type one"

three = "You are in a maze of twisty passages all alike. You continue on for a while and the passageway branches to the right. To continue straight on type three. To turn right type six. To turn back, type one"

Excitedly you copy and paste these three lines into an open python terminal. You decide to start your adventure, head south, then north, enter the tunnels, and return back the way you came:

>>> one
'You are in a small dark room. You can see a dim light coming from the north and south exits. Type two to go south, and three to go north'
>>> two
'You have entered a clearing. It is a warm and sunny clearing, and you hear birds chirriping, and children playing in the south. You smell the strong familiar scent of coffee to the east. To go east, type four. To go south type five. To return north, type one'
>>> one
'You are in a small dark room. You can see a dim light coming from the north and south exits. Type two to go south, and three to go north'
>>> three
'You are in a maze of twisty passages all alike. You continue on for a while and the passageway branches to the right. To continue straight on type three. To turn right type six. To turn back, type one'
>>> three
'You are in a maze of twisty passages all alike. You continue on for a while and the passageway branches to the right. To continue straight on type three. To turn right type six. To turn back, type one'
>>> three
'You are in a maze of twisty passages all alike. You continue on for a while and the passageway branches to the right. To continue straight on type three. To turn right type six. To turn back, type one'
>>> one
'You are in a small dark room. You can see a dim light coming from the north and south exits. Type two to go south, and three to go north'

Happily you sit back, you realise that now it could be just a matter of translating a story into a number of assignment statements, entering those into the interpreter, sitting back and enjoying the results.

Get Some Exercise

Suddenly a storm cloud comes over the horizon, and you sit, worried. How can I avert this, and you realise there is only one way - you have to get some exercise - you have to write your first version of the adventure. Yes its trivial right now, and actually writing the adventure might actually be the harder part here, and you notice that your existing code is decaying and dying. The principles of that code remain in your mind - associate a section with a name starting with one. In the prose of the section associated with that name state "To do X type <sectionname>", and for all the section names include some text.

Some suggestions spring to the screen.

• Imagine you are writing a choose your own adventure computer game set around discovering the body, entering at the mouth. Some example possible sections:
• one - "You are in the mouth. Would you like to look around (type two), go down the throat (type three), or open a vein and dive in (type four) ?"
• two - "You don't see anything particularly interesting and decide to: go down the throat (type three) or open a vein and dive in (type four)."
• etc
• Imagine you have a time machine that can materialise and dematerialise at any point (or points) in time and space. You start off in your local city and time (one), and from there on have the choice of traveling through time (two), space (three) or both (four).
  

This is clearly the first exercise, and is actually a fair amount of work, though largely creative. It's worth noting here that being silly is probably a good idea, since it'll a) be more fun b) probably create a larger volume of text and sections to be working with. Certainly this tutorial is longer than I anticipated due to the slightly whimsical tone :-) I'd suggest at least ten sections, but no more than 20. When you're done, it'd be really cool to see different answers posted as replies to this blog entry. I'll hold back moderating replies with answers as public for about a week, and then make them public.

In case no one actually posts any answers, I'll post a set of answers as well!