Quick Start Guide

TO ADD: test the machine - really, really old ones might not work
TO ADD: block a "put"
TO ADD: one-way connection
TO ADD: pair a one-way w/ a block
TO ADD: intransitive verbs
TO ADD: transitive verbs
TO ADD: multiple actions

Introduction

This page is a guide to teaching Interactive Fiction (aka Text Adventures) with JIFFEE, aimed at those who have a basic familiarity with personal computers and the web, but who do not consider themselves to be programmers or computer geeks. Specifically, this will walk you through setting up a computer for developing a JIFFEE game, writing the game, and playing it. The focus here is purely on technical matters; organizing your classroom and managing your students is left entirely up to you. Note that these directions tell you how to set up a single system, but you'll need to repeat them for each system that a student will be using.

Because the majority of personal computers are running some flavor of Microsoft Windows, this guide assumes that's what you have. If you happen to have a Mac or Linux system you can still use JIFFEE just as easily, but you'll have to adapt some of the details slightly.

It is possible for multiple students to collaborate on a single game using separate computers, but it requires extra overhead so this guide does not cover that. Although collaboration can be a useful addition to the student experience, it's just too much to cover in this guide, and there is another version of JIFFEE planned that will make it much easier anyway.

Basic Concepts

JIFFEE has been designed to keep administrative overhead to an absolute minimum. There are only a few basic concepts that you and your students will have to deal with:

The basic user interface of your computer.

For most of you, this will be Windows. You don't have to be an expert, but this guide assumes that you already know how to do the really basic stuff like getting the system turned on, viewing a web page, and finding and moving files around on your disk.

A text editor.

In order to edit your file, you need a text editor. I strongly recommend choosing the simplest editor you have available on your system, and specifically recommend against using a word processing system like Microsoft Office or Open Office because by default they add a lot of junk to the file that will break your game.

On a Windows system, "Notepad" works very well. On Ubuntu Linux, I use "gedit". For a Mac, any similar program will work fine. If your editor needs to be told what kind of file you have, tell it to use plain text or plain ascii.

A browser.

All JIFFEE games run inside a browser. JIFFEE is compatible with just about any modern browser (Firefox, Safari, Chrome, Internet Explorer, or Opera) and it doesn't matter which one you use to play the game. However, for developing your games I recommend using Firefox because it is widely available, runs about the same way everywhere, and especially because it has decent debugging capability right out of the box.

The game file.

Everything required for a JIFFEE game is included in a single file, formatted as plain text (no special word-processing stuff) to make it easy to edit and compatible with just about every computer you can find. Most of this file will be the JIFFEE library, which is a lot of "boilerplate" that neither you nor your students will ever have to look it. There are comments near the top of this file which say "YOUR GAME BEGINS HERE" and "YOUR GAME ENDS HERE", which is the only part you care about — that's where you put your game code.

How to Play Interactive Fiction.

Before you can write or teach Interactive Fiction you need to understand the basics of how the genre works. The best way to learn this is to play through a game, which you can do by pointing your browser at: http://jiffeegames.com/games/sunny-day/sunny-day-en.html. That should be enough to get you started, but if you want more information about Interactive Fiction then please check out the Links page on this website.

Setting up Your System

First make sure you have Firefox set up. Many systems already have this installed, but if yours doesn't you can install it easily by going to http://www.firefox.com and following the instructions there which apply to your system. (In some cases you may need administrator privileges to do the installation.)

Now configure your text editor. For Notepad, the following settings are convenient:

Finally, you need to download an empty game. Point your browser at http://jiffeegames.com/src/example-game.html, then in the browser menu do a "File -> Save Page As", and give the saved version the name you want to use for your game. Be sure to use a name which ends in ".html" to avoid confusion later on.

At this point, it's a good idea to do a quick test to verify that everything is set up correctly and working the way it should:

Adding the First Place

We're going to gradually add things to this empty game until we have something a bit more substantial, but we'll do it in small steps. The first step is to add a place of our own and give it some colorful descriptions. To do this, delete the two existing lines in the game which refer to "beginning of my new game", and replace them with the following 4 new lines:
places.describe("cabin",
"You're outside the cabin.",
"You are standing outside a small, rustic cabin.  The door is secured with a padlock and the windows are shuttered.  The basic structured is sound, but the wooden walls are heavily weathered and the roof is covered with a thick layer of dry pine needles.  It's been a long time since anyone slept here.");
traits.set("player", "location", "cabin");

By the way, I advise you to "play along" here by starting up an editor and browser window and actually following these directions instead of just reading them. If you want to save yourself some typing, just copy-and-paste the relevant lines from the browser into the editor.

The first instruction here ("places.describe") provides the internal name of the place ("cabin"), a short description of the place, and a long description of the place. The long description will be displayed whenever a player reaches a place for the first time, and the short description will be used after that. If the player types the "look around" command, the game will display the long description again.

The second instruction ("traits.set") specifies where we want the player to be when the game first starts up.

Notice that it's OK to break up an instruction across multiple lines, so long as you do it after a punctuation mark. However, it's not OK to break up a quoted string. Those must be typed all on one line. Your editor will display the words on the next line, but you must not press ENTER while typing a string.

Testing Your Changes

Never add lots and lots of code and then test it all at once, because computers are extraordinarily picky and the more things you change at once, the harder it is to locate your mistakes. Instead, add just a few lines and then test:

This is the first place where things can go wrong. You might get a red error message, or it might even be the case that nothing at all seems to happen when you click Reload. This usually means you've made a syntax error, for example not matching your quotations marks or parentheses correctly. Whenever you see such suspicious or puzzling behavior, the first thing to do is open the error window: If your message says "unterminated string literal", it means you forgot a quotation mark somewhere. The line Firefox shows you isn't always the line where the error occurs, but it will give you a good hint. Once you fix the error, repeat the Save/Reload/diagnose/repair cycle until the game seems to start correctly.

If everything was already OK, go ahead and deliberately delete a quotation mark just so you can see what happens, and then fix it.

Adding More Places

An adventure isn't usually very interesting if you stay in one place (although there are some surprising and creative exceptions to this rule), so let's create some more places for our game by adding the following lines to the game file, right after the existing lines:

places.describe("forest",
"You're in deep forest.",
"You are wandering deep in an endless forest of tall pines.  Far above you the sun is shining brightly, but little of that light filters down through the branches to the forest floor.  The ground feels spongy beneath your feet, cushioned by a decades-long accumulation of fallen needles.  The air is still and there is no sound.");
places.describe("lake",
"You're on the shore of the lake.",
"You are standing on the shore of a very large lake.  The far shoreline appears to be at least five miles away, and the lake stretches out of sight to the west.  The water is calm, rippled only by an occasional gentle breeze, and a swarm of bees is busy at work in a thick patch of yellow and white water lilies which is growing a few yards offshore.");
places.describe("river",
"This is the north bank of the river.",
"You are standing along the north bank of a river.  It's only about 20 feet wide, but the water is rushing over granite boulders so fast that it would be foolish to try to cross it.  When you dip your hand into the water, it's icy cold as if fed by melting snowpack.");
(This is where you can start encouraging your students to use their imagination and practice their creative writing skills.)

Go ahead and run through the Save/Reload cycle to test this. You won't actually be able to move from one place to another yet because you haven't said anything about the spacial relationships between places, but you want to at least check for syntax errors before you get any further.

Now that you've tested that code, let's connect the places together so the player can move around. For this, I urge you to draw a map so you can keep track of what you're doing. (This is a great place to introduce map-reading and map-making skills to your students.) For this simple example, let's arrange our four places like this:

+----------------+
| cabin | forest |
+-------+--------+
| lake  | river  |
+-------+--------+
We describe this in JIFFEE by adding these lines:
places.connect("cabin", "north", "lake");
places.connect("forest", "north", "river");
places.connect("cabin", "west", "forest");
places.connect("lake" , "west", "river");
This places the cabin to the north of the lake, etc. The game infers the reverse directions, e.g. it automatically knows that the lake is to the south of the cabin. However, you do need to specify a connection for every pair of places between which you want to allow direct movement, so it won't currently allow you to move directly on the diagonal, e.g. from the cabin directly to the river. If you want to allow that, you need to add two more lines:
places.connect("cabin", "northwest", "river");
places.connect("lake", "southwest", "river");

Now do your Save/Reload cycle, making sure that the game can at least start correctly. Once you are that far, you can start functional testing:

If the game does not behave as you intended, you'll have to look carefully at which part is not working, then look carefully at the piece of code which handles that and try to see what's wrong. For example, if something about the "cabin" is malfunctioning, look at the lines of code which include "cabin" in them.

There is in fact such an error in this game. Did you find it? If you didn't, it means that you aren't testing thoroughly, which means testing everything. Try going to the lake and then move northeast. That should take you to the forest, but it doesn't, so look at the line that is supposed to describe that path. That line says that the lake is southwest of the river, but it's supposed to be southwest of the forest. This is a very typical type of mistake (and it's even a real one; I promise I did not put it there on purpose), so go ahead and fix it and then continue testing.

Adding Props

We now have a functioning skeleton of a game, but it's still pretty dull. Let's add some props which can be picked up and carried around. The syntax here is very similar to adding places, except that there are more things to specify: Let's add a key, and we'll leave it in the forest for the player to find. (Later on, we might want to make the key open the padlock on the cabin.) Here are the lines of code you need to add to your game file:
props.describe("key",
"forest",
"A key lies on the ground here.",
"A key nestles in your pocket.",
"This is an average-looking brass key, a bit green and weathered but it still appears quite serviceable.  It could fit almost any kind of lock.");
(JIFFEE is deliberately rife with opportunities for students to work on language skills. Here you could point out why the key "lies" instead of "lays".)

Adding overrides

Sometimes you'd like a command to fail with an interesting message. For example it might be impossible to move in a particular direction, or be inadvisable to pick up a prop. You can do this by overriding the default action, like this:

props.describe("rock",
"forest",
"There's a big rock here.",
"unused",
"A glacier must have left this rock here, because it's at least 4 feet across and must weigh several tons.  It appears to be granite, with a few igneous intrusions of quartz and feldspar.");

traits.set("rock", "get", "Don't be ridiculous, you'd put yourself in the hospital if you tried to pick up this monster.");

props.describe("fish",
"lake",
"A dead fish rots nearby.",
"unused",
"This fish has obviously been here for days.  It might have been a bass, but the flesh has rotted so badly it's hard to tell for sure.  The smell is enough to choke a goat.");

traits.set("fish", "get", "Eeeeeewwwwwww!  That's sooooooo disgusting I won't even discuss it.");

traits.set("river", "south", "The opposite shore looks tantalizingly close, but the rocks are too slippery and the current too treacherous.  You'd better look for a safer place to cross.");

Adding Verbs

Tracking Down Errors

The hardest part of programming in general, and of JIFFEE in particular, is often tracking down errors. Once you know what's wrong it's usually not too hard to fix the error, but finding where the error is can be difficult and frustrating.

One trick that can be helpful is to "comment out" pieces of code. If you suspect a chunk of code is causing a problem, you can surround it with a /* and a */ and try loading the code again. By gradually moving around the /* ... */ you can narrow down the exact line that is causing trouble.

Add more stuff here about debugging.

One of the nastiest errors occurs when you are editing the game file, and you accidentally modify (i.e. corrupt) the boilerplate that you're not supposed to touch. Of course you'd never do that on purpose, but accidents happen and sometimes you don't even realize you've done it. Because of this, if all else fails and you just can't figure out what's going on, try loading a fresh copy of the empty game file and then copy your code into it. If there was any corruption of the boilerplate, this will fix it.

Distributing and Publishing Your Game

What you now have is a standard HTML file. You can play it from your local disk, you can send it as an attachment in email, or you can write it to a flash-drive or a CD to transport it. It is also in just the right format to post it on the web, which can be done in many ways but here is the simplest way I know of: