9. Time

Writing with Inform

WI §9.1 When play begins

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.

WI §9.2 Awarding points

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.

WI §9.3 Introducing tables: rankings

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.

WI §9.4 When play ends

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.

WI §9.5 Every turn

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.

WI §9.6 The time of day

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.

WI §9.7 Telling the time

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.

WI §9.8 Approximate times, lengths of time

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.

WI §9.9 Comparing and shifting times

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.

WI §9.10 Calculating times

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.

WI §9.11 Future events

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.

WI §9.12 Actions as conditions

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.

WI §9.13 The past and perfect tenses

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.

WI §9.14 How many times?

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.

WI §9.15 How many turns?

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.