Chapter 2: The Source Text
Part 1
Now we get into the meat of things!
Mostly this thread was tongue in cheek about reading the manual being like doing a let’s play, but yeah I do want to actually check out the example too!
In section 2.1: Creating the World, we get our first taste of actual content creation!
This section deals with the difference between ‘things’ and ‘rules’. As the author states:
A new Inform project is void and without form, so to speak, with nothing created: but it starts with hundreds of standard rules already in place.
This to me is one of the reasons I strongly prefer Inform over languages that are less strongly rule-based, like Adrift or Adventuron or even Twine. In Inform, if I make the assertions he gives as an example:
The wood-slatted crate is in the Gazebo. The crate is a container.
Mr Jones wears a top hat. The crate contains a croquet mallet.
Then I instantly can do all sorts of interactions: remove the hat, put it in the crate, etc. I realize that some of this is baked into those language I mentioned earlier, but as games get more complex, Inform and its related powerful languages like Dialog, Hugo, and TADS have an upper hand because they’re all about creating rules and less about creating objects.
(Feel free to disagree!)
I’d like to point out that I’ve never used or even known that you can assert things the way he does in the second line:
Mr Jones wears a top hat. The crate contains a croquet mallet.
I’ve always written it the other way around:
Mr Jones is a man. A top hat is worn by mister jones.
The crate is a container. A croquet mallet is contained by the crate.
So I’m already learning here!
And just to be clear about what I meant earlier about inform, typing these sentences above sets a lot of machinery in motion. For instance, I learned (as detailed in another thread) that saying something ‘wears’ something else automatically makes the first object a person and assigns them the male gender.
In section 2.2, we meet the first rule, the Ur-rule of the Inform manual:
Instead of taking the crate, say "It's far too heavy to lift."
This is appropriate for the first rule, since as John Ziegler recently pointed out, having custom messages for objects you can’t take is an important part of creating a sense of immersion.
The manual goes on:
We never see the complexity behind the scenes because the whole aim is to provide a basic, penny-plain, vanilla flavoured sort of realism. It would be surprising if one could put the crate inside itself, so a rule exists to forbid this. It would be surprising if one could drop something which was already on the ground, and so on. These basic rules of realism are the ones which every new Inform project starts with.
This is why I’ve often found it easier in Inform to start with a class of object that already exists in the game and modify it instead of making new rules for something out of scratch. For instance, staircases can be made as special doors that are always open and go up and down.
The steps to follow here are called “phrases”. Inform knows about 400 built-in phrases, but most of them are needed only occasionally. These three are used over and over again:
if tells Inform to do something only if some “condition” holds, here “the player is wearing the hat”;
now tells Inform to change the situation, here so that the hat moves to the crate; and
say tells Inform to say something, that is, to write some text for the player to read.
I’ve never thought of those as being all the same type of thing, but it makes sense now. Dialog does the same kind of thing, except instead of phrases it uses ‘predicates’, which are formed by placing two things inside of parentheses next to each other, which in context can be an if statement or a variable assignment.
Learning how to create my own phrases really helped over the years, and we’ll cover that later. For those familiar with programming, phrases essentially act like functions.
Phrase definitions are all linked to in the Phrases page of a project’s Index.
Really? That’s neat. I just checked it out, and it’s there! That’s so helpful. I wish I had seen this index years ago; there’s stuff in there I’ve searched intfiction or past source code so much for to get the phrasing right. Reading this manual is already paying off!
Section 2.3 is Punctuation. Here he mentions things like how full stops can go inside quotations without needing a stop outside:
The description is "Shiny." It is valuable.
is read as equivalent to
The description is "Shiny.". It is valuable.
I’ve noticed that, that I tend to get more errors about run on sentences when I don’t end in punctuation.
More specifically:
Sentence breaks like this occur only when the final character of the quoted text is a full stop, question mark or exclamation mark (or one of these three followed by a close bracket) and the next word begins, in the source code, with a capital letter. A paragraph break also divides sentences, behaving as if it were a full stop.
Then he mentions how brackets are used as comments when not inside of double-quotations and as ‘text substitutions’ when inside.
Single quotation marks at the edges of words are printed as double. So:
"Simon says, 'It's far too heavy to lift.'"
produces
Simon says, "It's far too heavy to lift."
This is a useful tool (and has led me to permanently struggle with whether to use single or double quotes when putting a word in quotations in written text). But of courses it causes lots of problems with plural possessives like
"the millers' tales"
which gets rendered as
the millers" tales
Okay, I’m going to do a big quote now about this next part:
- Texts which end with sentence-ending punctuation - full stop, question mark, exclamation mark - are printed with a line break after them. So:
say "i don't know how this ends";
say "I know just how this ends!";
would come out quite differently - this doesn’t affect the appearance of the text, but only the position where the next text will appear. Something to be careful about is that this only applies when the punctuation occurs at the end of a “say”, as in these examples. (It doesn’t apply when a varying textual value is printed, using some text substitution, because then the pattern of where line breaks occur would be unpredictable - sometimes the value might end in a punctuation mark, sometimes not.)
These three punctuation rules for texts feel very natural with practice, and Inform users sometimes don’t realise the third rule is even there, because it just seems the right thing to happen.
…
and Inform users sometimes don’t realise the third rule is even there, because it just seems the right thing to happen.
Anyway, moving on…
(Actually, before moving on, Inform is my favorite IF language, but this is the one thing I’ve struggled the most with. I’ve probably spent > 15-20 hours over all my projects combined dealing with weird whitespace issues. When I tried the Dialog language, I found I preferred Inform over it in most areas, but one of its major selling points to me is its perfect handling of whitespace. I never had to debug line breaks even once).
Anyway, back to the text! We have this mysterious comment which I don’t quite understand:
It also has the more exotic “|” (not a capital I, a vertical stroke) for paragraph breaks outside of quoted text, but people hardly ever need this.
If anyone can give me an example of this, I’d love to see one!
Section 2.4 is about ‘problems’, not in the general sense, but as the little helpful things that pop up when you compile. My style of programming usually results in 3-10 ‘problems’ every time I compile. Here is the example ‘problem’ given:
Problem. You wrote ‘A starting pistol is in the cup’ 
, but in another sentence ‘A Panama hat is on the cup’ : the trophy cup cannot both contain things and support things, which is what you’re implying here. If you need both, the easiest way is to make it either a supporter with a container attached or vice versa. For instance: ‘A desk is here. On the desk is a newspaper. An openable container called the drawer is part of the desk. In the drawer is a stapler.’
I know sometimes these problems can be unhelpful, but I find that they almost always resolve my problem quickly.
Next is one of my favorite sections: Headings!
Firstly, we can put the title at the top. If the first paragraph consists only of a single quoted piece of text, then that’s the title; and an author can also be given, as follows:
"Spellbreaker" by Dave Lebling
But this isn’t the type of heading I’m talking about. I’m talking about this:
A sentence which is the only one in its paragraph and which begins with any of the words “volume”, “book”, “part”, “chapter” or “section” is considered to be a heading or a sub-heading. It must not contain a typed line break, and in order to stand alone in its paragraph there should be a skipped line both before and after it. For instance:
Section 2 - Flamsteed's Balloon
I find this incredibly useful for organizing my code. It makes it easy to hop back and forth and also serves as an outline that I can sketch out and then fill in. My current project is filled with a bunch of empty Volumes and Books and such to represent different areas of the game, where Chapters are for individual rooms and Sections for individual NPCs or important objects.
Section 2.6 explains why section headings are important:
*They’re used in ‘problem’ reporting when compiling
*They’re used in the ‘index’ to allow quick travel (and I should mention they also create separate webpages when releasing your source as an html file)
*Inform allows you to refer to objects by part of their name (like ‘the yellow dog’ can be called just ‘dog’). When compiling ambiguous code (perhaps you refer to ‘dog’ when there is also a ‘red dog’), instead of throwing an error, the compiler assumes by default that you meant the object of that name in the heading nearest your current code.
In section 2.7 we’re getting to the debug commands. I don’t use these very often, so this will be useful!
This sections introduces SHOWME, a ‘godlike’ command that only shows up in the IDE, and not when hitting ‘release’.
The testing command SHOWME prints out a brief summary about a room or thing, and any contents or parts it may have. Typing SHOWME on its own shows the current room, but any item or room in the story, however distant, can be named instead. For instance:
>showme
Boudoir - room
four-poster bed - supporter
yourself - person
pillow
>showme diamonds
diamonds - thing
location: in the strongbox on the dresser in the Drawing Room
unlit; inedible; opaque; portable; singular-named; improper-named
description: The diamonds glitter dangerously.
printed name: diamonds
I almost never use that.
In 2.8, though, we get the TEST command, one I use all the time. This is ‘unit testing’ (I think, I’ve never actually figured out what that means), but it lets you check that a certain set of actions in your code works. I use it to make sure the game is still winnable after making changes.
It is an alternative to the skein:
All the same, most works of interactive fiction contain occasional vignettes, either in terms of short scenes of narrative, or in the behaviour of particular things or rooms, which we would like to test without the fuss of using the full story-level Skein tool. The examples in the documentation are like this: in almost every example, typing TEST ME puts the story through its paces.
Testing commands show up in all of the inform examples. I first used them when I created an Inform extension for the first time.
You create testing sequences like this:
Test balloon with "get balloon / blow balloon / drop balloon".
This has no effect on the design itself, but ensures that when the story is played, typing “test balloon” will run through the given three commands in sequence, as if we had typed “get balloon” and then “blow balloon” and then “drop balloon”.
You can also nest testing scripts:
Test all with "test balloon / test door".
I have dozens of testing commands. For each puzzle I have one, and if a room has multiple puzzles, I have a bigger one for each room, then a bigger one for each area, and then one mega one.
Finally, there’s a little cheaty command:
Sometimes when testing it’s convenient to get hold of something not easily available at the moment. The testing command “PURLOIN” does this:
The jewelled Turkish clockwork hat is in the sealed glass box.
Section 2.9 is brief. It basically gives you a way to add more cheater code for debugging.
If you add the words ‘not for release’ after a section, it makes that section’s code disappear when ‘releasing’. Here is an example:
Section 10 - Open sesame - Not for release
Universal opening is an action applying to nothing.
Understand "open sesame" as universal opening.
Carry out universal opening: now all doors are open.
Report universal opening: say "Open Sesame!"
I haven’t really used this before, and I do have some cool meta-testing commands (like printing every description in the game). But leaving that in might be fun to find as an easter egg…IDK.
2.10 is about extensions. I’ll be honest, I almost always avoid extensions. I just don’t like them. I’d rather code the thing myself. The only times I use them are when they’re something that essentially should or could be core Inform functionality (like Emily Short’s Locksmith or the Numbered Disambiguation extension by Aaron Reed).
I have written my own extension for conversation, since I was copying it from game to game anyway, but I don’t think anyone else has ever used it.
Extensions are in a weird spot. There is an official extension website, official github, and official way to download directly from Inform IDE, but if I recall some of those or obsolete, nonexistent, or give outdated extensions, and I’m not sure which is which.
For those not aware of what extensions are, it’s just a way of splitting up code into separate files. You could just as well copy the extension’s code directly into your text, but using extensions allows you to keep it neat and tidy.
2.11 says how to include extensions, which is fairly easy once they’re in the right folder:
Include Locksmith by Emily Short.
Next, in 2.12, are the ‘Use’ options. I first learned about these when I was copying Emily Short’s Glass code for my first game.
These are global options for the game that you invoke at the beginning. Here are some options highlighted here:
Use American dialect.
Use the serial comma.
Use scoring.
Use full-length room descriptions.
Use abbreviated room descriptions.
Use VERBOSE room descriptions.
Use BRIEF room descriptions.
Use SUPERBRIEF room descriptions.
Use undo prevention.
Some of these overlap (VERBOSE and full-length are two ways of saying the same thing).
He mentions about UNDO prevention (and I have to agree):
(Many players consider UNDO to be their birthright, and that any work using this option is an abomination: indeed, it has even been suggested that this section of the Inform documentation be censored. To use the option is to court controversy if not outright hostility.)
Fortunately for me as a player, even if someone codes in UNDO prevention, there are special interpreters that have their own built-in UNDO, and it’s impossible to fully remove UNDO from an inform game.
(I was going to split this update over two posts but a lot of these sections are short).
2.13 is ostensibly about administering classroom use. But it really comes down to two small things.
The first is that you can add a text file called ‘options.txt’ in the Inform home folder that will run code in every single game file you compile on that computer. It only works for use options, test commands, and release instructions.
The second thing is that you can add ‘use telemetry recordings’ at the top of a game file (or in options.txt) to send all of its outcome and problem messages to a txt file in the folder. He adds:
Telemetry only records the contents of the “Problems” panel - notes of success or failure, and problem messages - and nothing is transmitted via any network, so it isn’t really surveillance. The user can deliberately add a note to the current telemetry file by writing something like this in source text:
> * "I don't get it! What's a kind? Why can't the lamp be lighted?"
(This is a way to make a note for the benefit of someone who will read the telemetry file - for instance, to comment on a problem message that has just appeared. Note the double-quotes. Otherwise, it’s meant to look like the standard way that beta-testers mark up IF transcripts.)
Has anyone used this before? That would be interesting. Apparently they’re due to requests from teachers using Inform in the classroom.
Section 2.14 is formats: glulx versus z-machine. Here are the two described:
Newly created projects are set up with the Glulx format. This has largely taken over from an earlier format called the Z-machine, but Inform can still generate a version 8 Z-machine file (a so-called “z8”) if required. The Z-machine is of historic importance, and may continue to be useful for certain tasks where Glulx support is not yet available, but most users will want to keep the Glulx format set all of the time.
Of course, right now there is a big retro movement (as seen in the PunyJam), where the z-machine has seen increased emphasis.
The z-machine has inherent memory limits that cannot be overcome.
Section 2.15 is about bug reporting, for which instructions are given here:
The final section in this chapter is 2.16: Does Inform really understand English?
The answer is, of course, no.
Here is an example of understood code vs not unerstood code:
For instance, Inform understands
something which is carried by the player
but not (at present, anyway)
something which the player carries
He also gives:
an example which genuinely arose in beta-testing:
The life support unit fits the egg.
in which Inform construed the verb as support and not fits, and then created items called “the life” (plural) and “unit fits the egg”.
And that’s it for Chapter 2!
This chapter was both fun and disappointing. Fun, because I learned about the phrases index, and disappointing, because there were a ton of technical details, very technical ones in fact, and we haven’t reached a single example yet! This style seems more suited to math textbooks (which I love to read), that start out with the precise foundations of things at very theoretical level before outlining the individual steps. Perhaps the recipe book will be more friendly for starting off a game.
Next time we’ll pick up with the chapter on Things!
- A simple example, fairly easily guessed.
indicates that more detailed information can be read further down the text in the same panel: clicking it jumps down to this more detailed report.
hints that there is a relevant page of this manual: clicking this opens the Documentation panel and switches to it.
