Alice: An Inform tutorial, part 3Alice: An Inform tutorial, part 3"Now, if you'll only attend, Kitty, and not talk so much, I'll tell you all my ideas about Looking-glass House."
Several years ago, Gareth Rees used the idea of writing an adventure based upon Lewis Carroll's Through the Looking Glass to produce an excellent Inform tutorial;
Doug Atkinson then extended the game, but didn't provide any accompanying
text. In my version of Part Three, I offer more words but less substance,
discussing the process of developing the game as a whole (planning, testing,
debugging, modifying code).
You will need to have read Gareth Rees' tutorial to get the most from this one. In some sections I talk about general principles, then use Alice as an example; the "Alice-Head" (visible at the beginning of this introduction) shows where I get down to specifics.
"It seems very pretty," she said when she had finished it, "but it's rather hard to understand!" (You see she didn't like to confess, even to herself, that she couldn't make it out at all.)
Every author has their own preferences for code layout, file use, text style, and so on; shared projects such as this one cause difficulties when the people working on it have differing opinions. If working as a team, the co-authors need to agree on a compromise solution; when writing serially each must work with what they are given, but for the duration of their "tenure" have complete control.
Doug Atkinson's looking.inf,
written for Inform 5.5, is 758 lines long. It is short enough that I could
reformat and reorganise it completely if I wished (1,000 lines is about my
limit) so I have a free hand.
The result of this is alice5.inf, which functions just the same as before but is easier for me to read.
"Now here, you see, it takes all the running you can do, to keep in the same place. If you want to get somewhere else, you must run at least twice as fast as that!"
It is all too easy to make an innocent-seeming code change in order to get one puzzle to work (or just to make the code cleaner), only to find out much later that it has some entirely unintended consequences elsewhere. By the time you discover this you will frequently have forgotten what you changed.
Avoiding this is a very important part of any programming project, and whole books have been written about "regression testing" -- the art of making sure that adding new features does not break old ones. The process can be extremely tedious if the developer has to do it by hand -- nobody wants to go back over old ground when there are new vistas waiting -- and it is often quietly forgotten, leading to long periods of even more painful debugging later.
Happily, IF authors have an ideal tool for automating this: the transcript. With only a little self-discipline you can double-check your work after each change, no matter how small. [This ideas is suggested in the Fourth Edition DM, section 7, but in small type -- in my opinion it deserves a little more emphasis.]
When initially testing your code, type the following three commands (assuming you're using the standard library) before doing anything else:
recording on
random
script on
'Recording on' starts capturing your commands to a file, 'random' makes sure that any random events produce consistent results, and 'script on' starts capturing the output of the program. Perform the actions you wish, then end with
script off
recording off
You have now generated two important files, the command log and the output log (what they are called will depend on your interpreter). These are your reference files.
For Alice, I did this with the version compiled by Doug Atkinson using Inform 5.5, producing a command file and transcript.
I read the source first to get an idea of what results were intended, then
tried to exercise as much of the code as possible without going overboard.
When you have compiled new code, you can run the same command sequence using
replay
-- which will generate a new output log. You can then use a file comparison utility (such as 'diff') to see what has changed. If everything is as you expect, all well and good (and the new transcript becomes your "reference copy"); otherwise you may wish to investigate further.
I recompiled Doug Atkinson's code (now renamed Alice4.inf) using Inform 6 and ran the previously-created command file, producing another transcript. Comparing the two is interesting:
5 <! Release 1 / Serial number 951029 / Inform v1502 Library 5/12 D 6 <! Standard interpreter 1.0 7 <! Interpreter 6 Version F / Library serial number 951024 !> Release 1 / Serial number 010904 / Inform v6.21 Library 6/10 SX !> Standard interpreter 1.0 (6F) / Library serial number 991113
The banners differ. This is expected, although under normal development only the first line would have changed (and that only on the first compilation of the day).
63 <! You wouldn't want to catch a chill, would you? Better leave the window shut. !> You wouldn't want to catch a chill, would you? Better leave the window shut.
I would almost certainly have overlooked this (and the several other instances) if checking by hand. I have a command set up in my editor to run the Inform compiler; this loads "default.icl", a set of compile options I always use. One of these instructs Inform to contract double spaces after full stops, which was presumably not used in the original build of "looking.z5".
Examining the code I find that there are inconsistencies in the use of single or double spaces after full stops, so it looks like a good idea to keep this option (although I will also consider tidying up the source file).
195 >give her to black 196 <! I'm not sure what "her" refers to. !> (the red queen to the black kitten) 197 <- 198 <- >give queen to black 199 You toss the red queen onto the floor and the black kitten scampers after it. 200 201 The white kitten jumps into the ball of worsted and gets tangled up in a mess of 202 threads. (197) -> (198) -> >give queen to black !> (first taking the red queen) !> You toss the red queen onto the floor and the black kitten scampers after it.
This is interesting. I thought that the red queen not being recognised as "her" was a bug in the game, but it turns out to be a problem with Inform 5.5. This is good, because it's one less thing to fix. Not so good is the fact that this particular bug messes up the random messages from now on; I'll ignore the resulting differences.
226 >put it in chair 227 <! You need to be holding it before you can put it into something else. 228 <- 229 <- The white kitten purrs contentedly to itself. !> You need to be holding the arm-chair before you can put it into something else.
This is just a case of the Inform 6 message being more informative. Checking the whole transcript shows that I had just been talking about the white kitten; the problem is to do with pronouns, and is already on a list of bugs presented toward the end of the first tutorial.
Considering I didn't change any code there were a lot of differences to investigate. Nothing has changed for the worse, however, so I'll make the Inform 6 transcript my new master and continue.
Adding new tests to the end of a script is easy. Replay the original, then type 'recording on' and make sure you write the command log to a different file. Perform the actions you wish to add, then end with 'recording off'.
You now have two command scripts. Open them in a text editor and copy the contents of the new one, (excluding the final 'recording off' line) into the first, just before the 'script off' line. This is actually quicker to do than to explain! The last step is to replay it; the transcript produced should be the same as before except for the extra material at the end.
Changing scripts can be harder, but has to be done sometimes (for instance, when you change the actions needed to complete a pre-existing puzzle). There are a few ways to tackle this:
"While you're refreshing yourself," said the queen, "I'll just take the measurements." And she took a ribbon out of her pocket, marked in inches, and began measuring the ground, and sticking little pegs in here and there.
I have now spent some time looking at Doug Atkinson's additions to the code
in order to reformat it, and to work out what to put into my original transcript.
I think
I know what he was aiming for, but if you are out there, Doug, I welcome
corrections. In this section I shall quickly run through the state of the
game then introduce a couple of new code techniques.
The original tutorial built up a puzzle from the first scene of Chapter One, making use of as many items mentioned in the text as possible; Part Two will take the action up to the end of Chapter Two using the same methods. Items available in the Looking-glass room include the chess pieces moving around in the hearth, the table, the Jabberwocky book, and the White King's memorandum-book and pencil. Also mentioned in passing are a bottle of ink, a clock with an old man's face, and animated portraits. The outside scenes add only a few objects, all owned by the Red Queen -- biscuits, a measuring ribbon, and pegs.
The puzzle here will be learning how to move about in Looking-glass Land. In the book this is merely a case of befriending the Red Queen by talking to her politely, but such puzzles are extremely tricky to implement well. We'll incorporate an element of that by preventing the Queen talking to you before you curtsey, but otherwise we'll use object-manipulation as before. Perhaps the queen needs to write down the instructions, and you need to provide her with a pencil -- which you can get from the White King after he's finished making his memorandum about being lifted onto the table. As a final twist, we'll have the note be in mirror-writing -- the Jabberwocky book can be a clue that you need to hold it up to the mirror to read.
Most of the code for the objects (including characters such as the White King and Red Queen) should be readily understandable to anyone who has worked through the original tutorial, and examining it is left as an exercise for the reader.
This is the first time we have had to deal with character speech, and we need to decide how they should speak. While it might be satisfying to take all such speech from the text of the book, doing so is too limiting; we could use a modern style, which is easy to write, but this will certainly sound odd in context. We need to bite the bullet and aim for a "pseudo-Carrollian" style (including oddly-spelled words, such as "ca'n't"), even though this is tricky to maintain.
This brings us up-to-date.
One of the advantages of a virtual machine with a text-based format is that programs written with Inform can be run on a wide variety of computers. Unfortunately this also means that certain features (such as colour) may or may not be present. One thing that varies a lot is screen width.
I noticed when reformatting that two places had hard-coded line breaks: the triple row of asterisks when you pass through the window (reminiscent of the original book) and the centred text for the poem "Jabberwocky". Each supposes a screen width of at least 72 characters, and would probably look best with 80.
[to be continued]
"A pawn goes two squares on its first move, you know. So you'll go very quickly through the Third Square--by railway, I should think--and you'll find yourself in the Fourth Square in no time. Well, that square belongs to Tweedledum and Tweedledee--the Fifth is mostly water--the Sixth belongs to Humpty Dumpty--But you make no remark?"
"Now, Kitty, let's consider who it was that dreamed it all."
This page originally found at http://www.elvwood.org/InteractiveFiction/Alice/Alice3.html
Last updated: 14 March 2002
