Writing with Inform

1. Welcome to Inform

Welcome to Inform, a design system for interactive fiction based on natural language.

Interactive fiction is a literary form which involves programming a computer so that it presents a reader with a text which can be explored. Inform aims to make the burden of learning to program such texts as light as possible. It is a tool for writers intrigued by computing, and computer programmers intrigued by writing. Perhaps these are not so very different pursuits, in their rewards and pleasures.

The sheer joy of making things... the fascination of fashioning complex puzzle-like objects of interlocking moving parts and watching them work in subtle cycles... the delight of working in such a tractable medium. The programmer, like the poet, works only slightly removed from pure thought-stuff. He builds his castles in the air, from air, creating by exertion of the imagination. (Frederick P. Brooks, "The Mythical Man-Month", 1972)

Writing with Inform is one of two interlinked books included with Inform: a concise but complete guide to the system. The other book is The Inform Recipe Book, a comprehensive collection of examples, showing its practical use.

These notes are arranged so that the reader can, in principle, write whole works of fiction as early as the end of Chapter 3. Each subsequent chapter then extends the range of techniques available to make livelier and more intriguing situations.

Today's Inform language (sometimes called "Inform 7") is very different from its 20th-century predecessor, which was called Inform 6. A few advanced sections of this book show how unusual effects can be achieved by mixing low-level coding in Inform 6 notation with more usual Inform text. However, most users will never need this. For information about Inform 6, see inform-fiction.org.

This book is also a guide to the Inform language, rather than a manual on how to use its supporting tools. Those tools, when used at the command line rather than inside the Inform app, have numerous features not covered here. Manuals for them are all available online: see github.com/ganelson/inform.

Programming is best regarded as the process of creating works of literature, which are meant to be read... so we ought to address them to people, not to machines. (Donald Knuth, "Literate Programming", 1981)

Example

An explanation of the examples in this documentation, and the asterisks attached to them.

Inform 7 is dedicated to Emily Short and Andrew Plotkin, whose shrewd and sceptical suggestions made a contribution which can hardly be overstated. A long email correspondence with Andrew entirely subverted my original thoughts about natural-language IF, as he convinced me that the "new model" of rule-based IF was a truer foundation; while Emily's wry, witty analysis and how-about-this? cheered me at low moments, besides providing the impetus and often the specifics for a lot of the best ideas.

From the outset, I have thought of Inform 7 as no longer being a command-line compiler, but a compiler in combination with a humanising user interface. All credit for the reference implementation under Mac OS X belongs to Andrew Hunter. How simple the metaphor of an interactive book with facing pages may seem, but the coding was an enormous challenge. In 2014 Toby Nelson, my brother, put months of time into the project by rewriting and modernising the Mac OS X application: sandboxing it for the Mac App Store, giving it a more contemporary design, and much more. He continues to maintain it today.

Though David Kinder's Windows application does indeed visually follow the OS X original, the two programs were coded independently, and the programming task taken up by David was formidable indeed. Philip Chimento's Gnome-based user interface for Linux became officially part of the project in November 2007, when the first easy-to-install packages for Ubuntu and Fedora were offered. Adam Thornton gave invaluable assistance in the closed-source age of Inform to make generic Unix binaries available, too.

While Inform is not strictly speaking a project of the Interactive Fiction Technology Foundation (IFTF), it benefits enormously from the Foundation's good work. In particular, the Narrascope conferences were invaluable in the period 2017-2022, and I thank Judith Pintar and Andrew Plotkin for arranging speaking slots at them.

Inform in its widest sense incorporates work by so many people that it's simply impossible to thank all of them, but Zed Lopez, Dannii Willis, Mark Musante, Brian Rushton, Dan Fabulich, Hugo Labrande, Erik Temple, Ron Newcomb, Eric Eve, Justin de Vesine and Juhana Leinonen all deserve special mention. Many hundreds of users have filed patient and careful bug reports, keeping us on the straight and narrow. They're contributors, too.

The original development of Inform 7 was a long haul, and I would particularly like to thank Sonja Kesserich, David Cornelson and other volunteers for their early testing of a then-fragile system. The final months before the Public Beta release of Inform 7 were made more enjoyable, as well as more productive, by fruitful discussions leading to a cross-platform standard for bibliographic data and cover art. Special mentions to L. Ross Raszewski, who wrote frighteningly efficient reference software in frighteningly little time; the librarians of the IF-Archive, Andrew Plotkin, David Kinder and Paul Mazaitis; and my fellow authors of IF design systems – Mike Roberts (of the Text Adventure Development System); Kent Tessman (of Hugo); and Campbell Wild (of ADRIFT).

At the start the only panels available are a blank space in which to write the first lines of a new interactive fiction – the Source panel – and this one, the Documentation. Clicking on the other choices will do nothing.

The exception is the Settings panel, which contains some preference settings for the individual project – not the whole application. This is always available, but it controls settings which can be left alone almost all of the time.

Clicking the Go button translates the text in the Source panel into a computer program which enacts the interactive fiction, and automatically sets it going (in the Story panel, which opens as needed).

If the Source is empty of text, Inform will be unable to create anything: it needs at least one name of a location where the drama can unfold. For reasons of tradition, such locations are normally called "rooms", though people have used them to represent anything from grassy fields to states of mind and other metaphorical places.

"Midsummer Day"
The Gazebo is a room.

Clicking Go with this text in the Source panel will result in a short delay, after which the Story panel will appear, from which we can explore this newly created world: an interactive fiction called "Midsummer Day". It will not be very exciting, since Inform has only five words to go on, but we can add more detail to the source at any point and then click Go again to try out the changes. (Note that there is no need to "quit" these explorations in the Story panel. When Go is clicked, any story already in progress is discarded in favour of the new version.)

Replay works identically to Go, except that it does something further: once the story is created, it automatically plays through the same commands as were typed into the previous version. For instance: suppose we click Go to bring Midsummer Day into being, and find ourselves playing the story. We type "look" and find that there is not much to see. Going back to the source, we add

"A white canvas parasol raised up on stakes driven into the grass."

so that the source now reads

"Midsummer Day"
The Gazebo is a room. "A white canvas parasol raised up on stakes driven into the grass."

Instead of clicking Go, we click Replay, and can sit back and watch what has changed. In this example, it only saves us the trouble of typing "look", but once stories become long and elaborate, Replay is invaluable: and especially when we notice in play that something very minor is wrong – a spelling error, say – and want to fix it immediately, without fuss.

If, when Go! is clicked, the text in the Source panel is not fully understood, then Inform will generate a report of the problems it found, which will open in the "Errors" panel. (Other information is also available in "Errors", but most of it is used for debugging Inform, and can be ignored.)

On the other hand, if the text was fully understood then another new panel will become available: the "Index". This is a cross-referenced index of the source, or rather, of the interactive fiction which has been generated. The Index is only an optional convenience, but becomes more and more helpful as the fiction grows larger. Its exact format does not matter for now.

The icon always denotes a reference to a particular line in the Source text, that is, to something written in the source: clicking it opens the Source panel and jumps to that position.

The icon 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.

Lastly, the icon hints that there is a relevant page of this manual: clicking this opens the Documentation panel and switches to it.

The Replay button demonstrates that Inform must be quietly remembering the commands typed into the last run through the story. In fact it remembers, and automatically organises, every previous run.

Inform's approach to testing interactive fiction is to treat it as being like the analysis of other turn-based games, such as chess. It would be prohibitively difficult to work out every possible combination of moves: instead, we analyse those which go somewhere, and look for significant choices. Every Queen's Gambit begins with the same first three moves (1. d4, d5; 2. c4), but then there is a choice, as the next move decides whether we have a Queen's Gambit Accepted (dxc4) or Declined (e6). Books about chess often contain great tables of such openings, which run together for a while but eventually diverge. To learn chess, one must explore all of these variations.

Inform's Skein panel is just such a table, built automatically. If we think of the list of typed commands as a thread, then the skein is (as the name suggests) braided together from all these threads. In the display, time begins at the top, with the start knot, and the threads of different play-throughs hang downwards from it.

Double-clicking on a command translates the source afresh and replays the story from start down to that command, and then stops. We are then free to continue play by typing commands into the Story panel, of course, and these commands will automatically be recorded in the Skein as a new variation of play, diverging from the previous threads.

The user interface for the Skein looks slightly different on different versions of the Inform apps (that is, the MacOS version is not quite the same as the Windows version, and so on), so this manual is not the best place to describe it. In any case, the best way to find out about it is probably to experiment.

2. The Source Text

Designing an interactive fiction can be divided into two related activities. One is the creation of the world as it appears at the start of play: where and what everything is. The other is to specify the rules of play, which shape how the player interacts with that initially created world. 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.

The same division between creating things, and laying down rules, is visible in Inform source text. The creation of the world is done by making unconditional factual statements about it. For example,

The wood-slatted crate is in the Gazebo. The crate is a container.

Inform calls sentences like these "assertions". The verb is always written in the present tense (thus the crate "is", not "will be"). Further examples are:

Mr Jones wears a top hat. The crate contains a croquet mallet.

The words "is", "wears" and "contains" are forms of three of the basic verbs built in to Inform. There are only a few built-in assertion verbs, of which the most important are to be, to have, to carry, to wear, to contain and to support. (As we shall see, further assertion verbs can be created if needed.)

The world described by these assertions is the starting condition of the story: what happens when play begins is another matter. If somebody picks up the crate and walks off with it, then it will no longer be in the Gazebo. Mr Jones may remove his hat.

The other kind of sentence tells Inform what should happen in certain circumstances, and reads like an instruction issued to someone:

Instead of taking the crate, say "It's far too heavy to lift."

This is a "rule", and it changes the crate's behaviour. The player who tries typing "take crate", "pick up the crate" or similar will be met only with the unhelpful reply "It's far too heavy to lift." The many different kinds of thing which the player can do are called "actions", and are always written as participles: "taking …", for instance, or "putting … on …".

Inform is built on a mass of several hundred rules, some quite complex, and it could even be said that Inform is that mass of rules. 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.

A rule always starts with a situation which it applies to, and then follows with one or more things to do. Here's an example where the situation is "Before taking the crate" – the player is just starting to try to pick the box up – and there's a three-step process to follow, but steps 2 and 3 happen only if step 1 comes out in a particular way:

Before taking the crate:
   if the player is wearing the hat:
      now the hat is in the crate;
      say "As you stoop down, your hat falls into the crate."

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.

Every one of the built-in phrases has a definition somewhere in this book. The full definition of "say" will come later, but in the simple form above it writes out the given text for the player to read. (Normally this text is simply shown on screen, not spoken aloud, unless software adapted for partially sighted people is being used.) Phrase definitions are all linked to in the Phrases page of a project's Index.

An example rule from the previous section demonstrates one of Inform's conventions about punctuation, and is worth pausing to look at again.

Instead of taking the crate, say "It's far too heavy to lift."

In English grammar, it's usual to regard a full stop as closing its sentence even when it occurs inside quotation marks, provided there is no indication to the contrary, and this is also the rule used by Inform. Thus:

The description is "Shiny." It is valuable.

is read as equivalent to

The description is "Shiny.". It is valuable.

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.

Material in square brackets [like so] is "comment", in computing jargon: it is considered as being an aside, a private note by the author, and not read in by Inform. This allows us to make notes to ourselves like so:

The China Shop is a room. [Remember to work out what happens if the bull gets in here!]

Inform is all about text, so pieces of text are often quoted in Inform source. This example is typical:

The description is "Shiny." It is valuable.

Quotations always use double-quotation marks, which aren't part of the text. So the description here is just the five letters and full stop in between the marks:

Shiny.

That seems straightforward, but there are three conventions to watch out for.

1. Square brackets [ and ] inside quoted text don't literally mean [ and ]. They're used to describe what Inform should say, but in a non-literal way. For example,

"Your watch reads [time of day]."

might produce

Your watch reads 9:02 AM.

These are called "text substitutions". They're highly flexible, and they can take many different forms.

2. 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."

3. 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. But occasionally the rules get in the way of what we want to do. (For instance, how do we get a literal [ or ]? What if we want a single quote mark where Inform thinks we want a double, or vice versa?) So we'll come back to these rules in more detail in the chapter on Text.

Inform also reads other punctuation marks. Colon ":" and semicolon ";" turned up in the previous section, in the writing of rules.

As these examples begin to show, Inform source imitates the conventions of printed books and newspapers whenever there is a question of how to write something not easily fitting into words. The first example of this is how Inform handles headings, but to see why these are so useful we first look at Problems.

See Also

How Inform reads quoted text for a fuller exploration of the punctuation rules for text.

The language used in the source reads as if it were English aimed at a human reader (and this is intentional: the designer, after all, is a human reader and needs to be able to understand his or her own source), but in reality Inform can only understand a very modest range of sentences and will complain if its limits are passed. Subtler problems arise if the source contains contradictions. For instance, the following "Problem" might be produced:

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.'

This is a rather discursive error message, and if a similar problem were to occur in the same run through, it would be curtailed to:

Problem. You wrote 'A firing pistol is in the box' , but in another sentence 'A fedora hat is on the box' : again, the croquet box cannot both contain things and support things.

Inform provides for us to organise the source code in just the way that a printed book would be organised: with headings and subheadings. 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

We will later see that more bibliographic information can also be placed here, in the same way that the imprint page of a novel comes before the text gets going. The author's name can normally be given without quotation marks, so long as it contains no punctuation. For instance:

"Three Men in a Boat" by "Jerome K. Jerome"

needs quotes as otherwise the full stop after the K will be mistaken for the end of a sentence.

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

Headings can be written in any format, provided they start with one of the five indicator words, and they are hierarchical: a "Part …" heading is considered more significant than a "Chapter …" heading but not so significant as a "Book …" heading, and so on. (We do not need to use all five kinds of heading.)

Reports of problems, as we have seen, often quote back the source to justify themselves. Rather than quoting line numbers ("Midsummer Day, line 2017" or something similar) Inform uses the icon. The down side of this is that a glance at the list of problems might give little hint of whereabouts in the source the difficulties lie. Inform therefore makes use of headings to give a general indication:

In Part the First, Chapter 1 - Attic Area:
Problem. You wrote 'South of the Attic is the Winery' , but in another sentence 'South of the Attic is the Old Furniture' : this looks like a contradiction, which might be because I have misunderstood what was meant to be the subject of one or both of those sentences.
In Chapter 2 - Deeper In:
Problem. You wrote 'The Disused Observatory is south of the Dark Room' , but in another sentence 'South of the Dark Room is the Cupboard' : again, this looks like a contradiction.

Secondly, headings are used in the Contents page of the Index, and they allow rapid navigation through the source, by jumping to any heading or subheading with a single click.

Finally, headings are used when working out what a name refers to. Suppose the source contains both a "four-poster bed" and also a "camp bed", and we write something like "The pillow is on the bed." Inform decides which bed is meant by giving priority to whichever is defined in the current section (so far), or failing that the current chapter, or current part, or current book, or finally the current volume. This allows us to write, for instance,

The four-poster bed is in the Boudoir. The pillow is on the bed.

and not have the pillow mysteriously turn up on the camp bed, which hasn't been mentioned since way back in Chapter 2.

Problem messages are generated when the source text does not make sense to Inform. Even if it does make sense, though, there is no guarantee that it does what the author intends, and the only way to find out is to test the result by playing through it (or asking others to). For the most part one plays as if one were the eventual reader of the work, but sometimes it is highly convenient to have the god-like powers which are an author's prerogative. These are provided by the testing commands, which are present at every stage until the final release version (generated by the Release button). They will be introduced in this manual as they become relevant: here is the first.

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

Much of this can be seen, and seen more easily, in the World tab of the Index panel: but that only shows the initial state of play, whereas the SHOWME command reveals the situation in mid-story. ("Room", "supporter" and so on are kinds, of which more in Chapter 3.)

See Also

High-level debugging commands for more convenient testing commands like this one.

The only way to thoroughly test a work of IF is to run a complete solution through it, and carefully check the resulting transcript of dialogue. The Skein and Transcript tools of the Inform application are provided for exactly this purpose.

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.

Solutions or sequences for testing ("scripts") can be defined with sentences like so:

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".

The name for the test (balloon in this example) has to be a single word. Typing just "test" at the story prompt gives a list of all the test scripts known to the story. Test scripts can make use of each other, for instance:

Test all with "test balloon / test door".

One convenient way to keep track of the solution for a work being written is to include a test script at the end of each section, and to place a master test script (like "test all") at the top of the source. But different designers will prefer different approaches, and this testing system is no more than an optional convenience.

Many tests will only be sensible in given places, which may be hard to reach from the initial position; or with the aid of given things, which may be difficult to obtain. We are therefore allowed to add stipulations to test scripts:

Test balloon with "get balloon / blow balloon / drop balloon" holding the balloon.

The "… holding the balloon" means that the balloon will be transferred to the player's ownership immediately before the test script is run, unless it is already held. Similarly:

Test jam with "get jam / taste jam / eat jam" in the Kitchen.

Or we might want to say both:

Test jam with "get jam / taste jam / eat jam" in the Kitchen holding the jam.

(Single quotation marks in test scripts are interpreted the same way in test scripts as they are in other text: that is, they are sometimes read as double-quotes unless they appear to be present as apostrophes. The notation ['] forces a single quotation mark if necessary. Similarly, [/] forces a literal forward slash, and prevents the / from being read as dividing up two commands.)

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.
> PURLOIN HAT
[Purloined.]

This can also make test scripts shorter, but of course it's important to make sure that people without PURLOIN powers can still play through.

Special testing commands, like "TEST" and "SHOWME", are automatically excluded from the story if it is exported from the Inform application using the Release button. We sometimes want to write our own for-testing-purposes-only code, though, and for this purpose we are allowed to designate whole headings as being "not for release":

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!"

Clearly we do not wish the final reader to be able to type "OPEN SESAME", so this whole heading will be disregarded in the Release version, as will any heading whose name includes "not for release".

Note that if a chapter, say, is marked as "not for release", then its subheadings (mere sections) will also not be for release. If in doubt, check the "Contents" index: if any section is "not for release" then so are all of its subheadings.

The reverse effect is produced by:

Section 10 - Open sesame - For release only

That is, it marks material included only in a Release version.

The original Inform of 1993 provided no special facilities for "extensions" – in effect, additional packets of rules providing extra features – but the creation and circulation of these extensions soon became a flourishing part of Inform culture. Today's Inform actively promotes sharing of such extensions, both to bring writers together and to support good practice. For the user of an extension, the advantage is clear: why go to great trouble to (say) work out how to make doors open automatically as needed, when somebody else has already perfected this? For the writer of an extension, there is the satisfaction of producing a good solution to a ticklish problem, and contributing to the public good.

Newcomers will probably not need extensions for quite some while, but there is nothing difficult about using them, so a few brief notes are worth giving here. (The final chapter of the documentation covers the writing of new extensions.)

Extensions are identified by name (say "Following People") and also by author (say "Mary Brown"). They need to be installed before they can be used, which means downloading them from the Internet. By far the easiest way to do this is to use the Public Library feature of Inform: then the application can do everything, letting us either choose individual extensions or download them en masse. But it's also possible to install extensions by hand.

In fact, though, Inform can automatically install extensions for us: we need only select the "Install Extension…" item on the File menu.

The actual extension file should always be named with a ".i7x" suffix, meaning "i7 extension" – for instance, "Following People.i7x".

To provide an example, Emily Short's useful extension "Locksmith" is one of a small number of extensions which come ready-installed as part of the basic Inform package, and need not be downloaded and installed.

Each time that Inform translates any source text, it performs a quick check of the extensions available, and updates its own internal records. A directory of the extensions currently installed can be found by clicking on "Installed Extensions" from the Extensions panel. This is also worth visiting in order to browse the Public Library, a selection of extensions contributed by Inform users.

We talk about "including" such an extension into a work of IF because the process merges rules and behaviours from the extension with those we have described ourselves. It's not uncommon for contributions by five or six different people to be pooled together this way.

Including an extension is only a matter of writing a single sentence in the source. For instance:

Include Locksmith by Emily Short.

Note that it is compulsory to name both extension and author.

Many extensions come with their own documentation. Again, follow the "Installed Extensions" link to see what's available from them.

One more preliminary. Inform has a small number of optional settings which affect the result of translating the source. The sentence:

Use American dialect.

makes the resulting work of IF use American spellings (except where the designer spells otherwise) and the American convention for spelling out numbers (thus, "one hundred seventeen" not "one hundred and seventeen"). Similarly:

Use the serial comma.

uses a comma when printing lists: thus "Julian, Dick, George, and Anne" rather than "Julian, Dick, George and Anne". A more profound change is made by

Use scoring.

which introduces the concept of a numerical score – something which modern authors of interactive fiction often feel is inappropriate, which is why Inform only provides it on request. Two alternative options:

Use full-length room descriptions.
Use abbreviated room descriptions.

change the normal way room descriptions are shown: normally they are given in full, but in abbreviated mode, they're never given. (The latter is a bad idea in any publicly released story, but is provided for completeness and in case it may help testing.) Alternatively, we can set the traditional Infocom-style of room description to any of VERBOSE, BRIEF and SUPERBRIEF:

Use VERBOSE room descriptions.
Use BRIEF room descriptions.
Use SUPERBRIEF room descriptions.

The default is now VERBOSE, but until 2010 it was BRIEF.

Next we have:

Use undo prevention.

which disables the UNDO verb, both in play and after death, for the benefit of stories which are heavily randomised and where we do not want players to keep on UNDOing until they get a random outcome which is to their taste. (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.)

We can combine any number of options in a single "Use" sentence, so for example:

Use American dialect and the serial comma.

brings about both of these changes.

Inform is increasingly used in education, where teachers sometimes need to install it on a whole room of computers at once, and want to monitor their students' progress. There is no special "classroom" version of Inform, but a couple of small administration features in the standard Inform – usually never needed – might be helpful to teachers.

When Inform starts up, it now looks for a file called Options.txt inside the user's home folder for Inform. (On Mac OS X, this is "~/Library/Inform"; on Windows, "My Documents\Inform", and so on.) If the file is present, then the text in it is added to the source text of everything Inform translates.

This must be used only to set use options, specify test commands, and give release instructions. For example, the following is a valid "Options.txt":

Use American dialect.
Test fish with "fish/fish with pole/angle".
Release along with source text.

The idea is that this file can be used for setting up a standard configuration on multiple machines in a classroom setting. Here the instructor can make sure the Release button will do what she would like, and can arrange for each student's copy of Inform to respond to given Test commands: for instance, if the class has an assignment to create a simulation of a camera, the instructor could set up "Options.txt" so that TEST CAMERA would run through some commands the camera ought to respond to.

A new use option, "Use telemetry recordings.", causes Inform to copy its outcome and problem messages to files in its home folder (see above) as they occur. These files are dated, so that for instance

Telemetry 2009-03-25.txt

contains all of the recorded activity on 25 March 2009. 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.)

These two features have been added in response to requests from education users. Let's suppose that Mr Lebling, who teaches 5th grade in Minnesota, wants to set things up just right for his class. He installs Inform on the ten computers they will use, and also copies an Options.txt file from his memory stick onto each one. The Options.txt file reads:

Use serial comma.
Use American dialect.
Use telemetry recordings.

Now Mr Lebling's class won't be confronted with English spellings, and so on. And most of the kids are happy, but Mr Lebling gets the feeling that young Marc wasn't really paying attention, so after class he checks that day's Telemetry file for that computer to see what Marc was up to, and whether he was stuck on something.

No computer has unlimited capacity, and a large, complex project may eventually bump its head against the ceiling.

Inform is a system for translating textual descriptions of interactive fiction into "story files". No single format of story file is standard to the IF community. The formats developed over the history of IF differ in three key respects:

- the range of computers or devices capable of playing them;
- how large they are, that is, how much play they can express;
- what extra-textual effects they can bring off.

Inform can write to two different formats. Neither of these is proprietary, and neither was created by the authors of Inform: each format is a community property, defined by published standards documents. An individual Inform project can make its own choice of story file format, using that project's Settings panel. Outside the Inform app, Inform can even be used at the command line to generate C programs rather than story files, and those can be compiled to run on almost any computer.

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.

Internally, the Inform application uses a tool called Inform 6 (which was once the entire Inform system) as the final stage in manufacturing the story file. Inevitably, though, this can go wrong if the story is so large or complex that it exceeds some fundamental limitation of the current story file format. This is only likely to happen with the Z-machine format, since Glulx has a huge capacity; so the cure here is to switch to Glulx in the Settings. But if that's not possible for some reason – say, if we want a story file playable on a tiny handheld computer unable to manage Glulx – we still have a few options. Unless the story is very large (in which case there is little we can do), the "z8" format is most likely to be exhausted for lack of what is called "readable memory", with a message like so:

This program has overflowed the maximum readable-memory size of the Z-machine format. See the memory map below: the start of the area marked "above readable memory" must be brought down to $10000 or less.

followed by a tabulation of how the Z-machine's storage has been used, a large but not very useful diagram. The first time one runs into the problem on a large project, it can be postponed, by adding the following to the source:

Use memory economy.

(Economy cuts down the verbosity of some of the testing commands, but otherwise subtracts no performance.) Writing this into the source is the equivalent of a diver switching to an emergency oxygen tank: it gives us a generous safety margin, but also tells us that now is the time to wrap things up.

If we hit the problem again, genuine cuts must be made. As a general rule, the most memory-expensive ingredients of an Inform design are various-to-various relations between large kinds such as "thing" or, if there are many rooms, "room". Other than that, if a kind has been festooned with new properties and we have created dozens of items of that kind, then we can get a fairly large saving simply by doing without one of those properties; and so on.

The ultimate memory-saving device, of course, is the one used by book publishers when there are too many pages to bind: to cut the design into two stories, Part I and Part II.

All software has bugs, and Inform is no exception. The most obvious bugs are the ones which Inform catches itself, when it confesses that it has halted in failure, or translated the source text into a program which cannot be compiled further. But sometimes it will also happen that Inform will issue a misleading Problem message, or appear to work normally but to produce a story which does not do what it should have done.

It is very helpful for users to report faults, so that the program can be improved for everyone else. To report a fault, please first check with the Inform home page to make sure that the version of Inform you have used to detect the fault is the latest version available. You can find the latest versions at

If the bug is still present in the latest version, please report the bug using Inform's bug tracking database. Links for this can be found from the Inform source code page:

It may be that someone else has already identified the bug and even that a workaround for users is suggested. If not, please make an account at the bug tracking system and submit the requested information to help Inform's maintainers track and fix the fault.

No. No computer does, and Inform does not even try to read the whole wide range of text: it is a practical tool for a particular purpose, and it deals only with certain forms of sentence useful to that purpose. Inform source text may look like "natural language", the language we find natural among ourselves, but in the end it is a computer programming language. Many things which seem reasonable to the human reader are not understood by Inform. For instance, Inform understands

something which is carried by the player

but not (at present, anyway)

something which the player carries

even though both are perfectly good English. So it is not always safe to assume that Inform will understand any reasonable instruction it is given: when in doubt, we must go back to the manual.

More philosophically, to "understand" involves contextual knowledge. Just because Inform recognises and acts on a sentence, does it really understand what we meant? It will turn out that Inform is both good and bad at this. For instance, from

Mr Darcy wears a top hat.

Inform will correctly deduce that Darcy is a person, because inanimate objects do not ordinarily wear clothes, and that the top hat is clothing. But it will not automatically know that Darcy is a man rather than a woman because it does not know the social convention implied by "Mr". Moreover, if instead we had written

Mr Darcy carries a top hat.

then Inform would not guess that the top hat is clothing. This is because it does not have the vast vocabulary and experience of a human reader: it is probably discovering the word "hat" for the first time.

Finally, it is best to avoid ambiguities rather than rely on Inform to know which meaning is patently absurd. For instance, in

Heatwave bone breaks clog hospital.

(a headline once printed by the Oxford Mail newspaper) a human reader quickly realises that there is no clog hospital being broken. But if Inform had been taught the verbs to break and to clog then that is exactly the conclusion it would have drawn. Or 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".

That disclaimer completes the groundwork, and we are ready to begin on simulating a world to explore.

3. Things

At its simplest, the interactive fiction will be simulating a physical world to explore. The forerunner of today's IF is generally agreed to be a computer simulation by Will Crowther of the exploration of a cave system in the Mammoth and Flint Ridge chain of caves in Kentucky, a part of which might be described in Inform thus:

"Cave Entrance"
The Cobble Crawl is a room. "You are crawling over cobbles in a low passage. There is a dim light at the east end of the passage."
A wicker cage is here. "There is a small wicker cage discarded nearby."
The Debris Room is west of the Crawl. "You are in a debris room filled with stuff washed in from the surface. A low wide passage with cobbles becomes plugged with mud and debris here, but an awkward canyon leads upward and west. A note on the wall says, 'Magic word XYZZY'."
The black rod is here. "A three foot black rod with a rusty star on one end lies nearby."
Above the Debris Room is the Sloping E/W Canyon. West of the Canyon is the Orange River Chamber.

Here we sketch in four of Crowther's locations, and two objects: just enough to be able to walk around the caves and pick up the rod and the cage. The text in quotation marks will appear verbatim as paragraphs shown to the player as the caves are explored. The first paragraph, as we have seen, is the title of the work. The other quotations describe the places and objects introduced.

If we play this story, we find that we can type TAKE CAGE or TAKE WICKER CAGE, for instance, but not TAKE SMALL CAGE. Inform saw that we called this "a wicker cage" when it first appeared in the source text, and assumed that the player would call it that, too. (Whereas it didn't look inside the descriptive text to allow for TAKE SMALL CAGE or TAKE DISCARDED CAGE or TAKE NEARBY CAGE.) A small limitation here is that probably only the first 9 letters of each word are read from the player's command. This is plenty for handling the wicker cage and the black rod, but it might be embarrassing at a meeting of the Justice League to find that KISS SUPERHERO and KISS SUPERHEROINE read as if they are the same command.

So we have already found that Inform has made some assumptions about what we want, and imposed some limitations on how much computational effort to go to when the work of IF is finally played. If Inform guesses what we need wrongly, we need to know more advanced features of the language in order to overcome these problems. (We shall see how to change the way the player's commands are read in the chapter on Understanding.)

This is often how Inform works: make the standard way of doing things as simple as possible to describe, but allow almost any behaviour to be altered by more elaborate source text. As an example of that, the player begins in the Cobble Crawl because it was the first room created in the source text, but we could instead have written text like:

The player is in the Cobble Crawl.

to override that. This can make the source text easier to follow if the rooms are sometimes being created in a less obvious way. For example, if we write:

The silver bars are in the Y2 Rock Room.
The Cobble Crawl is a room. South of the Crawl is Y2.

then the first room to be created will actually be the Y2 Rock Room, so that's where the player will be starting unless we say otherwise.

Examples

2.
Bic
Testing to make sure that all objects have been given descriptions.
3.
Making rooms give brief room descriptions when revisited.
4.
A room whose description changes slightly after our first visit there.

Rooms are joined together at their edges by "map connections", most of which are pathways in one of the eight cardinal compass directions: north, northeast (written without a hyphen), east, southeast, south, southwest, west, northwest. We also have up and down, suitable for staircases or ladders. In real life, people are seldom conscious of their compass bearing when walking around buildings, but it makes a concise and unconfusing way for the player to say where to go next, so is generally accepted as a convention of the genre.

Two more directions are provided by Inform: "inside" and "outside". These are best used when one location is, say, a meadow and the other is a woodcutter's hut in the middle of it; we might then say

Inside from the Meadow is the woodcutter's hut.

The "from" is important, as it clarifies that we intend to link two different locations, not to create an item – the hut – in a single location – the meadow.

A problem which sometimes arises when laying out maps is that Inform allows short forms of room names to be used as abbreviations. This is usually a good idea, but has unfortunate results if we write:

The Airport Road is west of the Fish Packing Plant. The Airport is west of the Airport Road.

…because "Airport" is taken as a reference to "Airport Road", so Inform makes only two locations, one of which supernaturally leads to itself. We can avoid this by writing:

The Airport Road is west of the Fish Packing Plant. A room called the Airport is west of the Airport Road.

Using "called" is often a good way to specify something whose name might give rise to confusion otherwise. It always makes something new, and it is also neatly concise, because we can establish something's kind and name in the same sentence. As another example, suppose we want to create a room called "South of the Hut", to south of the Hut. We can't do so like this:

South of the Hut is a room. South of the Hut is south of the Hut.

…because Inform will read that first sentence as placing a (nameless) room to the south of a room called "Hut". Once again "called" can save the day:

South of the Hut is a room called South of the Hut.

It is best to use "called" in the simplest way possible, and in particular, best not to use "called" twice in the same sentence. Consider:

The kitchen cabinet contains a container called a mixing bowl and a portable supporter called a platter.

It is unlikely that anyone would want to name something "a mixing bowl and a portable supporter called a platter", but not impossible, and Inform tends not to be a good judge of what is likely.

(If we really want to get rid of this issue once and for all, starting the source text with the use option "Use unabbreviated object names." will do it, but the effect is drastic. This instructs Inform not to recognise names other than in full. For example:

West of the Kitchen is the Roaring Range. South of the Range is the Pantry.

is ordinarily read by Inform as constructing three rooms (Kitchen, Roaring Range, Pantry); but with this use option set, it makes four (Kitchen, Roaring Range, Range, Pantry), in two disconnected pieces of map. Handle with care.)

Examples

5.
A partial implementation of Port Royal, Jamaica, set before the earthquake of 1692 demolished large portions of the city.
6.
Up and Up ★★
Adding a short message as the player approaches a room, before the room description itself appears.
7.
Starry Void ★★★
Creating a booth that can be seen from the outside, opened and closed, and entered as a separate room.

Connections are ordinarily two-way, but do not have to be. One of the map connections in the Mammoth Cave simulation was made by the sentence:

The Debris Room is west of the Crawl.

Besides reading this sentence at face value, Inform also deduced that the Crawl was probably meant to be east of the Debris Room: in other words, that the path between them is a two-way one. When Inform makes guesses like this, it treats them as being less certain than anything explicitly stated in the source. Inform will quietly overturn its assumption if information comes to hand which shows that it was wrong. That might happen in this case if another sentence read:

The Hidden Alcove is east of the Debris Room.

These two sentences are not contradictory: Inform allows them both, simply accepting that the world is more complicated than it first assumed. There are relatively few situations where Inform has to make educated guesses, but when it does, it tries always to follow Occam's Razor by constructing the simplest model world consistent with the information in the Source text.

We can even explicitly make a route which turns around as it leads between two rooms:

West of the Garden is south of the Meadow.

If we want to establish a route which cannot be retraced at all, we can specify that a particular direction leads nowhere:

East of the Debris Room is nowhere.

Finally, note that Inform's assumptions about two-way directions are only applied to simple sentences. When the source text seems to be saying something complicated, Inform takes it as a precise description of what's wanted. So, for example, in:

The Attic is above the Parlour.
The Attic is a dark room above the Parlour.

Inform makes guesses about the first sentence, and makes a two-way connection; but it accepts the second sentence more precisely, with just a one-way connection.

Examples

8.
Another part of Port Royal, with less typical map connections.
A simple elevator connecting two floors which is operated simply by walking in and out, and has no buttons or fancy doors.

Rooms represent individual places to which one can go, but we tend to think of the world around us in larger pieces: we think of a house and a garden, rather than each of the single rooms of the house and all corners of its garden. To Inform a collection of rooms is called a "region", and we can create one like so:

The Arboretum is east of the Botanical Gardens. Northwest of the Gardens is the Tropical Greenhouse.
The Public Area is a region. The Arboretum and Gardens are in the Public Area.

The real usefulness of creating regions like "Public Area" will only appear later, when we begin defining rules of play which apply in some areas but not others, but in the mean time we can see the effect by turning to the World tab of the Index. In the World Index, Inform draws a map – or at least a stylised attempt at a diagram of the rooms and their connections: this will not always correspond to how we imagine things, but with any luck it should mostly be right.

Rooms are represented by coloured squares, and the colour-coding is done by region. In the above example, the two "Public Area" rooms are coloured green (as it happens); the Greenhouse, since it belongs to no region, is a neutral grey.

Regions can be put inside each other:

The University Parks is a region. The Public Area is in the University Parks.

but they are not allowed to overlap other than by one being entirely inside the other.

See Also

Improving the index map for ways to adjust the way the index map is drawn or exported for publication.

Example

10.
Division of Port Royal into regions.

The following description runs to only 33 words, but makes a surprisingly intricate design. It not only places things within rooms, but also places them very specifically with respect to each other:

"Midsummer Day"
East of the Garden is the Gazebo. Above is the Treehouse. A billiards table is in the Gazebo. On it is a trophy cup. A starting pistol is in the cup.

Inform needs to identify the places and objects being described by the nouns here, and to guess what it can about them. For instance, the pistol can be picked up but not walked inside, whereas the Treehouse is the reverse. (This is obvious to someone who knows what these words mean, less obvious to a computer which does not, but the text contains sufficient clues.) Inform does this by sorting the various nouns into different categories, which are called "kinds". For instance:

Garden, Gazebo, Treehouse - room
billiards table - supporter
cup - container
starting pistol - thing
East, up (implied by "above") - direction

(A container is something which can contain other things, and a supporter similarly.) For instance Inform knows that if one thing is in another, then the second thing is either a room or a container, and if one thing is on another, the second thing is a supporter. This worked nicely for the design above, but:

In the Treehouse is a cardboard box.

results in the cardboard box being made only a "thing": because nothing has been put inside it, there is no reason for Inform – which does not know what a cardboard box looks like – to guess that it is a "container". So we need to add:

The box is a container.

It is rather clumsy to have to write two sentences like this, so we would normally write this instead:

In the Treehouse is a container called the cardboard box.

Examples

Allowing the player to use different synonyms to refer to something.
A few sentences laying out a garden together with some things which might be found in it.

Some containers, like bottles, can be opened: others, like buckets, cannot. If they can be opened, then sometimes they will be open, and sometimes closed. These are examples of properties, which can change during play. The following source sets some properties:

The cardboard box is a closed container. The glass bottle is a transparent open container. The box is fixed in place and openable.

There are only four different properties referred to here. Closed means not open, and vice versa, so these two adjectives both refer to the same property. (As might be expected, when a container is open, one can see inside and place things within, or take them out.) The glass bottle and the box being containers is a matter of their kinds, which is something fundamental and immutable, so "container" does not count as a property.

A "transparent" container is one which we can see inside even when it is closed, and the opposite is an "opaque" container.

The property of being "fixed in place" ensures that the player cannot pick the item up and walk away with it: this is useful for such things as oak trees or heavy furniture. The opposite condition is to be "portable".

A container which is "openable" can be opened or closed by the player; as might be expected, the opposite is "unopenable".

With a really large cardboard box, we might imagine that the player could get inside: such a container should be declared "enterable".

Example

13.
Tamed
Examples of a container and a supporter that can be entered, as well as nested rooms.

Properties depend very much on kind. It makes no sense to ask whether a room is transparent or opaque, for instance, so Inform will not allow this either to be specified or queried.

Another way that kind influences properties can be seen from an earlier example:

The Gazebo is a room. A billiards table is in the Gazebo. On it is a trophy cup. A starting pistol is in the cup.

The cup, the pistol and the table are all allowed to have the "fixed in place" property, but in fact only the table actually has it: the cup and the pistol are created as "portable" instead. This is because Inform knows that most things are portable, but that supporters – such as the table – are usually fixed in place. If this assumption is wrong, we need only add the line:

The table is portable.

Example

A running example in this chapter, Disenchantment Bay, involves chartering a boat. This is the first step: creating the cabin.

As we have just seen, making something "fixed in place" will prevent it from being picked up or moved. But it remains substantial enough to be described in its own paragraph of text when the player visits its location. This can be unfortunate if it has also been described already in the body of the main description for that location. For instance, if we wrote:

The Orchard is a room. "Within this quadrille of pear trees, a single gnarled old oak remains as a memory of centuries past." The gnarled old oak tree is fixed in place in the Orchard.

This would end up describing the oak twice, once in the paragraph about the Orchard, then again in a list of things within it:

Orchard
Within this quadrille of pear trees, a single gnarled old oak remains as a memory of centuries past.
You can see a gnarled old oak tree here.

We avoid this by making it "scenery" instead of "fixed in place":

The gnarled old oak tree is scenery in the Orchard.

Any thing can be scenery, and this does not bar it from playing a part in the story: it simply means that it will be immobile and that it will not be described independently of its room. Being immobile, scenery should not be used for portable objects that are meant to be left out of the room description.

If a supporter is scenery, it may still be mentioned in the room description after all, but only as part of a paragraph about other items, such as

On the teak table are a candlestick and a copy of the Financial Times.

If the player takes the candlestick and the Times, the teak table will disappear from mention. (Scenery containers do not behave in this way: their contents are assumed to be less immediately visible, and will be mentioned only if the player looks inside them.)

Examples

Disenchantment Bay: creating some of the objects in the cabin's description.
16.
Changing the response when the player tries to take something that is scenery.

It is a cardinal rule that nothing can be in more than one place at the same time, but rules were made to be broken, and an exception is allowed for a special kind of thing called a "backdrop". For instance:

"Streaming"
The Upper Cave is above the Rock Pool.
The stream is a backdrop. It is in the Upper Cave and the Rock Pool.

Backdrops are ordinarily in the background: if the sky needed to be referred to in the course of play, it might be represented by a backdrop, for instance. Here we have a stream of water running through two rooms, though it might be any number. Backdrops are always fixed in place.

Backdrops can be put in regions as well as rooms, and if so, then they are present at every room in the given region (or regions), as well as any specific rooms they may also be put into. For instance:

The Outdoors Area is a region. The Moon is a backdrop. The Moon is in the Outdoors Area. The Moon is in the Skylight Room.

The special place "everywhere" can be given as the location of a backdrop to make it omnipresent:

The sky is a backdrop. The sky is everywhere.

Inform assumes that backdrops are also scenery unless told otherwise, so this will not result in messages like "You can also see the sky here." being included in room descriptions. In the case of the stream above, we could artfully mention it in passing in the room descriptions of the Upper Cave and the Rock Pool.

See Also

Moving backdrops for ways to place backdrops in dynamically changing selections of rooms.

Example

Disenchantment Bay: adding a view of the glacier.

The properties we have seen so far have all been either/or: either open or closed, either transparent or opaque, either fixed in place or portable, either openable or not openable. However, some properties can have a much wider range of possibilities. For instance, the "description" of a room is the text revealed when the player first enters it, or types "look". This needs to be textual: Inform would complain if, for instance, we tried to set the description of something to the number 42. We have already seen a concise way to set the description of a room:

The Painted Room is north of the Undertomb. "This is the Painted Room, where strange wall drawings leap out of the dark at the gleam of your candle: men with long wings and great eyes, serene and morose."

This does the same thing as:

The Painted Room is north of the Undertomb. The description of the Painted Room is "This is the Painted Room, where strange wall drawings leap out of the dark at the gleam of your candle: men with long wings and great eyes, serene and morose."

Or even:

The Painted Room is north of the Undertomb. The description is "This is the Painted Room, where strange wall drawings leap out of the dark at the gleam of your candle: men with long wings and great eyes, serene and morose."

The player's first sight of something is the text used as its "initial appearance":

The plain ring is here. "Cast aside, as if worthless, is a plain brass ring."

This text appears as a separate paragraph in the text describing the Painted Room. It will continue to be used until the first time player picks the ring up (if this ever happens), so it normally describes things in their original, undisturbed context. (Inform uses an either/or property called "handled" for this: something is "handled" if it has at some point been carried or worn by the player.)

Thus when a piece of text stands alone as a sentence in its own right, then this is either the "description" of the most recently discussed room, or the "initial appearance" of the most recently discussed thing. Either way, it is used verbatim as a paragraph in the text shown to the player visiting the room in question.

But a thing also has an ordinary "description", which is used to give a close-up look at it. This text is ordinarily only revealed to the player when a command like "examine ring" is keyed in:

The description of the plain ring is "No better than the loops of metal the old women use for fastening curtains."

See Also

Creating a scene for the description of a scene, which is set in the same way.

Examples

Disenchantment Bay: fleshing out the descriptions of things on the boat.
19.
Laura ★★
Some general advice about creating objects with unusual or awkward names, and a discussion of the use of printed names.

The map of an interactive fiction is the layout of rooms and the entrances and exits which connect them. So far, these map connections have always run from one room to another, like so:

The Painted Room is north of the Undertomb.

However, we can also interpose doors between rooms, like so:

The heavy iron grating is east of the Orchard and west of the Undertomb. The grating is a door.

The second sentence is needed since otherwise Inform will take "heavy iron grating" to be the name of a third room, whereas what we want is for the grating to be something physically present in both the Orchard and in the Undertomb, and acting as a conduit between them. To this end it needs to be a "door", a kind we have not so far seen. In the absence of any other instruction, a newly created door will be fixed in place, closed and openable.

The grating really does come in between the two rooms: the grating is what lies immediately east of the Orchard, not the Undertomb room. So if we wrote the following:

The Undertomb is east of the Orchard. The heavy iron grating is east of the Orchard and west of the Undertomb. The grating is a door.

then Inform would say that this is a contradiction: we said the Undertomb was east of the Orchard, but then we said that the grating was east of the Orchard.

Inform's "door" kind can be used for all manner of conduits, so the word door need not be taken literally. In Ursula K. Le Guin's beguiling novel "The Tombs of Atuan", from which the above rooms are stolen, it is not a grating which interposes, but:

The red rock stair is east of the Orchard and above the Undertomb. The stair is an open door. The stair is not openable.

In real life, most doors are two-sided, and can be used from either of the rooms which they join, but this is not always convenient for interactive fiction. Here is a one-sided door:

The blue door is a door. It is south of Notting Hill. Through it is the Flat Landing.

(Note the use of "it" here as an optional abbreviation.) This will make a door visible only on the Notting Hill side; no map connection will be made in the reverse direction, unless we ask for one.

So much for creating and describing individual doors. Once we need to write about doors in general, we are likely to want a way to find out where a given door sits in the map. The following phrases reveal this:

front side of (object)room

This phrase produces the first of the one or two rooms enclosing a door – first in the order given in the source text. Example: if

The red rock stair is east of the Orchard and above the Undertomb.

then "front side of the red rock stair" produces the Orchard. For a one-sided door, this produces the only room containing the door.

back side of (object)room

This phrase produces the last of the one or two rooms enclosing a door – last in the order given in the source text. Example: if

The red rock stair is east of the Orchard and above the Undertomb.

then "back side of the red rock stair" produces the Undertomb. A one-sided door has no "back side."

More often, we are dealing with a door and want to know what it leads to, but that depends where we're standing:

other side of (door) from (room)object

This phrase produces the room on the other side of the door, as seen from the given vantage point, which needs to be one of its sides. Example: if

The red rock stair is east of the Orchard and above the Undertomb.

then "other side of the red rock stair from the Undertomb" produces the Orchard, and vice versa.

direction of (door) from (room)object

This phrase produces the direction in which the door leads, as seen from the given vantage point, which needs to be one of its sides. Example: if

The red rock stair is east of the Orchard and above the Undertomb.

then "direction of the red rock stair from the Undertomb" produces up.

See Also

Adjacent rooms and routes through the map for more phrases which can look at the current map layout.

Examples

Disenchantment Bay: adding the door and the deck to our charter boat.
21.
Escape ★★
Window that can be climbed through or looked through.
22.
Garibaldi 1 ★★★
Providing a security readout device by which the player can check on the status of all doors in the game.

It seems unwise for a door in Notting Hill to be unlocked, so:

The blue door is lockable and locked. The matching key of the blue door is the brass Yale key.

Since the second sentence here is a little clumsy, we can equivalently say

The brass Yale key unlocks the blue door.

Yet a third way to say this is:

The blue door has matching key the brass Yale key.

This introduces three new properties: a door can be locked or unlocked; lockable or not lockable; and it can have a matching key, which must be another thing. The same thing can be the matching key of many different locks: and note that a door can be locked and even lockable without having a matching key at all, in which case the player trying to open it will be permanently out of luck. Doors are ordinarily unlocked, not lockable, and without a matching key.

Containers can also have locks, in exactly the same way, and are allowed to have the same properties. On the other hand supporters never have locks: it makes no sense to be able to lock a tabletop, for instance, and Inform will not allow any discussion of the matching key of a supporter, or of a supporter being locked or unlocked.

Examples

Disenchantment Bay: locking up the charter boat's fishing rods.
A locked door that can be locked or unlocked without a key from one side, but not from the other.

A "device" is another of the standard kinds of thing, and should be used for anything which can be switched on or off: a light switch, say, or a slide projector. Devices are generally machines, clockwork or electrical. A device is always either "switched on" or "switched off", but is switched off unless we specify otherwise.

That makes three kinds of thing which will likely change their appearance according to which of their two possible states they are in: doors and containers, which can be open or closed; and devices, which can be switched on or switched off. We would like to produce text accordingly, and we can do this using Inform's ability to make (almost) any piece of text change with circumstances. For instance:

The coffin is an openable container in the Undertomb. "[if open]The lid of a plank coffin yawns open.[otherwise]A plank coffin lies upon the dirt floor of the Tomb."

We could use a similar trick to make the appearance of a device change "if switched on". There will be much more about text substitutions, as instructions in square brackets like these are called, in later chapters.

See Also

Text with substitutions for more on varying what is printed.

Examples

Disenchantment Bay: making the radar and instruments switch on and off.
26.
Down Below ★★
A light switch which makes the room it is in dark or light.

Rooms can be "dark" or "lighted", though they are lighted by default, and are lighted in all the examples we have seen so far.

The Sinister Cave is a dark room. "A profoundly disquieting rock formation, apparently sculptured by some demonic hand, this is not a cave in which to relax."

When the player is in a dark room, he can still go in various directions, but he cannot see the room description or interact with any of the objects in the room, except those he is holding. This means that, unless we should change the Cave in some way during play, the text above ("A profoundly…") will only be read if the player succeeds in bringing light into the Cave, perhaps by bringing along the following:

The flaming torch is in the Sandy Passage. "Stuck loosely into the sand is a flaming torch." The flaming torch is lit.

A thing with the property of being "lit" will enable the player to see inside dark rooms, and to carry out other activities requiring light, such as examining items. A lit thing in an open container will still light up a room; a lit thing in a closed container will not, unless the container has been given the "transparent" property.

It is possible to adjust the way darkness behaves, and we will see more on this topic in the chapter on Activities.

See Also

Printing a refusal to act in the dark for the first of several ways to control what is printed in the dark.

Next in the tour of standard kinds is the "vehicle". This behaves like (indeed, is) an enterable container, except that it will not be portable unless this is specified.

In the Garage is a vehicle called the red sports car.

The player can enter the sports car and then move around riding inside it, by typing directions exactly as if on foot: and the story will print names of rooms with "(in the red sports car)" appended, lest this be forgotten.

We have already seen that some things are portable, others fixed in place. In fact we can also make a third sort of thing: those which, although not portable, can be pushed from one room to another with commands like "push the wheelbarrow north". At a pinch, we might just be willing to allow:

The red sports car is pushable between rooms.

But of course this is a property which almost any thing can have, not just a vehicle. (Only "almost" because Inform will not allow a door to be pushable between rooms, in the interests of realism rather than surrealism.)

If we need vehicles which the passenger sits on top of, like a horse or a tractor, the standard "vehicle" kind will not be ideal. However, by loading one of the extensions which comes ready-installed:

Include Rideable Vehicles by Graham Nelson.

…we are provided with two more kinds, "rideable vehicle" and "rideable animal", just right for the tractor and the horse respectively. (As with all extensions, the documentation can be seen by clicking Go on some source which contains the above line, and then turning to the Contents index; or from the Installed Extensions tab of the Extensions panel.)

See Also

Going by, going through, going with for further ways to customize vehicle behaviour.

Examples

27.
A journey from one room to another that requires the player to be on a vehicle.
Disenchantment Bay: a pushable chest of ice for the boat.
29.
Hover ★★★
Letting the player see a modified room description when he's viewing the place from inside a vehicle.

Rounding out the standard kinds provided by Inform are four for living things: "person", which is a kind of thing, and "man", "woman" and "animal", all kinds of person. For instance:

In the Ballroom is a man called Mr Darcy.

For the time being, men and women will be little more than waxworks: they will come to life only when we go beyond the present stage of creating an initial state of the world.

People can be male or female: this is an either/or property for the "person" kind, and it affects play at run-time a little, because the player can use "him" and "her" to refer to male or female people encountered. Men and women are always male and female respectively, and for animals we can choose either way, for example making a stallion male or a nanny goat female. Animals are male unless we say otherwise.

If our animal is instead something like a beetle or an earthworm, where gender doesn't seem to matter or even to exist, we can use the further property "neuter":

The spider is a neuter animal in the Bathroom.

The Standard Rules don't make people behave differently according to their genders, and the main difference comes down to language: whether we want the animal to be called "her", or "it". Because of the existence of "neuter", we sometimes need to be cautious about the use of the adjective "male": since Inform, partly for historical reasons, uses an either/or property for masculinity, neuter animals are also "male".

Example

Disenchantment Bay: enter the charter boat's Captain.

Suppose we have said that:

In the Ballroom is a man called Mr Darcy.

When the Ballroom is visited, the man is listed in the description of the room as "Mr Darcy", not as "a Mr Darcy". This happened not because Inform recognised that Darcy is a proper name, or even because men tend to have proper names, but because Inform noticed that we did not use "a", "an", "the" or "some" in the sentence which created him. The following shows most of the options:

The Belfry is a room. A bat is in the Belfry. The bell is in the Belfry. Some woodworm are in the Belfry. A man called William Snelson is in the Belfry. A woman called the sexton's wife is in the Belfry. A man called a bellringer is in the Belfry.
In the Belfry is a man called the vicar. The indefinite article of the vicar is "your local".

In the resulting story, we read:

You can see a bat, a bell, some woodworm, William Snelson, the sexton's wife, a bellringer and your local vicar here.

The subtlest rule here is in the handling of "the". We wrote "The bell is in the Belfry", but this did not result in the bell always being called "the" bell: in fact, writing "A bell is in the Belfry" would have had the same effect. On the other hand, "A woman called the sexton's wife is in the Belfry." led to the wife always being known as "the" sexton's wife, not "a" sexton's wife, because Inform thinks the choice of article after "called" shows more of our intention than it would elsewhere. These rules will never be perfect in all situations, so we are also allowed to specify indefinite articles by hand, as the vicar's case shows.

"Some" is worth a closer look, because English uses it in several different ways. By introducing the woodworm with "some", above, we established that it was plural. We might imagine that there are many worms, even though they are represented by a single thing in Inform. We can expect to see text in the story such as:

You can see some woodworm here.
The woodworm are fixed in place.

But suppose we wanted something which there is an amount of, but which is not made up of individual items – a so-called mass noun like "water", or "bread". Now we can write:

The water is here. The indefinite article is "some".

and this time Inform does not treat the "some water" thing as a plural, so we might read:

You can see some water here.
The water is hardly portable.

rather than "The water are hardly portable."

Finally, we can override these settings, if they still come out not as we intend, by explicitly changing the either/or properties "singular-named" (vs "plural-named") and "proper-named" (vs "improper-named").

Examples

31.
Belfry
You can see a bat, a bell, some woodworm, William Snelson, the sexton's wife, a bellringer and your local vicar here.
32.
Changing the name of a character in the middle of play, removing the article.

The containers and supporters created so far have been boundlessly capacious: or rather, though we seldom notice the difference, have had a maximum carrying capacity of 100 items. This is clearly unrealistic for a small purse or a modest mantelpiece. We can impose upper limits with sentences like so:

The carrying capacity of the jewelled purse is 2.
The bijou mantelpiece has carrying capacity 3.

Attempts by the player to overfill, or overload, will now be rebuffed with a message such as "There is no room on the mantelpiece".

The player is not a container or a supporter, but nevertheless does have a carrying capacity: this is interpreted to mean the maximum number of items which can be carried at once.

The carrying capacity of the player is 4.

These restrictions only apply to the player (and other in-world characters): as the omnipotent creators, we are not restrained by them. Nothing prevents this:

The carrying capacity of the jewelled purse is 2. The diamond, the ruby and the sapphire are in the purse.

The player will be able to remove all three items, but only put two of them back. (This is probably something we only want very occasionally: perhaps to create a sack stuffed almost to bursting point.)

We have seen how to place objects in rooms, and in containers or on supporters. But what about people? Perhaps it could be said that they "contain" the fillings in their teeth, or "support" a top hat, but this is not very natural. Inform therefore never speaks of things being "in" or "on" people. Instead, they have two sorts of possessions: the things they carry, and the things they wear. (Body parts, such as arms and legs, are different again: see "parts" below for a clue to how to do these.) Thus:

Mr Darcy wears a top hat. Mr Darcy carries a silver sword.

In fact, Inform deduces from this not only who owns the hat and the sword, but also that Darcy has the kind "person", because only people can wear or carry.

As all the assertion verbs do, "to wear" and "to carry" have participles which Inform knows about. So we could equally well write:

The scarlet coat is worn by Mr Wickham. The duelling pistol is carried by Mr Wickham.

If we do not specify who does the wearing, or carrying, then this is assumed to be the player. Thus:

A brass lantern and a rusty iron key are carried. The mosquito-repellent hat is worn.

It would make no sense to "wear" the key, for instance, so Inform needs to distinguish between what is clothing and what is not. It does this with an either/or property called "wearable": if something has this property then the player will be allowed to wear it, provided it can first be picked up. Anything which is worn by somebody at the start of play is assumed to be wearable (unless we say otherwise). But if nobody is initially wearing the item in question, then we have to be explicit:

The player carries a scarlet gown. The gown is wearable.

(When we come to asking questions about the current situation, we will need to remember that "to carry" and "to wear" are different. Thus "if Lancelot carries the plate armour" will not be true if he is wearing it rather than carrying it under his arm. As we will later see, we can instead vaguely say "if Lancelot has the plate armour" to mean either carrying or wearing.)

See Also

To carry, to wear, to have for a more detailed explanation of carrying, wearing, and possessing as Inform understands them.

Example

Disenchantment Bay: things for the player and the characters to wear and carry.

When the player has only limited carrying capacity, play is likely to be tiresome, but we can make life easier by providing a way for the player to carry endless items without dozens of free hands to hold them all:

"Sackcloth"
The Attic is a room. The old blue rucksack is a player's holdall. The player is wearing the rucksack.
The carrying capacity of the player is 3.
In the Attic are a CD entitled No Smoke Without Fire, a 70s photograph of an American winning Wimbledon, a fraxinus branch, an urn holding your late great-aunt's remains, a convention badge from the American Society of Hypertension and a ghost story by M R James.

This example story introduces a new kind of container, the "player's holdall". This is a kind of which most stories will contain at most one example, but in principle there can be any number. A player's holdall is a capacious bag into which the player automatically places surplus items whenever his or her hands are full: trying the above example story and getting the items one by one will give the general idea.

Of course, if the carrying capacity of the player is never reached then there will never be any surplus items and a player's holdall will behave just like any other (portable, usually openable) container.

See Also

Units for the tools to implement a more sophisticated capacity system.

Example

Disenchantment Bay: making a holdall of the backpack.

We have nearly reached the end of the chapter on Things, but one either/or property for things remains: every thing is either "edible" or "inedible". Unless we say otherwise, things are inedible. But for instance we might write:

The player carries a Macintosh apple. The Macintosh is edible.

(The type of computer is named after a variety of apple descended from a tree cultivated in 1811 by John McIntosh of Ontario.) Edible things are just like inedible ones, except that the player can EAT them. This will usually only consume the foodstuff in question, effectively destroying it, but using techniques from later chapters we could make the consequences more interesting.

Everything has one and only one kind. This is both good and bad: good for clarity, bad if something needs to behave in two different ways at once. How might we simulate a car with an ignition key, given that no single thing can be both a "vehicle" and a "device" at the same time?

The Inform world model takes the view that such a car is too complicated to be simulated with a single thing. Instead it should be simulated as a vehicle (the car) which has a device (the ignition) attached. This is done using a third kind of containment to those seen so far ("in…" and "on…"): "part of".

"Buttons"
The Confectionary Workshop is a room. The Chocolate Machine is here. "The Chocolate Machine has pride of place. A lever and two buttons, one white, the other brown, seem to be the only controls. On top is a hopper."
A container called the hopper is part of the Chocolate Machine. The lever, the white button and the brown button are parts of the Chocolate Machine.
The Chocolatier's desk is here. "The Chocolatier evidently works at the imposing green-leather topped desk facing the Machine. It has three drawers with brass handles."
The upper drawer, the middle drawer and the lower drawer are parts of the desk. The upper drawer, the middle drawer and the lower drawer are openable closed containers. In the middle drawer is a sugared almond. In the lower drawer is a Battenburg cake. On the desk is a liquorice twist.
The cake, the twist and the almond are edible.

The machine and the desk each have several "parts" representing subsidiary pieces of themselves. The desk is a "supporter" (it needs to be, for the liquorice twist to be on top) but also has three "containers" attached, each of which can be opened or closed independently.

In the interests of realism, the standard rules of play protect these composite things. Thus if the desk were to be moved elsewhere (rolling on sugar casters perhaps) then its parts would move with it, and the player is not allowed to detach parts of things: the drawers can be opened or closed, but not pulled out altogether.

Note that rooms and regions are not allowed to have parts. (Rooms are already parts of regions, and to divide up rooms, we can either make several rooms or place containers or other obstacles in a single one.)

Examples

35.
Adding an enclosure kind that includes both containers and supporters in order to simplify text that would apply to both.
36.
Brown ★★★
A red sticky label which can be attached to anything in the game, or removed again.
37.
A final trip to Disenchantment Bay: the scenario turned into a somewhat fuller scene, with various features that have not yet been explained.

Though realism can become tiresome in interactive fiction, there are times when we cannot go along with Inform's normal assumption that all of a person's possessions are visible to everybody else. People are not like containers, which either show all of their holdings or not, according to whether they are open or transparent. If a man is carrying a fishing rod and a wallet, one will be on open show, the other not. Some clothing is outwardly visible, but not all.

Whether or not something is concealed is not like the either/or properties we have seen so far – such as being "open" or "closed" – because it is not really a property of the thing itself, but depends on the habitual behaviour of its current owner. To talk about behaviour we have to use sentences of a kind not seen so far, and which will not fully be explained for some chapters to come.

But straightforward cases are easy to write, if only by imitating the following examples.

Here we make the Cloaked Villain invariably conceal anything she is carrying or wearing:

Rule for deciding the concealed possessions of the Cloaked Villain: yes.

At which point we think about it more carefully, and then rewrite:

Rule for deciding the concealed possessions of the Cloaked Villain: if the particular possession is the sable cloak, no; otherwise yes.

(A rule which says neither "yes" nor "no" will decide yes, but it's best to spell out exactly what's wanted.)

Parts are treated exactly as if clothes or items being held, and the following will make the face and inscription on a coin invisible unless the player is carrying it – the idea being that they are too small to be seen from farther away.

The coin is in the Roman Villa. The face and inscription are parts of the coin. Rule for deciding the concealed possessions of the coin: if the coin is carried, no; otherwise yes.

There is also an either/or property called "described"/"undescribed", intended to be used only as a last resort, but which has the ability to hide something from room descriptions. This not really hiding: the idea is that "undescribed" should be used only for cases where some other text already reveals the item, or where its presence is implicit. Even then, it should only be used when the item is intended to be taken or moved by the player at some point – if the item isn't intended to move, it's much better to make it "scenery". (There's only one commonly-found example – the player's own body, the "yourself", is undescribed.)

Note that the "undescribed" property is automatically removed from anything carried by, worn by or part of the player, even indirectly; and that nothing on top of an "undescribed" supporter will be visible in a room description, even if it itself is "described". (Scenery supporters don't suffer from that restriction, which is one reason scenery is a better option when possible.)

Example

38.
A smuggler who has items, some of which are hidden.

The model world created by Inform is partitioned into rooms. If we write a sentence such as

Professor Wilderspin is a man.

and say nothing more about Wilderspin, then he does not physically exist at the start of the story: he is said to be "out of play" or "off-stage", and stays that way until we move him into one of the rooms. A better metaphor might be that he is waiting in the wings, ready to come onto the stage.

Every thing is either out of play, or can be found in one of the rooms, and the property "location of X" gives us the room in question. The following condition tests, in effect, whether a thing is in play:

if the location of Wilderspin is a room, ...

Which uses a new phrase:

location of (object)room

This phrase produces the room in which, perhaps indirectly, the object given resides. Example: if the player stands in Biblioll College and wears a waistcoat, inside which is a fob watch, then

location of the fob watch

is Biblioll College, the same as for the waistcoat or player.

The location of a room is itself. Regions and directions don't have a location, so for them "location of" produces the special object value nowhere, the same as for things that are off-stage.

The location of a door is usually its front side, but for two-sided doors, it's subject to change. When the player visits a two-sided door's back side room, the door's location becomes that room and it remains the back side room until the player visits the front side room again.

The location of phrase should not be used with backdrops: its results aren't meaningful.

We very often want to know the location of the player, and this is more simply called just "the location". (This is actually a value that varies rather than a phrase, but that's a technicality we can ignore here.)

We say that one object "holds" another if it contains it, supports it, wears it, carries it, or incorporates it (i.e., if the other object is a part of it). An object cannot be held by more than one object, but it can be held by nothing.

The idea of indirect holding is useful enough to have a name: Inform calls it "enclosure". A thing encloses whatever it holds, and whatever those things hold, and so on. When something moves around, anything it encloses will move with it. In the example above, Biblioll College (a room) holds the player, the player holds the waistcoat, and the waistcoat holds the fob watch. Also, the waistcoat encloses the fob watch, the player encloses both the waistcoat and the fob watch, and Biblioll College encloses all three of the player, the waistcoat, and the fob watch.

Enclosure is only useful when being used as a question. So the following is fine:

if the player encloses the fob watch, ...

But these will produce problem messages:

The player encloses the fob watch.
The location of the trilobite is the Museum.

because they are too vague. Inform needs to know exactly where the fob watch and the trilobite will begin the story, whereas these sentences leave room for doubt about in what way the thing would be enclosed. You might expect the same to hold true for holding, but "holds" can be used in assertions, where it means just carrying (and so it must have a person as the subject).

In general, a thing's location encloses it. But a two-way door is enclosed by the rooms on both sides of it, though it is contained and thus held only by its location (which varies, as noted above).

Backdrops are usually held by the room where the player most recently encountered it, but backdrops are never enclosed, a unique exception to the generality that the holder of a thing encloses it.

Though a room's location is itself, it neither holds nor encloses itself.

See Also

Looking at holding by hand for more details on holding.

Example

39.
A character who approaches the player, then follows him from room to room.

"Direction" is a kind which is quite unlike most of those seen so far. While it has to do with the physical world, a direction does not exactly belong to it. One cannot find "southeast" sitting on a shelf. "Direction" is not a kind of thing, nor a kind of room: it is a kind in its own right.

Every direction has an "opposite" property, which is always another direction. These occur in matched pairs. The opposite of north is south, just as the opposite of south is north. The opposite of southeast is northwest, the opposite of inside is outside, and so on. When Inform reads a sentence like…

Bangkok is south of Nakhon Sawan.

…it assumes that the opposite map connection is probably also valid, so that

Nakhon Sawan is north of Bangkok.

The chapter began with the twelve directions built into Inform:

north, northeast, east, southeast, south, southwest, west, northwest, up, down, inside, outside

But the built-in set is not always appropriate. Sometimes this is too many; if we wanted to write about a Flatland, for instance, then up and down ought to go. But in practice it is better not to abolish them as directions but instead to forbid travelling in them. (See the Recipe Book for examples.)

But away from our familiar Earth, the usual frame of reference loses its meaning. Terry Pratchett's "Discworld" comedies, set on a rotating disc, use the directions turnwise, widdershins, hubwards and rimwards. On board a Zeppelin airship, which constantly changes its course, the cockpit has no fixed compass bearing from the passenger cabin: it is not very naturally "north". In zero gravity, there is no up or down. Mars does not have a magnetic core, so a compass doesn't work there.

New directions must always be created in opposing pairs, and each must be declared with a clear simple sentence of the form "X is a direction." For instance:

Turnwise is a direction. The opposite of turnwise is widdershins.
Widdershins is a direction. The opposite of widdershins is turnwise.
Hubwards is a direction. The opposite of hubwards is rimwards.
Rimwards is a direction. The opposite of rimwards is hubwards.

It is then possible to write, say, that:

Ankh-Morpork is hubwards of Lancre and turnwise from Borogravia.

Of course the Map page of the Index for the project normally draws a map based on compass bearings, so it will get a little befuddled by this. But the map drawn in the Index can be given hints to improve its legibility. More on this later, but for now note that

Index map with turnwise mapped as east.

maps turnwise directions as if they were east, that is, pointing rightwards on the page. (This has no effect on the story file produced; it does not mean turnwise is simply a new name for east; it affects only the look of the Index map, which is only a convenience for the author in any case.)

At one time, directions had to have shortish names (up to three words only), but that's no longer true:

Just the tiniest smidge off magnetic north is a direction. The opposite of
just the tiniest smidge off magnetic north is just the tiniest smidge
off magnetic south.
Just the tiniest smidge off magnetic south is a direction. The opposite of
just the tiniest smidge off magnetic south is just the tiniest smidge
off magnetic north.

Examples

A button that causes a previously non-existent exit to come into being.
Replacing the ordinary compass bearings with a set of six directions to impose a hexagonal rather than square grid on the landscape.
42.
Fore ★★★
Understand "fore", "aft", "port", and "starboard", but only when the player is on a vessel.

4. Kinds

Values are to Inform what nouns are to English sentences. They represent numbers, times of day, pieces of text, places, people, doors, and so on. Because they have such an enormous variety, and because we often want to talk about what some of them have in common, we need a way to sort all of these different ideas out. That's the main aim of Inform's concept of "kind".

Every value has a kind. The kind of 10 is "number"; the kind of 11:30 PM is "time"; the kind of "jinxed wizards pluck ivy from my quilt" is "text"; and so on. The Kinds index panel shows the kinds present in the current Inform project, which will always include a wide range of built-in kinds, and usually also some new ones created in that project.

Some kinds are more general than others. For example, if we write:

Growler is an animal in the Savannah.

then Growler is an "animal", which is a kind of "thing", which is a kind of "object". When we talk about "the" kind of Growler, we mean "animal", the most specific one, but actually he belongs to all of those kinds.

As we see from this example, kinds have a whole hierarchy. Some are specialised versions of other kinds; some are not. Browsing the Kinds index shows that Inform builds its model world out of "objects". (That's really what objects are: "object" is a kind of value used to make the ingredients of the model world.) The objects fall into four fundamental kinds, "room", "thing", "direction" and "region", and "thing" is more subdivided still.

All the same, Inform starts out with a fairly simple arrangement. Because taxonomy – setting up kinds for everything – is so difficult, and depends so much on what you want it for, Inform creates relatively few kinds in advance: it has "animal" built in, but not "mammal" or "Bengal tiger". When we need more, we must make them ourselves. Let's see how we might invent these new kinds. The easy one is:

A Bengal tiger is a kind of animal.

Given that, we can then write:

Growler is a Bengal tiger in the Savannah.

That's easy enough. Adding "mammal" now looks awkward, though, because it seems to belong in between the two. All Bengal tigers are mammals, but not all animals are. But Inform can sort this out:

A mammal is a kind of animal. A Bengal tiger is a kind of mammal.

If we look at the Kinds index, we should indeed see a hierarchy:

object > person > animal > mammal > Bengal tiger

though the diagram is laid out as a sort of tree, just as zoologists do.

As another example, it may seem curious that Inform doesn't usually think "man" is a kind of "animal". This is really because, in English, people don't usually expect something like "if an animal is in the garden" to be true when it's only the Revd Mr Beebe going for a walk. People expect the word "animal" not to mean a human being, despite our common genetic ancestry. But if we want to rearrange Inform's default ideas, we can do that quite easily:

A man is a kind of animal. A woman is a kind of animal.

Or indeed we could say:

A human being is a kind of mammal. A man and a woman are kinds of human being.

While this is an ideal way to make new kinds for the model world, we are more restricted in what we can do outside of objects. For instance,

A glob is a kind of number.

isn't allowed. The numbers are fixed and all exist already; they aren't like Bengal tigers which we can simply imagine, and fill the world with. "Number" is not a concept we can specialise any further. But what we can do is to invent entirely new concepts, like so:

A distance is a kind of value.

We will see more of these later. (This isn't specialising anything – "value" is a sort of everything-category, and is too big and vague to be a kind.)

Example

43.
Vouvray ★★
Adding synonyms to an entire kind of thing.

This seems a good point to see what we can do with new kinds. Here we invent a new kind to provide a new sort of room:

A dead end is a kind of room.

Any dead end that we make is also a room, so it has all of the properties and behaviour of a room. For instance, every room is either "lighted" or "dark", and the default is to be lighted. But we can reverse that convention for dead ends, and we can also fill in some other properties:

A dead end is a kind of room with printed name "Dead End" and description "This is a dead end. You'll have to go back the way you came." A dead end is usually dark.
The Undertomb is a dark room. East is a dead end. South is a dead end with printed name "Collapsed Dead End". Northwest is a dead end called the Tortuous Alcove.
In the Undertomb is the candle lantern. It is lit.

As a result of this, three different rooms adjoin the Undertomb, all dead ends. This is much more concise than spelling them out one at a time would be.

Inform often doesn't mind in what order it is told about the world, but it may need to know the name of a kind before that kind can be used. For example,

A coffer is a kind of container. In the Crypt is an open coffer.

makes sense to Inform and results in the creation of a new thing, just called "coffer" in the absence of any other name to give it, whose kind is "coffer" and which is initially open. Whereas if Inform reads:

In the Crypt is an open coffer.

without knowing that "coffer" is a kind, it simply makes a thing called "open coffer" (and which is not a container). Inform has to be careful like this: English is simply too overflowing with multiple meanings. An "open railway ticket", for instance, is not a "railway ticket" that one can put objects into.

When we write:

A dead end is usually dark.

we are saying that it will be dark rather than lighted unless we should specify otherwise. So it would be fine to add:

The Tortuous Alcove is lighted.

because although dead ends are usually dark, this one is evidently an exception. On the other hand, if we had originally written

A dead end is always dark.

then Inform would not have permitted any exception to be made, and would have reported a problem if we had tried to make the Tortuous Alcove lighted. Besides "usually" and "always", we can also employ "seldom" and "never", which are their negatives. Thus, "never lighted" means the same as "always dark".

Examples

44.
Odin
Replacing "You see nothing special…" with a different default message for looking at something nondescript.
A staircase always open and never openable.

As the following examples show, sentences can make several assertions at once by using the plural. Suppose we have defined a kind called "high-up fixture", for instance like so:

A high-up fixture is a kind of thing. A high-up fixture is usually fixed in place.

Then the following sentence creates two such objects and puts them in their place:

The high shelf and the skylight window are high-up fixtures in the Lumber Room.

since it is equivalent to saying:

The high shelf is a high-up fixture. The skylight window is a high-up fixture. The high shelf is in the Lumber Room. The skylight window is in the Lumber Room.

Such plurals are allowed in almost any context, and we could even define two kinds at once:

Bucket and basket are kinds of container.

Inform constructs plurals by a form of Conway's pluralisation algorithm, which is quite good – for example, it gets oxen, geese (but mongooses), sheep, wildebeest, bream, vertebrae, quartos, wharves, phenomena, jackanapes and smallpox correct. But English is a very irregular language, and multiple-word nouns sometimes pluralise in unexpected ways. So we sometimes need to intervene:

A brother in law is a kind of man. The plural of brother in law is brothers in law.

We are allowed to define more than one plural for the same singular text, and for the names of things, rooms or kinds, all alternative versions will be used interchangeably. (For instance, Inform defines both "people" and "persons" as plurals of "person".)

Example

Using kinds of clothing to prevent the player from wearing several pairs of trousers at the same time.

So much for making new and more specialised kinds of object – for example, new kinds of room, or new kinds of animal. This allows us to describe the physical world in elegant ways, but what about concepts which aren't so physical?

Without getting into philosophy, we can probably agree that numbers like 1, 2, 3, …, and texts like "Jackdaws love my big sphinx of quartz", are not physical. Inside Inform, those are values, but not objects. Inform already has a good stock of this sort of concept built in, so it may not immediately seem clear why we need to create new ones. But in fact this is very useful. To describe the physical world, we need concepts like (for example) distance and brightness. We want to say that two armchairs are 12 feet apart, or that a given light-bulb is very dim. Here, "twelve feet" and "very dim" are clearly not physical objects; they need to be values, but not objects.

As these two examples suggest, sometimes we want a quantitative way to measure things, sometimes not. Thomas Hardy, in his novel "The Return of the Native", writes:

When he drew nearer he perceived it to be a spring van, ordinary in shape, but singular in colour, this being a lurid red.

Hardy doesn't tell us that the wavelength of the light is 700nm, he tells us that the colour is "lurid red", and we understand. Later in the same chapter, Hardy writes:

The loads were all laid together, and a pyramid of furze thirty feet in circumference now occupied the crown of the tumulus.

and now we do have a quantitative measurement: thirty feet. This is how people write about the world, and how they read about it. So Inform needs to provide both sorts of measurement.

(a) Here is a qualitative example. Suppose we would like a candle lantern to burn down, gradually diminishing in brightness. Then we'll need a way to talk about the current strength of the flame, but only in vague terms. Here goes:

Brightness is a kind of value. The brightnesses are guttering, weak, radiant and blazing.

"Brightness" is now a kind of value on a par with (for instance) "number" or "text". There are only four possible values, named as above. Kinds of value like this, where there are just a few named possibilities, are extremely useful, as we'll see.

(b) Now a quantitative example:

Weight is a kind of value. 1kg specifies a weight.

The difference here is not the way we create the kind, but the way we tell Inform what the possible values are. Instead of a list, we teach Inform some notation. As a result, "26kg" is now a value, for instance. Quantitative kinds like this are sometimes called "units", because – as in this example – they're often units in the sense of measuring things. Many Inform projects never need units, but they can still be very useful, and they're described in detail in the chapter on "Numbers and Equations".

So now we have seen two fundamental ideas: "value" and "kind". We have seen how to make a source text which refers to many values – for example, Growler the Bengal tiger, 23kg, "Collapsed Dead End", blazing, 7, all values of different kinds.

But we don't just want a way to refer to values, we want to lay out facts about them. Inform understands two sorts of fact, which it calls properties and relations. Properties are about single values in isolation: Growler is male. Relations are about how values interact with each other: Growler likes Bambi. (Or would like to eat Bambi, anyway.) Relations are really the central organising idea of Inform, and we've seen them many times already:

Growler is in the Savannah.

expresses a relation called "containment" between Growler and the Savannah. Much more about this in the chapter on Relations: for now, let's go back to the simpler idea of properties.

In Inform terms, a "property" is any fact about a value (other than its kind) which the author is allowed to choose. For example,

Growler is an animal. Growler is male. The description of Growler is "What immortal hand or eye could frame thy fearful symmetry?".

The first of these sentences talks about Growler's kind, but the other two sentences tell Inform about his properties. Properties are divided into either/or properties – "male" versus "female" – and value properties – such as the description of something, which can be any text.

The Kinds index shows which kinds of object are allowed to have properties. Every object is, so there's no problem with Growler. In general, if Inform can find a sensible way to store properties, then it will allow them. But it won't allow (for example) properties of numbers. There are only a finite number of Bengal tigers in the world (fewer than three thousand, alas), so Inform can easily store individual description texts for each one of them. But there are an infinite range of numbers. (Inform does allow adjectives like "even" or "odd" to be used about number – saying "if 7 is odd" is fine, for example – but they are not properties in the Inform sense, because the author doesn't get to choose. The author can choose whether Growler is a male or female tiger, but not whether 7 is an even or an odd number.)

Properties can't be handed out completely freely. In the previous chapter, we saw that we were allowed to make a chair "portable" and to make a room "dark". But if we try this the other way round, Inform produces a Problem message. This is because every property must be created in a way which lays out what values are allowed to have it. The Standard Rules built into Inform say that

A thing can be fixed in place or portable.

and as a result it won't allow "The Savannah is portable" because the Savannah is a room, not a thing.

We must do the same. To go back to our example "dead end" kind:

A dead end is either secret or ordinary.

This creates just one new property, not two. The names are taken as the two states of a single either/or property: secret means not ordinary, ordinary means not secret. Alternatively, we could just say:

A dead end can be secret.

in which case the opposite of "secret" would be "not secret".

Now we have a property which can be given to any value of the kind "dead end". We're also free to add to the definitions of kinds which already exist, including those built into Inform: for instance,

A room is either indoors or outdoors.

If we make the above definitions then all dead ends will be "ordinary" and all rooms "outdoors" unless the source text says otherwise. That is, in the absence of other information it's assumed that an either/or property is not true. We could reverse by writing:

A dead end is usually secret. A room is usually indoors.

A property can be used by several kinds at once. For example, the built-in either/or property "open" is used by both doors and containers, even though door isn't a kind of container and container isn't a kind of door. In fact, although it's more usual to declare properties for whole kinds, they can actually be given to single values one at a time, if we like:

The umbrella is carried by the player. The umbrella can be open.

And now the umbrella, which is a thing and not a door or container, can also have the property.

Example

47.
Implementing sleeping and wakeful states.

So much for either/or properties. Now we move on to properties which have values attached. The same principles apply, but the wording is different. For example,

A dead end has some text called the river sound. The river sound of a dead end is usually "a faint whispering of running water". The Tortuous Alcove has river sound "a gurgle of running water".

The property "river sound" is now applicable only to dead ends, so we would not be allowed to talk about "the river sound of the Savannah", say. Moreover, it's required to hold a piece of text. If we tried the following:

The river sound of the Tortuous Alcove is 7.

…then Inform would object, because the number 7 is the wrong kind of value to go into the "river sound" property. If we need a numerical property, we can try this instead:

A dead end has a number called the difficulty rating. The Tortuous Alcove has difficulty rating 7.

Suppose that we were to add:

The Exquisitely Narrow Defile is a dead end.

The Defile must have a river sound, of course, because we said that every dead end would have one. We haven't said what that river sound will be, but Inform can work it out, because we did say this:

The river sound of a dead end is usually "a faint whispering of running water".

If there are no instructions at all about the value of a property, Inform fills in the default value of the appropriate kind – in this case, it would be a blank text. (A table of the kinds which can be used for properties, and their default values, can be found in the Kinds index.)

Examples

Adding new properties to objects, and checking for their presence.
49.
Using text properties that apply only to some things and are not defined for others.

It turns out to be very useful to create a new kind of value, and then create a property to hold it. So useful, in fact, that Inform provides two shortened forms for doing so. Here is the first, and the second (making "conditions") is in the section following.

Suppose we go back to our example of the candle lantern whose brightness we have to measure. It's clear that what we want to do is to define:

Brightness is a kind of value. The brightnesses are guttering, weak, radiant and blazing.

And now we can use the technique of the previous section:

The lantern has a brightness called the flame strength. The flame strength of the lantern is blazing.

This works very nicely. The "flame strength" property is now only allowed to have one of four values we allowed: guttering light, weak light, radiant light or blazing light. So we have succeeded in recording our measurement.

But it seems artificial to call the brightness of the lantern "flame strength", when we could instead simply call it "brightness". Much simpler to write:

The lantern has a brightness. The lantern is blazing.

Now "brightness" is the name of both the property and the kind of value. What's particularly nice is that we can now use the names of the possible brightnesses – "weak", "blazing" and so on – as adjectives. Inform knows that "The lantern is blazing" must be talking about the brightness property, because "blazing" is a brightness.

Now we can improve our dead ends:

A dead end is a kind of room with printed name "Dead End" and description "This is a dead end, where crags in the uneven rock are caught by the [brightness of the lantern] flame you hold aloft. Despite [river sound] there is no sign of the stream." A dead end is usually dark.

The "[brightness of the lantern]" is printed not as literal text, but as whatever the brightness currently is. (The square brackets mark it as what is called a text substitution, which will be the subject of the next chapter.) So we get something like this:

This is a dead end, where crags in the uneven rock are caught by the blazing flame you hold aloft. Despite a faint whispering of running water there is no sign of the stream.

So now we have a lantern, which has a brightness as a property. But we can build on this further if we like. A brightness such as "guttering" is a value, so it can have properties in its own right. That can be quite useful, in fact:

A brightness can be adequate or inadequate. A brightness is usually adequate. Guttering is inadequate.

This is convenient because it divides up the brightnesses:

The player carries a book. The description of the book is "[if the brightness of the lantern is adequate]Many secrets are now yours.[otherwise]No, the print's too tiny by this awful light."

And while we're at it, let's give each brightness its own corresponding temperature:

Temperature is a kind of value. 100C specifies a temperature.
A brightness has a temperature. The temperature of a brightness is usually 700C. The temperature of blazing is 1400C. The temperature of radiant is 1100C.
The description of the lantern is "The lantern shines with a flame at [temperature of the brightness of the lantern]."

(Candle flames are hotter than most people think.)

See Also

Text with substitutions for more on varying what is printed.

Examples

A small map of dead ends, in which the sound of an underground river has different strengths in different caves.
51.
Flickering lantern-light effects added to the Undertomb.
52.
A description text that automatically highlights the ways in which the object differs from a standard member of its kind.
53.
Signpost that points to various destinations, depending on how the player has turned it.

Now for an even more abbreviated way to create a new kind of value, and at the same time create a property to hold it. Suppose we have something, say a wine cask, which we know is always in one of three different states. We can write:

The cask is either customs sealed, liable to tax or stolen goods.

This is just like our example of the lantern having possible brightnesses, but it's quicker to do, because we don't need to create or name the kind of value. (The trade-off is that we can't use it for anything else as well.)

Initially the cask will be "customs sealed", the first value we gave. We could now write, for instance,

The description of the cask is "A well-caulked Spanish wine cask.
[if liable to tax] It really is a shame to have to pay duty on it!"

Or, as a second example, here we're going to allow a whole kind to have the property, not just a single object:

Colour is a kind of value. The colours are red, green and white.
A colour can be bright, neutral or flat. Green is neutral.

Now in fact these properties are not anonymous: Inform has worked out names for them, even though we didn't give any. The usual arrangement is that the name is the name of the object with the word "condition" tacked on: for instance, "cask condition". So we could write:

The printed name of the cask is "wine cask ([cask condition])".

so that sometimes this would be "wine cask (liable to tax)", sometimes "wine cask (stolen goods)" and so on.

But only usually, because we might need to define several different conditions of the same thing, and then the names would collide. For instance, suppose we write:

A fruit is a kind of thing. A fruit can be citrus, berry, melon, or pome.

This makes a property and a kind of value each called "fruit condition". But now suppose we add that:

A fruit can be unripened, ripe, overripe, or mushy.

This is a quite unrelated property – a fruit could have any combination of these two properties, in fact. Left to itself, Inform will call the second one "fruit condition 2", which isn't really ideal if we ever do need to refer to it in other source text. So we are also allowed to give these conditions names of our own choosing:

A fruit can be unripened, ripe, overripe, or mushy (this is its squishiness property).

And now the resulting property and kind of value would be called "squishiness".

Just about every kind has a "default value". Inform needs this when it knows that something has to be a value of a given kind, but it hasn't been told what the value is. For example, in the previous chapter we saw that every thing has a "description" text, but we also created plenty of things without describing them. So if Inform reads

The conference pear is in the bowl.

and it isn't told anything else about the pear, what should it set the description of the pear to?

The answer is that Inform knows the description has to be a value of the kind "text", so it uses the default value of "text". Not very interestingly, this is just the blank text "".

Being uninteresting is exactly the idea, of course. The default number is 0, for instance. (Default values are tabulated in the Kinds index.)

It's sometimes useful to be able to refer to the default value of a kind without having to spell out what this is (especially if the kind is something obscure, or we're trying to write a rule for an extension which has to work in situations we don't fully know about).

default value of (name of kind)value

Produces the default value of the kind named. Examples:

The silver repeater is here. "You catch sight of a silver repeater watch, hands immobile at [default value of time]."

produces the output:

You catch sight of a silver repeater watch, hands immobile at 9:00 am.

because nine in the morning is the default time in Inform. If we have:

Brightness is a kind of value. The brightnesses are guttering, weak, radiant and blazing.

then "default value of brightness" is guttering, the first brightness created. When it comes to kinds of object, we sometimes have to be a little careful. For example,

default value of room

is always going to be fine (it's always the first room created in the source text). But

default value of vehicle

would produce a Problem message if there were no vehicles in the world.

Sometimes a value important to the simulated world will not naturally belong to any thing or room, and should not be kept in a property. In fact, we have seen a value that varies already: "location", which holds the room in which the story is presently taking place. Here's how we might make a new one:

The prevailing wind is a direction that varies. The prevailing wind is southwest.

Or "which varies" would also be allowed, as would the more traditional computing term "variable":

The prevailing wind is a direction variable. The prevailing wind is southwest.

A briefer way to do this is to use the word "initially", which alerts Inform to the possibility that the value will change in future:

The prevailing wind is initially southwest.

This creates the variable and gives it an initial value all in one sentence.

It's not compulsory to give an initial value. If we do not, Inform will use the default value for its kind. (See the table in the Kinds index.) For example, writing just

The grand tally is a number that varies.

will start it at the value 0, because that's the default value for numbers.

We can have variables of any of the kinds of value, including new ones, but should watch out for a potential error. If we write:

The receptacle is a container that varies.

in a world which has no containers at all, Inform will object, because it will be unable to put any initial value into the receptacle variable. A similar complaint will be made if we write:

Colour is a kind of value. The fashionable shade is a colour that varies.

without ever having defined any colours. Something else we are not permitted is:

The receptacle is an open container that varies.

because the openness of a given container may change during play, so that the value in the variable might suddenly become invalid even though the variable itself had not changed.

As a final note on kinds, when Inform reads something like this:

Peter is a man. The accursed one is initially Peter.

it has to make a decision about the kind of "accursed one". Peter is a "man", so that seems like the right answer, but Inform wants to play safe in case the variable later needs to change to a woman called Jane, say, or even a black hat. So Inform in fact creates "accursed one" as an object that varies, not a man that varies, to give us the maximum freedom to use it. If we don't want that then we can override it:

Peter is a man. The accursed one is initially Peter.
The accursed one is a man that varies.

thus telling Inform exactly what is intended.

Example

Allowing the player to turn off all access to hints for the duration of a game, in order to avoid the temptation to rely on them overmuch.

It's sometimes useful to name even values which don't change. For example, suppose the story involves driving, and the same speed limit value comes up in many places. Rather than typing "55" (say) every time it comes up, we might prefer to write:

The speed limit is always 55.

at the start of the source text, and then talk about "the speed limit" every time we would otherwise have typed "55". Just as the word "initially" alerts Inform that we want the named value to change during play, the word "always" tells it that we don't.

This might seem pointless, because "speed limit" only means the same thing as "55" and takes more typing. But there are two reasons why authors might want to use this feature anyway. One is that it's easier for a human reader to understand the significance of a line like:

if the speed is greater than the speed limit, ...

Another is that it makes it easier to change our minds about the value, because if we decide we want 70 as the limit and not 55, we only need to make one change at the start of the source text:

The speed limit is always 70.

which is much easier than combing through a long source text trying to find many individual things which need changing.

"Speed limit" is then a number constant. Any attempt to set this elsewhere, or change its value, will result in a Problem message, and moreover it can be used in contexts where only constant values are allowed. For example,

The generic male appearance is always "He is a dude."
Trevor is a man. The description of Trevor is the generic male appearance.

means that the SHOWME TREVOR testing command produces, among other data:

description: "He is a dude."

Although it is only useful to a limited extent, we can make any number of copies of something:

"Polygons"
A shape is a kind of thing. A square is a kind of shape. A triangle is a kind of shape.
The Geometry Lab is a room. In the Geometry Lab are three triangles and two squares.

The description "three triangles" makes three identical things, each of the kind "triangle", and similarly for the squares. When the above is compiled, the player can type TAKE TWO TRIANGLES or TAKE ALL THE TRIANGLES and so forth.

Four caveats. Firstly, a counted-out description like "two squares" is only allowed if it combines a number with the name of a kind which is already known (perhaps modified with adjectives, so "two open doors" is fine). If we say:

Two circles are in the Lab.

without having defined "circle" as a kind in advance, then only a single object will be created – whose name is "two circles". (This is because many natural names start with numbers: "six of clubs", for instance, referring to a single playing card, or "12 Hollywood Close" meaning a single house. We wouldn't want such names to be misinterpreted.)

The second caveat is that excessive duplication is expensive in memory and running time. It is perfectly legal to say

In the Lab are 75 triangles.

but the resulting story may be a little sluggish: and Inform draws the line at 100, refusing to create more duplicates than that in any single place. If we really need more than about fifty duplicated objects – say, a tombola containing raffle tickets numbered 1 to 1000 – it is usually better to find some less literal way to simulate this: for instance, only having a single raffle ticket, but with a randomly chosen number on it.

If there are very many items in the same place, commands like TAKE ALL and DROP ALL may mysteriously not quite deal with all of them – this is because the parser, the run-time program which deciphers typed commands, has only limited memory to hold the possibilities. It can be raised with a use option like so:

Use maximum things understood at once of at least 200.

(The default is, as above, 100. Note the "at least".)

Thirdly, note that Inform's idea of "identical" is based on what the player could type in a command to distinguish things. In a few cases this can make items unexpectedly identical. For example:

The Lab is a room. A chemical is a kind of thing. Some polyethylene and polyethylene-terephthalate are chemicals in the Lab.

results surprisingly in "You can see two chemicals here", because the run-time system truncates the words that are typed – POLYETHYLENE and POLYETHYLENE-TEREPHTHALATE look like the same word in a typed command. So Inform decides that these are indistinguishable chemicals. Typically words are truncated after 9 letters, though (unless the Glulx setting is used) punctuation inside a word, such as an apostrophe, can make this happen earlier. The best way to avoid trouble is simply to use more easily distinguishable names. For example:

Some polyethylene and polyethylene terephthalate are chemicals in the Lab.

works fine, because now only one chemical can be called TEREPHTHALATE, and that means they can be distinguished.

Finally: numbers up to twelve may be written out in words in the source text, but larger ones must be written as numerals. So "twelve" or "12", but "13" only.

Example

55.
Early Childhood ★★★
A child's set of building blocks, which come in three different colours – red, green and blue – but which can be repainted during play.

In the previous chapter, we saw that it was possible to make sub-parts of things. For instance,

The white door is in the Drawing Room. The handle is part of the white door.

creates a door with an attached handle. But what if we want to say that not just this door, but every door, should have a handle? To do this we first need to create a kind called "handle", since there will clearly need to be many handles. The solution is:

A handle is a kind of thing. A handle is part of every door.

"Every" is a loaded word and best used sparingly. A sentence like "A handle is part of every handle" would, if taken literally, mean that a handle takes forever to make and is never finished. Inform will reject this, but the moral is clear: we should think about what we are doing with "every".

We will usually want to work with smaller collections – not literally every room, but with a whole set of them all the same. We can do that like so:

A silver coin is a kind of thing. A banking room is a kind of room. Five silver coins are in every banking room.

The effect of sentences like these is to make what we might call "assemblies" instead of single things. When a banking room is created, so are five more silver coins; when a door is created, so is another handle. Such sentences act not only on items created later on in the source text, but also on all those created so far.

This is especially useful for body parts. If we would like to explore Voltaire's suggestion that history would have been very different if only Cleopatra's nose had been shorter, we will need noses:

A nose is a kind of thing. A nose is part of every person.

Of course, if we make an assembly like this then we had better remember that the player is also a person and also gets a nose. In fact slightly odd things can happen if we combine this with changing the identity of the player. This works:

Cleopatra is a woman in Alexandria. The player is Cleopatra.
A nose is a kind of thing. A nose is part of every person.

but if those lines are in reverse order then Cleopatra's nose is assembled before she becomes the player, with the result that it ends up called "Cleopatra's nose" rather than "your nose" in play – which is very regal but probably not what we want. To avoid this, settle the player's identity early on in the source text.

All of the assemblies above make objects. Most make these new objects "part of" existing ones, but as we saw, they can also be "in" or "on" them. In fact, though, assemblies work in much more general ways: they can assemble values of almost any kind, placed in almost any relationship. To make use of that, we need to create a new verb, a topic which won't be covered properly until a later chapter, but here goes:

A colour is a kind of value. The colours are red, green and blue.
Liking relates various people to various colours. The verb to like means the liking relation.
Every person likes a colour.

Now every time a person is created, so is a colour which that person will like. If there are two people in the world, the player and Daphne, then we now have five colours: red, green, blue, Daphne's colour and the player's colour. Alternatively, we can assemble the other way around:

A person likes every colour.

Now we're telling Inform that every time a colour is made, a new person is also made – someone who will like that colour. So this sentence effectively makes three new people, one who likes red, one who likes green, and one who likes blue.

Examples

A kind for jackets, which always includes a container called a pocket.
57.
Model Shop ★★
An "on/off button" which controls whatever device it is part of.
58.
U-Stor-It ★★★
A "chest" kind which consists of a container which has a lid as a supporter.
59.
Instructing Inform to prefer different interpretations of EXAMINE NOSE, depending on whether the player is alone, in company, or with Rudolph the Red-nosed Reindeer.

Something skated over in the previous section is the question of how Inform gives names to objects (or other values) it creates in an assembly. The standard thing naming combines the names of what's being assembled. For example:

A nose is a kind of thing. A nose is part of every person. Antony and Cleopatra are people.

might result in the creation of "Antony's nose", part of Antony, and "Cleopatra's nose", part of Cleopatra. In this way, Inform names the noses after their owners. It will always do this unless there are multiple indistinguishable things being created, as in the "five silver coins are in every banking room" example: those will all just be called "silver coin".

A small pitfall of this is that if we write:

Marcus Tullius Cicero is a person.

then although "Marcus Tullius Cicero's nose" and "Cicero's nose" are both valid names for the consular nose, "Marcus's nose" is not.

The standard naming scheme is often about right, but as usual Inform offers a way to improve it in particular cases. For example, if we write:

Every room contains a vehicle (called its buggy).

then we will find the world full of, say, the Garden buggy, the Patio buggy and so on – instead of the Garden vehicle, the Patio vehicle and so on, which is what we would have had without the "called…" part. Similarly, we could write:

A person (called its fan) likes every colour.
Every person likes a colour (called his favourite colour).

The former would produce new people with names like "Green's fan", whereas the latter would produce new colours with names like "Daphne's favourite colour".

So much for an informal description. Here is exactly what Inform does:

(1a) If there is a "called..." text, Inform uses it, expanding out "its" (or "his" or "her" or "their") to a possessive form of the name of the owner, so to speak, and "it" (or "he" or "she" or "they" or "him" or "them") to the name itself.
(1b) If there's no "called..." text, Inform behaves as if we had written "(called its K)", where K is the name of the kind.
(2) If this results in a value which isn't an object being given a name which already exists, Inform tacks on a number to force the new name to be different from existing ones: e.g., "Daphne's colour 2", "Daphne's colour 3", ...

(The reason that (2) doesn't affect objects is that objects are allowed to have names clashing with other objects, or no name at all, whereas other values have to have names belonging to themselves alone.)

That concludes our tour through the design of the initial state of a simulated world. We have seen how to create rooms and to stock them with containers, supporters, devices, doors, men and women. The player of such a simulation can explore, move things around, open and close certain doors and containers, lock or unlock them provided a suitable key is found, switch machines on or off, and so on.

But that is about all. There is as yet no element of surprise, no aim or sense of progress to be earned, and no narrative thread. We have painted the backcloth, and laid out the properties, but the actors have yet to take the stage.

5. Text

In the previous chapter, we gave properties to certain kinds of things in order to change their appearance and behaviour, and saw brief glimpses of one of Inform's most useful devices: text substitution. The following gives a more complete example:

"The Undertomb"
A dead end is a kind of room with printed name "Dead End" and description "This is a dead end. You'll have to go back the way you came, consoled only by [river sound]." A dead end is usually dark.
The Undertomb is a dark room. East is a dead end. South is a dead end with printed name "Collapsed Dead End". Northwest is a dead end called the Tortuous Alcove. In the Undertomb is the lantern. It is lit.
A dead end has some text called river sound. The river sound of a dead end is usually "a faint whispering of running water". The Tortuous Alcove has river sound "a gurgle of running water".

The novelty here is the text in square brackets in the first paragraph. They imply more or less what they would when a journalist is quoting something in a newspaper article. The actual words "river sound" are not part of the text. Instead, when Inform prints up the description of a dead end, it will substitute the appropriate river sound in place of these words.

Thus the description of the Collapsed Dead End is "This is a dead end. You'll have to go back the way you came, consoled only by a faint whispering of running water.", whereas the description of the Tortuous Alcove is "This is a dead end. You'll have to go back the way you came, consoled only by a gurgle of running water." As the player explores these dead ends, subtle differences will appear in their room descriptions.

Text is so fundamental to Inform that the basics had to be covered back in Chapter 2, so let's begin this new chapter with a recap.

Literal text is written in double-quotation marks. It's mostly true that what you see is what you get: the literal text "The Hands of the Silversmith" means just

The Hands of the Silversmith

But four characters are read in unexpected ways: [, ], ' and ". The rules are as follows:

Exception 1. Square brackets [ and ] are used to describe what Inform should say, but in a non-literal way. For example,

"Your watch reads [time of day]."

might produce

Your watch reads 9:02 AM.

These are called "text substitutions". They're highly flexible, and they can take many different forms. But as useful as they are, they do seem to stop us from making actual [ and ] characters come through on screen. To get around that:

say "[bracket]"

This text substitution expands to a single open square bracket, avoiding the problem that a literal [ in text would look to Inform like the opening of a substitution. Example:

"He [bracket]Lord Astor[close bracket] would, wouldn't he?"

prints as "He [Lord Astor] would, wouldn't he?".

say "[close bracket]"

This text substitution expands to a single close square bracket, avoiding the problem that a literal ] in text would look to Inform like the closing of a substitution. Example:

"He [bracket]Lord Astor[close bracket] would, wouldn't he?"

prints as "He [Lord Astor] would, wouldn't he?".

Exception 2. 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 good because typing a double quotation mark inside the quote wouldn't work – it would end the text then and there. Single quotation marks inside words, such as the one in "it's", remain apostrophes.

The rule looks odd at first, but turns out to be very practical. The only problem arises if we need an apostrophe at the start or end of a word, or a double inside one. Again, substitutions can fix this:

say "[apostrophe/']"

This text substitution expands to a single quotation mark, avoiding Inform's ordinary rule of converting literal single quotation marks to double at the edges of words. Example:

Instead of going outside, say "Lucy snaps, 'What's the matter? You don't trust my cookin[apostrophe] mister?'"

produces:

Lucy snaps, "What's the matter? You don't trust my cookin' mister?"

A more abbreviated form would be:

Instead of going outside, say "Lucy snaps, 'What's the matter? You don't trust my cookin['] mister?'"

which has exactly the same meaning.

say "[quotation mark]"

This text substitution expands to a double quotation mark. Most of the time this is unnecessary because of Inform's rule of converting literal single quotation marks to double at the edges of words, so it's needed only if we want a double-quote in the middle of a word for some reason. Example:

"The compass reads 41o21'23[quotation mark]E."

which produces: The compass reads 41o21'23"E. (Note that ["] is not allowed; a double-quotation mark is never allowed inside double-quoted text, not even in a text substitution.)

Exception 3. 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. Again, sometimes this is not what we want – the full rules are complicated enough to be worth a whole section later in the chapter.

We can put almost any description of a value in square brackets in text, and Inform will work out what kind of value it is and print something accordingly. (Only almost any, because we aren't allowed to use commas or more quotation marks inside a square-bracketed substitution.)

say "[(sayable value)]"

This text substitution takes the value and produces a textual representation of it. Most kinds of value, and really all of the useful ones, are "sayable" – numbers, times, objects, rules, scenes, and so on. Example:

The description of the wrist watch is "The dial reads [time of day]."

Here "time of day" is a value – it's a time that varies, and time is a sayable kind of value, so we might get "The dial reads 11:03 AM."

The values we say most often are objects. If we simply put the name of what we want into square brackets, this will be substituted by the full printed name. We might find:

"You admire [lantern]."
= "You admire candle lantern."

But this reads oddly – clearly "the" or "a" is missing. So the following substitutions are used very often:

say "[a (object)]"
or…
say "[an (object)]"

This text substitution produces the name of the object along with its indefinite article. Example:

Instead of examining something (called the whatever):
   "You can only just make out [a whatever]."

which might produce "You can only just make out a lamp-post.", or "You can only just make out Trevor.", or "You can only just make out some soldiers." The "a" or "an" in the wording is replaced by whatever indefinite article applies, if any.

say "[A (object)]"
or…
say "[An (object)]"

This text substitution produces the name of the object along with its indefinite article, capitalised. Example:

Instead of examining something (called the whatever):
   "[A whatever] can be made out in the mist."

which might produce "A lamp-post can be made out in the mist.", or "Trevor can be made out in the mist.", or "Some soldiers can be made out in the mist." The "A" or "An" in the wording is replaced by whatever indefinite article applies, if any.

say "[the (object)]"

This text substitution produces the name of the object along with its definite article. Example:

Instead of examining something (called the whatever):
   "You can only just make out [the whatever]."

which might produce "You can only just make out the lamp-post.", or "You can only just make out Trevor.", or "You can only just make out the soldiers." The "the" in the wording is replaced by whatever definite article applies, if any.

say "[The (object)]"

This text substitution produces the name of the object along with its definite article, capitalised. Example:

Instead of examining something (called the whatever):
   "[The whatever] may be a trick of the mist."

which might produce "The lamp-post may be a trick of the mist.", or "Trevor may be a trick of the mist.", or "The soldiers may be a trick of the mist." The "The" in the wording is replaced by whatever definite article applies, if any.

This may not look very useful, because why not simply put "the", or whatever, into the ordinary text? The answer is that there are times when we do not know in advance which object will be involved. For instance, as we shall later see, there is a special value called "the noun" which is the thing to which the player's current command is applied (thus, if the player typed TAKE BALL, it will be the ball). So:

After taking something in the Classroom:
   "You find [a noun]."

might produce replies like "You find a solid rubber ball.", "You find an ink-stained blouse.", "You find some elastic bands.", or even "You find Mr Polycarp." (the school's pet hamster, perhaps).

When a numerical value is given in a square-bracketed substitution, it is ordinarily printed out in digits. Thus:

"You've been wandering around for [turn count] turns now."

might print as "You've been wandering around for 213 turns now.", if the story has been played out for exactly that many commands. But if we prefer:

say "[(number) in words]"

This text substitution writes out the number in English text. Example:

"You've been wandering around for [turn count in words] turns now."

might produce "You've been wandering around for two hundred and thirteen turns now." The "and" here is natural on one side of the Atlantic but not the other – so with the "Use American dialect." option in place, it disappears.

Either way, though, there is some risk of the following:

You've been wandering around for one turns now.

We can avoid this using the special substitution:

say "[s]"

This text substitution prints a letter "s" unless the last number printed was 1. Example:

"You've been wandering around for [turn count in words] turn[s] now."

produces "… for one turn now." or "… for two turns now." as appropriate. Note that it reacts only to numbers, not to other arithmetic values like times (or, for instance, weights from the "Metric Units" extension).

This only solves one case, but it's memorable, and the case is one which turns up often.

Example

60.
Ballpark ★★★
A new "to say" definition which allows the author to say "[a number in round numbers]" and get verbal descriptions like "a couple of" or "a few" as a result.

We often want running text to include lists of items.

say "[list of (description of objects)]"

This text substitution produces a list, in sentence form, of everything matching the description. Example:

"Mr Darcy glares proudly at you. He is wearing [list of things worn by Darcy] and carrying [list of things carried by Darcy]."

And, if this were from a dramatisation of the novel by Miss Fielding rather than Miss Austen, we might find:

Mr Darcy glares proudly at you. He is wearing a pair of Newcastle United boxer shorts and carrying a self-help book.

If the description matches nothing – for instance, if Darcy has empty hands – then "nothing" is printed.

As with all lists in Inform, the serial comma is only used if the "Use serial comma." option is in force. So by default we would get "a fishing pole, a hook and a sinker", rather than "a fishing pole, a hook, and a sinker".

We then need variations to add indefinite or definite articles, and to capitalise the first item. For example,

"Mr Darcy impatiently bundles [the list of things carried by Darcy] into your hands and stomps out of the room."

might result in

Mr Darcy impatiently bundles the self-help book and the Christmas card into your hands and stomps out of the room.
say "[a list of (description of objects)]"

This text substitution produces a list, in sentence form, of everything matching the description. Each item is prefaced by its indefinite article. Example:

a maritime bill of lading, some hemp rope and Falconer's Naval Dictionary
say "[A list of (description of objects)]"

This text substitution produces a list, in sentence form, of everything matching the description. Each item is prefaced by its indefinite article, and the first is capitalised, so that it can be used at the beginning of a sentence. Example:

A maritime bill of lading, some hemp rope and Falconer's Naval Dictionary
say "[the list of (description of objects)]"

This text substitution produces a list, in sentence form, of everything matching the description. Each item is prefaced by its definite article. Example:

the maritime bill of lading, the hemp rope and Falconer's Naval Dictionary
say "[The list of (description of objects)]"

This text substitution produces a list, in sentence form, of everything matching the description. Each item is prefaced by its definite article, and the first is capitalised, so that it can be used at the beginning of a sentence. Example:

The maritime bill of lading, the hemp rope and Falconer's Naval Dictionary

So much for articles. A more insidious problem comes with something like this:

"The places you can go are [list of rooms]."

The trouble is that the list may end up either singular or plural. We might be expecting something like:

The places you can go are Old Bailey, Bridget's Flat and TV Centre.

But if there is only one room, then the result might be:

The places you can go are Bridget's Flat.

which is wrong. We can get around this with careful wording and a slightly different substitution:

"Nearby [is-are list of rooms]."
say "[is-are list of (description of objects)]"

This text substitution produces a list, in sentence form, of everything matching the description. The whole list starts with "is" (if there's one item or none) or "are" (more than one). Examples:

is marlin-spike
are maritime bill of lading, hemp rope and Falconer's Naval Dictionary
say "[is-are a list of (description of objects)]"

This text substitution produces a list, in sentence form, of everything matching the description. Each item is prefaced by its indefinite article, and the whole list starts with "is" (if there's one item or none) or "are" (more than one). Examples:

is a marlin-spike
are a maritime bill of lading, some hemp rope and Falconer's Naval Dictionary
say "[is-are the list of (description of objects)]"

This text substitution produces a list, in sentence form, of everything matching the description. Each item is prefaced by its definite article, and the whole list starts with "is" (if there's one item or none) or "are" (more than one). Examples:

is the marlin-spike
are the maritime bill of lading, the hemp rope and Falconer's Naval Dictionary
say "[a list of (description of objects) including contents]"

This text substitution produces a list, in sentence form, of everything matching the description, noting any contents in brackets. This is really intended only to be used by the Standard Rules.

Examples

Objects which automatically include a description of their component parts whenever they are examined.
62.
A lawn made up of several rooms, with part of the description written automatically.

Text sometimes needs to take different forms in different circumstances. Perhaps it needs an extra sentence if something has happened, or perhaps only one altered word.

say "[if (a condition)]"

This text substitution produces no text. It's used only for a side-effect: it says that the text following should be said only if the condition is true. That continues until the end of the text, or until an "[end if]" substitution, whichever comes first. If the "[otherwise]" and "[otherwise if]" substitutions are also present, they allow alternatives to be added in case the condition is false. Example:

The wine cask is a container. The printed name of the cask is "[if open]broached, empty cask[otherwise]sealed wine cask".

we find that the cask is described as "a broached, empty cask" when open, and "a sealed wine cask" when closed. A longer example which begins and ends with fixed text, but has two alternatives in the middle:

The Customs Wharf is a room. "Amid the bustle of the quayside, [if the cask is open]many eyes stray to your broached cask. [otherwise]nobody takes much notice of a man heaving a cask about. [end if]Sleek gondolas jostle at the plank pier."
say "[unless (a condition)]"

This text substitution produces no text. It's used only for a side-effect: it says that the text following should be said only if the condition is false. That continues until the end of the text, or until an "[end if]" substitution, whichever comes first. If the "[otherwise]" and "[otherwise if]" substitutions are also present, they allow alternatives to be added in case the condition is true. Example:

The Customs Hall is a room. "With infinite slowness, with ledgers and quill pens, the clerks ruin their eyesight.[unless the player is a woman] They barely even glance in your direction."
say "[otherwise]"
or…
say "[else]"

This text substitution produces no text, and can be used only following an "[if …]" or "[unless …]" text substitution. It switches from text which appears if the condition is true, to text which appears if it is false. Example:

The wine cask is a container. The printed name of the cask is "[if open]broached, empty cask[otherwise]sealed wine cask".
say "[end if]"

This text substitution produces no text, and can be used only to close off a stretch of varying text which begins with "[if …]".

say "[end unless]"

This text substitution produces no text, and can be used only to close off a stretch of varying text which begins with "[unless …]".

say "[otherwise/else if (a condition)]"

This text substitution produces no text, and can be used only following an "[if …]" or "[unless …]" text substitution. It gives an alternative text to use if the first condition didn't apply, but this one does. Example:

The wine cask is a container. The printed name of the cask is "[if open]broached, empty cask[otherwise if transparent]sealed cask half-full of sloshing wine[otherwise]sealed wine cask".
say "[otherwise/else unless (a condition)]"

This text substitution produces no text, and can be used only following an "[if …]" or "[unless …]" text substitution. It gives an alternative text to use if the first condition didn't apply, and this one is false too.

We sometimes need to be careful about the printing of line breaks:

The Cell is a room. "Ah, [if unvisited]the unknown cell. [otherwise]the usual cell."

This room description has two possible forms: "Ah, the unknown cell. ", at first sight, and then "Ah, the usual cell." subsequently. But the second form is rounded off with a line break because the last thing printed is a ".", whereas the first form isn't, because it ended with a space. The right thing would have been:

The Cell is a room. "Ah, [if unvisited]the unknown cell.[otherwise]the usual cell."

allowing no space after "unknown cell."

When varying descriptions are being given for kinds of rooms or things, it can be useful to make use of a special value called "item described", which refers to the particular one being looked at right now. For example:

A musical instrument is a kind of thing. The tuba and the xylophone are musical instruments. The description of a musical instrument is usually "An especially shiny, well-tuned [item described]."

The tuba now has the description "An especially shiny, well-tuned tuba.", and similarly for the xylophone.

The "item described" value can similarly be used in any textual property of a room or thing, and in particular can be used with the "initial appearance" and "printed name" properties, which are also forms of description.

Examples

63.
When?
A door whose description says "…leads east" in one place and "…leads west" in the other.
64.
Whence? ★★★
A kind of door that always automatically describes the direction it opens and what lies on the far side (if that other room has been visited).
65.
Persephone ★★★
Separate the player's inventory listing into two parts, so that it says "you are carrying…" and then (if the player is wearing anything) "You are also wearing…".

Sometimes we would like to provide a little quirky variation in text, especially in messages which will be seen often. We can achieve this with the "[one of]… [or] … [or] …" construction.

say "[one of]"

This text substitution produces no text. It's used only for a side-effect: it switches between a number of alternative texts, which follow it and are divided by "[or]" substitutions, according to a strategy given in a closing substitution. Example:

"You flip the coin. [one of]Heads[or]Tails[purely at random]!"

Here there are just two alternatives, and the strategy is "purely at random". Exactly half of the time the text will be printed as "You flip the coin. Heads!"; and the other half, "You flip the coin. Tails!".

say "[or]"

This text substitution produces no text, and can be used only in a "[one of]…" construction. It divides alternative wordings. Example:

"You flip the coin. [one of]Heads[or]Tails[purely at random]!"

There are seven possible endings, each making the choice of which text to follow in a different way:

say "[purely at random]"

This text substitution produces no text, and can be used only to end a "[one of]…" construction. It indicates that the alternatives are chosen uniformly randomly.

say "[then purely at random]"

This text substitution produces no text, and can be used only to end a "[one of]…" construction. It indicates that the alternatives are chosen in sequence until all have been seen, but that after that they are chosen uniformly randomly.

say "[at random]"

This text substitution produces no text, and can be used only to end a "[one of]…" construction. It indicates that the alternatives are chosen at random except that the same choice cannot come up twice running. This is useful to avoid the deadening effect of repeating the exact same message. Example:

"The light changes randomly again; now it's [one of]green[or]amber[or]red[at random]."

Here we can safely say the light "changes", because the new colour cannot be the same as the one printed the last time.

say "[then at random]"

This text substitution produces no text, and can be used only to end a "[one of]…" construction. It indicates that the alternatives are chosen in sequence until all have been seen, and then after that, at random except that the same choice cannot come up twice running. Example:

"Maybe the murderer is [one of]Colonel Mustard[or]Professor Plum[or]Cardinal Cerise[then at random]."
say "[sticky random]"

This text substitution produces no text, and can be used only to end a "[one of]…" construction. It indicates that a random choice is made the first time the text is printed, but that it sticks from there on. Example:

"The newspaper headline is: [one of]War Casualties[or]Terrorists[or]Banks[sticky random] [one of]Continue To Expand[or]Lose Out[sticky random]."

Although the newspaper headline will change with each playing, it will not alter during play.

say "[as decreasingly likely outcomes]"

This text substitution produces no text, and can be used only to end a "[one of]…" construction. It indicates that the alternatives are chosen at random, except that the first is most likely to be chosen, the second is next most likely, and so on down to the rarest at the end. Example:

"Zorro strides by, [one of]looking purposeful[or]grim-faced[or]deep in thought[or]suppressing a yawn[or]scratching his ribs[or]trying to conceal that he has cut himself shaving[as decreasingly likely outcomes]."

There are six outcomes here: the first is six times as likely as the last, and those in between are similarly scaled, so Zorro cuts himself shaving only once in 21 tries, while he looks purposeful almost a third of the time.

But suppose we want to tuck some useful information in these messages, and we want to be sure that the player will see it. Because all of the above options involve randomness, it's possible that an unlucky player might miss a clue placed into only one variant of the message. One fix for this is to make sure that everything turns up sooner or later:

say "[in random order]"

This text substitution produces no text, and can be used only to end a "[one of]…" construction. A random order is chosen for the alternative passages of text, and they are used in that order as the text is printed again and again. When one random cycle finishes, a new one begins. The effect is somewhat like the "shuffle album" feature on an iPod. Example:

"You dip into the chapter on [one of]freshwater fish[or]hairless mammals[or]extinct birds[or]amphibians such as the black salamander[in random order]."

One small restriction: if there are more than 32 variations, purely random choices will be printed, and there will be no guarantee that repeats are prevented.

Another fix is to avoid randomness altogether:

say "[cycling]"

This text substitution produces no text, and can be used only to end a "[one of]…" construction. It indicates that the alternatives are used one at a time, in turn: after the last one is reached, we start again from the first. Example:

"The pundits discuss [one of]the weather[or]world events[or]celebrity gossip[cycling]."
say "[stopping]"

This text substitution produces no text, and can be used only to end a "[one of]…" construction. It indicates that the alternatives are used one at a time, in turn: once the last one is reached, it's used forever after. Example:

"[one of]The phone rings[or]The phone rings a second time[or]The phone rings again[stopping]."

Finally, here's a convenient shorthand for one of the commonest things needed:

say "[first time]"
or…
say "[only]"

This pair of text substitutions causes whatever is between them to be printed only the first time the text is printed. Example:

"The screen door squeaks loudly as when you open it. [first time]Well, you'll get used to it eventually. [only]"

This is exactly equivalent to

"The screen door squeaks loudly as when you open it. [one of]Well, you'll get used to it eventually. [or][stopping]";

but easier to read.

Something to watch out for is that texts are sometimes being printed internally for purposes other than actual output which the player can see, and this is particularly true of names. For example:

Before printing the name of the traffic signal: say "[one of]green[or]amber[or]red[cycling] ".

This looks good for some purposes, but may not cycle in the sequence expected, and can result in incorrect indefinite articles being printed – "an red traffic signal", for example. What's happening is that the name is being printed internally to see whether it begins with a vowel; that prints "amber traffic signal", but invisibly to us, and since this does begin with a vowel, "an" is visibly printed; then the name is visibly printed, but now it has changed to "red traffic signal", and so the result on screen is "an red traffic signal". There are many ways to avoid this (for example, to give the traffic signal a state which changes every turn, not every time the name is printed), but it's a trap to look out for.

Examples

66.
A radio that produces a cycle of output using varying text.
67.
Creating characters who change their behavior from turn to turn, and a survey of other common uses for alternative texts.

Inform controls the flow of text being said so that it will read, to the player, in a natural way. There are two principles:

(a) pieces of text ending with full stop, exclamation or question marks will be followed by line breaks (or "new lines", as some computer programming languages would call them); and

(b) pieces of text produced by different rules in Inform will be separated by paragraph breaks.

The effect is that authors can forget about paragraph spacing most of the time, but the mechanism is not impossible to fool, so text substitutions are provided to override the usual principles. First, to manipulate line breaks:

say "[line break]"

This text substitution produces a line break. Example:

"There is an endless sense of[line break]falling and[line break]falling."

Line breaks are not paragraph breaks, so the result is:

There is an endless sense of
falling and
falling.

with no extra vertical spacing between these lines.

say "[no line break]"

This text substitution produces no text. It's used only for a side-effect: it prevents a line break where Inform might otherwise assume one. Example:

"The chorus sing [one of]Jerusalem[or]Rule, Britannia![no line break][at random]."

Here the "[no line break]" stops Inform from thinking that the exclamation mark means a sentence ending – it's part of the name of the song "Rule, Britannia!". So we get

The chorus sing Rule, Britannia!.

with no line break between the "!" and ".".

And similarly for paragraph breaks. Because Inform can be pretty trigger-happy with these, the first need is for a way to stop them:

say "[run paragraph on]"

This text substitution produces no text. It's used only for a side-effect: it prevents a paragraph break occurring after the present text is printed, in case Inform might be tempted to place one there. Example:

Before taking something, say "Very well. [run paragraph on]".

This allows the reply to, say, TAKE ENVELOPE to be

Very well. Taken.

rather than

Very well.
Taken.

which is how texts produced by different rules would normally be shown. (It's a traditional printer's term. See Oldfield's Manual of Typography, 1892, under "When two paragraphs are required to be made into one, or, in technical language, 'to run on'.")

But sometimes we actually want paragraph breaks in unexpected places. One way is to force them outright:

say "[paragraph break]"

This text substitution produces a paragraph break. Example:

"This is not right.[paragraph break]No, something is terribly wrong."

Paragraph breaks have a little vertical spacing in them, unlike mere line breaks, so the result is:

This is not right.
No, something is terribly wrong.

More subtly, we can give Inform the option:

say "[conditional paragraph break]"

This text substitution either produces a paragraph break, or no text at all. It marks a place where Inform can put a paragraph break if necessary; in effect it simulates what Inform does every time a "before" or similar rule finishes. If there is text already printed, and text then follows on, a paragraph break is made. But if not, nothing is done. This is sometimes useful when producing a large amount of text which changes with the circumstances so that it is hard to predict in advance whether a paragraph break is needed or not.

Really finicky authors might possibly want to know this:

if a paragraph break is pending:

This condition is true if text has recently been said in such a way that Inform expects to add a paragraph break at the next opportunity (for instance when the present rule ends and another one says something, or when a "[conditional paragraph break]" is made).

Finally, there are two special sorts of paragraph break for special circumstances. They are mainly used by the Standard Rules, and imitate the textual layout styles of traditional IF.

say "[command clarification break]"

This text substitution produces a line break, and then also a paragraph break if the text immediately following is a room description brought about by having gone to to a different room and looking around, in which case a line break should be added. In traditional IF, this is used when clarifying what Inform thinks the player intended by a given command. Example:

say "(first opening [the noun])[command clarification break]";

might result in

(first opening the valise)
You rummage through the valise for tickets, but find nothing.
say "[run paragraph on with special look spacing]"

This text substitution produces no text. It's used only for a side-effect: it indicates that the current printing position does not follow a skipped line, and that further material is expected which will run on from the previous paragraph, but that if no further material turns up then a skipped line would be needed before the next command prompt. (It's very likely that only the Standard Rules will ever need this.)

Example

Making the SEARCH command examine all the scenery in the current location.

Inform does not go in for the use of fonts: a work of IF will be rendered with different fonts on different machines anyway, from tiny personal organisers up to huge workstations. However, it does allow for a modest amount of styling.

say "[bold type]"

This text substitution produces no text. It's used only for a side-effect: to make the text following it appear in bold face. "[roman type]" should be used to switch back to normal. Example:

"Jane looked down. [bold type]Danger[roman type], the sign read."
say "[italic type]"

This text substitution produces no text. It's used only for a side-effect: to make the text following it appear in italics. "[roman type]" should be used to switch back to normal. Example:

"This is [italic type]very suspicious[roman type], said Peter."
say "[roman type]"

This text substitution produces no text. It's used only for a side-effect: to return to ordinary Roman type after a previous use of "[bold type]" or "[italic type]".

but there is one other effect we can employ:

say "[fixed letter spacing]"

This text substitution produces no text. It's used only for a side-effect: to make the text following it appear with fixed letter spacing. In variable letter spacing, a lower case "m" is much wider than an "l", which is natural to the eye since it has been printing practice since the Renaissance. Fixed letter spacing is more like typewriting, and it is best used to reproduce typewritten text or printed notices; it can also be convenient for making simple diagrams. Example:

"On the door is written: [fixed letter spacing]J45--O-O-O[variable letter spacing]."
say "[variable letter spacing]"

This text substitution produces no text. It's used only for a side-effect: to return to ordinary letter spacing after a previous use of "[fixed letter spacing]".

Whichever effect we use, we should be careful to ensure that we return to normal – roman type and variable letter spacing – after any specially-treated text has been printed. Combining these effects (for, say, bold fixed-spaced lettering) is not guaranteed to work, though on some platforms it will.

Example

69.
Adding coloured text to the example of door-status readouts.

Inform 7 is infused by the English language, so it's a challenge using it to write a work of IF in any other language. (With that said, extensions do exist which have made considerable progress on this problem: nil desperandum.) But even a book in English contains occasional quotations or words borrowed from other tongues, so we are going to need more than plain A to Z.

The world has a bewildering range of letters, accents, diacritics, markers and signs. Inform tries to support the widest range possible, but the works of IF produced by Inform are programs which then have to be run on a (virtual) computer whose abilities are more constrained: few players will have an Ethiopian font installed, after all. So a degree of caution is called for.

(a) Definitely safe to use. Inform's highest level of support is for the letters found on a typical English typewriter keyboard, including both the $ and £ signs (but not the Yen or Euro symbols ¥ and €), and in addition the following:

ä, á, à, ã, å, â and Ä, Á, À, Ã, Å, Â
ë, é, è, ê and Ë, É, È, Ê
ï, í, ì, î and Ï, Í, Ì, Î
ö, ó, ò, õ, ø, ô and Ö, Ó, Ò, Õ, Ø, Ô
ü, ú, ù, û and Ü, Ú, Ù, Û
ÿ, ý and Ý (but not Ÿ)
ñ and Ñ
ç and Ç
æ and Æ (but not œ or Œ)
ß
¡, ¿

These characters can be typed directly into the Source panel, and can be used outside quotation marks: we can call a room the Église, for instance.

(b) Characters which can safely be used, but will be simplified. As it reads in the text, Inform silently converts all kinds of dash (en-rules, em-rules, etc.) to simple hyphens; converts the multiplication symbol to a lower case "x"; converts all kinds of space other than tabs (em-spaces, non-breaking spaces, etc.) to simple spaces, and all kinds of quotation marks to "straight" (non-smart) marks.

(c) Characters which can be used provided they are in quoted text (other than boxed quotations), and which will probably but not certainly be visible to the player. All other Latin letter-forms, including the œ ligature, East European forms such as ő, ş and ž, and Portuguese forms such as ũ; the Greek and Cyrillic alphabets, with their associated variants and accents; and the principal currency symbols, such as € and ¥. Such characters are not legal in unquoted text: so we could write

The Churchyard is a room. The printed name of the Churchyard is "Łodz Churchyard".

but not

Łodz Churchyard is a room.

Moreover, the player is not allowed to type these characters in commands during play: or rather, they will not be recognised if he does. They are for printing only.

(d) Characters which might work in quoted text, or might not. The Arabic and Hebrew alphabets are fairly likely to be available; miscellaneous symbols are sometimes legible to the player, sometimes not. Other alphabets are chancier still. (If a work of IF depends on these being visible, it may be necessary to instruct players to use specific interpreters, or to provide a way for the player to test that all will be well.)

As we have seen, Inform allows us to type a wide range of characters into the source text, although the more exotic ones may only appear inside quotation marks. But they become more and more difficult to type as they become more obscure. Inform therefore allows us to describe a letter using a text substitution rather than typing it directly.

Unicode characters can be named (or numbered) directly in text. For example:

"[unicode 321]odz Churchyard"

produces a Polish slashed L. If the Unicode Character Names or Unicode Full Character Names extensions are included, characters can also be named as well as numbered:

"[unicode Latin capital letter L with stroke]odz Churchyard"

The Unicode standard assigns character numbers to essentially every marking used in text from any human language: its full range is enormous. (Note that Inform writes these numbers in decimal: many reference charts show them in hexadecimal, or base 16, which can cause confusion.) Inform can only handle codes [unicode 32] up to [unicode 65535], so it is not quite so catholic, but the range is still enormous enough that code numbers are unfamiliar to the eye. Inform therefore allows us to use the official Unicode 4.1 names for characters, instead of their decimal numbers, provided we have Included the necessary extension like so:

Include Unicode Character Names by Graham Nelson.

This extension provides names for some 2900 of the most commonly used characters. It means, for instance, that we can write text such as:

"Dr Zarkov unveils the new [unicode Hebrew letter alef] Nought drive."
"Omar plays 4[unicode black spade suit] with an air of triumph."

Admittedly, these can get a little verbose:

"[unicode Greek small letter omega with psili and perispomeni and ypogegrammeni]"

But before getting carried away, we should remember the hazards: Inform allows us to type, say, "[unicode Saturn]" (an astrological sign) but it appears only as a black square if the resulting story is played by an interpreter using a font which lacks the relevant sign. For instance, Zoom for OS X uses the Lucida Grande and Apple Symbol fonts by default, and this combination does contain the Saturn sign: but Windows Frotz tends to use the Tahoma font by default, which does not. (Another issue is that the fixed letter spacing font, such as used in the status line, may not contain all the characters that the font of the main text contains.) To write something with truly outré characters is therefore a little chancy: users would have to be told quite carefully what interpreter and font to use to play it.

The "Unicode Character Names" extension, which is pre-installed in the standard distribution of Inform, defines names for the Latin, Greek, Cyrillic, Hebrew and Braille alphabets, together with currency and miscellaneous other symbols, including some for drawing boxes and arrows. It is only optionally installed because even this is quite large: but in case it should still prove inadequate, an alternative can be used:

Include Unicode Full Character Names by Graham Nelson.

This includes all 12,997 named characters in the 16-bit range of the Unicode 4.1 standard: it is the size of a small novel and its inclusion will slow Inform down. But if you want to experiment with Arabic, ecclesiastical Georgian, Cherokee, Tibetan, Syriac, the International Phonetic Alphabet, hexagrams or the unified Canadian aboriginal syllabics, "Unicode Full Character Names" (again built into Inform) is the extension for you.

Example

This example provides a fairly stringent test of exotic lettering.

Text is normally printed in between the typed commands of the player, rolling upwards from the bottom of the screen, as if a dialogue is being typed by an old-fashioned teletype. But it can also be displayed in a bolder way, floating above the main text, and this is sometimes used to display quotations.

display the boxed quotation (text)

This phrase displays the given text on screen in an overlaid box. For reasons to do with the way such quotations are plotted onto the screen, their text is treated literally: no substitutions in square brackets are obeyed. The quotation will only ever appear once, regardless of the number of times the "display the boxed quotation …" phrase is reached. Rather than being shown immediately – and thus, probably, scrolling away before it can be seen – the display is held back until the next command prompt is shown to the player. Example:

After looking in the Wabe, display the boxed quotation
   "And 'the wabe' is the grass-plot round
   a sun-dial, I suppose? said Alice,
   surprised at her own ingenuity.
   Of course it is. It's called 'wabe,'
   you know, because it goes a long way
   before it, and a long way behind it --
   -- Lewis Carroll".

This was the original example used in Trinity, by Brian Moriarty, which invented the idea. A player exploring Kensington Gardens comes upon a location enigmatically called The Wabe; and by way of explanation, this quotation pops up.

Note that exotic accented characters, such as the "Ł" in "Łodz", can't be displayed in boxed quotations. This is only a simple feature, and we should go in search of a suitable extension for fancier screen effects if we would like to do more.

If we have some textual effect which needs to occur in several different messages, we might want to create a new text substitution for it. For instance:

The Missile Base is a room. "[security notice]Seems to be a futuristic missile base." M's Office is east of the Missile Base. "[security notice]Admiral Sir M.- M.- glares up from his desk."
To say security notice:
   say "This area is a Prohibited Place within the meaning of the Official Secrets Act 1939. "

This is only the tip of the iceberg in how to define ways to do things using "To…", as we shall see. The definition makes "say the security notice" a new phrase known to Inform. A text substitution is exactly a phrase whose name begins with "say" (well – except for the "say" phrase itself), so the effect is that "[security notice]" is a new text substitution. Several of the examples in this chapter make use of this trick.

Inform often ignores the casing of the text it reads, but sometimes uses it as a clue to meaning. We have already seen that "[an item]" and "[An item]" produce different results, for instance. Similarly, it's possible to define two text substitutions which are the same except for the initial casing. We might write:

To say Security Notice:
   say "THIS AREA IS A PROHIBITED PLACE WITHIN THE MEANING OF THE OFFICIAL SECRETS ACT 1939. "

And now Inform will act on "[Security Notice]" differently from "[security notice]".

See Also

The phrasebook for other forms of phrase besides To say....

Examples

Using text substitution to make characters reply differently under the same circumstances.
Writing your own rules for how to carry out substitutions.

6. Descriptions

It is in describing circumstances that Inform really capitalises on the concise, expressive power of natural language, and this chapter brings together the facts about "descriptions".

The simplest descriptions consist of a noun alone. Some refer to single things ("lantern", or "wine cask"), others to kinds of thing ("dead end" or "container"). But we have also seen adjectives alone:

The oaken desk is fixed in place.

Here, "fixed in place" is a description which, to Inform's simple-minded grammar, is a single adjective. And of course adjectives and nouns can be combined:

The cargo trunk is an openable container.

The description "openable container" consists of the noun "container", meaning a kind of thing, and the adjective "openable", which means one of the two possible states of an either/or property held by that thing.

As the next chapter will show, rules also make great use of descriptions:

Instead of throwing something at a closed openable door, say "Or you could just use the handle like anyone else, of course."

We have already seen that we can list the items fitting a given description:

"You look down at [the list of things in the basket]."

It's also sometimes convenient to count them up:

number of (description of values)number

This phrase counts the number of values matching the description, which may of course be 0. Example:

number of open doors

produces the number of doors, anywhere in the model world, which are currently open. A Problem message is produced if the number is potentially infinite, or impractical to count: for instance, Inform rejects "number of odd numbers".

It is because descriptions are so widely useful that they deserve a chapter of their own, and this is it.

Descriptions can contain a noun, but need not, and can contain any number of adjectives:

supporter = the noun supporter
closed = the adjective closed
the open wine cask = the adjective open + the noun wine cask
something portable = (some) + the noun thing + the adjective portable

Note that we are not allowed to have more than one noun in the same description (something English occasionally does allow as a coded form of emphasis, as in "the man Jenkins" or "the harlot Helen").

Nouns are simple enough, referring either to kinds or specific things. The noun "something" means "some thing", so is actually a reference to the kind "thing". Inform treats this as having the same meaning as "anything", and all told there are eight special nouns of this kind, but with only three different meanings between them:

something = anything
someone = anyone = somebody = anybody
somewhere = anywhere

So for instance "anybody male" or "somewhere dark" are valid descriptions. These eight nouns are unusual in being allowed to come at the front of a description: nouns are usually expected to be at the end. (Inform also understands "nothing", "nowhere", "nobody", "no-one" and even "no one", which in a sense are opposites of "something" and the like, but for now we'll look at descriptions of things which do exist rather than don't.)

We have seen two sorts of adjectives so far: those which refer to either/or properties, like "open" and "closed", and those which come out of new kinds of value. If we define

Texture is a kind of value. The textures are rough, stubbly and smooth. Everything has a texture.

…then "rough", "stubbly" and "smooth" all become adjectives. (That last sentence "Everything has a texture" was essential, because without it Inform would not know that these words could meaningfully be applied to things.)

In addition to these adjectives, we can create new ones (as we shall see), and a few special adjectives such as "visible", "touchable" and "adjacent" are already defined for us by Inform.

Suppose we want to coin a word for supporters currently supporting something. We can do so with the following sentence:

Definition: A supporter is occupied if something is on it.

Note the colon, which is essential, and the usage of "it" in the definition part to refer to the object in question. (For this purpose we would write "it" even if we were defining a term about, say, a woman instead of a supporter, so that "she" or "her" might seem more appropriate – but see below.)

This creates the adjective "occupied", and gives it a definition valid for supporters. That restriction on validity means that non-supporters would always fail the description "something occupied"; which might be unfortunate if we wanted to talk about rooms being occupied. We could give a second definition thus:

Definition: A room is occupied if a person is in it.

These are entirely different senses of the word "occupied" – a mantelpiece is occupied if an invitation is on it, but for a drawing room to be occupied there must be human presence – and Inform applies whichever sense is relevant when deciding whether or not a given object is "occupied".

Often, though not always, we also want to give a name to the opposite possibility. We can do that as follows:

Definition: A room is occupied rather than unoccupied if a person is in it.

The "rather than…" part of the definition is optional, but it saves having to write a boringly similar definition of "unoccupied" out in longhand. (Note that Inform does not guess the meaning of "unoccupied" unless it has been explicitly told it. Such guesses are too risky, when so many "un-" words fail to conform to this pattern: "unified", "uncle", "ungulate" and so on.)

Newly defined adjectives cannot be used when creating things, because they are not explicit enough. Inform could not satisfy:

The Ballroom is occupied. The bucket is a large container.

because there is not enough information: by whom is the Ballroom occupied? How large, exactly? On the other hand, newly defined adjectives are very helpful in conditions and for rules, as we shall see later on.

It is occasionally clumsy having to refer to the subject of a definition using "it". We can avoid this and give the definition better legibility by supplying a name instead. For instance:

Definition: a direction (called thataway) is viable if the room thataway from the location is a room.

which is a good deal easier to read than

Definition: a direction is viable if the room it from the location is a room.

See Also

New conditions, new adjectives for giving more extensive definitions of new adjectives, using phrases.

Example

The "another" adjective for rules such as "in the presence of another person".

In general, any noun can have adjectives applied to it, and this means that values can have adjectives just as objects can. We have already seen that they can (in some cases, at least) have either/or properties, and this gives them adjectives just as for objects. But we can also write out definitions which apply to values:

Definition: A number is round if the remainder after dividing it by 10 is 0.
Definition: A time is late rather than early if it is at least 8 PM.

That makes the numbers 20 and 170 but not 37 meet the description "a round number", and the times 8 PM and 11:23 PM but not 9 AM meet the description "a late time". Because they come up fairly often, Inform contains several adjectives for numbers built in:

positive - one which is greater than zero (but not 0 itself)
negative - one which is less than zero (but not 0 itself)
even - a number like ..., -4, -2, 0, 2, 4, ...
odd - a number like ..., -5, -3, -1, 1, 3, 5, ...

Similarly, two useful adjectives are built in to talk about text:

empty - the text "", with no characters in it, not even spaces
non-empty - any text which does have at least one character in

Adjectives can have multiple definitions and, as long as each applies to a different sort of noun, there will be no problem. We could write:

A thing can be round, square or funny-shaped.
A container can be odd or ordinary.

And these definitions of "round" and "odd" will not interfere with the ones applying to numbers, because Inform can always look at the noun to see which definition is meant in any given case. For instance,

if the score is round, ...

must mean "round" in the sense of numbers, because the score is a number. Inform itself makes good use of this; "empty" also has meanings applying to rulebooks, lists and activities, for instance, as will be seen later.

Although it's more usual to give a definition to apply to a whole kind, we can actually give a specific definition to apply to just a single object or named value. For example:

A colour is a kind of value. The colours are red, green and blue.
Definition: red is subtle if the player is female.
Definition: a colour is subtle if it is blue.

The first definition of "subtle" takes precedence, of course, since it has the more specific domain – it applies only to red. The effect of this is that, if the player's female, the subtle colours are red and blue; if not, just blue.

Example

74.
Only You... ★★★
Smoke which spreads through the rooms of the map, but only every other turn.

Adjectives are often used in English to give a sense of where something is on a sliding scale. We talk about "a tall man" and "a short man", but without meaning that all men are either tall or short. If pushed, we might say that tall means about 6 feet and up, short means about 5 feet 6 and down, but we more often compare one person's height against another's.

Inform allows us to use adjectives in the same way. For example, every container has a number called its "carrying capacity". We can define:

Definition: A container is huge if its carrying capacity is 20 or more.
Definition: A container is large if its carrying capacity is 10 or more.
Definition: A container is standard if its carrying capacity is 7.
Definition: A container is small if its carrying capacity is 5 or less.

These definitions are similar to those in the previous section, but have a very specific (and strictly enforced) shape to them. The adjective must be a single word. We have to say "its" (i.e., of it), not the ungrammatical "it's"; we have to specify a property, and a literal value of it, and we must either give an exact value or else conclude with "or more" or "or less". If we create something with one of these properties:

The basket is a large container in the Shop. The thimble is a small container in the Shop. The matchbox is a standard container in the Shop.

then they will have the most moderate values they can have, that is, the basket will have carrying capacity 10 and the thimble 5 (and of course the matchbox 7). Both of the following tests will then fail:

if the basket is huge ...
if the basket is a small container ...

because the basket is neither huge nor small, but somewhere in between.

Sometimes the meaning of adjectives must depend on their context, as we see from the following example, where we assess heights in inches:

A person has a number called height. Definition: A man is tall if his height is 72 or more. Definition: A woman is tall if her height is 68 or more.

Inform then judges whether someone is or is not "tall" using different standards for men and for women, and

In the Shop are a tall man and a tall woman.

creates a man 72 inches tall and a woman 68 inches tall.

The special definitions in the previous section have a further effect. When we define:

Definition: A container is large if its carrying capacity is 10 or more.

we not only say how to test if something is large (see if its capacity is at least 10) and how to create something large (give it a capacity of exactly 10), we also create a new form of comparison. Thus,

if the basket is larger than the thimble ...
if the thimble is not larger than the basket ...

are both true. If we also define "huge" and "small", as in the previous section, we also get comparisons "huger than" and "smaller than". Note that "huger than" has exactly the same meaning as "larger than": we can use whichever wording seems more natural. (For bacilli, for instance, we would probably not say "huger than", even though the meaning would be unambiguous.)

We can also compare two things to see if they share the same value of a property. For instance, to go back to the heights example, once we define "tall" and "short", we get that exactly one of the following will be true:

if Adam is taller than Eve ...
if Adam is the same height as Eve ...
if Adam is shorter than Eve ...

Though it will not always seem natural wording, we can use the comparison "the same P as" for any property P which has a value. Do we think "if the basket is the same carrying capacity as the thimble" is good English? Maybe, maybe not. But we are always at liberty to spell things out in full:

if the carrying capacity of the basket is the carrying capacity of the thimble ...

Lastly, if we define an adjective in this calibrating way, we also automatically benefit from the use of the superlative form. That is, if we define

Definition: A container is large if its carrying capacity is 10 or more.
Definition: A container is small if its carrying capacity is 5 or less.

then we can talk about things like this:

the largest container
the smallest open container

Though we should be careful, in the second case, because we might get nothing: maybe all the containers are closed at the moment this is used. And in general there might be several equally large largest containers, in which case we should not rely on getting any particular one of those rather than another.

Note that Inform constructs comparatives and superlatives by a pretty simplistic system. If we want to use these forms for an adjective expressing the relatively large size of a room, we had better go with "roomy" (roomier, roomiest) – not "spacious" (spaciouser, spaciousest).

A description can not only talk about things in terms of themselves, but also in terms of their relationships to the rest of the world. For instance,

an open container on the table
a woman inside a lighted room
an animal carried by a man
a woman taller than Mark
something worn by somebody

are all valid descriptions. These are really abbreviations, having missed out the words "which is" or "who is", as appropriate:

an open container which is on the table
a woman who is inside a lighted room
an animal which is carried by a man
a woman who is taller than Mark
something which is worn by somebody

and indeed those are also valid descriptions. The other sentence verbs can all be used here, too. So for instance:

a man who does not wear anything
something which supports something

And sometimes we should spell out "who is" regardless:

a man who is not Sherlock Holmes

Since these clauses can be attached to the end of any valid description, descriptions can grow longer still:

something worn by a woman who is in a dark room

Pedants who flinch when "which" is used to introduce a restrictive clause are welcome to use "that" instead.

Example

75.
Versailles ★★
A mirror which will reflect some random object in the room.

"There" is a curious word in English, which mostly refers to some place which is being talked about – but which can sometimes mean the whole world. In Ian Fleming's novel "From Russia With Love", a chapter narrating a committee meeting of SMERSH officers in Istanbul ends with one of the Russians saying:

There is a man called Bond.

What does this "there" mean? It really just means that Bond exists. In fact, he's watching the meeting through a concealed periscope, but the SMERSH general doesn't know that. All he is saying is that Bond is out there somewhere, and is not imaginary, or dead.

Inform also allows "there is" (or "there are") to talk about what exists, or does not. This is especially useful if, for some reason, we don't want to give a name to something. For example:

There is a door in the Summerhouse.

Another reason might be that we want to create something but not put it anywhere. If Inform reads the sentence:

There is a man called Bond.

then it creates a man, gives him the name Bond, but places him initially off-stage – not in any room, that is, but available to be brought into play later on, like an actor who is not needed until Act II.

"There" also provides a useful way to test what exists:

if there is a woman in the Summerhouse, ...

Or even:

if there is a woman, ...

which will be true if the model world contains even a single woman, on-stage or off. The alternative "there are" can also be used:

if there are women in the Summerhouse, ...

but note that this does not necessarily imply more than one woman is present, despite the plural. If we want that, we have to be more explicit:

if there is more than one woman in the Summerhouse, ...

or, of course, we needn't use "there is" at all:

if more than one woman is in the Summerhouse, ...

And we can also test non-existence:

if there is nobody in the Summerhouse, ...
if there is nothing on the mantelpiece, ...

What does "in" mean? It's worth just a brief diversion to cover this, because "in" has two subtly different meanings.

Meaning 1. Usually, if X is "in" Y then this is because of containment. A croquet ball is "in" a croquet box, which is "in" the Summerhouse. This is the standard meaning, and is the one which happens if we write something like:

The croquet ball is in the box.

or if we ask a question like:

if the croquet box is in the Summerhouse, ...

This kind of "in" talks only about direct containment. If we ask

if the croquet ball is in the Summerhouse, ...

then the answer is that it isn't – it is in the box which is itself in the Summerhouse, but that's not the same thing.

This is almost always the meaning of "in" that we intend. This is only one of a number of relationships between objects – there are also "part of", "on", "worn by" and "carried by", for example. If we have

The bird feed is on the sundial.

…then "if the bird feed is in the sundial" won't be true: the relationship here is one called support (being on top of, in effect), not containment. But there's no confusion because "on" and "in" are different words, so it's no problem that they have different meanings.

Meaning 2. Much less common. If X is "in" Y and Y is a region, then the meaning is slightly different. Suppose the Garden Area is a region, and contains several rooms – the Croquet Lawn, the Terrace and so on. Then

if the croquet box is in the Garden Area, ...
if the bird feed is in the Garden Area, ...
if the Terrace is in the Garden Area, ...

are all true. This seems very natural, but in fact is quite different from the first meaning of "in". It allows rooms (and even other regions) to be "in" a region, and it allows indirect containment.

How Inform decides. So which meaning does Inform use, and when? Since these two meanings are so different, it clearly matters.

The answer is that meaning 1 is always the meaning of "X is in Y" unless Y is explicitly the name of a region. Thus:

if the croquet box is in the Garden Area, ...

is meaning 2, because "Garden Area" is the name of a region. That seems fair enough, but values are indeed sometimes given names (becoming "variables", or values "that vary"). Suppose "mystery value" is a name for a value which is an object, but which has different identities at different times. Then Inform reads

if the croquet box is in the mystery value, ...

as meaning 1, because whatever "mystery value" is, it isn't explicitly a region name, even if from time to time it might happen to be equal to a region.

That sometimes makes meaning 2 difficult to express. If we ever need it, and this is fairly rare, we can write it like so:

if the croquet box is regionally in the mystery value, ...

because "regionally in" is always meaning 2 of "in".

"To be in" is functionally the inverse of "to contain", so all the different meanings "is in" might have also apply to "contains", but in the other direction. This will be explored further in the chapter on Relations.

([TODO See…]

Like "in", "nothing" has two slightly different meanings, though here there's much less potential for confusion.

Meaning 1. "Nothing" as "no thing". This is the meaning in sentences like:

Definition: a container is bare if there is nothing in it.

And similar for conditions like "if the box contains nothing". It's a word which describes the absence of things: it says that, though there might have been many possible items here, it turned out that there were none.

That the thing that nothing is no of is a thing per se has results that may seem odd at first glimpse. If the player is held by a room, "nothing holds the player" is true. It's a room, so it's not the case that there is a thing that holds the player: a room but no thing holds the player. "nowhere holds the player" will be false, however. [TODO: not today] (Similarly, what nobody, no one, and no-one are not is a person.)

Meaning 2. "Nothing" as a value. This is much less commonly seen, but sometimes Inform stores a value such as a property (or a variable) which always has to be an object. In some circumstances, "nothing" is then a special value meaning that this is not set at present. For instance,

Definition: a container is impossible if its matching key is nothing.

The "matching key" property of a container is always an object, but is allowed to be "nothing" when there isn't a matching key anywhere. (If such a container is locked, nobody will ever be able to unlock it.)

How Inform decides. So which meaning does Inform use, and when? The answer is that it depends on the relationship being talked about. When this is "is", values are being compared and we are using meaning 2. But when it is any other relationship, like "is in" – which talks about containment – then we are using meaning 1.

Two of the adjectives built into Inform are:

"visible" - the player can see this
"touchable" - the player can touch this

So we can write descriptions such as "someone visible" or "a touchable container". We also have adjectives "invisible" and "untouchable", as might be expected. The visibility adjectives are particularly useful because the following is likely to go wrong:

if Helen is in a dark room, ...

This tests whether the room is dark, of itself; Helen may in fact be able to see by means of a torch, but the room is still "dark".

We can also talk about what other people can see and touch:

something which can be seen by Helen

something which can be touched by Paris

And we can write such conditions as

if Helen cannot see Agamemnon, ...
if Cressida can see Troilus, ...

Note that it is essential to establish who does the seeing and touching: so "something which can be seen" will not be allowed, whereas "something which can be seen by Helen" will. Note also that to test the negative we use "cannot": either of "can not" or "can't" will result in a compiler error.

In fact, inside Inform the adjective "invisible" (for instance) has the following straightforward definition:

Definition: Something is invisible if the player cannot see it.

The exact definitions of visibility and touchability are complicated, because there are so many ways in which vision and touch can be obstructed, but the gist is that they behave as one would expect. Note that in darkness, nothing is visible, and that nobody can see from one room to another. In general anything invisible is also untouchable, but there are a few exceptions to do with being in the dark. Lastly, the player's own body (usually called "yourself" during play) is both visible (in light) and touchable.

Example

76.
Lean and Hungry ★★★
A thief who will identify and take any valuable thing lying around that he is able to touch.

Another useful adjective built into Inform is "adjacent". Two rooms are said to be adjacent if there is a map connection between them which does not pass through some barrier such as a door. This is easily tested:

if the Hallway is adjacent to the Study ...

We usually want to know about the places adjacent to the current scene of the action, so that is what the adjective "adjacent" means when applied to rooms. For instance:

if somebody is in an adjacent room, ...

As with the case of "visible", the adjective is a cut-down version of the more general relationship. This often happens: "worn" and "carried", for instance, imply "by the player" unless something else is specified.

If we want to ask a more direct question, we can obtain specific map connections as follows. (Recall that every map connection leads either to a door, to a room, or to nothing.) If we know which direction we want to look in, then the easiest thing is to use its relation – every direction in the map, say "north", has its own relation, say "mapped north of". So:

if the Ballroom is mapped north of the Hallway, ...

Alternatively, and particularly if the direction is not a constant,

room (direction) from/of (room)room

This phrase produces the room which the given map direction leads to, or the special value "nothing" if it leads nowhere. If it leads to a door, the result is the room through that door. Examples:

say "You look north into [the room north from the Garden]."
if the room north from the Garden is nothing, say "The grass leads nowhere."
door (direction) from/of (room)door

This phrase produces the door which the given map direction leads to, or the special value "nothing" if it leads nowhere or to a room. Examples:

let the barrier be the door north from the Garden;
if the barrier is a door, say "Well, [the barrier] is in the way.";
room-or-door (direction) from/of (room)object

This phrase produces the object which the given map direction leads to, which will always be either a room, a door or the special value "nothing". The phrase is used mainly by the Standard Rules, for technical reasons, and usually it's better to use "room … from …" or "door … from …" instead.

The map can be a great sprawling mass of rooms and doors connected together, and it can be quite hard to find a way through it one step at a time.

best route from (object) to (object)object

This phrase produces a direction to take in order to get from A to B by the shortest number of movements between rooms, or produces "nothing" if there is no way through at all. Example:

The description of the brass compass is "The dial points quiveringly to [best route from the location to the Lodestone Room]."

Best routes are ordinarily forbidden to go through doors, but if the suffix "using doors" is added as an option then any open or openable and unlocked door may be used on the way; and if "using even locked doors" is given, then any door at all will do. Since magnetism is no respecter of property, that seems right here:

The description of the brass compass is "The dial points quiveringly to [best route from the location to the Lodestone Room, using even locked doors]."

In practice this simple approach sometimes produces impossible journeys, rather the way Google Maps directions from New York to London would recommend driving down to the docks and then swimming. A more careful approach is to use:

best route from (object) to (object) through (description of objects)object

This phrase produces a direction to take in order to get from A to B by the shortest number of movements between rooms which match the given description, or produces "nothing" if there is no way through at all. Example:

best route from the Drawbridge to the Keep through visited rooms

The condition – in this case, that "visited rooms" must be used – also applies to both ends of the journey, so if either Drawbridge or Keep are unvisited then this is "nothing". (Similarly, saying something like "…through containers" would mean there is never a route.)

Lastly, the following phrases can find out how long the journey would be. (They are quite a bit faster than using the "best route…" phrases repeatedly and counting.)

number of moves from (object) to (object)number

This phrase produces the number of map connections which must be followed in order to get from A to B by the shortest number of movements between rooms. If A and B are the same, the answer is 0; if there is no route at all, the answer is -1. Example:

The description of the proximity gadget is "You are now [number of moves from the location to the Sundial] moves from the Sundial.";
number of moves from (object) to (object) through (description of objects)number

This phrase produces the number of map connections which must be followed in order to get from A to B by the shortest number of movements between rooms matching the given description. If A and B are the same, the answer is 0; if there is no route at all, or if either A or B fail to match the description themselves, the answer is -1.

Route-finding makes it possible to write quite sophisticated conditions concisely. But these sometimes run slowly, because they call for large amounts of computation. How rapidly Inform can find routes depends on which of two methods it uses. Both have advantages – one is fast but needs large amounts of memory, the other is slow but economical. We can choose between them with one of these two use options:

Use fast route-finding.
Use slow route-finding.

If neither is specified, "fast" is used where the project uses the Glulx virtual machine (see the Settings panel), and "slow" on the Z-machine, where memory is tighter. Fast route-finding is ideally suited to situations where dozens of characters are constantly route-finding through the map as they meander around in a landscape.

See Also

Indirect relations for route-finding through a relation rather than the map.

Examples

A person who moves randomly between rooms of the map.
Layout where the player is allowed to wander any direction he likes, and the map will arrange itself in order so that he finds the correct "next" location.
Signposts such as those provided on hiking paths in the Swiss Alps, which show the correct direction and hiking time to all other locations.
80.
A LOOK [direction] command which allows the player to see descriptions of the nearby landscape.
81.
Unblinking ★★★
Finding a best route through light-filled rooms only, leaving aside any that might be dark.

When testing conditions, we normally talk only about specific things, or else ask if a particular circumstance happens:

if the oaken door is open
if a woman is carrying an animal

But we can also use "all", "each" or "every" to check the whole range:

if each door is open
if anyone is carrying all of the animals
if everybody is in the Dining Room

Inform allows other English "determiners" (as they are sometimes called), as well:

if some of the doors are open
if most of the doors are open
if almost all of the doors are open

are true if at least one case is true, if a majority (any number greater than one half) or at least 80 per cent of the possible cases are true, respectively.

And we can also use "none" and "no". These three are all ways to say the same thing:

if no door is open
if all of the doors are not open
if none of the doors is open

though it may be clearer style to find a positive way of putting things:

if all of the doors are closed

All, each and every can be applied to values, too – but only in some cases. For example, suppose we write:

Colour is a kind of value. The colours are red, orange, yellow, green, blue, indigo and violet. A colour can be found or unfound.

And suppose that, during play, we assign the "found" property to any colour which the player notices on a wall. We might then want to write conditions like so:

if every colour is found
if most of the colours are found
if any colour is found

But we always have to bear in mind that Inform might have no reasonable way to decide these questions. It will refuse to allow these, for example:

if every number is positive
if any text is palindromic

(even supposing the adjective "palindromic" has been defined) – there are practically infinitely many possible numbers and texts, so the search cannot sensibly be done.

Example

A small game about resentful furniture and inconvenient objects.

Lastly we can also ask for a more specific number of possibilities, like so:

if two women are carrying animals
if at most three doors are open
if fewer than 10 portable containers are closed
if all but two of the devices are switched on
if there are more than six locked doors

Likewise for "less than", "at least", "all except". Something to watch out for is that

if two doors are open

will be found true if there are (say) three open doors: after all, if three doors are open, then certainly two doors are. So this is not quite counting. We can be more precise by writing

if exactly two doors are open

The "all but" counts – say, "if all but two doors are open" – are exact: if, in fact, all of the doors are open then this will be found false.

We can often use these counting forms with values, too. As with the use of "all", this is allowed only if the kind of value is one which can reasonably be searched through. For example:

if more than three scenes are happening
if there are more than two non-recurring scenes

are allowed because the built-in kind of value "scene" (of which much more later on) has only a small number of possible values.

Lastly, note that the "the" in text like "two of the doors" matters: without it, the phrase will not be recognised as a requirement on the number. (This is to make sure that names of things like "two of hearts" are not misinterpreted.)

With a proposition like "if all doors are open" or "if no doors are open", or any specific number of doors, you can count on it being the case that if it's true, then its negation ("if all doors are not open", "unless no doors are open") is false, and vice versa. But beware of the logical error of expecting that to be true of "some doors" or "a door" or anything else that isn't specific as to quantity. That "some doors are open" and "some doors are closed" can both be true may sound too obvious to bother stating. Yet it can be a surprisingly easy trap to expect "if a door is open" and "unless a door is closed" to be opposites, though there's no guarantee of that if there are two or more doors.

Example

83.
Set of drawers where the item the player seeks is always in the last drawer he opens, regardless of the order of opening.

7. Basic Actions

"Actions" are what we get if we try to break down a narrative into its irreducible parts. We might casually say that we are "going shopping", but this involves many smaller steps: going north, going east, entering the shop, examining a loaf of bread, taking it, giving money to the baker, and so on.

An action is an impulse to do something. This may or may not be a reasonable aspiration, and may or may not be achieved. The player's exploration of an interactive fiction is made by a sequence of actions, so much of the designing process comes down to responding to these actions.

We write actions using present participles. For instance, if the player types "take napkin" or "get the napkin" or something similar then the resulting action would be written as:

taking the napkin

The details of what words the player actually typed are unimportant to us: we deal only in actions.

Every action ends in success or failure. In this context, success means only that the player's intention has been fulfilled. If the player sets out to take the napkin, but finds a million-pound banknote in its folds instead, the action will be deemed to be a failure.

The testing command ACTIONS causes Inform to log every action as it happens, and what its outcome is. (ACTIONS OFF turns this off again.) For instance:

>s
[going south]
Security Vault
You can see a metal door here.
[going south - succeeded]
>close door
[closing metal door]
You close the metal door.
[closing metal door - succeeded]
>take door
[taking metal door]
That's fixed in place.
[taking metal door - failed the can't take what's fixed in place rule]

A good way to get a sense of the constant flow of actions is to use this command and then wander around an existing work, trying things out. ACTIONS can also give an insight into the web of rules governing play: there are more than ten different ways an attempt to take something can fail, for instance.

An action is ordinarily handled by running it through Inform's extensive rulebooks of what might be called normal behaviour. An action such as "taking the napkin", for instance, will be run through numerous checks to see if it is physically reasonable, and then provided all is well, the napkin will be moved into the possession of the player.

Instead, though, we can bypass the rules to do with an action and do something else:

Instead of eating the napkin: say "Why not wait for the actual dinner to arrive?"

This is an example of a "rule": a set of circumstances followed by a list of instructions. When those circumstances apply, the instructions are carried out. In the case of an "instead" rule, after this is done the action is immediately ended (and counts as a failure, since the original intention has been thwarted).

A friendly alternative can be used when there is only a single instruction, as here: in such rules the colon can be replaced with a comma. Thus:

Instead of eating the napkin, say "Why not wait for the actual dinner to arrive?"

Examples

84.
A grill, from which the player is not allowed to take anything lest he burn himself.
85.
Change the player's appearance in response to EXAMINE ME.

Despite what was said in the previous section, instead rules do not quite bypass all of the usual rules. Inform knows that certain actions require light: for instance,

examining the napkin; looking; looking under the dining table

and if it is dark then none of these actions will be allowed, and any instead rules about them will not even be reached. Similarly, Inform knows that most actions require physical access to their objects: so "taking the napkin" would be blocked if the napkin were, say, inside a closed glass bottle, whereas "examining the napkin" would not. So an instead rule can only take effect if the action has already passed these basic reasonability tests.

"Before" rules genuinely precede checking of any kind. They also differ from instead rules in that they do not automatically stop the action in its tracks. Rather, they are provided as an opportunity to ensure that something else is done first. For example:

Before taking the napkin, say "(first unfolding its delicate origami swan)".

whence

>GET NAPKIN
(first unfolding its delicate origami swan)
Taken.

We have seen that instead rules automatically stop actions, whereas before rules automatically allow them to continue. We sometimes want to change this. The magic word "instead" can therefore be tacked on to any instruction in a before rule, and will have the effect of immediately stopping the action at that instruction. Thus the following two rules are (almost) equivalent:

Before taking the key, instead say "It seems to be soldered to the keyhole."
Instead of taking the key, say "It seems to be soldered to the keyhole."

It is also possible to be explicit about stopping the action:

stop the action

This phrase stops the current rule, stops the rulebook being worked through, and finally stops the action being processed. Example:

Before taking the key:
   say "It seems to be soldered to the keyhole.";
   stop the action.

Finally, we can prevent Inform from stopping the action when it otherwise might:

continue the action

This phrase ends the current rule, but in a way which keeps its rulebook going, so that the action being processed will carry on rather than being stopped. Example:

Instead of taking the napkin:
   say "(first unfolding its delicate origami swan)[command clarification break]";
   continue the action.

An "instead" rule ordinarily stops the action when it finishes, so the "continue the action" is needed to make things carry on. (This rule would have been better written as a "before" rule, in fact, but it shows the idea.)

As a general principle, it is good style to use instead rules whenever blocking actions, and before rules only when it is genuinely necessary to do something first but then to continue: in fact, it is good style to use "stop the action" or "continue the action" as little as possible.

Examples

86.
Make PUT and INSERT commands automatically take objects if the player is not holding them.
87.
Sand ★★★★
Extend PUT and INSERT handling to cases where multiple objects are intended at once.

Chapter 2 noted that surveys of Inform source text showed that the three most popular phrases used by authors are "say", "if" and "now". The fourth most popular is "try", which allows us to trigger off actions ourselves, rather than waiting for the player to type something which generates them. Thus:

try (action)

This phrase makes the action, which has to be named literally, take effect now. Example:

Instead of entering the trapdoor, try going up.

It's as if the player had typed GO UP as a command. Note that the action has to be specific:

try eating something;

is not allowed, since it doesn't say exactly what is to be eaten.

The word "try" is intended to make clear that there is no guarantee of success. For example:

Before locking the front door, try closing the front door.

could go wrong in any number of ways – perhaps the door is closed already, perhaps it is not openable, perhaps somebody has wedged it open. It would be safer to write:

Before locking the front door:
   try closing the front door;
   if the front door is open, stop the action.

There's no need to say anything if closing didn't work, because the closing action will have done that already. A neater approach still is to use:

silently try (action)
or…
try silently (action)

This phrase makes the action, which has to be named literally, take effect now, under the "silent" convention which means that routine messages aren't printed. Example:

try silently taking the napkin;

Silence is maintained only if this new action, the taking of the napkin, is successful (so if the napkin is successfully taken, the text "Taken." will not appear): if the action should fail, a suitable objection will be voiced as usual.

So now we have:

Before locking the front door:
   try silently closing the front door;
   if the front door is open, stop the action.

And this is neater because it won't produce a pointless "You close the front door." message.

See Also

Stored actions for how to store up actions as values and try those, too, so that isn't necessary to name the action as literally as in the examples above.

Examples

88.
Making writing that can be separately examined from the paper on which it appears, but which directs all other actions to the paper.
89.
A refinement of our staircase kind which can be climbed.

There is pleasantly little to be said about "after" rules. If an action has survived all the rules in its way, and has actually succeeded, then we need to give the player a response which acknowledges this. Inform's normal rules will be sufficient to say something undramatic: for instance, if "taking the napkin" has succeeded then it will reply "Taken." to the player.

An after rule is an opportunity to say something more interesting:

After taking the diamonds, say "Taken!"

(Well, slightly more interesting.) After rules automatically end the action (as a success), which is what we would want in the above case. Allowing it to continue would simply result in "Taken." being printed as well. However, should we really need to do something and then carry on:

After taking the diamonds: say "(Mr Beebe looks up sharply.) "; continue the action.

Example

When the player picks something up which he hasn't already examined, the object is described.

A few actions apply not to items alone, but also involve what might be called conversation. The first is the one used for looking things up in books (which is conversation of a kind, even if the author is not present): "consulting … about …". For example,

In the Grove is a book of sybilline verses.
After consulting the book about "grove", say "The Grove is a sacred yadda, yadda. There's a tree, that sort of thing. Wisdom."
After consulting the book about "future events", say "It's a bit, what's the word? Delphic."

Note that what follows "about" here is a piece of text in double-quotes, and not the name of something. It can be almost any text at all, and in fact we shall later see (in the chapter on "Understanding") that we can match complicated patterns of words, too.

Similar actions are used for conversing with people:

After asking the Sybil about "verses", say "She blushes."
After telling the Sybil about "persians", say "She nods gravely."
After answering the Sybil that "I am mad", say "She sighs."

These would be produced by commands like "ask sybil about verses", "tell sybil about persians" and "answer i am mad". Answering is little-used except that it also catches commands like "sybil, something unrecognized", which inexperienced players sometimes type. Asking and telling, however, are important actions and the difference between them is often worth preserving. If you would prefer to make "tell sybil about X" do the same as "ask sybil about X", the following rule would serve:

Instead of telling the Sybil about something, try asking the Sybil about it.

Games with a lot of conversation often involve great heaps of rules like the ones above, which can be repetitious to type out. We shall also later see (in the chapter on "Tables") that we can tabulate questions and answers in a much more concise way, if we prefer.

See Also

Topic columns for table-based ways to store and retrieve conversation.

Examples

91.
Direct all ASK, TELL, and ANSWER commands to ASK, and accept multiple words for certain cases.
92.
Lucy
Redirecting a question about one topic to ask about another.
93.
Sybil 2 ★★
Making the character understand YES, SAY YES TO CHARACTER, TELL CHARACTER YES, ANSWER YES, and CHARACTER, YES.
A fully-implemented book, answering questions from a table of data, and responding to failed consultation with a custom message such as "You flip through the Guide to Central American Birds, but find no reference to penguins."

The five senses are all simulated with actions. Sight is so informative that it is handled by a whole range of actions: "looking", which describes the general scene; "examining something", which takes a closer look at a specific thing; "looking under something", and so on.

The other senses have one action each: "listening to something", "touching something", "tasting something" and "smelling something". It makes no sense to touch or taste the general scene, but listening and smelling are a different matter: we often just listen, without listening to anything specific. If the player types the command "listen", Inform understands that as listening to the current location: similarly for the bare command "smell". Thus:

Instead of listening to the Seashore, say "The song of gulls."
Instead of smelling the Cave, say "Salt and old seaweed."

Example

95.
Things are all assigned their own noise (or silence). Listening to the room in general reports on all the things that are currently audible.

A description can include more than one choice of action. For instance:

examining or searching the desk

matches either of "examining the desk" or "searching the desk". We can have more than two actions, of course:

examining, looking under or searching the desk

The actions combined like this need to be compatible with each other, at least a little. For instance, this will generate a problem message:

waiting or searching the desk

because it makes no sense to "wait the desk". On the other hand, this is fine:

waiting or searching

The general rule is that if we specify one or more objects ("the desk" in the above example), then each of the actions we quote must take at least that many objects.

For example, the following saves us writing the same basic rule three times over:

Instead of examining, looking under or searching the desk: say "There's no use poking around in that old desk."

The special description "doing something" (or "doing anything") matches any action, and "doing something to …" also allows the noun to be specified.

For instance, the following puts its object out of bounds:

Instead of doing something to the cucumber sandwich, say "Lady Bracknell stares disapprovingly down her pince-nez at you, in a way which no amount of hunger or curiosity could overcome."

We sometimes need to be a little careful here: "waiting" qualifies as "doing something", but not as "doing something to something", because there is no object. "Putting the handbag on the cucumber sandwich" would also not qualify as "doing something to the cucumber sandwich" – only to the handbag.

More often, we would like to restrict the range of allowable actions to a select few. For instance:

Instead of doing something other than looking, examining or waiting: say "You must learn patience."

(Or we can write "except" instead of "other than".) Or we might have an object, too:

Instead of doing something other than examining, taking or dropping with the dagger: say "Don't fool around with that dagger. It's exceedingly sharp."

Note the "with", which is crucial here. Without it, the rule is subtly different:

Instead of doing something other than examining, taking or dropping the dagger: say "Don't fool around with that dagger. It's exceedingly sharp."

This second version matches if the action is, say, taking a shield, or even just looking, because that would be an action other than examining the dagger, taking the dagger or dropping the dagger.

Example

96.
Zodiac
Several variations on "doing something other than…", demonstrating different degrees of restriction.

Once we begin applying rules to actions which are not entirely known in advance, we have a problem: there's no way to find out what specifically is happening. Consider the following:

Instead of examining something, say "It is none of your concern!"

This is fine as far as it goes, but clumsy. What if the player had examined a human being? Then "it" would be inappropriate. A better approach would be this:

Instead of examining something, say "[The noun] is none of your concern!"

The "noun" and, when necessary, the "second noun" are values which can be used in any rule about actions, and it follows that they can also be substituted into text, as this example demonstrates. Results might include:

Lady Bracknell is none of your concern!
The silver cigarette case is none of your concern!

This seems a good moment to mention that if you use "The" in a substitution, then a capitalised "The" will be used so long as this is grammatically correct (Lady Bracknell, as a proper noun, takes no article); "the" becomes a lower-case "the" along the same lines; and "a" a lower-case indefinite article.

Instead of examining something in the Drawing Room, say "Under Lady Bracknell's eye, you feel constrained. Besides, it is only [a noun]."

Example

97.
ATTACK or DROP break and remove fragile items from play.

Three elaborations of action descriptions increase the range of possibilities further.

Instead of taking something in the Supernatural Void, say "In this peculiar mist you feel unable to grasp anything."

Like the objects to which the action applies, this location – the "in" clause – can take any description, not just an explicit place like "Supernatural Void":

Instead of listening in a dead end, say "You strain to hear further clues as to the course of the underground river, but to no avail."

But we often want a rule to apply in any of a set of rooms: and where, unlike the "dead end" example above, the rooms have nothing much in common except where they happen to lie on a map. For instance, we might want a rule to apply only inside a given building, or a garden consisting of five miscellaneous rooms. If so, we can create a "region" as a convenient way to refer to that group of rooms:

The Arboretum is east of the Botanical Gardens. Northwest of the Gardens is the Tropical Greenhouse.
The Public Area is a region. The Arboretum and Gardens are in the Public Area.
Instead of eating in the Public Area, say "The curators of the Gardens are ever among you, eagle-eyed and generally cussed."

Relative location can also be important: relative to other people, that is -

Instead of eating something in the presence of Lady Bracknell, say "Lady Bracknell disapproves thoroughly of gentlemen who snack between meals, and there are few disapprovals in this world quite so thorough as Lady Bracknell's."

As might be guessed, this applies when the action takes place in the same location as the person named: and of course that person can also be described more vaguely ("… in the presence of a woman", say), and can just as easily be an inanimate thing ("… in the presence of the radio set").

Lady Bracknell is a pushover compared to some matriarchs:

Instead of doing something other than looking, examining or waiting in the presence of the Queen: say "I'm afraid they take what you might call a zero tolerance approach to breaches of court etiquette here."; end the story saying "You have been summarily beheaded".

The last of the optional clauses we can tack on to the description of an action is the most general of all. We can add "when" and then any condition at all, as in:

Instead of eating something when the radio set is switched on, say "Something about the howling short-wave static puts you right off luncheon."

This supposes that the radio is so loud that it can be heard from any room: we could muffle it so that it's only audible from the room it is in like so:

Instead of eating something in the presence of the radio set when the radio set is switched on, say "Something about the howling short-wave static puts you right off luncheon."

Examples

98.
An item that the player can't interact with until he has found it by searching the scenery.
99.
A few notes on "In the presence of" and how it interacts with concealed objects.

Going is an action defined like any other: it is the one which happens when the player tries to go from one location to another. But it is unlike other actions because it happens in two locations, not just one, and has other complications such as vehicles and doors to contend with. To make it easier to write legible and flexible rules, "going" is allowed to be described in a number of special ways not open to other actions, as demonstrated by the following example story:

"Going Going"
The Catalogue Room is east of the Front Stacks. South of the Catalogue Room is the Musicology Section.
Instead of going nowhere from the Front Stacks, say "Bookcases obstruct almost all passages out of here."
Instead of going nowhere, say "You really can't wander around at random in the Library."
Before going to the Catalogue Room, say "You emerge back into the Catalogue Room."

Note that "going nowhere" means trying a map connection which is blank, and if no rules intervene then "You can't go that way" is normally printed. Unless "nowhere" is specified, descriptions of going apply only when there is a map connection. So "going from the Musicology Section" would not match if the player were trying to go east from there, since there is no map connection to the east. Similarly, "going somewhere" excludes blank connections.

The places gone "from" or "to" can be specific named regions instead of rooms. This is convenient when there are several different ways into or out of an area of map but a common rule needs to apply to all: so, for example,

Before going from the Cultivated Land to the Wilderness, ...
Before going nowhere from the Wilderness, say "Tangled brush forces you back."

Note that it must be "going nowhere from the Wilderness", not "…in the Wilderness". (Note also the caveat that the regions must be named: "going from a region", or something similarly nonspecific, will not work.)

An important point about "going… from" is that, as mentioned in general terms above, it requires that there is actually a map connection that way: whereas "going… in" does not. Suppose there is no map connection north from the Wilderness. Then:

Instead of going north from the Wilderness, say "You'll never read this."
Instead of going north in the Wilderness, say "Oh, it's too cold."

The first of these never happens, because it is logically impossible to go north from the Wilderness: but the second does happen. (Technically, this is because "going north" is the action, and "in the Wilderness" a separate condition tacked onto the rule.) This distinction is often useful – it allows us to write rules which apply only to feasible movements.

This may be a good place to mention a small restriction on the ways we can specify an action for a rule to apply to, and how it can be overcome. The restriction is that the action should only involve constant quantities, so that the following does not work:

The Dome is a room. The Hutch is north of the Dome. The rabbit is in the Hutch. Before going to the location of the rabbit, say "You pick up a scent!"

because "the location of the rabbit" is a quantity which changes in play (the player can pick up the rabbit and take him to the Dome, for instance). However, we can get around this restriction by defining a suitable adjective, like so:

The Dome is a room. The Hutch is north of the Dome. The rabbit is in the Hutch. Definition: a room is rabbit-infested if it is the location of the rabbit. Before going to a rabbit-infested room, say "You pick up a scent!"

Examples

100.
An effect that occurs only when the player leaves a region entirely.
101.
A&E ★★
Using regions to block access to an entire area when the player does not carry a pass, regardless of which entrance he uses.
102.
Offering the player a list of valid directions if he tries to go in a direction that leads nowhere.
103.
Polarity ★★★
A "go back" command that keeps track of the direction from which the player came, and sends him back.

Adding to the previous example story, we apply rules which depend on travelling by a particular vehicle:

The book trolley is in the Musicology Section. "The book trolley, a sort of motorised tractor for trundling around through the stacks, is parked here." The trolley is a vehicle. Instead of going nowhere by the trolley, say "Don't go crashing the trolley into walls."
Instead of going to the Front Stacks by the trolley, say "The Front Stacks are far too confined for the trolley to manoeuvre into them."

And, lastly, rules which apply to movements through particular doors:

The green baize door is east of the Catalogue Room and west of the Clerk's Office. The green baize door is an open door.
Before going through the green baize door, say "Through you go..." After going through the green baize door: try looking; say "...and here you are."

(Note that these apply whether the action is "going east" or "entering the green baize door", each having the same effect.) The last rule is worth a second look: the normal way that a "going" action is reported is to produce the room description of the new location. So if an "after" rule stops the action before we get to reporting, we have to produce any room description by hand (hence the "try looking" to cause the looking action). Alternatively, we could simply say something and let the normal course of events take place:

After going through the green baize door: say "...and here you are:"; continue the action.

Finally, going is an action which can also happen while the player is pushing something from one room to another, and we can describe this like so:

Instead of going from the Office with the trolley, say "But it looks perfectly placed here. Why push any further?"

"Going" is not the only action which moves the player. Another is "exiting", an action which moves the player out of whatever he/she is currently in or on. This action is often caused by the player typing just OUT or GET DOWN, and there's no noun as such. But Inform allows the syntax "exiting from" to make it easier to write rules about the exiting of particular containers or supporters:

After exiting from the Mini Cooper:
   say "You painstakingly unpack your limbs from the tiny car."

Examples

104.
A car which must be turned on before it can be driven, and can only go to roads.
Adding extra phrasing to the action to PUSH something in a direction.
106.
A plank bridge which breaks if the player is carrying something when he goes across it. Pushing anything over the bridge is forbidden outright.
107.
Allowing something like PUSH TELEVISION EAST to push the cart on which the television rests.
108.
Zorb ★★★
Replacing the message the player receives when attempting to push something that isn't pushable, and also to remove the restriction that objects cannot be pushed up or down.

Especially when people need to react to events going on around them, it is helpful to be able to categorise actions into whole areas of behaviour. For instance:

Kissing Mr Carr is unmaidenly behaviour.
Doing something to the painting is unmaidenly behaviour.
Instead of unmaidenly behaviour in the Inn, say "How unmaidenly!"

Here a new kind of action called "unmaidenly behaviour" has been created and then used in the description of an instead rule. The convenience of this approach is that when further actions suddenly occur to us as also being unmaidenly – say, attacking Mr Carr – we only need to add a single line:

Attacking Mr Carr is unmaidenly behaviour.

And this will automatically be reflected in any rules which concern the consequences of failing to be ladylike.

(Note that we were only allowed to say that "Kissing Mr Carr is unmaidenly behaviour." because Inform already knew from earlier sentences – see the example below – that Mr Carr was a person, and therefore that "kissing Mr Carr" made sense as a description of an action.)

Examples

Our heroine, fallen among gentleman highwaymen, is restrained by her own modesty and seemliness.
110.
Mimicry ★★★
People who must be greeted before conversation can begin.

We come at last to the final thing which can be specified about an action, and appropriately enough it must be specified with the final words of the description. This is the way to talk about repeated activity:

Instead of examining the tapestry for the third time, say "All right, so it's a masterpiece, but is this really the time to make a detailed study?"
Instead of examining the urn at least twice, say "It's an urn. What do you want from me?"
Instead of going nowhere for the 20th time, say "Do stop walking into walls, there's a good fellow."

Note that we are allowed to spell out numbers up to twelve in English words, but beyond that must use digits (thus "twelfth" is allowed but not "thirteenth": "13th" should be used instead). The following example is instructive:

Instead of taking something for the fourth time, say "No. I'm capricious."

This means that it is the fourth time a "taking…" action has been tried, and does not mean that the same item was taken each time. Also, note that we are counting the number of times the action has been tried, not the number of times it succeeded.

Examples

111.
Noticing when the player seems to be at a loss, and recommending the use of hints.
112.
A complete story by Emily Short, called "A Day for Fresh Sushi", rewritten using Inform 7. Noteworthy is the snarky commenter who remarks on everything the player does, but only the first time each action is performed.

We can also reckon the number of consecutive turns on which an action has been repeated, by talking about "turns" instead of "times", as demonstrated in the following example story. Note also that we are allowed to use the phrase "doing it" to mean "the same description as the previous one except for the part about turns or times", like so:

"Waiting Room"
The Antechamber is a room. The tattered copy of Women's Wear Daily is in the Antechamber. Instead of taking the Daily, say "It is stamped NOT TO BE TAKEN AWAY."
Instead of examining the Daily for the first time, say "The best article seems to be about how your star sign affects your best swimsuit colour. Really: that's the best article."
Instead of doing it for the second time, say "You now know a generous amount about a typical week in the life of a weather forecaster."
Instead of doing it for the third time, say "You would now know how to cook herb bread, except that you have already forgotten the names of both of the herbs."
Instead of doing it more than three times, say "Nope, you've drained it of all conceivable sustenance, even the small ads about French farmhouses to let (sleeps 7) and breast reduction surgery (with alarming photographs in sallow light)."
After waiting for four to six turns, say "This is getting mighty dull." After waiting for seven to eight turns, say "Really, exceptionally dull." After waiting for nine turns, end the story saying "You have died of boredom, something previously thought medically impossible".

Note once again that numbers above twelve must not be written out, so "more than twelve times" would be acceptable, but we would write "more than 13 times".

In this chapter, all actions have been carried out by the player, all have been drawn from the standard stock of built-in actions ("unlocking", "taking", "going" and so forth), and all of those built-in actions have been allowed to work in the standard way – we have seen how to prevent the taking of something, and how to give this unexpected consequences, but not how to make taking work in an entirely different way.

All three of those restrictions will later be lifted in the chapter on "Advanced Actions", but otherwise we have covered the ground thoroughly, and it is time to move on to the techniques enabling us to do more than make tart replies to the player: it is time to change the world.

8. Change

So far, what we have done in response to the player's commands amounts to little more than a few ripostes. The simulated world does change during play, as the player moves from room to room or picks up things, but all of this is happening automatically, not at our direct instruction. How then can we make the world change?

Recall that the world consists of rooms, in which are things, and that all of these have properties appropriate to their kinds. Some properties are either/or ("open" or "closed" but not both and not neither), while others have values (the "matching key" of a lockable door, for instance). Finally, we may also have created some free-standing values or "variables".

We take the last example first, as it is the simplest. Suppose we have:

"Winds of Change"
The prevailing wind is a direction that varies. The prevailing wind is northwest.
The Blasted Heath is a room. "Merely an arena for the play of witches and kings, my dear, where the [prevailing wind] wind blows."
Instead of waiting when the prevailing wind is northwest:
   say "A fresh gust of wind bowls you over.";
   now the prevailing wind is east.

The new phrase here is "now". This automatically checks that the new value is one which makes sense in the given context, so for instance it would not allow either of these:

now the prevailing wind is 25;
now the prevailing wind is the Heath;

the former being a number, and the latter a room, so that neither is a direction. Similarly, "now" will not allow constant values to be changed. So

Colour is a kind of value. The colours are blue, red and mauve.
After pulling the psychedelic lever:
   now blue is mauve.

…will result in a problem message; it's like writing "now 1 is 2". The difference between "the prevailing wind" and "blue" is that the wind was declared to be a "direction that varies", whereas blue wasn't.

The command prompt is the text printed by Inform to ask the player for another command. Ordinarily this is simply a greater-than-sign, ">", so we tend not to notice it as text at all. Internally, though, it is a variable value called "command prompt", which means we can change it.

For example, this will be a more conversational sort of prompt:

When play begins: now the command prompt is "What now? ".

Whereas this will be more up-to-the-minute and demanding:

When play begins: now the command prompt is "[time of day] >".

("Time of day" is another variable value, which is fairly self-explanatory, but will be covered in detail later on.) The prompt can be changed at any point, so can be used to indicate the current situation, or even as a sly way to introduce a sort of conversation between computer and player.

Example

113.
Combat scenario in which the player's footing and position changes from move to move, and the command prompt also changes to reflect that.

The status line is the black bar along the top of a story being played, which ordinarily displays the current position; in a story with scoring, it also usually shows the score and number of moves taken. Like the command prompt, it is not fixed but results from values which can be changed: the "left hand status line" and "right hand status line".

The default values are "[the player's surroundings]" for the left hand status line and "[score]/[turn count]" for the right hand status line (if there's scoring; it's blank otherwise). Score and turn count are numbers which vary in play (more about scoring later); "[the player's surroundings]" is a text substitution really intended for just this purpose:

say "[the/-- player's surroundings]"

This text substitution produces a succinct description of where the player is, be this in darkness, in a lighted room or inside an opaque container such as a large packing case. Example:

now the left hand status line is "You: [the player's surroundings]";

These make useful elements to juggle in redesigning the status line, as in the following example:

When play begins:
   now the left hand status line is
      "[the player's surroundings] / [turn count] / [score]";
   now the right hand status line is "Time: [time of day]".

The text in the right hand status line should be kept no more than 14 letters long, including any spaces. The left hand status line has more leeway, but should still be kept brief.

See Also

Awarding points for scoring.

Examples

Have the status line indicate the current region of the map.
115.
Centered ★★★
Replacing the two-part status line with one that centers only the room name at the top of the screen.

When we have an either/or property, we can set it like so:

Instead of waiting when the oaken door is closed:
   say "There is a slow, creaky click! sort of noise as the door swings open, apparently all by itself.";
   now the oaken door is open.

If it is open already, nothing changes: in any case nothing is said to the player unless we give explicit instructions to that effect, as we've done here.

Inform protects its model world from accidental damage in several ways, one of which is to ensure that things are not given properties which they are not allowed to have. So this, for instance, will not be accepted:

now the oaken door is unvisited

More subtle problems arise if it is not possible to tell, when the story is being constructed, what the object in question will be: for instance, if we try to change a randomly chosen object to be "unvisited". Inform therefore makes additional checks during play, printing up a suitable message only if the rules are violated. The net effect is that it is impossible for the oaken door ever to have the "unvisited" property.

Example

116.
An electrochromic window that becomes transparent or opaque depending on whether it is currently turned on.

Changing properties with values is very similar:

now the printed name of the Closet is "Suddenly Spooky Closet"

Inform checks three different things to ensure that this change is safe to perform. Firstly, the value must be the right kind for the property in question, so this for instance would be rejected:

now the printed name of the Closet is 7

Secondly, the object in question has to be allowed to have the given property. This, for instance, would be disallowed:

now the initial appearance of the Closet is "Dusty"

(since "initial appearance" is a property which only things can have, not rooms). Finally, the object has to actually have the property, not just have the right to have that property. Thus:

now the printed name of the Closet is "Suddenly Spooky Closet"

…is only permitted if the Closet is designed with a "printed name". In fact this is certain to be true: all rooms and things automatically have a printed name, which is the short boldface description in the case of rooms, and the usual text briefly describing something in the case of things.

"Now" is a simple way to change many things in Inform, but it's cumbersome to change the map of the model world using "now", because the map is such a complicated arrangement. (It's not a property: it's a sort of mesh of relations.) So a special phrase exists to change map connections:

change (direction) exit of (room) to (room)

This phrase alters the map so that the given map connection is made. Note that connections can be made to rooms, but not doors: the positions of doors are fixed. Example:

change the east exit of the Closet to the Tsar's Imperial Dining Salon

Since "nothing" is not a room, this doesn't allow us to change the exit to nothing, so there is a separate definition of:

change the west exit of the Closet to nothing
change (direction) exit of (room) to nothing/nowhere

This phrase alters the map so that the given map connection is unmade. Example:

change the west exit of the Closet to nowhere

Altering the map itself is not a very subtle way to adjust when and where the player can move – writing suitable rules is usually a cleaner solution – so this phrase is best avoided unless really needed.

Examples

117.
Thirst
A waterskin that is depleted as the player drinks from it.
118.
A campfire added to the camp site, which can be lit using tinder.

This seems a useful point to clarify something already seen. We normally call a property with a value something like:

the printed name of the West Ballroom

We are sometimes allowed to omit the "of the …" part, and simply call it "the printed name", for the sake of brevity. For instance, the following room description:

The West Ballroom is a room. "A handsome sweep of chequered floor beckons the eye into the [printed name]."

will result in "West Ballroom" being substituted for "[printed name]". Since the text belongs to the West Ballroom, that is assumed to be the owner of any properties named in its description. Similarly:

Instead of examining something, say "Hmm, let me see: [printed name]..."

Here the owner of the "printed name" is assumed to be the noun referred to in the action – in other words, the "something" alluded to in the rule.

We have now seen how to change the properties of rooms and things, and also any freestanding values which may have a bearing on the model world. We are not allowed to change the kind of anything during play. Our remaining freedom is to move things around. It would make no sense to move rooms around, because rooms are the fixed reference points in our geography, but anything else is mobile. This even includes things which are supposedly "fixed in place", for unlike the player, we have god-like powers. (There are minor restrictions: backdrops are trickier to move, since they are present in several rooms at once – see the next section. And doors, at the junction between two rooms, cannot be moved.)

Here is how to move something:

move (object) to (object)

This phrase moves the first-named object to the second. Example:

move the genie's lamp to Aladdin's Cave;

The first object named has to be a thing; the destination must be a room, as here, a container, a supporter, or a person. When something is moved, all its parts and contents (and all their contents, and so on) move with it. If the thing being moved is a person, then the destination is required to be a room or an enterable container. (In particular, a person cannot be carried by another person.)

Two options can be used if the object being moved is the player.

move the player to Aladdin's Cave, without printing a room description

omits the description which would otherwise be produced. A compromise is to use:

move the player to Aladdin's Cave, printing an abbreviated room description

which gives a full description if the player has never been here before, but only a brief one if it is a familiar scene. These options have no effect for any other objects being moved.

If the destination is a person, like so:

move the genie's turban to Aladdin;

then it will be carried rather than worn. We could arrange for it to be worn instead by writing

now the genie's turban is worn by Aladdin;

"Now…" is a much more flexible phrase than "move": more on this shortly.

Example

A meteor in the night sky which is visible from many rooms, so needs to be a backdrop, but which does not appear until 11:31 PM.

A backdrop can be in several rooms at once. When created, its position can be given as any specific collection of rooms, or as a region, or even as "everywhere". For instance:

The Upper Cave is above the Rock Pool. The Ledge is east of the Pool.
The stream is a backdrop. It is in the Upper Cave and the Ledge.

Moving backdrops is not like moving other things, because there's no single destination. There are several possibilities:

(a) A backdrop can be moved to a region. If we define:

Lower Level is a region. The Rock Pool and the Ledge are in the Lower Level.

then we can write either of

move the stream to the Lower Level;
now the stream is in the Lower Level;

and either way, the stream is now found in the Rock Pool and the Ledge but nowhere else.

(b) A backdrop can be moved to a category of rooms:

move (object) backdrop to all (description of objects)

This phrase moves the backdrop so that it is now present in every room matching the given description. Example: If we define

A room can be wet or dry. A room is usually dry. The Rock Pool is wet.

then we can write

move the stream backdrop to all wet rooms;

This phrasing, "move the … backdrop to all …" is deliberately meant to look unlike the simpler "move … to …", to emphasise that this kind of movement is possible only for backdrops.

What then happens is that the stream is present in whichever rooms are currently wet. But the stream's position is ordinarily checked only after movements, for efficiency's sake. So if the player is in a room which suddenly changes from being dry to being wet, the stream will not magically appear (though it will be there if the player goes out and comes in again). If this is not good enough, the phrase "update backdrop positions" can be used to ensure the accuracy of all backdrop locations after a dramatic change:

update backdrop positions

This phrase runs through all backdrops in the model world and makes sure they are correctly in, or not in, the current location, so that everything appears right from the player's point of view. Example:

The Upper Cave is above the Rock Pool. The Ledge is east of the Pool. The stream is a backdrop.
When play begins:
   move the stream backdrop to all wet rooms.
A lever is in the Cave. The lever is fixed in place.
Instead of pulling the lever when the Cave is dry:
   now the Cave is wet;
   now the lever is in the Rock Pool;
   now the lever is portable;
   update backdrop positions;
   say "The old rusty lever pulls away, and the thin cave wall goes with it, so that a stream bursts into the cave, falling to the pool below."

(c) A backdrop can be moved to be either everywhere or nowhere:

After sleeping:
   say "It's a bright new day!";
   now the stars are nowhere.
After waiting:
   say "Darkness falls rapidly here.";
   now the stars are everywhere.

Example

120.
Orange Cones ★★★
Creating a traffic backdrop that appears in all road rooms except the one in which the player has laid down orange cones.

The player is a thing, too, and can also be moved, which has the effect of instantaneous transportation, without the need for a suitable map connection to the new location. For instance, these are equivalent:

move the player to the Bodleian Library;
now the player is in the Bodleian Library;

This will ordinarily result in a room description of the Bodleian Library being printed up, but that might not always be desirable. For instance:

Instead of waiting in the Schola Maleficorum:
   say "A bored demon catches your eye (they really do have very inquisitive fingers) and throws you back out into the Antechamber.";
   move the player to the Antechamber, without printing a room description.

Thus tacking on the option "without printing a room description", remembering to add the comma, omits the description which would otherwise be produced. A compromise is to use the option "printing an abbreviated room description": this gives a full description if the player has never been here before, but only a brief one if it is a familiar scene.

The player's point of view can also be moved by shifting to another character. Suppose the story features two people, Alice and Bob, and the player at the keyboard is giving commands to Alice, and seeing everything from her point of view. The phrase:

now the player is Bob

switches the perspective so that now Bob is the one controlled by the human player, and it's Bob's point of view which counts. The human being at the keyboard may feel a sense of having jumped abruptly from place to place, but in fact neither Alice nor Bob has moved.

A change of player can sometimes cause confusing things to happen, if it takes place as part of a successful action. Suppose there's an action called "possessing", which enables the player to possess somebody else's body; and suppose the player types POSSESS ADELE. The action succeeds, so that the player moves into the mind of Adele. But that means that at the end of the action, the player is no longer the actor – that is, no longer the person who began the action; and consequently, Inform won't use the report rulebook to say what has just happened. It's a strange business, moving into another body.

Example

Multiple player characters who take turns controlling the action.

Some things will occasionally be in a limbo state called being "off-stage": like actors or props not needed in Act II, but perhaps to be brought back on-stage later, they wait on the sidelines. Anything created with no apparent location will start the story off-stage, as in the case of the lamp here:

Aladdin's Cave is a room. The genie's lamp is a container.

(Such things are easy to see in the World index because they are listed after all of the rooms and their contents, not belonging inside any room.) If we wanted to make this clearer to a human reader, we could add:

The lamp is nowhere.

to emphasise the point. In this context, "nowhere" means "in no room". Moving the lamp onto the stage-set, so to speak, is easy:

now the lamp is in the Cave;

or perhaps:

now the player is carrying the lamp;

and we can whisk it away again like so:

now the lamp is nowhere;

(We can't say "now the lamp is somewhere" because that's too vague about exactly where it is.) In older builds of Inform, the usual thing was to write "remove the lamp from play", but that's now a deprecated phrase: better to use "nowhere" instead.

remove (object) from play

Removes the given object from play, so that it is not present in any room. We are not permitted to remove rooms, or doors, or the player, from play; but we are permitted to remove backdrops, making them disappear from all rooms in which they are present. Example:

remove the gold coin from play;

We can test whether something is on-stage or off-stage with:

if the gold coin is somewhere, ...
if the gold coin is nowhere, ...

Inform also understands two adjectives for this:

if the gold coin is on-stage, ...
if the gold coin is off-stage, ...

Because these are adjectives, they can be used in a few ways which "nowhere" and "somewhere" can't, such as:

say "Ah, so many absent friends. Who now remembers [list of off-stage people]?"

Note that "on-stage" and "off-stage" apply only to things. Rooms, directions and regions are the stage itself: so it makes no sense to ask the question of whether they are "on-" or "off-". Doors are always on-stage; a backdrop, say "the sky", is always on-stage unless it has been taken off by writing something like "now the sky is nowhere".

Examples

A potion that the player can drink.
A character who sulks over objects that the player has broken (and which are now off-stage).
124.
A supply of red pens from which the player can take another pen only if he doesn't already have one somewhere in the game world.

"Now" has already appeared several times in this chapter, being used like a Swiss army knife to change values of all kinds:

now the score is 100;

In fact, "now" is by far the most flexible phrase known to Inform.

now (a condition)

This phrase makes the condition become true. Examples:

now the score is 100;
now the player is Kevin;
now the front door is open;
now Mr Darcy is wearing the top hat;
now all the doors are open;
now all of the things in the sack are in the box;

Inform issues a problem message if the condition asks to do the impossible ("now 3 is an even number") or is vague ("now the duck is not in the Lily Pond") or not in the present tense ("now the front door had been open").

We've now seen all three things which can be done with a condition S which describes the world:

S. - The relation holds at the start of play.
if S, ...; - Does the relation hold right now?
now S; - Make the relation hold from now on.

For instance,

The apple is in the basket.
if the apple is in the basket, ...;
now the apple is in the basket;

Examples

125.
A maze with directions between rooms randomized at the start of play.
126.
Hatless ★★
It's tempting to use "now…" to distribute items randomly at the start of play, but we need to be a little cautious about how we do that.
127.
A ray gun which destroys objects, leaving their component parts behind.

Once we begin to deal with named values (or table entries, list entries or other ways to describe places where values are kept), we find that we often want to change them. We could if we wanted always use "now" for this, but it can be a little clumsily worded if we want to increase or decrease something:

now the score is the score plus six;

Because of that, we have some convenient abbreviations which have the advantage that the value being changed only has to be named once:

increase (a stored value) by (value)

This phrase increases the variable, table entry, list entry, or property by the given amount, which must be of a compatible kind. Example:

increase the score by 8;
increase the time of day by 5 minutes;
decrease (a stored value) by (value)

This phrase decreases the variable, table entry, list entry, or property by the given amount, which must be of a compatible kind. Example:

decrease the score by 6;
decrease the carrying capacity of the player by 10;

An even greater abbreviation can be made when we are changing a number by 1 either way:

increment (a stored value)

This phrase increases the variable, table entry, list entry, or property by 1. Example:

increment the score;
decrement (a stored value)

This phrase decreases the variable, table entry, list entry, or property by 1. Example:

decrement the score;

"Increment" and "decrement" are traditional computing terms, though they have been used in engineering for at least a century and in finance for longer still.

We have seen that while rooms are fixed, their contents move around, so we will need ways to examine the current whereabouts of things. The following examples show the kind of conditions allowed:

if the genie's lamp is in Aladdin's Cave ...
if Aladdin is not in Aladdin's Cave ...
if Aladdin's Cave contains the genie's lamp ...
if the genie's lamp is carried by Aladdin ...
if Aladdin is carrying the genie's lamp ...
if Aladdin does not have the genie's lamp ...
if the table supports the genie's lamp ...
if the table is supporting the genie's lamp ...
if the genie's lamp is supported by the table ...
if the genie's lamp is on the table ...
if the genie's lamp is on top of the table ...
if the genie's lamp is in the cupboard ...
if the genie's lamp is contained in the cupboard ...
if the genie's lamp is inside the cupboard ...
if the genie's lamp is within the cupboard ...
if the wick is part of the genie's lamp ...

These are exactly like the assertions which we use to set up the world, except that we make them questions by placing "if" in front. But we shall later see that we can also use three other tenses, not to mention plural forms, so that new verbal forms like "had not been inside" and "were not supported by" are legal here (which they would not be in assertions). What we are not allowed is to contract these verbs with apostrophes: "isn't", "hasn't" and "hadn't" are forbidden.

Overwhelmingly the condition we check most is whether the player is carrying something. The following are therefore equivalent:

if the genie's lamp is carried by the player ...
if the genie's lamp is carried ...

And similarly for "not carried", "worn" and "not worn". To be precise, if a form of to be carried or to be worn is not followed by any other description, then "the player" is assumed to be doing the carrying or wearing.

The examples just given were all basically of the form "X relation Y" where X and Y were specific names of things. For example,

if the genie's lamp is carried by Cinderella ...
if the genie's lamp is inside the cupboard ...

Just as actions could be described with patterns to be matched ("taking an open container", say), so can the positions of things. Giving subtler descriptions of our X and Y sometimes broadens the possibilities, sometimes narrows them:

if the genie's lamp is carried by a woman ...
if the genie's lamp is inside the closed cupboard ...

In the first case, Y is allowed to be one of a whole range of things – any of the women existing in the world. This makes for a broader condition. In the second case, Y has not only to be the cupboard, but at a time when it is closed: which makes for a narrower condition. We can, of course, also vary X:

if an animal is inside the cupboard ...
if a container is carried ...

And we can even vary both X and Y at once:

if a woman is holding an animal ...

a condition which will be true if, anywhere in the story's world, any woman is holding any animal.

Conditions like "if somebody is in an adjacent room" allow complicated tests to be performed with a minimum of fuss, but it's rare that we want to know only whether they are true: more likely we also want to know which person, and which room.

For this purpose, we are allowed to supply a name for any such vaguely-described object which comes up, and then to use that name thereafter.

if somebody is in an adjacent room (called the Hiding Place), say "You hear distant breathing from [the Hiding Place]."

We can even name more than one of the things discovered:

Instead of waiting when a woman (called the kidnapper) is holding an animal (called the pet), say "How can you think of rest when, somewhere out there, [pet] has been cruelly kidnapped by [the kidnapper]?"

Note the brackets, which are essential. The result of typing "wait" is then

How can you think of rest when, somewhere out there, a lapdog has been cruelly kidnapped by Baroness Orczy?

Of course, that might be just one of many animals held by women in the story. We shall later see ways to go through all of the possibilities found, performing some action with each in turn.

A calling, if we can use that word, should be made immediately after the noun it refers to, and not left to hang back after any relative clauses. For instance,

if something (called the penitential object) held by the player is hot

is allowed, but not

if something held by the player (called the penitential object) is hot

because there is too much potential ambiguity – are we trying to call the player something?

See Also

Repeat running through for systematically working on everything matching a description.

Example

All doors in the game automatically attempt to open if the player approaches them when they are closed.

It is very often useful to know how many things are in a given situation, and for this purpose we have the "number of …" construction. For instance:

the number of edible things carried
the number of things on the table
the number of people in the Dining Room

Whereas "a woman is holding an animal" makes the same test as "an animal is held by a woman", getting the same result, counting is not so even-handed:

the number of women holding animals
the number of animals held by women

are different questions and, unless the ration is strictly one lapdog per baroness, will have different answers. If Cruella de Vil has 101 dalmatians, they may be very different indeed.

It can also be helpful to count things with no particular location, like so:

the number of rooms
the number of closed doors

For instance:

When play begins:
   now the right hand status line is "Explored: [number of visited rooms]/[number of rooms]".

Provided that the possible range is finite, we can also use "number of" to count values which match a description. For instance:

the number of non-recurring scenes

or if we were to define

Colour is a kind of value. The colours are red, orange, yellow, green, blue, indigo and violet.

then "the number of colours" would evaluate to 7. As with other ways of talking about whole ranges of values, this only works if the range is manageable. "The number of numbers" cannot sensibly be worked out: there are infinitely many, for all practical purposes, and similarly for "the number of texts".

The descriptions outlined in the last few sections are intended to deal with almost all of the routine questions we might have about what currently resides where.

holder of (object)object

This phrase produces the object that holds an object, thus the person who carries or wears a thing, or the supporter that supports a thing, or the thing it's a part of, or the thing or room that contains it, or, for regions, the region that contains it. If nothing holds the object, holder of produces the special object value nothing.

It's sometimes useful to go the other way. Given an object, what are its contents, or occupants, or possessions? But there is an important caveat to the following phrases: parts are not included.

[ TODO discuss regions? ]

first thing held by (object)object

This phrase produces the first of the list of things held by the object, excluding by incorporation. Example:

first thing held by Baroness Orczy

This provides an efficient way to tell whether a container, supporter, or room is empty, or whether a person neither wears nor carries anything:

if the first thing held by Baroness Orczy is nothing

If that's false for a person, you know they wear at least one thing or carry at least one thing, or both. It may or may not be the case that they wear nothing or carry nothing: you would have to check more closely.

next thing held after (object)object

This phrase produces the next item of the list of things held by something, excluding by incorporation. Example: suppose Baroness Orczy is carrying a lapdog and a string of pearls.

next thing held after the lapdog

is then the string of pearls.

These phrases be used together to loop through things carried, worn, contained, or supported:

let the item be the first thing held by Baroness Orczy
while the item is not nothing:
   [...]
   now the item is the next thing held after the item;

As noted, the above would never yield any parts the Baroness may have. If she *did* incorporate something, you would encounter additional results if you were to loop with:

repeat through the list of things held by Baroness Orczy:
   [...]

to borrow a phrase we'll see later on in the chapter on Lists.

Another caveat is that the verbs "to be held in" and "to be held inside" are associated with *containment*, not with holding. If an object is *held inside* another object, you know it is also *held by* that object, but the reverse is not necessarily true. (There is an exception here: a region contains the rooms that are directly within it, but does not hold them.)

Sometimes we want to introduce random behaviour into play. We usually do this by generating random values, and then acting differently depending on what they are. The following:

a random number from 2 to 5

produces, as it suggests, a random number drawn from the choices 2, 3, 4 or 5, each of which is equally likely to come up. In fact, this isn't limited to numbers:

a random (name of kind) between (arithmetic value) and (arithmetic value)value
or…
a random (name of kind) from (arithmetic value) to (arithmetic value)value
or…
a random (name of kind) between (enumerated value) and (enumerated value)value
or…
a random (name of kind) from (enumerated value) to (enumerated value)value

This phrase produces a uniformly random value in the range given. Examples:

a random number from 10 to 99
a random time from 2:31 PM to 2:57 PM

If we make a new kind of value:

A cloud pattern is a kind of value. The cloud patterns are cumulus, altocumulus, cumulonimbus, stratus, cirrus, nimbus, nimbostratus.

then we can also take random values from it:

a random cloud pattern between stratus and nimbus

which has three possible outcomes, all equally likely.

We can also use random conditions:

if a random chance of (number) in (number) succeeds:

This condition is true X/Yths of the time, where X and Y are the numbers. Example:

if a random chance of 2 in 3 succeeds, ...

Here is a rule which applies only 15% of the time:

Instead of waiting when a random chance of 15 in 100 succeeds: ...

Testing IF which makes random choices can be rather frustrating, because a problem showing up on one attempt may not show up on another. We can get around this by making use of the fact that computers do not actually generate true randomness, but instead make a sequence of apparently random numbers by applying a complicated formula to each one in order to make the next. The starting point is a number called the "seed", because the next choice grows out of it.

seed the random-number generator with (number)

This phrase changes the seed number as specified. Any random numbers generated after that depend only on the seed. Example: the following sentence will "fix" the process of generating these random numbers so that they are not random at all – the same sequence of random numbers will be produced on each run.

When play begins, seed the random-number generator with 1234.

The seed value "1234" can be anything positive; a different sequence of random numbers will be produced for each different seed value. A seed value of 0 restores the RNG to properly random behaviour again.

Alternatively, it's possible the "fix" the RNG by clicking the "Make random outcomes predictable when testing" option on the Settings panel. This makes the behaviour predictable whenever the story is played within Inform, but (unlike the rule above) has no effect on the story file once released.

Examples

129.
A pair of dice which can be rolled, and are described with their current total when not carried, and have individual scores when examined.
130.
Very simple randomized combat in which characters hit one another for a randomized amount of damage.
131.
The automatic weather station atop Mt. Pisgah shows randomly fluctuating temperature, pressure and cloud cover.
132.
Uptown Girls ★★★
A stream of random pedestrians who go by the player.

Writing "a random number" is not allowed, because the possible range is too large, but that was the only reason why not.

a/-- random (description of values)value

This phrase makes a uniformly random choice from values satisfying the description given. Example:

a random visited room
a random scene

A problem message is issued if the range is too large (for instance, "a random text"). Unexpected results may follow if no value fits the description, unless we are describing objects, in which case the result is the special value "nothing".

For instance:

say "You can see [number of adjacent rooms] way[s] from here; how about [random adjacent room]?"

But it's important to worry about the possibility that nothing qualifies – here, that no adjacent rooms exist. The above would then say:

You can see 0 ways from here; how about nothing?

Examples

133.
Candy
One of several identical candies chosen at the start of play to be poisonous.
134.
A "Carousel Room", as in Zork II, where moving in any direction from the room leads (at random) to one of the eight rooms nearby.

9. Time

With the material from previous chapters, we are now able to set up a simulated world, to respond to the player's actions within it, and to make it change in perhaps unexpected ways.

The resulting experience can be as lively as we want to make it, but so far we have no very good ways to give it any structure: a beginning and an end, for instance, or a sense of plot. This next chapter is all about the passage of time, and it begins at the beginning.

We have already seen an example of how to write a rule which applies just once, at the start of the story:

When play begins: say "Welcome to Old Marston Grange, a country house cut off by fog."

The "when play begins" rules are checked only at the start of a story, not when a saved session is restored from disc. What happens is that these rules are followed, then the story's banner is printed, then the initial room description is printed up, and then the player is asked for a first command.

Example

135.
A murderer for the mystery is selected randomly at the beginning of the game.

Traditionally-written stories award points throughout play, as an indication of progress. If we want to be traditional, we must first write:

Use scoring.

Without this, the SCORE, NOTIFY ON and NOTIFY OFF commands do not work; the final score is not shown at the end of a story; and the status line above the player's text area shows only the turn count, not (as is more usual) both the score and the turn count. Changing the "score" (see below) has no visible effect, though it is not actually illegal.

With "Use scoring" in place, we can award points as follows:

increase the score by 5;

substituting whatever number we feel is appropriate. We should be careful not to give out the same points over and over, that is, not to reward the same basic achievement many times over if the player simply repeats the same action. This, for instance, is open to abuse:

After taking the trophy:
   increase the score by 5;
   say "Well done!"

The player may simply take the trophy, drop it again, take it again, … and win five points every time around. We can prevent this by phrasing the rule more carefully:

After taking the trophy when the trophy was not handled:
   increase the score by 5;
   say "Well done!"

("Was handled", not "is handled", because this rule happens after the trophy has been taken – so by the time this rule has been considered, the trophy is always handled.) Rather than being an open-ended scoring system, IF normally has a maximum possible score, which can be specified with a sentence like so:

The maximum score is 10.

The score and maximum score are just numbers that vary, so we can freely change them:

After eating the poisoned mushroom:
   now the score is -100.

Examples

136.
Awarding points for visiting a room for the first time.
137.
Recording a whole table of scores for specific treasures.

Another tradition of interactive fiction is that the player has a current 'rank' according to how far his or her score has got. We can (but need not) choose to provide such rankings, and should do so by specifying a table like this:

Table 1 - Rankings
ScoreRank
0"Beginner"
25"Amateur Adventurer"
50"Novice Adventurer"
100"Junior Adventurer"
200"Adventurer"
300"Master"
330"Wizard"
350"Master Adventurer"

Typographically, tables in Inform look as much as possible like those found in non-fiction books: they can have many columns, so this is only a simple example (drawn from the actual rankings used by Infocom's Zork I, 1979). Each line in the source represents one row in the table, and the entries on a line must be separated by at least one tab character. (An entry might of course have several words with spaces in between, so a space is not enough to separate entries: this is the only context when Inform distinguishes between spaces and tabs.) The table must occupy a single whole paragraph, with no skipped lines or missing entries. We are free to use extra tabs to indent it if we like.

Ordinarily we must explicitly ask to use the information presented in a table, but the table of rankings is a special case: Inform uses it automatically, if it is provided at all. To be recognised it must have the name "Rankings" and must have two columns named and arranged as shown. The scores should be given in ascending order. Customarily, the score in the final row should be the maximum possible achieved in the story – so that only a player with maximum possible score can be awarded the final ranking – and the value of "maximum score" is automatically set to this bottom-row value if it has not been explicitly set anywhere else in the source text.

Short of something like a power cut, the story can only end when one of the two participants chooses to end it: either the player, by deciding that enough is enough, or us.

In story-telling, there are many kinds of ending: happy, sad, decisive, bittersweet, surprise. Inform doesn't try to interfere in that kind of artistic choice, but it does need to know one thing about the ending: is it final, or not? Many authors like to make additional menu items available if the player has completed the story right through, but not if she has reached an early or wrong ending. (See the activity "amusing a victorious player", for example.)

end the story

This phrase ends the story at the next opportunity (typically as soon as the current rule ends), with the closing message "The End." The end is not considered final.

end the story finally

This phrase ends the story at the next opportunity (typically as soon as the current rule ends), with the closing message "The End." The end is considered final, and any hidden menu options will be revealed.

end the story saying (text)

This phrase ends the story at the next opportunity (typically as soon as the current rule ends), with the closing message given in the text. The end is not considered final. Example:

end the story saying "You have been stymied"
end the story finally saying (text)

This phrase ends the story at the next opportunity (typically as soon as the current rule ends), with the closing message given in the text. The end is considered final, and any hidden menu options will be revealed. Example:

end the story finally saying "You have defeated Sauron"

The closing message is traditionally set out in asterisks:

*** The End ***

This style is traditional in IF, and goes back to 1980 if not earlier.

We can test the current state like so:

if story has ended:

This condition is true if an end has been declared using one of the "end the story…" phrases.

if story has not ended:

This condition is true if no end has been declared using one of the "end the story…" phrases.

if story has ended finally:

This condition is true if an end has been declared using one of the "end the story finally…" phrases, so that an ending has been reached which the author feels is a completion of the player's experience.

if story has not ended finally:

This condition is true if an end has been declared using one of the "end the story…" phrases, but not "finally", so the author feels that the player can get further experience by playing again and trying different approaches.

The rulebook "when play ends" is the matching bookend to "when play begins". It is followed when the story decides to end (not when the player simply gives up and quits), and before any epitaph like

*** You have been poisoned ***

appears. For example:

When play ends, say "Oh dear."

Surprisingly, the end is not always the end:

resume the story

This phrase causes an ended story to resume exactly as if no "end the story…" phrase had been used. Example:

When play ends:
   if the story has not ended finally:
      say "Oh dear. Still, here's another chance.";
      resume the story.

The phrase is likely to be sensible only as part of a "when play ends" rule. Other traditional uses include giving the player three lives, as in an old-school arcade machine.

Example

138.
Big Sky Country ★★★
Allowing the player to continue play after a fatal accident, but penalizing him by scattering his possessions around the game map.

The passage of time in interactive fiction is broken up into a succession of turns, in each of which the player types a request and is given a response. Usually each such request triggers one action, but sometimes a whole sequence are fired off, as when the player types "get all" in a cluttered room.

As we've seen, the variable "turn count" holds the number of turns of play so far. By convention turn number 0 is the time when Inform prints up the banner and any initial text; it becomes turn number 1 when the player's first command is typed.

One of the last things to happen in each turn is that Inform will apply any rules which have been set to occur "every turn", like so:

Every turn, say "The summer breeze shakes the apple-blossom."

This is equivalent to writing:

An every turn rule: say "The summer breeze shakes the apple-blossom."

Note that the text about blossom, which will quickly become tiresome, is said at the end of every turn, not at the beginning, and in particular not before the player's first opportunity to type a command.

As usual when defining rules, we can add stipulations: any condition can be attached using "when".

Every turn when the location is the Orchard, say "The summer breeze shakes the apple-blossom."
Every turn when the player can see the rotting fish, say "Your nose twitches involuntarily."

Examples

139.
Witnessed 1 ★★★
A kind of battery which can be put into different devices, and which will lose power after extended use.
140.
Text Foosball ★★★★
A game of foosball which relies heavily on every-turn rules.

Inform keeps track of the time of day automatically: play ordinarily begins at 9 AM and each turn takes one minute. In some works of interactive fiction, time of day is crucial: in others, it is irrelevant or even, by a sort of tacit convention, non-existent. So Inform does nothing to act upon the time, or to reveal it to the player, without instruction. Nevertheless it is there.

A sentence like the following allows the initial time to be set up as something other than 9 AM:

The time of day is 3:13 PM.

Here, "3:13 PM" is a constant value of a kind not seen before: it's a kind of value called "time", and the value "time of day" is a time that varies. After one turn it will be 3:14 PM, then 3:15 PM and so on.

Note that the sentence above is an assertion (a statement about the initial state of affairs), not an instruction which can be part of a rule. It would be equivalent to write:

When play begins: now the time of day is 3:13 PM.

We more often change "time of day" to take care of drastic events:

At the time when the player loses consciousness:
   now the time of day is 10:12 AM;
   say "A mist comes over your vision, and when you come to, it is morning and you are in bed."

Example

141.
IPA ★★
Shops which each have opening and closing hours, so that it is impossible to go in at the wrong times, and the player is kicked out if he overstays his welcome.

Now that we have the time of day, we can of course use this value in room descriptions and the like:

The Clock Chamber is a room. "The dark chamber behind the clock face, a mill-room of gears which grind down the seconds. Through the glass you can see the reversed hands reading [the time of day]."

It seems odd, though, to read a precise numerical description of the time here: after all, it isn't a digital clock. A friendlier version would use:

say "[(time) in words]"

This text substitution produces the given time written out in English sentence form. For example:

"Through the glass you can see the reversed hands reading [the time of day in words]."

might produce

Through the glass you can see the reversed hands reading twenty to nine.

To reiterate an example which came up earlier, we could even work the time of day into the command prompt, which would lend the proper sense of urgency to a story played out against the clock:

When play begins: now the command prompt is "[time of day] >".

Example

Printing the time of day in 24-hour time, as in military situations.

Clocks and watches vary considerably in how much detail they show, and we tend not to report the time over-precisely: half-past ten is an elastic concept. The following room description for the Clock Chamber comes across much more naturally:

The Clock Chamber is a room. "The dark chamber behind the clock face, a mill-room of gears which grind down the seconds. Through the glass you can see the reversed hands reading [the time of day to the nearest five minutes in words]."

The phrase "… to the nearest …" rounds off the given time, just as it sounds; as we'll see later, it can actually round off any arithmetic values, not just times. For instance, "9:58 PM to the nearest ten minutes" is 10:00 PM.

In talking about lengths of time, rather than times of day, it's useful to have these:

(number) minutestime

This phrase converts numbers into lengths of time. Example:

15 minutes

Because it's a phrase, not just a notation for writing constants down, the number doesn't have to be given literally:

let X be 5;
if the player is in the Slow Room, now X is 10;
let deadline be the time of day plus X minutes;

Note that lengths of time can't exceed 1440 minutes.

(number) hourstime

This phrase converts numbers into lengths of time. Example:

10 hours

Note that lengths of time can't exceed 24 hours.

Carrying out easy calculations with times is straightforward:

The chronometer is in the Clock Chamber. "On one wall is a terribly self-important chronometer showing the time in major world cities. London: [time of day]. Paris: [one hour after the time of day]. Tokyo: [9 hours after the time of day]. Cupertino, California: [7 hours before the time of day]."

Here we are using two phrases:

(time) before (time)time

This phrase produces a time earlier by the amount given, keeping within the 24 hour clock. Example:

7 hours before 5:30 AM

produces 10:30 PM.

(time) after (time)time

This phrase produces a time later by the amount given, keeping within the 24 hour clock. Example:

9 hours after 11 AM

produces 8 PM.

Similarly, we have conditions:

if (time) is before (time):

This condition is true if the first time occurs earlier in the day than the second. In recognition of the fact that very few stories begin before 4 AM, whereas many run on past midnight, the start of the day is taken to be 4 AM: thus 3:59 AM is after 11:10 PM, but 4:04 AM is before it.

if (time) is after (time):

This condition is true if the first time occurs later in the day than the second. In recognition of the fact that very few stories begin before 4 AM, whereas many run on past midnight, the start of the day is taken to be 4 AM: thus 3:59 AM is after 11:10 PM, but 4:04 AM is before it.

We will occasionally need to perform more complex calculations with time, and in order to do that, we have a way to convert the time of day to numbers. Thus the phrase "the minutes part of …" takes a time and produces a number from 0 to 59; similarly "the hours part of …" extracts a number from 0 to 23, using the twenty-four hour clock.

minutes part of (time)number

This phrase converts a time to a number, then takes the result mod 60, which in effect produces the number of minutes after the hours are thrown away. Example:

minutes part of 12:41 PM

produces 41.

hours part of (time)number

This phrase converts a time to a number, then divides the result by 60, which in effect produces the number of hours after minutes are thrown away. Example:

hours part of 8:21 AM

produces 8.

To go the other way, we can convert any number to a duration by writing "minutes" or "hours" after it. For instance:

The clock error is a number that varies. To thump the mechanism: now the clock error is a random number from -10 to 10.
The broken grandfather clock is in the Chamber. "An erratic grandfather clock seems to say it is [clock error minutes after the time of day]."
When play begins, thump the mechanism. Instead of attacking the broken clock: thump the mechanism; say "You thump the clock, which now reads [clock error minutes after the time of day].".

Note that "clock error" is a number, but "clock error minutes" is a time.

We often want to arrange for something to happen at some point in the future. Here is yet another timepiece:

An egg-timer is in the Chamber. "A plastic egg timer in the shape of a chicken can be pressed to set it going."
Instead of pushing the egg-timer:
   say "It begins to mark time.";
   the egg-timer clucks in four turns from now.
At the time when the egg-timer clucks:
   say "Cluck! Cluck! Cluck! says the egg-timer."

The event here is called "the egg-timer clucks". It only happens if we instruct so, using one of the following phrases:

(rule) in (time) from now

This phrase causes the given rule to be run at a given time offset from the current time of day. Example:

the egg-timer clucks in 18 minutes from now;
(rule) in (number) turn/turns from now

This phrase causes the given rule to be run at a given number of turns after the current one. Example:

the egg-timer clucks in four turns from now;
(rule) at (time)

This phrase causes the given rule to be run at a given time of day. Example:

the egg-timer clucks at 11:35 AM;

If we know in advance what time we want something to happen, we can more simply write:

At 4 PM: say "The great bells of the clock tower chime four."

(Note that in either case such rules begin with the word "at": they are the only rules allowed to begin with the word "at".)

A small warning: timed events like these only have a chance to occur during the turn sequence, that is, once every turn. In most stories, one turn takes one minute, so there will in due course be a turn happening at exactly (say) 11:35 AM. But if the clock is being advanced faster than this, it's possible that there are turns at (say) 11:32 AM and then not until 11:37 AM. But an event set for 11:35 AM will nevertheless happen – it will run at the first available turn after that time, which will be 11:37 AM. Events can thus happen up to half an hour late, though Inform cancels them if the elapsed time is greater than that.

The Scenes panel of the Index can be a useful way to see what events have been set.

Examples

143.
MRE
Hunger that eventually kills the player, and foodstuffs that can delay the inevitable by different amounts of time.
144.
Totality ★★
To schedule an eclipse of the sun, which involves a number of related events.
145.
Empire ★★
A train which follows a schedule, stopping at a number of different locations.
146.
Allowing the player to make an appointment, which is then kept.

There are two ways that descriptions of actions can be used as conditions. First, we can simply describe an action, and then the condition will be true if that is what the player is trying to do, and not otherwise:

if taking a container, ...

This is actually an abbreviation for the longer, some would say preferable form:

if we are taking a container, ...

Secondly, we can talk about the past as well as the present, which is very useful since interactive fiction often contains situations which are changed by earlier events.

Instead of waiting when we have taken the lantern, say "No, your acquisitive nature is roused now, and simply waiting will no longer do."

More on the past tense later follows in the next section: note that "we are taking" has become "we have taken". For the rule to apply, it is not enough that the action "taking the lantern" has been tried: it must have succeeded. Note also that it's enough for any actor in the story to have successfully taken the lantern: it doesn't have to be the player.

Examples

147.
A room which changes its description depending on whether an object has been examined.
148.
Zero ★★★
A box which called "horribly heavy box" after the player has tried to take it the first time.

The remaining sections of this chapter go into more technical ways to think about the progress of the story through time, and can be skipped at a first reading.

Conditions are clauses which require Inform to make a decision: is such-and-such true, or not true? We have already seen conditions attached to rules using "when":

Instead of waiting when the Sorting Hat is in the Hall: ...

and, as we shall later see, we will often want to write instructions like:

if the Sorting Hat is in the Hall, say "Hermione blinks apprehensively."

The condition is "the Sorting Hat is in the Hall", and during play this will sometimes be true and sometimes false.

A condition in the form "X is Y" is of course written in the present tense, and refers to the current state of affairs. Three other tenses are allowed. First, the present perfect:

if X has been Y ...

is true if it has ever been the case that "X is Y" at the start of any turn (or any action). So, for instance,

if the gate has been open ...

will be valid if and only if the gate has ever been made open by any action (even if it is closed now), or if it started out by being open when play began.

Next is the past tense:

if X was Y ...

holds if and only if "X is Y" was true at the start of the most recent action. This is convenient when trying to describe what has changed in the course of the action, but sometimes also when making the action itself happen. For instance:

if the lantern was switched on, now the lantern is switched off;
if the lantern was switched off, now the lantern is switched on;

Completing the set is the past perfect:

if X had been Y ...

which records whether "X has been Y" was true at the start of the most recent action. All these verbs can of course be negated (though "wasn't" and "hadn't" are disallowed as poor style: we use "was not" and "had not" instead). So for example,

if the player had not been in the Ballroom ...

is true if the player hadn't visited the Ballroom at the start of the most recent action.

Something we must watch out for is that variables might not have the same values in the past that they have now. As a result, writing conditions such as "if the noun has been open" is a bad idea, because in the past "the noun" very likely referred to something different. It is really only safe to talk in the past tense about definite, fixed things: "if the Great Gates of Kiev have been open" would be fine.

Examples

149.
An overview of all the variations of past and present tenses, and how they might be used.
A candle which reacts to lighting and blowing actions differently depending on whether it has already been lit once.
151.
Elsie ★★
A door that closes automatically one turn after the player opens it.

There are two further ways to examine the historical record. Given any condition, we can say

if (...condition...) for the second time ...
if (...condition...) twice ...
if (...condition...) 2 times...
if (...condition...) two times...

(all of which are synonymous: the words once, twice, thrice, one, two, three, four, five, six, seven, eight, nine, ten, first, second, third, fourth, fifth, sixth, seventh, eighth, ninth and tenth all mean what they obviously should). The result is true if the condition holds now and has held for only one previous spell in the past. A condition holding for, say, fifteen consecutive turns without a break counts as only one "time" – so what we mean by "twice" here is that it is true now, was previously false for a while, and was previously true for a while before that, but no more. In effect, then,

if the player is in the Ballroom for the third time ...

is true if this is the third visit to the Ballroom. We can also say

if the player is in the Ballroom for more than the third time ...

or similarly "less than", "at least", "at most". It would be more natural, though, to say

if the player has been in the Ballroom three times ...

The adjective "only" (or equivalently "exactly") can be added to obtain

if the player has been in the Ballroom only three times ...

To recap, this means there have been exactly three visits to the Ballroom in history, whereas

if the player is in the Ballroom for the third time ...

means there have been exactly three visits, the third of which is still going on – an important distinction.

Example

152.
A room whose description changes depending on the number of times the player has visited.

So much for "times" – spells in which a condition is true. We can also test the length of time, in turns of play, that something has been true. Thus:

if ... for three turns;

means that the condition holds now, and held at the start of this turn, at the start of last turn, and at the start of the turn before that. In particular:

if the floppy hat has been worn for three turns ...

will be false if the hat is not currently worn (even if it has been often in the past) and, on the other hand, will be true if the hat has been worn for twenty turns. Here again we can be more specific. These are synonymous:

if the floppy hat is worn for the third turn ...
if the floppy hat has been worn for only 3 turns ...
if the floppy hat has been worn for exactly three turns ...

all requiring that the hat wasn't worn four turns ago. As before, "more than", "less than", "at least" and "at most" so forth can also be used – say, "for at least 21 turns".

A warning: we must be careful when writing something like

if the noun has been open ...

since this tests whether it has ever been true that the noun of the then action was open: not whether the current noun-object has ever been open.

Lastly, note that the beginning of play – when (usually) initial text and a banner is printed, followed by a room description – counts towards these counts. In effect, this is a turn: one in which the player compulsorily performs the looking action, rather than being asked for a command. (By convention it is numbered as turn number 0, and doesn't contribute towards the turn count.)

Example

A child who after a certain period in the car starts asking annoying questions.

10. Scenes

As we have seen, Inform divides up space into individual places called "rooms", and allows us to group rooms together into "regions" if we find that convenient. And Inform also divides time up, into individual turns. These too we can group together: the equivalent of a region is a "scene".

To put this another way, if we think of the interactive fiction as a stage play, then up to now it has simply contained endless dialogue and stage directions – there has been no convenient way to divide up its running time into dramatic episodes, in the same way that a playwright might make Act II take place in the same drawing-room as Act I, but (let us say) six months later, after many things have changed. The script contains cues for one scene to end and another to begin: when those cues are reached, the stage hands rearrange props, actors reposition themselves and so on.

Inform also allows us to create scenes, with cues for them to start and end, and some stage machinery (so to speak) making it easy to move the action on. But interactive fiction is interactive, so the metaphor of the theatre only goes so far. We can have several different scenes going on at once – perhaps with the relevant events taking place in different rooms, which the player is free to walk between. And the player may make a choice which changes the story-line, causing scenes to happen which otherwise would not have happened, and so on. Scenes can even be "recurring", that is, can repeat themselves.

So organising the story-line into scenes is not simply a matter of making a list (Scene 1, then Scene 2, then Scene 3, finis). It is more like a chart in which one scene can lead in several possible ways to others – a sort of map of time, which as we shall see Inform displays in its "Scenes" index.

As usual, we only need to say that something is a scene to make it so:

Train Stop is a scene.

We conventionally write scene names with capital letters, as this demonstrates.

This works, and shows up in the "Scenes" index, but does nothing. We have given no instructions on when it begins – no cue, in stage-play terms – so it never will begin, and even if it did, nobody would notice since it does nothing. First, to give it a beginning:

Train Stop begins when the player is in the Station for the third turn.

In theory any condition can be used to cue the scene – here, it's "the player is in the Station for the third turn" – but it's wise to look for a state of affairs which will last at least a brief time, because scene changes only happen at the start and end of turns. (Something like "…when examining the timetable" may be true only for a part of the middle of a turn, and so go unnoticed.)

Every scene has two rulebooks attached, one at each end, so to speak. These look very like "when play begins" and "when play ends", and work in the same way. Thus:

When Train Stop begins:
   now the Flying Scotsman is in the Station;
   say "The Flying Scotsman pulls up at the platform, to a billow of steam and hammering."
When Train Stop ends:
   now the Flying Scotsman is nowhere;
   if the player is in the Station, say "The Flying Scotsman inches away, with a squeal of released brakes, gathering speed invincibly until it disappears around the hill. All is abruptly still once more."

Thus when the scene begins, our imaginary stage-hands wheel in a steam train; when it ends, they get rid of it again. Note that we know where the player will be at the start of the scene, but by the end he may have wandered off across the fields, so we must be careful not to report something he might not be in a position to see.

When Train Stop begins, we printed some text, but we did this by hand. We didn't need to, because Inform automatically prints out the description of a scene (if it has one) when the scene begins. Scenes can have properties, just like objects, and in particular they have the "description" property. For example, we could write:

Arrival is a scene. "There's a flourish of trumpets."

which saves us the trouble of writing the rule:

When Arrival begins: say "There's a flourish of trumpets."

We can also write rules like this which apply to a whole variety of scenes at once. For instance:

A scene can be bright or dim. A scene is usually dim. Dawn is a bright scene.
When a scene which is bright ends: say "So passes the bright [scene being changed]."

Here, instead of naming a scene ("Train Stop"), we've given a description ("a scene which is bright"). When a scene begins, these general rules come before those which name the scene exactly; when it ends, the reverse is true.

Examples

154.
Pine 1
Pine: Using a scene to watch for the solution of a puzzle, however arrived-at by the player.
155.
Entrapment ★★
A scene in which the player is allowed to explore as much as he likes, but another character strolls in as soon as he has gotten himself into an awkward or embarrassing situation.

But when we test the previous section's example, we find that after a brief wait, the train pulls up: but it never goes away again. We have given instructions on how the scene ends, but not when it ends, and as a result the scene goes on forever once started.

Even with simple story-lines, and this one could hardly be simpler, it is surprisingly easy to overlook something so that the whole story-line is derailed.

The Scenes page of the index is intended to help with this. The Plot section shows all of the scenes and how they are to begin, along with a key to the symbols used on it. One scene always included is "Entire Game", a special scene which, as its name implies, is always being played out. But if we look at the Scene index for the previous example, we will also see our Train Stop scene, and find that it is marked with the red warning symbol for "never ends". Let us fix this:

Train Stop ends when the time since Train Stop began is 3 minutes.

Note the useful value "time since Train Stop began":

time since (scene) begantime

This phrase produces the time since the named scene began, which only makes sense, of course, if it has indeed begun. Example:

time since Entire Game began
time since (scene) endedtime

This phrase produces the time since the named scene ended, which only makes sense, of course, if it has indeed ended. Example:

time since Formal Dinner ended

The actual times, in case they are needed, can be obtained with:

time when (scene) begantime

This phrase produces the time (i.e., the value of the "time of day" variable) at the moment when the given scene began.

time when (scene) endedtime

This phrase produces the time (i.e., the value of the "time of day" variable) at the moment when the given scene ended.

The testing command SCENES causes Inform to monitor the beginning and ending of scenes, and report on them. For instance:

>ask monk about lodging
"Welcome a poor traveler for the night?" you ask, rubbing your fingers together to restore a little feeling.
The monk looks you up and down for a moment and you sense his reaction hanging in the balance; then he slaps you on the back, hard enough to drive the air from your lungs. "In."
[Scene 'Greeting' ends]
The monk takes your elbow and pushes you imperiously toward dinner.
[Scene 'Banquet' begins]

Example

156.
The railway-station examples so far put together into a short game called "Age of Steam".

Scenes are not only useful for changing the setting, by moving items or people around and providing a little narration. We can also make the rules different in one scene from another. For instance, at a sleepy country halt there is no reason why one should not walk across the tracks: but if there is a train in the way, that would be impossible.

Before going north during the Train Stop, say "The train blocks your way." instead.

Any rule can have the clause "during …" attached, provided that clause goes at the end and either explicitly names a scene, or gives a description of which scenes would match. This is especially useful with "every turn":

Every turn during the Train Stop, say "Water is sluiced out of the tank and into the engine."

We can test whether a scene is happening with the adjective "happening":

if Train Stop is happening, ...
if (scene) has happened:

This condition is true if the given scene has both begun and ended.

if (scene) has not happened:

This condition is true if the given scene has not ended (or never started).

if (scene) has ended:

This condition is true if the given scene ended at least once.

if (scene) has not ended:

This condition is true if the given scene has never ended.

We need to be a bit careful: it's possible to set things up so that the Train Stop scene will play out more than once, so "Train Stop is happening" and "Train Stop has happened" might both be true at once.

The kind of value "scene" is one which is allowed to have properties – it has a tick in the "properties" column in the chart in the Kinds index – and this can be very useful in describing scenes. For instance, we could write:

A scene can be thrilling or dull. Train Stop is dull.
A scene has a text called cue speech. The cue speech of Train Stop is "All aboard!".

Inform has the adjectives "recurring", "non-recurring" and "happening" all built in to describe scenes, and the above would add "thrilling" and "dull". Moreover, the "during" clause of a rule can give a description of a scene as easily as a specific scene name. For instance:

Before going north during a dull non-recurring scene, ...

Examples

157.
Random atmospheric events which last the duration of a scene.
We'll be back in just a moment, with more exciting adventures of the… Space Patrol!
Creating a category of scenes that restrict the player's behavior.
160.
Day One ★★★
A scene which plays through a series of events in order, then ends when the list of events is exhausted.

Let us suppose that somebody gets off the train, after all, so that a second scene follows on.

Brief Encounter is a scene. Brief Encounter begins when Train Stop ends.

The effect of this is that they occur in sequence. If we add a third to the chain of scenes:

Village Exploration is a scene. Village Exploration begins when Brief Encounter ends.

…we find another chance to fool ourselves: if we check the Scenes index again, we can see the linkages between these scenes, but we also see that Brief Encounter never ends (despite its name). All we have said is that another scene begins where Brief Encounter leaves off, but it never does, so this is moot.

Example

161.
Pine 2 ★★★
Pine: Adding a conversation with the princess, in which a basic set of facts must be covered before the scene is allowed to end.

We are allowed to link the beginning or end of any scene to the beginning or end of any other scene. So, for instance:

Luggage Trouble is a scene. Luggage Trouble begins when Brief Encounter begins.

Thus the two scenes run concurrently, at least for a while. We can also add that:

Luggage Trouble ends when Brief Encounter ends.

This can be useful when a large, complicated scene really contains several smaller sub-scenes.

A special exceptional case is that we can have any scene or scenes starting right at the outset:

Railway Meeting is a scene. Railway Meeting begins when play begins.

When play ends, of course, all scenes end, so there is no need to say that.

Examples

Scenes used to provide pacing while the player goes through his possessions.
163.
Entrevaux ★★★
Organizing the game by scenes, where each scene has a location and prop lists so that it can be set up automatically.

It is quite allowed for a scene to be linked to several other scenes, and this is useful if several alternate strands of plot are being brought together in a common resolution scene:

Bittersweet Ending begins when Stranger's Rejection ends.
Bittersweet Ending begins when Stranger's Acceptance ends.

and we can also have the same scene beginning when a condition holds. In general, it will begin the first time it gets any chance to do so.

All scenes are ordinarily set up so that they can happen only once. But sometimes we want them to repeat. Suppose the train calls not once only, but every twenty minutes. We could set this up with two scenes linked back to back like so:

Train Stop is a recurring scene. Train Wait is a recurring scene.
Train Wait begins when play begins.
Train Stop begins when Train Wait ends.
Train Wait begins when Train Stop ends.

The difference here is that these scenes have been declared as "recurring". In all other respects they are the same as any other scene.

Examples

Cycling through a sequence of scenes to represent day and night following one another during a game.
165.
Pine 3 ★★★
Pine: Allowing the player to visit aspects of the past in memory and describe these events to the princess, as a break from the marriage-proposal scene.

Interactive fictions vary considerably in the extent to which the player is allowed to influence the story-line. Sometimes the appearance of making choices is wholly bogus, as only one possible line is given more than lip service. But in other works, the player can radically change the outcome, and whole rafts of plot differ between one person's experience and another's. Inform allows multiple endings to its scenes to make this kind of branching story-line easy to achieve.

Any scene can have up to 31 alternate endings, differentiated by name (unless the Z-machine format has been selected on the Settings panel, in which case, 15). These alternates are created as and when conditions are set for them:

Brief Encounter ends happily when ...
Brief Encounter ends wisely but sadly when ...

"Ends happily" and "ends wisely but sadly" behave just like "ends". We can have rules "When Brief Encounter ends happily, …" and so forth, in addition to rules "When Brief Encounter ends, …" – if a rule doesn't specify any particular ending, it applies to all of them.

We can also link rules together from these branches, so

Stranger's Acceptance begins when Brief Encounter ends happily.
Stranger's Rejection begins when Brief Encounter ends wisely but sadly.

With this set-up and that of the previous section, there are now two possible paths through the story:

(i) Train Stop - Brief Encounter - Stranger's Acceptance - Bittersweet Ending
(ii) Train Stop - Brief Encounter - Stranger's Rejection - Bittersweet Ending

We might later need to know which of these paths has been taken, and to help with this Inform provides conditions like so:

if Brief Encounter ended happily ...
if Brief Encounter did not end happily ...
if Brief Encounter ended wisely but sadly ...
if Brief Encounter did not end wisely but sadly ...

(For a scene which repeats, note that these conditions apply only to the most recent repetition: and that such conditions are always false if the scene is currently going on. "Brief Encounter did not end happily" will be true only when the scene has finished but in a different way.)

Examples

166.
Panache ★★★
Replacing the score with a plot summary that records the events of the plot, scene by scene.
167.
Pine 4 ★★★
Pine: Adding a flashback scene that, instead of repeating endlessly, repeats only until the Princess has understood the point.

In the part it plays in stories, time is like space. The endings of a scene (along with its beginning) are like the map connections leading out of a room. The Scenes index keeps track of the "map of time" through which these possible story-lines traverse. Some works of IF will have immensely complicated story-lines in only a few rooms, some will have no scenes at all despite a sprawling geography. The Scenes and World index tabs, side by side, show both kinds of map.

Just as Inform uses a simple but practical design for the boundaries between rooms (map connections and doors, that is), it also simplifies transitions between scenes. Scenes are based on states of things: we give circumstances for them to begin or end. There is no phrase with the power to say "make Act II begin right now", so perhaps it is worth explaining why not. The state-based approach was chosen because:

* it guarantees that each action falls entirely inside, or entirely outside, of any given scene (and therefore that "during..." clauses in the conditions for a rule are not affected by rule ordering);
* it ensures that scene changes occur outside actions, like every turn rules;
* it promotes a style of writing which makes it clearer to the reader of the source text when a scene begins and ends, and what conditions are guaranteed to be true during it;
* it makes it possible for the Scenes index page to show this information in a communicative way.

Settings in IF where one revisits the same location but at a different time, or after a dramatic change, have historically been difficult to test properly and prone to mistakes. (The classic example would be where a character killed during Act I reappears unharmed in Act II.) The design of scenes is an attempt to encourage a style of writing which minimises the risk of these accidents.

Since scenes are, in the end, only a convenient way to organise rules, and do nothing that cannot be done by other means, this simplified system of scene changing does not really restrict us.

Example

168.
Cheese-makers ★★★
Scenes used to control the way a character reacts to conversation and comments, using a TALK TO command.

11. Phrases

Phrases are instructions to Inform to do something, or to decide whether something is true or false, or to produce a value, or to say something. Inform has around 350 phrases built-in, and the chapters so far have already defined about 100 of those. In this chapter we'll see some key phrases for organising instructions of what to do, and also see how to define entirely new phrases.

Just to run through the four sorts of phrase with examples:

(a) Phrases to do something. These are the ones used in the body of a rule. For example,

When Train Stop begins:
   move the Flying Scotsman to the Station;
   say "The Flying Scotsman pulls up at the platform."

Rules like this begin with a "preamble", the beginning part which tells Inform when or how they apply, and then follow on with a list of instructions – here, just two of them. "move … to …" and "say …" are both phrases. Inform provides about 130 of these built-in. It's actually not quite true that they all do something, because one of them is:

do nothing

This phrase does nothing at all. It is very occasionally useful to make a rule which does nothing:

This is the largely ineffective rule:
   do nothing.

(b) Phrases to decide whether a condition is true. These are the ones which can be used in an "if":

if action requires light: ...

Not all conditions come from phrases. For example, "if the front door is closed" and "if Peter is wearing the sandals" have meanings which come from the verbs "to be" and "to wear". Inform provides about 60 built-in conditions, which give a friendly wording for questions which would be lengthy or difficult to write in any other way.

(c) Phrases to decide a value. For example:

square root of 16

produces a number, 4 of course, and can be used whenever a number is expected. Inform provides about 100 built-in phrases like this.

(d) Text substitutions. These are actually just phrases whose definition begins with "To say …". Example:

"It's now [time of day in words]."

Inform provides about 60 built-in text substitutions.

The Phrasebook is Inform's collection of recognised phrases, and it can always be browsed using the Index panel of the same name. Even the smallest project has a good-sized phrasebook, since it contains all of the built-in phrases. But most projects also define new phrases of their own.

Here is a simple definition of a new phrase:

To spring the trap:
   say "'Sproing!' go the hinges and, with a flash of silver, the enormous blades whisk together!";
   end the story.

Inform allows us to use whatever conventions of layout we prefer, but it's customary to use indentation like this, dividing off the preamble from the phrases which follow. As can be seen, definitions of new phrases look very like rules.

What makes this definition a simple one is that the wording is fixed. The only way to use this would be from another phrase or rule, like so:

Instead of entering the cage:
   spring the trap.

In the next section we'll see how to give more complicated definitions which, like "move … to …", allow for the wording to change with the circumstances.

In this section, let's make the following new phrase:

To admire (item - an object):
   say "You take a long look at [item].".

This does very little, of course, but it does allow the wording to be different each time the phrase is used:

admire the diamonds;
admire Mr Cogito;
admire the honey sandwich;

and our single definition covers all of these possibilities. The bracketed part of the definition, "(item – an object)", tells Inform to expect an object in that position, and Inform enforces this carefully. So this definition might tell Inform what "admire the barricade" means, but not what

admire "blue cheese";
admire 63;

mean. Unless some other definition sorts the matter out, Inform will reply to uses like this with a Problem message:

Problem. You wrote 'admire 63' , but '63' has the wrong kind of value: a number rather than an object.

The object does not need to be named literally, but can be anything which works out to be an object: for instance,

After dropping something in the Auction House:
   admire the noun.

which Inform allows because "noun", here, is a name for the object which is being acted on.

Inform decides which definition to apply in a process called "pattern matching".

The bracketed part of the example definition has the form "(name – kind)". The definition only applies if the text supplied agrees with the "kind" part – for instance, the diamonds agreed with "object", but 63 did not. If the definition does apply, then the Inform works through the rest of the phrase using "name" to mean whatever value matched. For example:

To slam shut (box - an open container):
   say "With great panache, you slam shut [the box].";
   now the box is closed.

When this phrase is followed, "box" means whatever open container the pattern-matcher found when it was called for. For example, if Inform reads

slam shut the Dutch armoire;

then it acts on this by following the definition of "slam shut …", using the Dutch armoire object as the value of "box", so it prints:

With great panache, you slam shut the Dutch armoire.

and renders it closed.

In fact any description can be given in the definition, and that includes a single, specific value. For instance, we could define:

To grant (bonus - a number) points:
   increase the score by the bonus.
To grant (bonus - 7) points:
   say "You shiver uncontrollably."

which would withhold this unlucky bounty. That would mean that:

grant 7 points;
grant seven points;

would each produce uncontrollable shivers, because Inform uses the definition applying to the number 7; but

grant six points;

would increase the score by 6. In general Inform always follows the principle that more specific definitions take priority over more general ones. So although the definitions:

To grant (bonus - a number) points: ...
To grant (bonus - 7) points: ...

both apply to the case of "grant 7 points", Inform uses the second, because it's the more specific of the two possibilities.

Sometimes it will not be possible to tell if the value supplied meets the requirements until the story is actually playing. If, at run-time, no definition fits some phrase which has to be carried out, a run-time problem message is produced.

Finally, and more straightforwardly, we can specify variations in wording using slashes between alternative words in a "To …" definition. For instance:

To grant (bonus - a number) point/points: ...

allows the final word to be either "point" or "points". Slashes like this can only be used with literal words, not bracketed values, and give alternative forms only of a single word at a time; the alternative "--" means "no word at all", and thus makes it optional:

To grant (bonus - a number) point/points/--: ...

makes "grant 3" do the same as "grant 3 points".

If we need more variation than that, we should make more than one definition.

Examples

169.
Ahem
Writing a phrase, with several variant forms, whose function is to follow a rule several times.
170.
Using the same phrase to produce different results with different characters.

We've already seen the SHOWME command, which can be typed into the Story panel to look at the state of something, usually a thing or room. SHOWME is a testing command which has no effect once the work is released; eventual players can't use it.

Inform also has a phrase called "showme", which works in much the same way:

showme (value)

This phrase is intended for testing purposes only. If used in a story file running inside the Inform application, it prints a line of text showing the given value and its kind; in a Released story file, it does nothing at all. Example:

When play begins: showme 11.

produces

number: 11

More usefully:

Every turn: showme the score.

Now, every turn, we get a line in the story's transcript like so:

"score" = number: 0

Inform uses the quotation marks and equals sign to show that it had to do some work to find the answer. "score" wasn't a constant value – it was a variable, and Inform had to look up the current value.

"showme" is a convenient way to see what's going on inside a phrase which isn't behaving as expected, or to find out the kind of a value. Here are some trickier examples. Suppose our design includes:

The matching key of the blue door is the brass Yale key.

If we then try this:

When play begins:
   showme matching key of the blue door.

we get, when the story starts up,

"matching key of the blue door" = object: brass Yale key

Why is this an "object", when we know that the key is actually a "thing"? After all, if we "showme key" instead, we get:

thing: brass Yale key

The answer is a little technical: it's because Inform guarantees that the matching key is always an object, but not that it's always a thing – it just happens to be a thing at the moment. There's not really a contradiction, because a "thing" is a kind of "object", so in fact the key is both. If we try "showme matching key", we get something like this:

objects valued property: property 23

which is even more technical – people never need to print the names of abstract property names during play, so Inform doesn't provide any good way of doing it. It is reduced to printing out an internal ID number ("property 23") instead of the name ("matching key"). This can't be helped: "showme" is a way to lift the lid and see what's going on inside Inform's machinery, and some of the corners are dark.

All the same, "showme" can be very useful in tinkering with rules to make them work properly. It prints nothing at all in a Release version of a project, so it's impossible for these private notes to be shown accidentally to our eventual readers.

A variety of "conditions" have already appeared in this documentation. A condition is a phrase which describes a situation which might be true, or might be false, and examples might include:

Mr Kite is in Bishopsgate
the score is greater than 10
Sherlock Holmes suspects a woman

These are all examples of sentences, formed by putting nouns either side of a verb, and clearly a wide range of conditions can be written this way. But there are also a few special conditions built into Inform which have a fixed wording, and test questions difficult to address with ordinary sentences. For instance:

if in darkness:

This condition is true if the player currently has no light to see by. Note that the test is more complicated than simply testing

if the player is in a dark room, ...

since the player might have a torch, or be inside a cage which is itself in a dark room, and so on.

Another example of a condition not easily written as a sentence is:

if player consents:

This condition is unusual in doing something and not simply making a silent check: it waits for the player to type YES (or Y) or NO (or N) at the keyboard, and then is true if the answer was yes. Example:

say "Are you quite sure you want to kiss the Queen? ";
if the player consents:
   ...

Whether it's put to the player like this or not, testing a condition is really asking a question, and there is always a yes/no answer. In Inform this answer is not usually a value (unlike in some other computer programming languages), but it can be made into one.

Firstly, we need a special kind of value to hold answers like this. It's called "truth state", and it has just two possible values, written as "true" and "false". We then need:

whether or not (a condition)truth state

This phrase converts a condition into its result as a value, which is always either "true" or "false". Example:

whether or not 20 is an odd number

produces the truth state "false". This is mostly useful for storing up results to look at later:

let victory be whether or not all the treasures are in the cabinet;

and then subsequently:

if victory is true, ...

As another example, in most stories this:

When play begins:
   showme whether or not in darkness.

…will produce a line:

"whether or not in darkness" = truth state: false

In short, "truth state" is a kind of value like any other. That means it can be the kind of a variable:

Salvation earned is a truth state that varies.

and it can similarly be used in table columns, lists, or anywhere else where values are allowed.

Example

171.
Proposal ★★
Asking the player a yes/no question which he must answer, and another which he may answer or not as he chooses.

Inform's most powerful phrases are those which control the others, making them repeat, or be skipped.

if (a condition) , (a phrase)
or…
if (a condition):

This phrase causes the single phrase, or block of phrases, following it to be obeyed only if the condition is true. (If the condition must contain a comma for some reason, the block form should be used.) Example:

if the red door is open, say "You could try going east?"

The sense of an "if" can be reversed by using the word "unless" instead:

unless (a condition) , (a phrase)
or…
unless (a condition):

This phrase causes the single phrase, or block of phrases, following it to be obeyed only if the condition is false. (If the condition must contain a comma for some reason, the block form should be used.) Example:

unless the red door is closed, say "You could try going east?"

"Unless" is clearly unnecessary, but it can be a good way to make the source text easier for humans to read.

As we have seen, there are many different forms of condition in Inform. They usually take a form quite like an assertion sentence, except that they're questions and not statements of fact. For example:

if the score is 10, ...
if all of the people are in the Atrium, ...

Questions like this are checked by Inform to see if they make sense. The following doesn't, for instance:

if 10 is a door, say "Huzzah!";

This produces the baffled reply:

Problem. In the line 'if 10 is a door, say "Huzzah!"' , I can't determine whether or not '10 is a door', because it seems to ask if a number is some sort of door.

In practice it is not enough to apply "if" to a single phrase alone: we want to give a whole list of phrases to be followed repeatedly, or to be followed only if a condition holds.

We do this by grouping them together, and there are two ways to do this. One is as follows:

To comment upon (whatever - a thing):
   if whatever is transparent, say "I see right through this!";
   if whatever is an open door:
      say "Oh look, an open door!";
      if whatever is openable, say "But you could always shut it."

Here we group two phrases together under the same "if". Note that the comma has been replaced by a colon, and that the indentation in the list of phrases shows how they are grouped together. In the example above, the source moves two tabs in from the margin; the maximum allowed is 25.

Indentation is the convention used in this manual and in the examples, but not everybody likes this Pythonesque syntax. So Inform also recognises a more explicit form, in which the beginning and ending are marked with the words "begin" and "end":

To comment upon (whatever - a thing):
   if whatever is transparent, say "I see right through this!";
   if whatever is an open door
   begin;
      say "Oh look, an open door!";
      if whatever is openable, say "But you could always shut it.";
   end if.

(Pythonesque because it's a style popularised by the programming language Python, named in turn after "Monty Python's Flying Circus".)

Examples

172.
A SEARCH [room] action that will open every container the player can see, stopping only when there don't remain any that are closed, unlocked, and openable.
The player is unable to sleep on a mattress (or stack of mattresses) because the bottom one has something uncomfortable under it.

We often need code which does one thing in one circumstance, and another the rest of the time. We could do this like so:

if N is 2:
   ...
if N is not 2:
   ...

but this is not very elegant, and besides, what if the action we take when N is 2 changes N so that it becomes something else?

Instead we use "otherwise":

otherwise if (a condition)
or…
otherwise unless (a condition)
or…
otherwise (a phrase)
or…
else if (a condition)
or…
else unless (a condition)
or…
else (a phrase)

This phrase can only be used as part of an "if …:" or "unless: …", and provides an alternative block of phrases to follow if the first block isn't followed. Example:

if N is 2:
   ...
otherwise:
   ...

When there is only a single phrase we can use the shortened form:

if N is 2, say "Hooray, N is 2!";
otherwise say "Boo, N is not 2...";

We can also supply an alternative condition:

if N is 1:
   ...
otherwise if N is 2:
   ...
otherwise if N is greater than 4:
   ...

At most one of the "…" clauses is ever reached – the first which works out.

If the chain of conditions being tried consists of checking the same value over and over, we can use a convenient abbreviated form:

if (value) is:

This phrase switches between a variety of possible blocks of phrases to follow, depending on the value given. Example:

if the dangerous item is:
   -- the electric hairbrush:
      say "Mind your head.";
   -- the silver spoon:
      say "Steer clear of the cutlery drawer."

One alternative is allowed to be "otherwise", which is used only if none of the other cases apply, and which therefore guarantees that in any situation exactly one of the blocks will be followed.

if N is:
   -- 1: say "1.";
   -- 2: say "2.";
   -- otherwise: say "Neither 1 nor 2.";

This form of "if" layout is not allowed to use "begin" and "end" instead of indentation: it would look too messy, and would scarcely be an abbreviation. It is also not allowed to use "unless" instead of "if", because the result would be too tangled to follow.

Example

174.
A simple exercise in printing the names of random numbers, comparing the use of "otherwise if…", a switch statement, or a table-based alternative.

The next control phrase is "while", which has the form:

while (a condition):

This phrase causes the block of phrases following it to be repeated over and over for as long the condition is true. If it isn't even true the first time, the block is skipped over and nothing happens. Example:

while someone (called the victim) is in the Crypt:
   say "A bolt of lightning strikes [the victim]!";
   now the victim is in the Afterlife;

We must be careful not to commit mistakes like the following:

while eggs is eggs:
   say "again and ";

which, as sure as eggs is eggs (which is very sure indeed), writes out

again and again and again and again and again and ...

forever. (Inform won't prevent this: we will find out the hard way when the story is played.) While we would probably never write anything so blatant as that, the mistake is all too easy to commit in disguised form. We should never design a loop, as repetitions like this are called, without worrying about if and when it will finish.

As with "if", we can use "begin" and "end" instead of a tabulated layout if we want to --

while ...
begin;
   ...
end while.

(The "begin" of an "if" must of course match an "end if", not an "end while", and so on.)

Experience shows that it is much more legible to lay out "while" loops as blocks, even in these rare cases when only a single phrase forms the body of the block.

The other kind of loop in Inform is "repeat". The trouble with "while" is that it's not obvious at a glance when or whether the loop will finish, and nor is there any book-keeping to measure progress. A "repeat" loop is much more predictable, and is more or less certain to finish.

There are several forms of "repeat", of which the simplest is similar to the old FOR/NEXT loop from the home-computer programming language BASIC, for those with long memories:

repeat with (a name not so far used) running from (arithmetic value) to (arithmetic value)
or…
repeat with (a name not so far used) running from (enumerated value) to (enumerated value):

This phrase causes the block of phrases following it to be repeated once for each value in the given range, storing that value in the named variable. (The variable exists only temporarily, within the repetition.) Example:

repeat with counter running from 1 to 10:
   ...

This, and runs through the given phrases ten times. Within those phrases, a special value called "counter" has the value 1 the first time through, then the value 2, then 3 and so on up to 10. (It can of course be called whatever we like: this is only an example.) The range can be from any kind where ranges make sense – anything on which arithmetic can be done, so for instance

repeat with moment running from 4 PM to 4:07 PM:
   ...

and also any enumeration:

Colour is a kind of value. The colours are red, orange, yellow, green, blue, indigo and violet.
...
   repeat with hue running from orange to indigo:
      ...

We are allowed to "nest" loops, that is, to put one inside another.

To plot a grid with size (S - a number):
   repeat with x running from 1 to S:
      say "Row [x]:";
      repeat with y running from 1 to S:
         say " [y]";
      say "."

If we then write

plot a grid with size 5;

then the result is

Row 1: 1 2 3 4 5.
Row 2: 1 2 3 4 5.
Row 3: 1 2 3 4 5.
Row 4: 1 2 3 4 5.
Row 5: 1 2 3 4 5.

Thus the innermost phrase, the say which mentions "y", happens 25 times.

Whenever dealing with numbers in Inform we may need to remember that if the Settings for the project are set to use the Z-machine, the range is restricted to -32768 up to 32767. Repeating with a counter up to exactly 32767 is hazardous, because the counter can never break through this barrier: it's infinity, so far as Inform is concerned, and that can cause the repetitions to go on forever. (On Glulx, numbers can be very much larger.)

Example

A lottery drum which redistributes the tickets inside whenever the player spins it.

Inform is not used very much for numerical work, so the kind of repeat loop described in the previous section is not much used. Inform's natural domain is really the world of things and rooms, so the following kind of repeat is much more useful.

repeat with (a name not so far used) running through (description of values):

This phrase causes the block of phrases following it to be repeated once for each value matching the description, storing that value in the named variable. (The variable exists only temporarily, within the repetition.) Example:

repeat with item running through open containers:
   ...

If there are no containers, or they are all closed, the phrases will not be followed at all. Inform will issue a Problem message if the range of the loop may be infinite: for example, it won't allow:

repeat with X running through odd numbers:
   ...

On the other hand it will allow:

repeat with T running through times:
   ...

which repeats 1440 times, starting with T at midnight and finishing at 11:59 PM. See the Kinds index for which kinds of value can be repeated through.

As with counting the "number of …" objects satisfying some property, we can run through a wide variety of possibilities – any description whose range is possible for Inform to search. For example:

repeat with dinner guest running through the people in the Dining Room:
   ...
repeat with possession running through things carried:
   ...
repeat with event running through non-recurring scenes which are happening:
   ...

The following lists the whereabouts of all men in lighted rooms:

repeat with suspect running through the men who are in a lighted room:
   say "[The suspect] is in [the location of the suspect].";

One small note of caution: if what the "repeat" loop does is to change the things being repeated through, changing in particular whether items not yet reached will qualify to be repeated through, the results can be unexpected. Rather than writing "repeat with X running through D", it may be safer to try "while there is D (called X)", though note that this will only finish if X is always changed so that it no longer qualifies.

Example

People who select partners for dance lessons each turn.

So "repeat" and "while" phrases cause a block of other phrases to be repeated, over and over. The number of repetitions and the flow of "control" has so far been controlled only by the way the original loop was described.

But in fact it's also possible to change this from inside the block being repeated, using these:

next

This phrase can only be used inside a "repeat" or "while" block, and causes the current repetition of the block to finish immediately. That either means the next repetition begins, or (if we are already at the last one) the loop ends too. Example:

repeat with X running from 1 to 10:
   if X is 4, next;
   say "[X] ".

produces the text "1 2 3 5 6 7 8 9 10 ", with no "4" because the "say" phrase was never reached on the fourth repetition.

In Monopoly terms, "next" is "Advance to Go" rather than "go directly, do not pass Go, do not collect $200" – the next iteration begins with the variable, if there is one, having cleanly moved on to the next value, just as if the loop had been run through in the normal way. ("Next" is called "continue" in a fair number of programming languages, so Inform issues a specific problem message to help people who forget this.)

break

This phrase can only be used inside "repeat", "while" block, and causes both the current repetition and the entire loop to finish immediately. Example:

repeat with X running from 1 to 10:
   if X is 7, break;
   say "[X] ".

produces the text "1 2 3 4 5 6 ", with nothing after "6" because the loop was broken at that point. The "say" wasn't reached on the 7th repetition, and the 8th, 9th and 10th never happened.

Now that it's possible to define phrases where different things are done in different circumstances, we sometimes want to halt early. This is what "stop" is for.

stop

This phrase causes the current rule to end immediately. It is most often used in the definition of other phrases:

To judge the score:
   if the score is 0, stop;
   say "The score is [score in words] more than it was a half-hour ago."

In the case when the score is 0, the "stop" ends the phrase immediately, so that the subsequent text is printed only if the score is not 0.

"Stop" can also be used in action rules, though this is not very good style – it's clearer to use "stop the action", which is exactly equivalent.

There are sometimes several slightly different ways to perform a given task but which have substantially the same definition. In the following example:

To go hiking, into the woods or up the mountain:
   if into the woods, say "Watch out for badgers.";
   if up the mountain, say "Better take your compass.";
   say "You go hiking."

…a phrase has been set up which can be used in three ways:

go hiking;
go hiking, into the woods;
go hiking, up the mountain;

Note that commas must be used to divide these "phrase options" from the rest of the text of the phrase. Within the definition of the phrase, the option's name is a valid condition, and

if up the mountain, ...

tests whether it is set; we can also test if it is not set using:

if not up the mountain, ...

A more substantial example from the Standard Rules is given by a phrase used mostly for internal, technical reasons:

list the contents of (object)

This phrase produces a list of all things whose holder is the given object, according to Inform's traditional conventions for room descriptions and inventory listings. Example:

list the contents of Marley Wood, as a sentence, with newlines
and including all contents;

Where this is possible, it's generally better to use "[list of things in …]" instead, which produces the same result in an acceptable way for the middle of a sentence.

Note that this phrase is allowed to have multiple options specified, whereas "go hiking" above was not: this is because it was defined thus:

To list the contents of (something - an object), with newlines, indented, as a sentence, including contents, including all contents, giving inventory information, giving brief inventory information, using the definite article, listing marked items only, prefacing with is/are, not listing concealed items, suppressing all articles and/or with extra indentation: ...

The significant difference is the word "and/or" instead of "or", which signals that more than one option can apply at a time.

Example

177.
Overview of all the phrase options associated with listing, and examples of how to change the inventory list into some other standard formats.

A variable, as we have seen, is a name for a value which changes, though always remaining of the same kind. For instance, if "target" is a number variable (or "number that varies") then it may change value from 2 to 4, but not from 2 to "fishknife".

To make complicated decisions, phrases often need to remember values on a temporary basis. We have already seen this for the counter in a "repeat" loop, which exists only inside that loop, and then is no longer needed.

We can also make temporary variables using "let":

let (a name not so far used) be (value)
or…
let (a temporary named value) be (value)

This phrase creates a new temporary variable, starting it with the value supplied. The variable lasts only for the present block of phrases, which certainly means that it lasts only for the current rule. Examples:

let outer bull be 25;
let the current appearance be "reddish brown";
let the special room be Marley Wood;

The kinds of these are deduced from the values given, so that, for instance,

say "The outer bull scores [the outer bull in words] when you practice archery in [special room]."

produces

The outer bull scores twenty-five when you practice archery in Marley Wood.

The variable name should be a new one; if it's the name of an existing one, then the kinds must agree. So:

let outer bull be 25;
let outer bull be 50;

is a legal combination, because the second "let" simply changes the value of the existing "outer bull" variable to a different number.

let (a name not so far used) be (name of kind)

This phrase creates a new temporary variable of the given kind. The variable lasts only for the present block of phrases, which certainly means that it lasts only for the current rule. Example:

let inner bull be a number;

The variable created holding the default value for that kind – in this case, the number 0. A handful of very obscure kinds have no default values, and then a problem message is produced. Inform also disallows:

let the conveyance be a vehicle;

because temporary variables aren't allowed to have kinds more specific than "object". (This is a good thing: suppose there are no vehicles in the world?) It's quite safe in such cases to use

let the conveyance be an object;

instead, which creates it as the special object value "nothing".

Temporary variables made by "let" are only temporarily in existence while a phrase is being carried out. Their values often change: we could say

let x be 10;
now x is 11;

for instance, or indeed we could "let x be 10" and then "let x be 11". But although we are allowed to change the value, we are not allowed to change the kind of value. The name "x" must always have the same kind of value throughout the phrase to which it belongs, so the following will not be allowed:

let x be 45;
now x is "Norway";

(The difference between using "let" and "now" here is that "let" can create a new temporary variable, whereas "now" can only alter things already existing: on the other hand, "now" can change many other things as well, whereas "let" applies only to temporary variables.)

Example

Three basic ways to inject random or not-so-random variations into text.

We can create new conditions by defining a phrase with "to decide whether" (or equivalently "to decide if"):

To decide whether danger lurks:
   if in darkness, decide yes;
   if the Control Room has been visited, decide no;
   decide yes.

If the player is indeed in darkness, the decision is "yes" because the "decide yes" stops the process right there. We can now write, for instance,

if danger lurks, ...

In fact, "danger lurks" is now a condition as good as any other, and can be used wherever a condition would be given. Rules can apply only "when danger lurks", for instance.

yes
or…
decide yes

This phrase can only be used in the definition of a phrase to decide whether a condition holds. It ends the decision process immediately and makes the condition true.

no
or…
decide no

This phrase can only be used in the definition of a phrase to decide whether a condition holds. It ends the decision process immediately and makes the condition false.

We can also supply definitions of adjectives like this. So far, new adjectives have been defined like so:

Definition: a supporter is occupied if it is described and something is on it.

If we want to give a definition which involves more complex logic, we can use a special form allowing us to make arbitrary decisions. In this longer format, the same definition would look like so:

Definition: a supporter is occupied:
   if it is undescribed, decide no;
   if something is on it, decide yes;
   decide no.

Here "it" refers to the supporter in question. Note that there are now two colons in this sentence, one after "Definition", the other after the clause being defined. But that apart, it's a phrase like any other: it must end in "yes" or "no" just as the "danger lurks" example must. "Decide no" and "decide yes" are needed so often that they can be abbreviated by leaving out "decide":

Definition: a supporter is occupied:
   if it is undescribed, no;
   if something is on it, yes;
   no.

Example

179.
Owen's Law ★★★
OUT always means "move to an outdoors room, or else to a room with more exits than this one has"; IN always means the opposite.

A condition is a yes/no decision, but we can also take decisions where the result is a value. Suppose we want to create a concept of the "grand prize", which will have different values at different times in play. Each time the "grand prize" is referred to, Inform will have to decide what its value is, and the following tells Inform how to make that decision:

To decide which treasure is the grand prize:
   if the Dark Room has been visited, decide on the silver bars;
   decide on the plover's egg.

Note that we have to say what kind the answer will be: here it's a kind of thing called "treasure" (which we're supposing has already been created), and as it turns out only two treasures are ever eligible anyway (we're also supposing that the plover's egg and the silver bars are treasures already created, of course). And note also that the phrase must in all cases end with a "decide on …" to say what the answer is:

decide on (value)

This phrase can only be used in the body of a definition of a phrase to decide a value. It causes the calculation to end immediately, with the outcome being the given value, which must be of the kind expected. Example:

To decide which number is double (N - a number):
   let D be N times N;
   decide on D.

Now that we have "grand prize" created, we can use it just as we would use any other value, so for instance:

if taking the grand prize, ...

As this is something of a dialect difference between English speakers, "what" and "which" are synonymous here, i.e., we could equally well write something like:

To decide what number is the target score: ...

(A phrase to decide if something-or-other is exactly the same thing as a phrase to decide a truth state, and indeed, if we want to then we can use "decide on T", where T is a truth state, in its definition. For instance:

To decide if time is short:
   if the time of day is after 10 PM, decide on true;
   ...
   decide on whether or not Jennifer is hurried.

"Decide on true" is exactly equivalent to the more normally used "decide yes", and of course it is optional. The last line is more interesting since it effectively delegates the answer to another condition.)

Examples

180.
A piece of ghost-hunting equipment that responds depending on whether or not the meter is on and a ghost is visible or touchable from the current location.
181.
Windows overlooking lower spaces which will prevent the player from climbing through if the lower space is too far below.

A point which has come up several times in recent chapters is that enumerated kinds of value have a natural ordering. For example, if we write:

Colour is a kind of value. The colours are red, orange, yellow, green, blue, indigo and violet.

…then we not only have seven possible values, we have put them into a sequence, in order of their naming. We can't perform arithmetic on colours, of course, but we can perform comparisons on them. Thus "red < yellow" is true, while "green >= violet" is not. (More on comparisons in the chapter on Numbers and Equations, which also covers arithmetic.)

It's also sometimes useful to get at the sequence directly. First, the two ends:

first value of (name of kind)value

This phrase produces the first-created value of the given kind, which should be an enumeration. Example: if we have

Colour is a kind of value. The colours are red, orange, yellow, green, blue, indigo and violet.

then "first value of colour" is red.

last value of (name of kind)value

This phrase produces the last-created value of the given kind, which should be an enumeration. Example: if we have

Colour is a kind of value. The colours are red, orange, yellow, green, blue, indigo and violet.

then "last value of colour" is violet.

And now how to step forward and back:

(name of kind) after (enumerated value)value

This phrase produces the next-created value of the given kind, which should be an enumeration. Example: if we have

Colour is a kind of value. The colours are red, orange, yellow, green, blue, indigo and violet.

then "colour after orange" is yellow.

(name of kind) before (enumerated value)value

This phrase produces the previous-created value of the given kind, which should be an enumeration. Example: if we have

Colour is a kind of value. The colours are red, orange, yellow, green, blue, indigo and violet.

then "colour before blue" is green.

Examples

182.
All objects in the game have a heat, but if not kept insulated they will tend toward room temperature (and at a somewhat exaggerated rate).
183.
Turns take a quarter day each, and the game rotates through the days of the week.

12. Advanced Actions

Actions are impulses to do something, which arise sometimes through typed commands:

>examine tapestry

and sometimes through "try" phrases occurring in other rules:

Before examining the tapestry, try switching the ultraviolet light on.

Every action either succeeds or fails, though failure may not be a bad thing (something better may have happened). Besides any rules applied in the source text, actions are subject to basic realism rules. A general rule ensures that actions are rejected if the actor would need to touch something which is out of reach, or see something which is invisible; and a couple of hundred other built-in rules police individual actions. For instance, if the ACTIONS testing command has been used to switch monitoring on, then:

>unlock cage with watermelon
[unlocking cage with watermelon]
That doesn't seem to fit the lock.
[unlocking cage with watermelon - failed the can't unlock without the correct key rule]

Actions generated by "try" phrases are allowed to run "silently", which means that if nothing out of the way happens and they succeed, then nothing is printed. For instance:

Before examining the tapestry: say "(Switching on the lamp first.)"; silently try switching the ultraviolet light on.

There are many ways to impose extra rules on actions, and we have seen three main kinds: Before rules, intended so that preliminary activities like the one above can happen before the action is tried; Instead rules, which block or divert the intention, or may cause something spectacularly different to happen; and After rules, which allow for unexpected consequences after the action has taken place.

The following flow chart shows the natural course of events when Inform deals with a new action – a "taking" action in the case drawn. For quite a long time, the action may still fail, and it may be that nothing actually happens: but eventually a deciding line is crossed, and once that happens the action will certainly succeed.

The coloured boxes on this chart represent "rulebooks", that is, collections of rules with a common purpose. The orange boxes for Before, Instead and After were covered in the Basic Actions chapter, but the blue boxes are new. The orange boxes are where we put rules to handle unusual situations, or unexpected events: special rules to cover the opening of a container which happens to be booby-trapped, or walking through a doorway into a room where a surprise party is about to be sprung.

Blue boxes hold the mundane, everyday rules – the generic ways that particular actions behave. Every action provides these: "Check" rules, to see if it makes sense – for instance, to see that the player is not trying to take his or her own body, or a whole room, or something he or she already has; then "Carry out" rules, to actually do what the action is supposed to do – in the case of taking, to move an object into the player's possession; and finally "Report" rules, which tell the player what has happened – perhaps printing up "Taken."

When we create a new action, we add a new column to the blue rows in this diagram. As we shall see, we can also put new rules into the existing blue boxes: for instance, if we wanted to increase physical realism by forbidding the player to carry more than a certain weight, we would want to add a new "check taking" rule, and this is entirely legal.

In subsequent chapters, we will see ways to intervene at almost every point in the above diagram – from how "Can we see or touch things?" is reckoned, to each and every individual rule in all of these books. Action-processing may be the single most important thing Inform does, so the system is designed to be immensely flexible. On the other hand, that does make it a lot to take in at one look. Newcomers should probably concentrate on "Instead" and "After" as the basic tools for designing the situations turning up routinely in interactive fiction. There are guidelines at the end of this chapter offering advice on which tricks to use when it comes to more complicated needs.

So far, all actions have been carried out by the player: which is fine for exploring the passive world of an empty warehouse, but less good for a drama in which other characters have to be contended with. In fact, an action can be carried out by anybody – by any instance of the "person" kind, that is, which includes all the men, women and animals in the story, and not only the player.

In interactive fiction, players conventionally ask other characters to do something with commands like so:

> will, go west

Clearly "will, go west" should not produce the same action as "go west", because a different person will be trying it: this person is called the "actor", and while the actor is ordinarily the player, here it is the character called Will. Inform distinguishes these two actions like so:

going west
asking Will to try going west

As a result, we can write rules like so:

Instead of asking Will to try going west, say "Will scratches his head, baffled by this talk of westward. Is not the ocean without bound?"

To write rules like this, we sometimes want to generalise about who is supposed to do the deed. To do this we can refer to "person asked", just as the "noun" stands for whatever noun was typed:

Instead of asking somebody to try taking something, say "I don't think we ought to tempt [the person asked] into theft, surely?"

So if the player types "Algy, take sandwich", the "person asked" would be Algy; the "noun" would be the sandwich; and there would be no "second noun".

Examples

184.
Virtue
Defining certain kinds of behavior as inappropriate, so that other characters will refuse indignantly to do any such thing.
185.
Latris Theon ★★★
A person who can accept instructions to go to new destinations and move towards them according to the most reasonable path.

"Asking … to try …" actions run through their Before and Instead rules like any other actions, but then (if no rule has intervened) something different happens: Inform has to decide whether the person asked consents to try the action or not. By default, the answer is always no, and text like the following will be printed:

> will, go west
Will has better things to do.

However, we can intervene to make the answer "yes", using a special kind of rule which produces a yes/no answer. The following examples show how we can give broad or narrow permission, as we choose:

Persuasion rule for asking people to try going: persuasion succeeds.
Persuasion rule for asking Will to try going west: persuasion succeeds.

Such a rule can either declare that "persuasion succeeds", or that "persuasion fails", or make no decision and leave it to another rule to say. If it decides that persuasion fails, it is also allowed to say something, describing why: in that event, the standard message ("Will has better things to do.") is suppressed. For example,

Persuasion rule for asking Will to try going:
   say "Will looks put out, and mutters under his breath.";
   persuasion fails.

The following rule, which is really only suitable for testing, makes everybody infinitely obliging:

Persuasion rule for asking people to try doing something: persuasion succeeds.

Supposing that Will does decide to cooperate, a new action is generated:

Will going west

and this is then subject to all of the usual action machinery. For instance, we could write a rule such as:

Instead of Will going west, say "He runs out into the waves, but soon returns, rueful."

So in this case the new action ("Will going west") failed: but the original action, "asking Will to try going west", is still deemed to have succeeded – after all, Will did try. To put it more formally, "asking X to try A" succeeds if the persuasion rules succeed, and otherwise fails.

Note also that "Instead of…" rules written for other people will be treated by Inform as failures, even if we write something like

Instead of Will pulling the cord:
   say "The bell rings."

and thus may produce unsatisfactory results such as

>WILL, PULL CORD
The bell rings.
Will is unable to do that.

If we wish to write new successful actions for another character, we will need to create appropriate carry out and report rules for them: these will be explained in the sections to follow.

(Finally, note that the mechanism Inform uses to see if we have printed a refusal message of our own, in the event of persuasion rules failing, can be fooled if we write a persuasion rule explicitly ending with a "[paragraph break]" text substitution.)

Examples

A hypnotist who can make people obedient and then set them free again.
187.
Several friends who obey you; a policeman who doesn't (but who takes a dim view of certain kinds of antics).

Suppose, finally, that Will not only consents to try the action, but it also survives its passage through Before and Instead rules. What happens then? In principle, what happens to Will is exactly what would have happened to the player in his place. For instance:

> will, go east
Will leaves to the east.

If on the other hand Will's attempt is frustrated because one of the checking rules stops him, then Will's action fails. For instance, if Will tries going northeast but there is no room to northeast, one of the rules checking the "going" action will stop him. We will then see this:

> will, go northeast
Will is unable to do that.

This is rather a generic message, and we may want something more interesting. We can provide that using yet another special kind of rule:

Unsuccessful attempt by Will going: say "Will blunders around going nowhere, as usual."

Even that is still a little generic, though, because it treats all of the various ways that "going" can fail as the same. If we have ACTIONS switched on, we can see what goes on behind the scenes when we ask Will to walk into a door:

>will, go west
[asking Will to try going west]
[(1) Will going west]
[(1) Will going west - failed the can't go through closed doors rule]
Will blunders around going nowhere, as usual.
[asking Will to try going west - succeeded]

(The "(1)" lets us know that a new action is starting during the old one, and before the old one finishes: sometimes we go up to three or four deep, though seldom more in practical cases.) We can now rewrite the "unsuccessful attempt" rule like so:

Unsuccessful attempt by Will going:
   if the reason the action failed is the can't go through closed doors rule, say "Will looks doubtful and mumbles about doors.";
   otherwise say "Will blunders around going nowhere, as usual."

The value "reason the action failed" is set to whichever checking rule threw out the action which Will tried. The names of these rules try to be self-explanatory – at any rate, those with gnomic names are not useful for this sort of thing, and can be ignored – and can be found out either using ACTIONS or by consulting the Actions index.

Finally, note that "unsuccessful attempt" rules apply only when the person in question is being asked to perform the action by somebody else – as in the examples above.

Example

188.
A person who goes along with the player's instructions, but reluctantly, and will get annoyed after too many repetitions of the same kind of unsuccessful command.

The player's actions happen not only when he types a command, but can also happen spontaneously as a result of a "try" phrase.

try going west
try asking Will to try going west

The latter might, of course, result in Will trying going west: or it might not – that depends on the persuasion rules. But as the author, we have the ultimate powers of persuasion, and can make Will act in any way we like, without asking:

try Will going west

Nobody in the simulated world requested this: it is an impulse felt by Will alone, so that – from the player's point of view – Will is acting spontaneously. The player need not be anywhere nearby, and may never know what happened. Recall that when actions work their way down through the flow-chart, they are stopped before reaching the "report" stage – when the player is told about them – if they are running "silently". This is also where Inform stops an action which is not witnessed by the player.

To repeat a point in the previous section: "unsuccessful attempt" rules do not apply to actions which the author has caused to happen, using "try". When such actions fail, they invoke no special set of rules. Indeed, when "try" causes somebody other than the player to try an action, nothing will be printed to report back on success or failure. If Will can't go west, that's his problem.

Note that the text "try Will going west" involves the actor's name immediately placed next to the action he is to try, which in a very few cases might cause ambiguities. If the actor's name contains a participle like "going" – say, if Will's full name turned out to be Mr Will Going – then we would have to write out the action name in full, using "trying" to clarify matters:

try Will Going trying going west

Examples

189.
Introducing Ogg, a person who will unlock and open a container when the player tells him to get something inside.
190.
Boston Cream ★★★★
A fuller implementation of Ogg, giving him a motivation of his own and allowing him to react to the situation created by the player.

It is not often that we need to create new actions, but a large work of interactive fiction with no novelty actions is a flavourless dish. Here we shall create an action for photographing things.

The Ruins is a room. "You find this clearing in the rainforest oddly familiar." The camera is in the Ruins. "Your elephantine camera hangs from a convenient branch."
Photographing is an action applying to one visible thing and requiring light.

In theory that text is already sufficient to make the new action, but what we have so far is rudimentary to say the least. The two qualifications give Inform the useful information that we cannot photograph in the dark, and that we need to be photographing something – not, as in the case of waiting or taking inventory, acting without reference to any particular thing external to ourselves.

The word "visible" here tells Inform that we do not need to be able to touch the thing in question: a line of sight is good enough. These two stipulations were necessary because the default arrangement is that any object must be in touching range, and that most actions can be performed in darkness. (Also, note that if you invent an action which needs to apply to directions like "north" or "south", you need to make this apply to visible things, because the object used inside Inform to represent the idea of "north" can be seen but not touched. So for understanding purposes, "visible thing" is understood as meaning any visible thing or direction: it's more general than "thing", not more specific.)

Occasionally, when writing general rules about actions, it can be useful to find out what the current action's requirements are: the following conditions do what they suggest.

if action requires a touchable noun:

This condition is true if the action being processed is one whose (first) noun is an object which needs to be touchable by the actor. For example, it's true for "taking", but false for "examining".

if action requires a touchable second noun:

This condition is true if the action being processed is one whose second noun is an object which needs to be touchable by the actor. For example, it's true for "putting the brick in the sack", but false for "throwing the brick at the window".

if action requires a carried noun:

This condition is true if the action being processed is one whose (first) noun is an object which needs to be carried by the actor. For example, it's true for "dropping", but false for "taking".

if action requires a carried second noun:

This condition is true if the action being processed is one whose second noun is an object which needs to be carried by the actor.

if action requires light:

This condition is true if the action being processed is one which can only be performed if the actor has light to see by. For example, it's true for "examining", but false for "dropping".

As further examples, here we create "blinking" and "scraping X with Y". Note the use of "it" to indicate that the name of an object should go here.

Blinking is an action applying to nothing. Scraping it with is an action applying to two things.

The photographing action now exists, but with two provisos: (a) it never happens, because Inform does not know what commands by the player should cause it, and (b) even if it were to happen, nothing would follow, because Inform does not know what to do. (There are no check, carry out or report rules yet.)

The first problem is easily overcome:

Understand "photograph [something]" as photographing.

We will return to the whole subject of parsing, as this process of understanding the player's commands is called, later. But this gives the gist of it.

See Also

Understand for the full story.

Examples

191.
A DIAGNOSE command which allows the player to check on the health of someone.
192.
Frizz ★★★
Liquid flows within containers and soaks objects that are not waterproof; any contact with a wet object can dampen our gloves.
193.
3 AM ★★★
A shake command which agitates soda and makes items thump around in boxes.

Our three example actions can be recognised in play using the following:

Understand "photograph [something]" as photographing.
Understand "blink" as blinking.
Understand "scrape [something] with [something]" as scraping it with.

The last of these examples shows why Inform does not risk generating this automatically: English is so full of irregular verbs. Inform could have guessed "blink" and "photograph", but might then have opted for "scrap" instead of "scrape".

Inform does risk automatically generating the past participle of an action. (Many past participles are never needed, so the stakes are lower if Inform gets this wrong.) What usually happens is that the "-ing" is replaced with "-ed", thus photographed, blinked, scraped – but Inform has a dictionary of some 460 irregular exceptions, such as caught, fled, crossbred, taken, woven. So with luck Inform will guess correctly. If not, we can get around this like so:

Squicking is an action with past participle squacked, applying to one thing.

The normal behaviour of an action is specified by its three associated rulebooks – check, carry out and report. In the case of our "photographing" example, these rulebooks will be:

Check photographing. Here, for instance, we need to verify that the player has the camera. If any of our checks fail, we should say why and stop the action. If they succeed, we say nothing.
Carry out photographing. At this stage no further checking is needed (or allowed): the action now definitively takes place. At this point we might, for instance, deduct one from the number of exposures left on the film in the camera, or award the player points for capturing something interesting for posterity. But we should say nothing.
Report photographing. At this stage no further activity is needed (or allowed): whatever effect the action had, it has happened and is now over. All we can do is to say what has taken place.

So far we have not really gone into the business of what rulebooks are, and we don't do so here either – suffice to say that we can now create whatever rules we need:

A check photographing rule:
   if the camera is not carried:
      say "You can hardly photograph without a camera, now can you?" instead.

In fact, writing "a check photographing rule" is over-formal. We can more simply label our rules like so:

Check photographing:
   if we have photographed the noun:
      say "You've already snapped [the noun]." instead.
Report photographing: say "Click!"

For the sake of brevity, photography has no interesting consequence (no points to be won, no film to use up), so there are no carry out rules here. Note the way we used the word "instead" once again to stop actions in their tracks.

We can continue to add rules at any point, and a classic thing that happens when testing a new work is that the designer realises there is a case which has not been thought of:

Check photographing:
   if the noun is the camera:
      say "That would require some sort of contraption with mirrors." instead.

Examples

An electric light kind of device which becomes lit when switched on and dark when switched off.
195.
Paddington ★★
A CUT [something] WITH [something] command which acts differently on different types of objects.
Adding a "sanity-check" stage to decide whether an action makes any sense, which occurs before any before rules, implicit taking, or check rules.
197.
Noisemaking ★★★
Creating a stage after the report stage of an action, during which other characters may observe and react.

For some complex situations, it can be useful to keep track of a few values throughout the processing of the action. This is not an everyday occurrence: in the Standard Rules, for instance, only two or three out of 90 actions need to do this. But suppose we want to write a more deluxe version of our "photographing" action. This time, rather than having a single thing called the "camera", we will provide a whole range of possible cameras, varying in quality:

Photographing is an action applying to one visible thing and requiring light. Understand "photograph [something]" as photographing.
The Studio is a room. Sally is a woman in the Studio. A foam-lined tote bag is in the Studio.
A camera is a kind of thing. A camera has a number called picture quality. The digital SLR camera is a camera in the tote bag. The player carries a camera called the instant one-shot camera. The picture quality of the SLR camera is 10. The picture quality of the one-shot is 2. Definition: a camera is sharp if its picture quality is 5 or more.

And we will want the photographing action to have the player use the best-quality camera which comes to hand. We will give the action a variable called the 'camera photographed with', thus:

The photographing action has an object called the camera photographed with.

Every action's variables must be named differently from those of all other actions, because there are some "before" rules (for instance) which take effect for many different actions, and which might need access to any of their variables. So action variables should be named in a way marking out to which action they belong. The best way to do this is to include the past participle of the action name – just as "camera photographed with" contains the past participle "photographed" of the action "photographing".

This value is created when the action begins, and disappears when the action ends. (If the action should happen a second time before the first time was completed, a second copy of the value is created, leaving the original undisturbed.) When the action begins, the value starts out as something neutral – so if it is a number, it starts out as 0, if a text, it starts out as the blank text "", and so on. Here it is an object, so it starts out as nothing – the value meaning no object at all. But of course we want to give it a value ourselves. We can do that using the "setting action variables" rulebook. For instance:

Setting action variables for photographing:
   now the camera photographed with is the sharpest camera which is carried by the actor.

The "setting action variables" rulebook is run through before even the before rules, and it has no power to stop or change the action. Its rules should say nothing and do nothing other than to set rulebook variables like this one. Note that it is intended to work for any actor, not only the player: so rather than referring to the player as the performer of the action, we need to write "the actor", as in the example above. (See subsequent sections for more on actors.)

We can now write rules such as:

A check photographing rule:
   if the camera photographed with is nothing:
      say "You can hardly photograph without a camera, now can you?" instead.

Only rules to do with the photographing action – before, instead, after, check, carry out, or report rules, and so on – are allowed to see the 'camera photographed with' value: it's the private property of the action.

A further elaboration allows us to make rules about photographing neater to write. If we create our variable like so:

The photographing action has an object called the camera photographed with (matched as "using").

…then we are now allowed to add an optional 'using …' clause onto a description of the action. The clause has to be introduced with a single word: here, it's 'using'. For instance, we could write rules such as

Instead of photographing something using the one-shot camera:
   say "But you promised to give this to Sally's nephew."
Check photographing something using the noun:
   say "That would require some sort of contraption with mirrors." instead.
Report photographing something using a sharp camera:
   say "You feel cool and important as the shutter clicks."

(This is the method used by the Standard Rules to attach optional clauses such as 'to', 'with' and 'through' to the going action.)

Examples

198.
TAKE expanded to give responses such as "You take the book from the shelf." or "You pick up the toy from the ground."
The young William Wordsworth, pushing a box about in his room, must struggle to achieve a Romantic point of view.
Adapting the going action so that something special can happen when going from a dark room to another dark room.
A system in which every character has a body, which is left behind when the person dies; attempts to do something to the body are redirected to the person while the person is alive.
202.
Croft ★★★
Adding special reporting and handling for objects dropped when the player is on a supporter, and special entering rules for moving from one supporter to another.

The "photographing" action now works very nicely when the player does it. But not when others try. Suppose that neither the player, nor Clark Gable, is holding the camera:

>photograph clark
You can hardly photograph without a camera, now can you?
>clark, photograph me
>

An uncanny silence. What has happened is that the rules written so far are all implicitly restricted to the player only. This is because when we write -

Check photographing:
   if the camera is not carried:
      say "You can hardly photograph without a camera, now can you?" instead.

the action is "photographing", not "Clark photographing". In the next few sections we shall see how to make the rules work nicely for everybody. This is a little bit harder, so it should be noted right away that in many projects there is no need. In a story which has no other characters who succumb to persuasion, for instance, only the player will ever try the action.

Examples

203.
An escaping action which means "go to any room you can reach from here", and is only useful to non-player characters.
Replacing the inventory reporting rule with another which does something slightly different.
205.
Under Contract ★★★★
Creating a person who accepts most instructions and reacts correctly when a request leads implicitly to inappropriate behavior.

If we want to impose the restriction about carrying the camera on other people, we need a rule like the following:

Check someone photographing: if the person asked does not carry the camera, stop the action.

Implicitly, that "someone" excludes the player. Note that we say nothing in this rule, stopping the action without a word: after all, Clark might well be out of sight when trying this. If he is within sight, then we read:

>clark, photograph me
Clark Gable is unable to do that.

We saw before that Inform's built-in rules all have handy names (the "can't drop what's already dropped rule", and such), and that these are useful when writing better "unable to…" messages. So for a deluxe version, we end up with:

Check someone trying photographing (this is the other people can't photograph without the camera rule): if the person asked does not carry the camera, stop the action.

And now, with ACTIONS on, we find that:

>clark, photograph me
[asking Clark Gable to try photographing yourself]
[(1) Clark Gable photographing yourself]
[(1) Clark Gable photographing yourself - failed the other people can't photograph without the camera rule]
Clark Gable is unable to do that.
[asking Clark Gable to try photographing yourself - succeeded]

which means that we could have, say,

Unsuccessful attempt by Clark photographing:
   if the reason the action failed is the other people can't photograph without the camera rule, say "Clark is too suave to be embarrassed. 'Frankly, my dear, I don't have a camera.'";
   otherwise say "Clark tries, and fails, to take a photograph."

Examples

206.
Changing the check rules to try automatically leaving a container before attempting to take it. (And arranging things so that other people will do likewise.)
207.
Barter Barter ★★★
Allowing characters other than the player to give objects to one another, accounting for the possibility that some items may not be desired by the intended recipients.

Report rules for the player's actions are easy to write, and for many actions, they are not much harder for other people either:

Report photographing: say "Click!"
Report someone photographing: say "Click! [The person asked] takes a snapshot of [the noun]."

But once other people are involved, we have to go to some trouble to get all of the possibilities right. Here is a case which did not immediately occur to the author of the "going" action, for instance:

>get in cage
You get into the cage.
>clark, get in automobile
Clark Gable gets into the automobile.
>clark, push cage west
Clark Gable goes west in the automobile, pushing the cage in front, and you along too.
The Lot (in the cage)
In the Lot you can see an automobile (in which is Clark Gable).

We said before that report rules are skipped if the action is running "silently", or if the action is one that the player does not witness. But that is also a tricky concept. Inform's doctrine is that you witness an action if you can see any of the actor, the noun or the second noun at either the beginning or the end of the action; except that being able to see a backdrop does not count. Thus if Clark Gable, in Beverly Hills, photographs the Hollywood sign then we do not witness this from Sunset Boulevard merely because we, too, can see the Hollywood sign.

While the report rules for actions by the player must actually report something, report rules for other people's actions are under no such obligation. For instance, if Clark unlocks a door from the other side to the player, then this counts as an action that the player witnesses – and after all, it could be argued that the player should hear the key turning in the lock – but in fact the standard rules for reporting locking choose to say nothing.

Examples

Elaborating the report rules to be more interesting than "Clark goes west."
209.
Fate Steps In ★★★
Fate entity which attempts to make things happen, by hook or by crook, including taking preliminary actions to set the player up a bit.

In the previous sections, we created a new action by providing one set of rules for the player and another for anybody else who might try to perform it. These rules began with action descriptions in one of the following forms:

Instead of taking a container, ...
Instead of P taking a container, ...

The first form implies that the player must be performing the action: the second allows for any person matching P to be the action, except that this person must not be the player. That means that all rules seen so far either affect only the player, or only other people.

This is often convenient, but sometimes we need to set up a complicated action which really does work in the same way for every actor – for instance, the built-in Inform actions provided by the Standard Rules aim to do this. We can write such rules thus:

Instead of an actor taking a container, ...

Here the rule applies to anyone who tries taking a container, player or not. Inside such a rule, the special value 'the actor' is the person performing the action. For instance, the Standard Rules include this one:

Carry out an actor wearing (this is the standard wearing rule):
   now the actor wears the noun.

The actions seen so far are all impulses causing the protagonist inside the fictional world to do something, or at least try to. But when the player types "quit" or "save", that is not a request for anything to happen in the fictional world: it is an instruction to the program simulating that world. In fact, just the same, such requests are treated as actions, but of a special category called "out of world" actions. They do not cause time to pass by, so the turn counter does not advance, nor does this command cycle count as a turn at all; and they are altogether exempt from "Before", "Instead" and "After" rules. Only the player is allowed to try them.

We can also create new out-of-world actions. Suppose we want a dialogue like so:

>ROOMS
You have been to 1 out of 8 rooms.

Here is a complete implementation:

Requesting the room tally is an action out of world.
Report requesting the room tally: say "You have been to [number of visited rooms] out of [number of rooms] room[s]."
Understand "rooms" as requesting the room tally.

It is important not to use "out of world" actions for anything affecting what goes on in the fictional world, or realism will collapse, and action-processing may also fail to work in the usual way. "Out of world" actions should be reserved for providing commands like ROOMS, which monitor events rather than participate in them.

Examples

210.
P. David Lebling's classic "Spellbreaker" (1986) includes a room where the game cannot be saved: here is an Inform implementation.
In some of the late 1970s "cave crawl" adventure games, an elaborate scoring system might still leave the player perplexed as to why an apparently perfect play-through resulted in a score which was still one point short of the supposed maximum. Why only 349 out of 350? The answer varied, but sometimes the last point was earned by never saving the game – in other words by playing it right through with nothing to guard against mistakes (except perhaps UNDO for the last command), and in one long session.

The flow chart back at the start of this chapter shows that, early on in processing an action (between Before and Instead), Inform asks the question "Can we see or touch things?" This is where it enforces the requirements in the action's definition:

Photographing is an action applying to one visible thing and requiring light.
Scraping it with is an action applying to two things.

Seeing and touching are two different questions, which Inform answers in different ways. We shall see ways to modify or entirely alter what can be seen using the "deciding the scope of something" activity when we get to the Understanding and Activities chapters, and later in this chapter we will change the definition of touchability. What both have in common is that they are complicated questions, affected by the circumstances. We cannot simply declare that the player can touch a given lever, or can see in a given room: we must arrange for there to be no barriers between the player and the lever, or for there to be a light source in the room.

An example of rules applying to given objects is provided by the way that Inform decides whether the player can reach something or not. For instance, suppose the following:

The Laboratory is a room. In the Laboratory is a conical flask. The flask is closed and transparent. In the flask is an antibumping granule.

The player will be able to examine the granule but not to take it, as that would require reaching through glass. Suppose the player does type TAKE GRANULE: then Inform looks for potential barriers between the player and the granule, and of course finds the conical flask. If, as in this case, the thing to be touched is on the inside, then Inform asks the "reaching inside" rules for permission. There are two reaching inside rules built in to Inform:

can't reach inside rooms rule
can't reach inside closed containers rule

and in fact the second of these rules will cause the taking action to fail, because the conical flask is a closed container. (The other rule has to do with a player in one room able to see another room through, say, a telescope – merely having a line of sight doesn't give the ability to reach into the frame.)

Symmetrically, Inform also has "reaching outside" rules, used if the player is inside something and wants to reach an object in the wider room. (From a bed, probably yes; from a cage, probably no.) This ordinarily contains just one rule:

can't reach outside closed containers rule

Example

212.
Carnivale ★★
An alternative to backdrops when we want something to be visible from a distance but only touchable from one room.

To recap, actions are created like so:

Photographing is an action applying to one visible thing and requiring light.
Depositing it in is an action applying to two things.
Taking inventory is an action applying to nothing.

Actions can involve up to two different things. We can place additional requirements on any of these things by describing them as a "visible thing", "touchable thing" or "carried thing". (If we simply say "thing" or "things", as in the second example, Inform assumes the requirement to be "touchable".) These three conditions are increasingly strong:

- To be "visible", something needs only to be possible to refer to by the player, which in practice means that it must be visible to the player-character. The noun or second noun produced by any action resulting from a command at the keyboard will always satisfy this minimal condition.

- To be "touchable", the player-character must be able to physically touch the thing in question: this normally means that it must be in the same room, and there must be no physical barriers in between.

- To be "carried", the player-character must (directly) carry the thing in question. (But if the player types a command using an action requiring something "carried", like WEAR HAT, the thing in question – the hat – will sometimes be picked up automatically. This is called "implicit taking", and results in text like "(first taking the top hat)" being printed.)

If an action involves two things, they need not have the same requirement as each other:

Waving it at is an action applying to one carried thing and one visible thing.

Thus to "wave magic wand at banyan tree", the player must be carrying the wand, but need only be able to see the tree.

Note one special case. Requirements on touchability are waived in the case of "try" actions applied to people other than the player where the things they would need to touch are doors or backdrops. (This is a compromise to avoid difficulties arising from the ambiguous locations of such items.)

Examples

213.
Eddystone ★★
Creating new commands involving the standard compass directions.
214.
Creating an amulet of tumblers that can be used to lock and unlock things even when it is worn, overriding the usual requirement that keys be carried.

The question of what the player can, and cannot, reach to touch is important in interactive fiction. It contains some of the subtlest ideas in the model world, though they often go unnoticed. For instance, if a key is on a shelf which is part of a closed box, can we reach for the key? This comes down to whether the shelf, described only as "part of" the box, is on the inside or the outside: and in fact, because it cannot know which is the case, Inform allows either. So in general it is best to regard "parts" as being exterior parts, but to avoid having parts on containers that might in the course of play be closed up with the player inside.

We can, if we wish, change the principles of what can be touched by writing new reaching inside or reaching outside rules. Returning to the example of the conical flask:

A rule for reaching inside the flask: say "Your hand passes through the glass as if it were not there, chilling you to the bone."; allow access.

(Or this could equally be called "a reaching inside rule for the flask".) More generally, we could give the usual flexible description of what the rule applies to:

A rule for reaching inside open containers: say "Your hands seem enigmatically too large for [the container in question]."; deny access.

The "container in question" is the one to which the rule is being applied. Note that a reaching inside rule can "deny access" (stopping with failure), or "allow access" (stopping with success), or neither, in which case the decision is left up to any subsequent rules in the rulebook to make. If none of them decide, access is allowed.

If it seems possible that these rules will be employed by people other than the player, then we need to write them a little more carefully, and in particular we need to ensure that they print nothing for other people. In the first case below, anybody can reach through the glass; in the second case, only the player cannot reach into open containers.

A rule for reaching inside the flask:
   if the person reaching is the player, say "Your hand passes through the glass as if it were not there, chilling you to the bone.";
   allow access.
A rule for reaching inside open containers:
   if the person reaching is the player:
      say "Your hands seem enigmatically too large for [the container in question].";
      deny access.

The "person reaching" is, as its name suggests, the person trying to reach through the barrier in question.

Examples

Kitty Pryde of the X-Men is able to reach through solid objects, so we might implement her with special powers that the player does not have…
216.
A backdrop which the player can examine, but cannot interact with in any other way.
217.
A window between two locations. When the window is open, the player can reach through into the other location; when it isn't, access is barred.

Ordinarily, Inform has a simple model for visibility: it is either fully light or it is fully dark, and certain actions are impossible in the dark, such as examining something.

We first need to remember that darkness affects what actions are even tried, as far as the player's typed commands go. If the player is in a dark room, and there is a screwdriver on the floor, the command EXAMINE SCREWDRIVER will not try any action: the screwdriver is not "in scope", which means that the parser thinks the player does not have any means of knowing it exists. (The rules for scope can be modified – see the chapter on Activities.) But let's suppose that the player types EXAMINE BOOK, and is holding the book in question. The book is now "in scope", so the action "examining the book" is tried.

Some actions require light to be present, and "examining" is one of those. So Inform consults the visibility rules to see if it can go ahead. By default, there is only one visibility rule, which says "yes" in the light and "no" in darkness. Here, though, we create another one:

Visibility rule when in darkness:
   if examining the book:
      say "You have to squint. Still...";
      there is sufficient light;
   there is insufficient light.

A visibility rule must always conclude "there is sufficient light", or "there is insufficient light", or else do nothing and leave it to other rules to decide.

It is a possibly unexpected fact that "looking" does not require light, but instead behaves differently in darkness – it prints a pseudo-room-description such as

Darkness
It is pitch dark, and you can't see a thing.

instead of printing the description of the player's current room. This means that the "looking" action is unaffected by visibility rules. All the same, what "looking" does in the dark can be changed by using the two activities "printing the name of a dark room" and "printing the description of a dark room" (see the Activities chapter for details).

Example

218.
Visibility set so that looking under objects produces no result unless the player has a light source to shine there (regardless of the light level of the room).

As we have seen, to describe an action fully takes a complicated little bundle of information – we need to know what is to be done, who will do it, and what it will be done to. There are times when we would like to remember an action and look back on it later (perhaps many turns later, after many other actions have taken effect) – but this is not easy to do with only the techniques we have seen so far. There are quite a few cases to get right, and it would be easy to not store quite enough of the details.

Fortunately, Inform provides a kind of value called "action" which can do all of this automatically. (In older versions of Inform this was called "stored action", but the word "stored" is now unnecessary, and makes no difference.) As with most other kinds of value, actions can be held in variables, "let" values, properties or table columns. For example:

The best idea yet is an action that varies.

creates a variable called "the best idea yet" which holds an action.

This will normally be created holding the default value – the player waiting. We really only have two ways to make more interesting actions. One is by typing them out explicitly, like so:

now the best idea yet is pushing the button;

Here "pushing the button" is a constant of the kind "action", so it goes into happily into "best idea yet" in the same way that a number like 3 could go into a number that varies. The action must be specific in every respect, so "taking something" or "doing something" will not work – "taking something" is really a general description of many possible actions, not an action in its own right.

The other way to produce a useful action is:

current actionaction

This phrase produces the action currently being processed as a value – it literally stores the action, and remembers, if necessary, the exact wording of the player's command at the time it was stored – so that even actions arising from commands like LOOK UP X100 IN THE CODE BOOK can be stored faithfully. Examples:

let the present whim be the current action;
say "How you would like to be [current action].";

This only makes sense if an action is currently going on, so it shouldn't be used in "every turn" rules, for instance.

So much for making actions: now for making use of them. The first obvious idea is to store up an action for several turns and then have it take effect later. That's easily done: just as we can "try" any action written out explicitly, so we can also try a stored one. The phrase to do this has exactly the same wording either way, since it does the same thing either way.

But actions can still be useful even if we never intend to try them. For one thing, we can say them, and this produces a fairly natural description of what the action is:

Before doing something in the presence of the bearded psychiatrist: say "'Zo, the subject vishes to engage in [the current action]. Zis is very interesting.'"

will produce text such as:

"So, the subject vishes to engage in rubbing the fireman's pole. Zis is very interesting."

One of Inform's most convenient features is its ability to test if the action being processed matches vague or complicated descriptions of whole classes of actions. For example,

if the best idea yet is taking something, ...

works even though "taking something" is not a single action; it's a description which could apply to many different actions (taking a box, taking a ball, and so on). What Inform tests is whether the "best idea yet" value, a single action, fits this description or not. We can be even vaguer:

if the best idea yet is doing something to the lever, ...

Just occasionally, this can lead to ambiguities. For instance,

if the current action is wearing something, ...

fails because Inform thinks "wearing" is meant in the sense of the current action having clothes on, so it produces a problem message. To avoid this, simply write:

if the current action is trying wearing something, ...

which can't be misunderstood. Something else to be aware of is that the terms "actor", "noun" and so on will refer to that action: for instance, in

if the best idea yet is taking the noun, ...

"noun" here refers to the noun in "best idea yet", not to its meaning outside of this phrase (if indeed it has such a meaning).

When dealing with actions, we sometimes want to know what they are dealing with. We can extract this information using the following phrases:

action name part of (action)action name

This phrase produces the action name part of an action. Example: suppose the current actor is Algy, who is throwing the brick at Biggles. Then

action name part of the current action = throwing it at action
noun part of (action)object

This phrase produces the (first) noun of an action. Example: suppose the current actor is Algy, who is throwing the brick at Biggles. Then

noun part of the current action = the brick

If the noun is something other than an object, this produces just "nothing", the non-object.

second noun part of (action)object

This phrase produces the second noun of an action. Example: suppose the current actor is Algy, who is throwing the brick at Biggles. Then

second noun part of the current action = Biggles

If the second noun is something other than an object (for instance for the command SET DIAL TO 3417 it would be the number 3417), this produces just "nothing", the non-object.

actor part of (action)object

This phrase produces the person who would be carrying out the action if it were being tried. Example: suppose the current actor is Algy, who is throwing the brick at Biggles. Then

actor part of the current action = Algy

The following phrase is a convenient shorthand form:

if (action) involves (object):

This condition is true if the object appears as any of the actor, the noun or the second noun in the action. Example:

if the current action involves Algy

would be true for "give revolver to Algy", "Algy trying flying the Sopwith Camel", "examine Algy" and so on, but false for "ask Raymond about secret airfield".

action of (an action)action

This phrase is now seldom needed. It produces a literally typed action as a value. Example:

now the best idea yet is the action of pushing the button;

Nowadays in most contexts we can just type "pushing the button" as a value, and that will work fine, so this phrase is retained only to keep old code working.

Examples

219.
Bosch
Creating a list of actions that will earn the player points, and using this both to change the score and to give FULL SCORE reports.
For every character besides the player, there is an action that will cause that character to wither right up and die.
221.
A video camera that records actions performed in its presence, and plays them back with time-stamps.
222.
Anteaters ★★
The player carries a gizmo that is able to record actions performed by the player, then force him to repeat them when the gizmo is dropped. This includes storing actions that apply to topics, as in "look up anteater colonies in the guide".

Looking at the action-processing diagram, there seem to be a bewildering number of ways to intervene. For instance, suppose it must be fatal to pick up a land mine. All six of the following rules would do the business:

Before taking the land mine: end the story saying "Bang!"
Instead of taking the land mine: end the story saying "Bang!"
Check taking the land mine: end the story saying "Bang!"
Carry out taking the land mine: end the story saying "Bang!"
After taking the land mine: end the story saying "Bang!"
Report taking the land mine: end the story saying "Bang!"

So which should we use? Of course, we could decide that it really doesn't matter: what works, works. But it is a good idea to play along with the conventions used by Inform, if only because that will make our rules interact better with each other and with rules by other people which we may someday want to borrow. So this chapter ends by offering a few guidelines. Let us suppose that we have some effect which we want to achieve.

1. Are we just trying to correct the player's typing?

For instance, responding to the command "STEAL GOLDEN EAGLE" with a reply like "To steal something, just try to TAKE it." It is bad style to make a special action for this, which does nothing except to print up this text: better is to use the "Understand … as a mistake" technique, which will come up in the chapter on Understanding.

2. Does the effect apply only to a particular situation, or is it a general phenomenon?

In other words, does the effect apply only to particular people, things or places, or is it a generic rule of play? In the case of the land mine, this is an easy question to answer: it is a unique situation. On the other hand, stopping the player from carrying unduly heavy weights would be a generic rule of play.

Rules like the one saying that photography is only possible if one holds the camera are, by convention, also counted as generic rules of play: they are not really special rules about the camera, but apply to all possible acts of photography anywhere, so are actually generic.

Sometimes we can choose our own answer to this question, and go either way. Suppose we want a certain place to be muddy-floored, affecting things that happen there. One way would be to write exceptional rules applying to that one room. But we could alternatively create a general concept of muddiness ("A room can be clean or muddy. A room is usually clean.") and then regard the new behaviour as being a set of generic rules applying in muddy rooms. We could then, of course, create a second muddy room with much greater ease, or transplant these rules to other works and have muddy rooms in those too.

3. Particular situations: use Instead or After (or sometimes Before).

The next question is: does the effect kick in after the hoped-for action has taken place, or not? In the case of the land mine, to answer that means deciding whether we think the detonator is sensitive to the slightest touch – in which case the explosion would happen at the first touch, and should be in an "Instead" rule – or whether one must actually pick up and disturb the mine – in which case an "After" should be used.

That leaves us a choice of two rulebooks if the effect takes place when the merest impulse towards the action is felt: "Before" and "Instead". Which to use? In cases of doubt, choose "Instead". But if the effect is intended to absolutely suppress all such impulses – for instance, in a silent examination room there must be no talking – then "Before" might be more appropriate. We could imagine that someone about to say something first has a mental impulse to speak, then opens his mouth so that it becomes visible to others that some talking is about to go on, and finally utters words. Here are three possible responses:

"You cannot contemplate breaking this smothering silence." (Before)
"The invigilator stares you down through her horn-rimmed glasses." (Instead)
"Everyone turns, appalled, as the silence is broken like the surface of a swimming pool by a falling elephant." (After)

4. Generic situations: work with action rules (or sometimes Before).

(a) If the effect takes place only when an action is definitely being tried, then we should use one of the action's three rulebooks: check, carry out or report. Check rules should do nothing, and should say nothing either unless they block the action (in which case, they should say why).

Carry out rules must not block the action – it is too late for that – and should not say anything – that hasn't happened yet. (There are a few exceptions: if the action is to look at something, then carrying it out is in a sense the same thing as reporting it. But in all cases of doubt, a carry out rule should say nothing.) Adding a carry out rule to an existing action can make it do something extra.

Report rules must neither block the action nor do anything. Working with new report rules is a way to make more natural-seeming, or more informative, messages appear. For instance, an effect where we want to be able to see through a door when it is first opened ("You open the panelled door, through which is the Board Room.") would be a case for a report rule.

In all cases, it is good style to write check, carry out or report rules in such a way that they could be used in other works too, or in situations that could conceivably have happened in this one (even if in fact it never does). We may one day want to put our new rules into an extension to be used by other people or in other projects, after all.

In this chapter, we have only seen the addition of new rules. We could add a new "check taking" rule, for instance, with the techniques seen so far. But what if the effect we want is not a matter of adding a rule but taking away, or restricting the applicability, of an existing one? In that case, we will need to say that the rule "does nothing" under certain circumstances (see the Rulebooks chapter). The check, carry out and report rules for all of the built-in actions are named, and they appear in the Actions index.

(b) If the effect takes place to divert or supplement an action, before that action actually takes place, then this should be done with a "Before" rule. This is the biggest practical use of "Before" rules: to try other actions, either instead or as well as the one just getting under way.

For example, if we want an automatic mechanism to try opening a container before taking something inside it, that would be a classic case for "Before". Indeed, that is the only way it could work – "Before" rules have a chance to get in before the touchability conditions are tested.

If we wanted a special "stealing" action for the act of taking another person's possessions, we might want to divert any taking action for such items into our new "stealing" action – that too would be a "Before". This would ensure that any "Instead" rules to do with taking do not apply.

5. Changing the behaviour of out-of-world actions.

Remember that "Instead", "Before" and "After" do not apply: so use "check" rules to forbid certain out-of-world activities, or specify that their rules do nothing (see the Rulebooks chapter).

Finally…

These are only guidelines. The system is designed to be flexible in order to give the author the widest possible range of options, and nobody should feel ashamed of making use of them.

13. Relations

Descriptions of things – "open door", "people in the Drawing Room" – have already had a whole chapter to themselves. But descriptions are only half of the story of Inform's highly flexible language for talking about places, things and circumstances: this chapter is the other half, and is about the "sentence". Of course all text is made up of sentences, but Inform has a more specific meaning than that. Consider the following pieces of source text:

The mouse is in the teapot.
Every turn when the mouse is in the teapot, say "A tail hangs out of the spout."
Instead of taking the mouse:
   say "The mouse slips from your hand and disappears into the teapot!";
   now the mouse is in the teapot.

What these three extracts have in common is the sentence "the mouse is in the teapot". Such a sentence can be used in three different ways: to declare the original state of the world, to ask during play if the world currently has that state, or to change things during play so that it does.

Actually, though, only definite sentences about the present can be used in all three ways. A vague instruction like

now Mr Darcy can see the mouse;

will fail, because there are so many ways in which Darcy might be able to see the mouse that Inform has no way to know how to arrange matters. And this by contrast is not merely difficult but impossible:

now Mr Darcy has never seen the mouse;

Which cannot be arranged because the past cannot be changed.

Verbs also turn up inside the more complicated descriptions. For instance,

things which are in the teapot
people who can see the mouse

are both descriptions, not sentences, but they contain "to be" and "to be able to see" respectively.

This chapter is about the verbs which can be used in sentences and descriptions. Inform involves many other features which use verbs – the action "taking the mouse" and the phrase "end the story" both use forms of verbs (to take and to end) – but this chapter has nothing to do with them: so for the sake of clarity, we will call verbs that occur in sentences "sentence verbs".

A sentence consists of two nouns with a verb between them. Usually, the two nouns are descriptions, as in:

Mr Collins is in a lighted room.

Here "Mr Collins" and "a lighted room" are descriptions. But there are sentences where one or both of the nouns is a value of some other kind. For instance, in

if the score is greater than 10, ...

the sentence "the score is greater than 10" consists of two number values ("the score" and "10") connected by a verb part ("is greater than").

This chapter is about getting the most out of sentences by defining new verbs to express ideas not already built in to Inform. Before we can define a new sentence verb, however, we must first look at the meanings of verbs: which Inform calls "relations".

Example

A more formal description of the sentence grammar used by Inform for both assertions and conditions.

Relations are what sentences express. They are yes/no questions about pairs of things: for example, to say that the coin is in the purse is to say that a particular relation ("being in") is true about a specific pair of things (the coin, the purse). It is neither a fact about the coin nor about the purse, but about the two together.

Inform comes with a number of relations built in, almost all of which have been used in previous chapters already. The following table names some of the more useful ones, giving examples of sentences to bring them about:

containment relation - The coin is in the purse.
support relation - The coin is on the table.
incorporation relation - The coin is part of the sculpture.
carrying relation - The coin is carried by Peter.
wearing relation - The jacket is worn by Peter.
possession relation - if Mr Darcy has a rapier...
adjacency relation - The Study is east of the Hallway.
visibility relation - if Darcy can see Elizabeth...
touchability relation - if Darcy can touch Elizabeth...

These relation names do not trip off the tongue, but they relatively seldom need to be referred to.

The same meaning can often be expressed by using several different verbs, or using the same verb in several different ways, as in the following examples:

The coin is in the purse.
The purse contains the coin.
The coin is contained by the purse.

all of which boil down to saying that the coin and purse satisfy the containment relation. Because of that, relations are not the same as verbs. To create a new idea, we will need first to create a new relation, and only then can we set up a verb which allows us to talk about that relation.

Inform has altogether five mutually exclusive ways in which one thing can be physically joined to another one:

containment relation - The coin is in the purse.
support relation - The coin is on the table.
incorporation relation - The coin is part of the sculpture.
carrying relation - The coin is carried by Peter.
wearing relation - The jacket is worn by Peter.

This is why we cannot have

The coin is on the table.
The coin is part of the table.

simultaneously, and it is a rare exception to the general rule that having one relation does not affect having another.

We have discussed how the holding relation applies if any one of those relations does. Another relation, similarly, is the union of two of them.

The possession relation is the meaning of the verb "to have". At first sight this seems the same as the carrying relation, but in fact it is a convenient shorthand for carrying or wearing, provided for conditions rather than assertions:

if Mr Darcy has a wet shirt ...

will be true during play if he is either carrying or wearing the shirt.

"to have" *can* be used in now phrase sentences, but in now phrases it always means carrying, only.

Still another relation exists which can be tested, but not declared to be true or false: the concealment relation, which is the meaning of the verb "to conceal". So we can ask:

if Mr Darcy conceals a fob watch ...

Examples

224.
Using the enclosure relation to let the player drop things which he only indirectly carries.
A wand which, when waved, reveals the concealed items carried by people the player can see.

We can create new relations like so:

Loving relates various people to one person.

Every relation has a name which ends with the word "relation", and in this case the name is "loving relation". While the name is often just two words long, as here, it doesn't have to be:

Adept sensitivity relates one person to one vehicle.

makes the "adept sensitivity relation". (The limit is 32 words.)

In such a definition, we have to say what kind of thing appears on the left and right of any relation, and also whether "one" or "various" possibilities can exist. In the example

Loving relates various people to one person.

what we are saying is that only people love, that they only love people, and that each person loves only one other person (at any given moment).

The "various" part comes in because, for instance, it might be the case that Verenka loves Stankevich *and* Liubov loves Stankevich. So, various people (Verenka and Liubov, to name but two) love one person (Stankevich). But we are forbidding anyone to love two other people at the same time: Stankevich must decide which of them to love, or pick someone else, or no-one at all.

Similarly, because loving relates various people to *one person*, if it had been asserted that Liubov loves Stankevich, a further assertion that Liubov loved Belinsky would result in a compiler error. Note the important difference between assertions and now phrases here. Assertions are what Inform uses to build the initial state of the game world, so it insists on consistency. All the compiler wants is to create the world you intended and any contradiction leaves it unsure what that is.

But relations are subject to change. The assertion that Liubov loves Stankevich only establishes what's true of the game world initially. Assuming we've established that the verb "to love" means the loving relation (more on which soon), any of your rules or phrases could include:

now Liubov loves Belinsky;

If Liubov already loved someone else, this would automatically cause Liubov to *cease* loving that person. With a one-to-one relation, a single now phrase creating a relation between two values could potentially break *two* other previously existing relations.

It is sometimes convenient to give a name to the other side of a relationship, so to speak. We might imagine:

Pet-ownership relates various animals to one person (called the owner).

It would then make sense to talk about "the owner of Loulou", and we could have phrases like "now Flaubert is the owner of Loulou" or "if the owner of Loulou is a woman…" and so forth. This, however, would not be allowed:

Pet-ownership relates various animals (called the pet) to one person.

because "the pet of Flaubert" would be ambiguous: he might have owned dozens.

The relationships described in this chapter so far are by no means always reciprocated. For instance, if a stone is on a table, then it is never true that the table is also on the stone. And the question may not even be meaningful to ask. If Peter wears a jacket, the jacket does not even have the possibility of wearing Peter.

But sometimes we do want a relation which works both ways equally well. These are simple to set up:

Meeting relates people to each other.

The effect is that various people know various other people, and this is always reciprocated. If Daisy knows Sophie then, automatically, Sophie knows Daisy. This even-handedness is maintained throughout play, so that whatever changes are made it is always true that if A knows B then B knows A.

And similarly for a reciprocal relation between one and another:

Marriage relates one person to another.

In this case, we can again give a name to the partner under a relation:

Marriage relates one person to another (called the spouse).

and now, for instance, we may have that the spouse of John is Yoko and the spouse of Yoko is John.

Since many of these examples have involved people, it might be worth mentioning again that any kind can be involved, not just the "person" kind.

Example

226.
Four Cheeses ★★★
A system of telephones on which the player can call distant persons and have conversations.

Finally, there is a kind of relation which binds even more strongly.

Nationality relates people to each other in groups.

This is a kind of relation which divides people up: we might wish to have all the Icelandic people related to each other, all the Peruvians to each other, and so on. If there were a Pacific island called Informia with one inhabitant, then that person would be related only to himself. As time goes by, we could imagine people emigrating, and so on, so that these groupings would switch: perhaps everyone would leave Belgium and, for a while, there would be no Belgian nationals at all.

The testing command RELATIONS prints out the current state of all the relations created in the source code. For instance:

>relations
Overlooking relates various rooms to various rooms:
   The Pub >=> the Garden
   The Garden >=> the Shrubbery
   The Shrubbery >=> the Sundial Plot
Friendship relates people to each other:
   Mr Wickham <=> Sophie
   Charlotte <=> Sophie
Marriage relates one person to another:
   Mr Wickham == Sophie

That can produce a lot of output. To see only a single relation, or to see it at some intermediate point in a calculation, there's also a testing phrase:

show relation (relation of values to values)

This phrase is for testing purposes only. It shows the current state of the named relation, that is, it shows which values relate to which other ones, where it's possible to do this in any sensible way.

But this is a phrase – not a typed command.

Examples

A machine that turns objects into other, similar objects.
228.
Otranto ★★★
A kind of rope which can be tied to objects and used to anchor the player or drag items from room to room.

It is all very well to define new relations, but a verb makes it useful. In fact, a relation is nothing more than what Inform uses as the "meaning" of a verb. The assertion verbs built in to Inform have the following built-in relations as their meanings:

[TODO – more verbs, more discussion of exceptions ]

Verb - Relation
to be - equality relation
to have - possession relation
to contain - containment relation
to support - support relation
to carry - carrying relation
to wear - wearing relation
to incorporate - incorporation relation

Some of Inform's built-in relations are expressed using prepositions:

Preposition - Relation
to be part of - (reversed) incorporation relation
to be adjacent to - adjacency relation

to be in – (reversed) containment relation

to be on – (reversed) support relation

It would be easy to make verbs for these if we wanted ("to adjoin", say) using the techniques of the next section.

The verb to be is grammatically different from any other, and its meaning is too complicated to be fully expressed by any one relation. A great deal of the Inform program is given over to its "meaning", which we are not allowed to change or imitate. The "equality relation" is simple enough, and is the one implied by conditions like

if the score is 20, ...

but to be can have more complicated implications – "if Mr Wickham is hungry" clearly doesn't test whether two quantities are equal. Likewise, to have, to hold, and to contain/to be in have different meanings in different contexts.

There are a few other built-in verbs, as can be seen in the Index, but these are mostly for experts only. For example:

Verb - Relation
to mean - meaning relation
to provide - provision relation

"To mean" can be used to make new verbs, as we'll soon see. Provision is to do with whether something can have a given property: for example, "if R provides the property lighted" tests whether R is able to have this property, not whether it actually has it at the moment.

Here is an example definition of a new verb:

The verb to sport means the wearing relation.

Once this is done, we can write the assertion

Mr Wickham sports a Tory rosette.

which will do the the same thing as

Mr Wickham wears a Tory rosette.

because both verbs have the same relation as their meaning.

[ TODO contradicts the description in 3.20 of these being participles ]

One can also use the present progressive (but not with "to be" or other verbs beginning "to be"):

Mr Wickham is sporting a Tory rosette.

Earlier versions of Inform needed to be told how to make other parts of the verb, but that's rarely true now. Just writing:

The verb to sport means the wearing relation.

is enough for Inform to understand "he sports", "they sport", "he sported", "it is sported", "he is sporting", "he had sported" and so on. It works with irregular verbs, too; it has a very comprehensive dictionary. But it's legal to spell out the conjugation if need be:

The verb to sport (he sports, they sport, he sported, it is sported) implies the knowledge relation.

Occasionally it's convenient to have the relation the other way around. For instance:

The verb to grace means the reversed wearing relation.

With that defined, these two sentences have identical meanings:

Mr Wickham sports a Tory rosette.
A Tory rosette graces Mr Wickham.

Reversed in this sense means that the things related – the subject and object of the verb – are the other way round.

This is so convenient that when you define a verb meaning a relation, Inform automatically creates a "to be (verbed) by" verb that means that relation reversed. So the following are *also* equivalent to the above:

A Tory rosette is sported by Mr Wickham.

Mr Wickham is graced by a Tory rosette.

Possible conditionals include:

if Mr Wickham is sporting a Tory rosette:
if a Tory rosette graces Mr Wickham:
if a Tory rosette is gracing Mr Wickham:

Or, in the negative:

if Mr Wickham does not sport a Tory rosette:
if a Tory rosette does not grace Mr Wickham:
if a Mr Wickham is not graced by a Tory rosette:

While "does *not*" can be used in negatives, "does" or "do" cannot be used in a positive: one cannot say "if Mr Wickham does sport a Tory rosette".

[TODO – not in 10.1 it doesn't. ]

The Phrasebook index contains all the verbs associated with assertions, in the Verbs section. When we add new verbs to our source, those will appear in the Phrasebook as well.

The verbs above are short ones, but we're free to make them longer than that. For example:

The verb to cover oneself with means the wearing relation.
Peter is covering himself with a tent-like raincoat.

Here we have "to cover oneself with", four words long; the limit is 29.

Examples

People are to be grouped into alliances. To kiss someone is to join his or her faction, which may make a grand alliance; to strike them is to give notice of quitting, and to become a lone wolf.
230.
An adaptive hint system that tracks what the player needs to have seen or to possess in order to solve a given puzzle, and doles out suggestions accordingly. Handles changes in the game state with remarkable flexibility, and allows the player to decide how explicit a nudge he wants at any given moment.

The term preposition is used here, a little loosely, to mean anything which we add to the verb to be in order to talk about some relation or other. We have seen many examples already, such as:

To be in - The ball is in the box.
To be part of - The lever is part of the slot machine.

These are defined just the way verbs are. Compare the following:

Suspicion relates various people to one person.
The verb to suspect means the suspicion relation.
The verb to be suspicious of means the suspicion relation.

The result of this is that

Hercule Poirot suspects Colonel Hotchkiss.
Hercule Poirot is suspicious of Colonel Hotchkiss.

are exactly equivalent, and so are these two descriptions:

somebody who suspects Colonel Hotchkiss
somebody suspicious of Colonel Hotchkiss

While most prepositions are short ("in", "part of", "suspicious of"), they're free to be longer if need be ("inordinately far away from"): the limit is 30 words, which should be ample.

We can also define verbs as auxiliaries, like so:

The verb to be able to approach means the approachability relation.

Now we can ask if Poirot "can approach" Hotchkiss, and so on.

[TODO] not all verbs are created equal.

Examples

A thorough exploration of all the kinds of relations established so far, with the syntax to set and unset them.
Building a marble chute track in which a dropped marble will automatically roll downhill.
An "underlying" relation which adds to the world model the idea of objects hidden under other objects.
234.
Bogart ★★★
Clothing for the player that layers, so that items cannot be taken off in the wrong order, and the player's inventory lists only the clothing that is currently visible.

We have already seen, in the chapter on Descriptions which is a forerunner of this one, that Inform provides not only "adjacent" as a way of seeing if one room is directly connected to another, but also "the best route from A to B", which allows us to see if any sequence of moves connects them.

Something similar – in fact, simpler – is allowed for any relation between objects. Suppose we would like to go sledging: we can go downhill, but not up. Some quite distant places may be reachable, while others close by may not be, even if lower than us, because they would involve climbing again at some point. The following would implement this:

Overlooking relates various rooms to various rooms.
The verb to overlook means the overlooking relation.
The Garden overlooks the Shrubbery. The Folly overlooks the Garden. The Shrubbery overlooks the Sundial Plot. The Old Ice House overlooks the Garden.
After looking:
   say "This wintry vantage point overlooks [the list of rooms overlooked by the location].";
   let the way be the next step via the overlooking relation from the location to the Sundial Plot;
   if the way is a room, say "To sledge downhill to the Sundial, aim for [the way].";
   otherwise say "It is not possible to sledge downhill to the Sundial."

Here we're making use of:

next step via (relation of values to values) from (object) to (object)object

This phrase tries to find a shortest route between the two given endpoints, using the given relation of objects to determine single steps. Example:

next step via the overlooking relation from the Folly to the Chinese Lake

The result is the special object value "nothing" if the two endpoints are the same or if no route exists.

number of steps via (relation of values to values) from (object) to (object)number

This phrase tries to find the length of a shortest route between the two given endpoints, using the given relation of objects to determine single steps. Example:

number of steps via the overlooking relation from the Folly to the Chinese Lake

The result is 0 if the two endpoints are the same, or -1 if no route exists.

Another example would be the "six degrees of separation" game, where it is claimed that any two people on Earth are connected by a sequence of up to six acquaintances. In an Inform implementation, we might talk about "the next step via the friendship relation from George Bush to Saddam Hussein", for instance, a phrase likely to evaluate to Donald Rumsfeld, and then

the number of steps via the friendship relation from George Bush to Saddam Hussein

would be… but that would be telling.

As with route-finding through the map, finding "the next step via" a relation can be slow. For instance, suppose we have dozens of articles of clothing all partially revealing each other, connected by two relations – overlying and underlying. Then "the next step via" these relations allows us to establish what can be worn on top of what else. If we need to calculate this often, and there are enormous wardrobes of clothes to choose from, speed starts to matter.

Once again there is a choice of algorithms: "fast" and "slow", where "fast" needs much more memory. To make route-finding for a given relation "fast", we have to declare it that way:

Overlying relates various garments to various garments with fast route-finding.
Overlapping relates various garments to each other with fast route-finding.

Otherwise, the "slow" method will be used.

This "with fast route-finding" note can only be added to various-to-various relations. (Although route-finding through various-to-one and one-to-various relations is fully supported, it exploits the relative simplicity of these problems to use a more efficient algorithm than either "fast" or "slow".)

See Also

Adjacent rooms and routes through the map for route-finding through the map rather than a relation.

Example

235.
A conversation in which the main character tries to build logical connections between what the player is saying now and what went immediately before.

One last way to create a new relation and, in many ways, the easiest of all. If we write:

Contact relates a thing (called X) to a thing (called Y) when X is part of Y or Y is part of X. The verb to be joined to means the contact relation.

then we would be able to talk about a handle being joined to a door, and a door being joined to a handle, and so on. We are not allowed to declare:

The hook is joined to the line.

because the question of whether they are joined is not for us to decide: that will be for the condition to determine, whenever we test it. Similarly, we cannot meaningfully write

now the hook is joined to the line;

(and Inform will not let us) because this relation is not something we can force either way: we can make it come true by other means, maybe, but we cannot simply make it true by saying so. Lastly, this kind of relation is restricted in that we are not allowed to find paths or calculate numbers of steps through it.

So this way to define relations is, on the face of it, just a sort of verbal trick to write conditions in a more attractive way. The more flexible, changeable relations in previous sections have much greater expressive power. All the same, it is nice to be able to write -

Nearness relates a room (called A) to a room (called B) when the number of moves from B to A is less than 3. The verb to be near means the nearness relation.

and then to be able to write rules like:

Instead of listening when the location is near the Sundial: say "You hear a splashing of water."

As with other relations, there's no reason why we have to use objects. For example:

Material is a kind of value. The materials are wood and metal. A thing has a material.
Materiality relates a thing (called X) to a material (called Y) when Y is the material of X. The verb to be made of means the materiality relation.

which enables us to write:

if the cube is made of wood, ...
say "The carpenter looks at [the list of things which are made of wood].";

And here is a mathematical one:

Divisibility relates a number (called N) to a number (called M) when the remainder after dividing M by N is 0. The verb to divide means the divisibility relation. The verb to be a factor of means the divisibility relation.

We now find that "2 divides 12", "5 is not a factor of 12" and "12 is divisible by 3" are all true. Again, we are only really gaining a nice form of words, but improving the clarity of the source text is never a bad thing.

Examples

A technical note about checking the location of door objects when characters other than the player are interacting with them.
Relations track the relationships between one character and another. Whenever the player meets a relative of someone he already knows, he receives a brief introduction.

[ TODO verb equivalents ]

Although most of the examples in this chapter have involved objects, relations can connect almost any values together. We can create relations in groups, one to various relations, various to one relations, one to one relations, and various to various relations for any combination of kinds. For example:

Partnership relates various texts to various texts.
The verb to belong with means the
partnership relation.
"cheese" belongs with "crackers".
"clam" belongs with "chowder".

How might we make use of this? Clearly it would be impractical to keep trying:

if "caviar" belongs with "aardvarks", ...
if "caviar" belongs with "abacuses", ...
...

to find out what "caviar" belongs with. It's still harder to find out if it belongs with anything at all – in theory we would have to try every possibility, which of course is impossible. Instead we have these phrases:

if (value) relates to (name of kind) by (relation of values to values):

This condition is true if the value V is such that V relates to something by the given relation. Example: suppose partnership relates various texts to various texts. Then we can test

if "chalk" relates to a text by the partnership relation, ...
if (name of kind) relates to (value) by (relation of values to values):

This condition is true if the value V is such that something relates to V by the given relation. Example: suppose partnership relates various texts to various texts. Then we can test

if a text relates to "cheese" by the partnership relation, ...

If a partner does exist, then we can find it with:

(name of kind) to which/whom (value) relates by (relation of values to values)value
or…
(name of kind) that/which/whom (value) relates to by (relation of values to values)value

This phrase produces an Y such that the given value V relates to Y by the given relation. Example: suppose partnership relates various texts to various texts. Then we can obtain

the text to which "chalk" relates by the partnership relation

which might be, say, "cheese". It's a run-time problem to use this if no such Y exists.

(name of kind) that/which/who relates to (value) by (relation of values to values)value

This phrase produces an X such that X relates to the given value V by the given relation. Example: suppose partnership relates various texts to various texts. Then we can obtain

the text which relates to "cheese" by the partnership relation

which might be, say, "chalk". It's a run-time problem to use this if no such X exists.

Of course, there might be many answers to this question, so perhaps these are neater:

list of (name of kind) that/which/who relate to (value) by (relation of values to values)value

This phrase produces a list of all the X such that X relates to the given value V by the given relation. Example: suppose partnership relates various texts to various texts. Then we can obtain

list of texts which relate to "cheese" by the partnership relation

which might be, say, { "chalk", "grapes", "macaroni" }. The answer might be the empty set, but that's not a problem.

list of (name of kind) to which/whom (value) relates by (relation of values to values)value
or…
list of (name of kind) that/which/whom (value) relates to by (relation of values to values)value

This phrase produces a list of all Y such that the given value V relates to Y by the given relation. Example: suppose partnership relates various texts to various texts. Then we can obtain

list of texts to which "chalk" relates by the partnership relation

which might be, say, { "cheese", "blackboard", "cliffs" }. The answer might be the empty set, but that's not a problem.

Finally, it's sometimes useful to get at the list of all values which can appear on the left or right hand side of a relation. We need tongue-twister like wording to do it, but:

list of (name of kind) that/which/whom (relation of values to values) relatesvalue

This phrase produces a list of all X which relate to anything under the given relation. Example: suppose partnership relates various texts to various texts. Then we can obtain

list of texts which the partnership relation relates
list of (name of kind) to which/whom (relation of values to values) relatesvalue
or…
list of (name of kind) that/which/whom (relation of values to values) relates tovalue

This phrase produces a list of all Y which anything relates to under the given relation. Example: suppose partnership relates various texts to various texts. Then we can obtain

list of texts which the partnership relation relates to

For efficiency reasons, there are no guarantees about what order these lists have – but they can of course always be sorted when found.

Examples

238.
A case in which relations give characters multiple values of the same kind.
A character who learns new actions by watching the player performing them.

As we've seen, most relations have names – "containment relation", for instance. These are themselves values in Inform, though there are a few restrictions on how they are used. (Relations can contain a colossal amount of data, so we don't want to have to copy them casually.)

Consider these two examples:

Parity relates a number (called N) to a number (called M) when N minus M is even.
Joint magnitude relates a number (called N) to a number (called M) when N plus M is greater than 7.

Here "parity relation" and "joint magnitude relation" are both values of the same kind: "relation of numbers to numbers". In general, every relation is a value of kind "relation of K to L", for the appropriate kinds K and L. So the parity relation doesn't have the same kind as the containment relation, for example. Because it often happens that K and L are the same, we can just say "relation of K" in this case, so we could equally say that the kind of the parity relation is "relation of numbers".

This is useful to know when writing phrases like so:

To chart (R - a relation of numbers):
   repeat with N running from 1 to 5:
      repeat with M running from 1 to 5:
         if R relates N to M, say "[N] <=> [M] ";
      say "[line break]";

and now "chart parity relation" will work nicely, but "chart visibility relation" will be rejected (as it should be, because it relates things, not numbers). In general, if R is any relation, we can write

if R relates X to Y, ...
now R relates X to Y;
now R does not relate X to Y;

to test, set and unset a relation R between two values. (Inform checks that the values X and Y have the right kind and produces a problem message if not.)

Several useful adjectives can be applied to relations:

"empty" - nothing relates to anything else
"symmetric" - by definition X relates to Y if and only if Y relates to X
"equivalence" - this is a relation "in groups", or an "equivalence relation"
"one-to-one" - it relates one K to one L
"one-to-various" - similarly
"various-to-one" - similarly
"various-to-various" - similarly

So for example it's possible to ask

if R is a symmetric one-to-one relation of texts, ...

With some relations, it's possible to clear them out by writing:

now R is empty;

and with temporary relations (see the next section), it's even possible to change their valencies (one-to-one vs. one-to-various, etc.) using "now", but only when they are empty. The exceptions where "empty" can't be used are those which can't be changed at all, like the parity relation above, and a few built-in cases such as the support, containment and incorporation relations, where emptying would dissolve the model world in a disastrous way.

Example

240.
The parity and joint magnitude relations explored.

So far in this chapter, we've only seen relations which exist permanently during play. The relationships might change – sometimes Red Riding Hood would be in the Woodcutter's Cottage, sometimes not – but the relations themselves were eternal.

In fact, though, we can also create relations to be dynamic data structures, like lists:

let (a name not so far used) be (description of relations of values to values)

This phrase creates a new temporary variable, and sets its value to the identity of a newly created and equally temporary relation. These last only for the present block of phrases, which certainly means that they exist only in the current rule. Example:

let the password dictionary be a relation of texts;

This makes a purely temporary various-to-various relation between texts, which lasts as long as the temporary value "password dictionary" lasts. By default, relations are various-to-various, but we could instead write, say:

let the nicknames catalogue be a various-to-one relation of texts;

Such a relation exists only in the current phrase, and is destroyed when the phrase finishes, like any other "let". Of course there's no verb whose meaning is this relation, but that's no obstacle, because we can manipulate it using "relates":

now the nicknames catalogue relates "Trudy" to "Snake-eyes";

(At present such a relation cannot be used outside its own phrase.)

It is easy to say what verbs are for: they are to express relations. But what are relations for?

Inform 7's focus on relations between objects is unusual as an approach to interactive fiction; the concept does not exist in most design systems, or rather, it does but is submerged. Traditional design systems do, after all, have the spatial relations of being inside, on top of, and so on. It could well be said that these are the only relationships that inanimate objects ever have. A stone can be on top of a table, and if so then that expresses their entire association.

This is because the stone, and the table, have no opinions, emotions, knowledge or memory. If the stone is taken away and then put back, nothing has changed. People, on the other hand, tend to remember having met each other before; they like being in some places, but not others; their behaviour depends on who, or what, is nearby. Being conscious, they have internal states, unlike the stone. Relations are a simple but powerful way to express and talk about such connections, and although they have numerous uses in physical contexts too, they are at their most powerful when helping to make the characters of interactive fiction come alive.

A note of caution: perfectly innocent conditionals involving relations can prove to be woefully inefficient in practice: testing a relationship among things may end up comparing a thing to every other thing. If that's occurring in multiple Every Turn rules and your things number in the hundreds, you may find your game slowing to a crawl. There can be dramatic differences that are impossible to anticipate. "If the first thing held by the box is nothing" is fast; "if there is nothing in the box" isn't terrible; "if nothing is in the box", however, can be very slow if there are a lot of objects in the game. In an ideal world, this would be beneath an author's concerns. In this world, it's a problem you could encounter in a large game. [TODO some statement of what to do about it? ]

See Also

Which and who for a review of things that can be done with relations, along with the remainder of the chapter on Descriptions.

Examples

A number of sleuths (the player among them) find themselves aboard the Orient Express, where a murder has taken place, and one of them is apparently the culprit. Naturally they do not agree on whom, but there is physical evidence which may change their minds…
242.
A general-purpose clothing system that handles a variety of different clothing items layered in different combinations over different areas of the body.
Some notes on relations from a mathematical point of view, provided only to clarify some technicalities for those who are interested.
Some notes on relations from the point of view of graph theory.

14. Adaptive Text and Responses

A conspicuous difference between interactive fiction and a traditional novel is the point of view from which it's told. Inform usually produces text like:

You can see a grey cat in the basket.

where a novel would usually write:

He saw a grey cat in the basket.

Standard interactive fiction (IF) is second person singular, and present tense; most novels are told in the third person singular, and past tense.

But these are just conventions – a few novels, for example, use the so-called present historic ("Napoleon looks up at the sky and sighs. Must Ney always be so doubting?"), and plenty are told in the first person singular ("I always get the shakes before a drop."). Inform allows some of this flexibility, too. The two values:

story viewpoint
story tense

control the style of the text produced. The story viewpoint has to be one of the values:

first person singular
second person singular
third person singular
first person plural
second person plural
third person plural

(which are actually the six possible values of a kind called "narrative viewpoint"), while the story tense must be one of:

past tense
present tense
future tense
perfect tense
past perfect tense

(from a kind called "grammatical tense"). Combining these gives 30 possibilities in all, though only a few are at all commonly used.

It's important to make a very large caveat here: Inform uses these settings in producing the replies ("responses") by the built-in actions, but the only way for all of our own text to have a particular tense or narrative viewpoint is to write it that way. If we write:

The Taj Mahal is a room. "You stand and admire the Taj Mahal."
When play begins:
   now the story viewpoint is first person plural;
   now the story tense is past tense.

then we're likely to see the following peculiar transcript:

Taj Mahal
You stand and admire the Taj Mahal.
>e
We couldn't go that way.

That's bec