## §4 ‘Ruins’ begun

This chapter introduces five fundamentals of Inform: how to construct games; messages, classes and actions; and how to debug games. Chapter III then makes a systematic exploration of the model world available to Inform games. Throughout both chapters, examples gradually build up a modest game called ‘Ruins’, a tale of Central American archaeology in the 1930s. Here is its first state:

    Constant Story "RUINS";
    Constant Headline "^An Interactive Worked Example^
                 Copyright (c) 1999 by Angela M. Horns.^";
    Include "Parser";
    Include "VerbLib";
    Object Forest "~Great Plaza~"
     with description
              "Or so your notes call this low escarpment of limestone,
              but the rainforest has claimed it back. Dark olive
              trees crowd in on all sides, the air steams with the
              mist of a warm recent rain, midges hang in the air.
              ~Structure 10~ is a shambles of masonry which might
              once have been a burial pyramid, and little survives
              except stone-cut steps leading down into darkness below.",
    has  light;
    [ Initialise;
      location = Forest;
      "^^^Days of searching, days of thirsty hacking through the briars of
      the forest, but at last your patience was rewarded. A discovery!^";
    ];
    Include "Grammar";

If you can compile this tiny beginning successfully, Inform is probably set up and working properly on your computer. Compilation may take a few seconds, because although you have only written twenty lines or so, the `Include` directives paste in another seven and a half thousand. This is “the Library”, a computer program which acts as umpire during play. The library is divided into three parts:

`Parser` which decodes what the player types;
`VerbLib` how actions, like “take” or “go north”, work;
`Grammar` the verbs and phrases which the game understands.

It does matter what order the three lines beginning with `Include` come in, and it sometimes matters where your own code goes with respect to them: objects shouldn't be declared until after the inclusion of the parser, for instance. For now, follow the structure above, with everything interesting placed between the inclusions of `VerbLib` and `Grammar`.

▲ Chapter I above said that every Inform program had to contain a routine called `Main`. Games like ‘Ruins’ are no exception, but their `Main` routine is part of the library, so that game designers do not need to write a `Main`.

· · · · ·

The two constants at the beginning are text giving the game's name and copyright message, which the library needs in order to print out the “banner” announcing the game. Similarly, the library expects to find a routine named `Initialise` somewhere in your source code. This routine is called when the game starts up, and is expected to carry out any last setting-up operations before play begins. In most games, it also prints up a ‘welcome’ message, but the one thing it has to do is to set the `location` variable to the place where the player begins. And this means that every game has to declare at least one object, too: the room where the player begins.

▲ In this book places are often called “rooms” even when outdoors (like `Forest`) or underground. This goes back at least to Stephen Bishop's 1842 map of the Mammoth and Flint Ridge cave system of Kentucky, which was the setting of the first adventure game, ‘Advent’, also called ‘Colossal Cave’ (c.1975). The author, Will Crowther, was a caver and used the word “room” in its caving sense. Don Woods, who recast the game in 1976–7, confused the word further with its everyday sense. Players of adventure games continue to call locations “rooms” to this day.

· · · · ·

‘Ruins’ is at this stage an exceedingly dull game:

Days of searching, days of thirsty hacking through the briars of the forest, but at last your patience was rewarded. A discovery!

RUINS
An Interactive Worked Example
Copyright (c) 1998 by Angela M. Horns.
Release 1 / Serial number 990220 / Inform v6.20 Library 6/8

“Great Plaza”
Or so your notes call this low escarpment of limestone, but the rainforest has claimed it back. Dark olive trees crowd in on all sides, the air steams with the mist of a warm recent rain, midges hang in the air. “Structure 10” is a shambles of masonry which might once have been a burial pyramid, and little survives except stone-cut steps leading down into darkness below.
>`inventory`
You are carrying nothing.
>`north`
You can't go that way.
>`wait`
Time passes.
>`quit`
Are you sure you want to quit? `yes`

· · · · ·

In an Inform game, objects are used to simulate everything: rooms and items to be picked up, scenery, the player, intangible things like mist and even some abstract ideas, like the direction “north” or the idea of “darkness”. The library itself is present as an object, called `InformLibrary`, though like the concept of “north” it cannot be picked up or visited during play. All told, ‘Ruins’ already contains twenty-four objects.

It is time to add something tangible, by writing the following just after the definition of `Forest`:

    Object -> mushroom "speckled mushroom"
      with name 'speckled' 'mushroom' 'fungus' 'toadstool';

The arrow `->` means that the mushroom begins inside the previous object, which is to say, the `Forest`. If the game is recompiled, the mushroom is now in play: the player can call it “speckled mushroom”, “mushroom”, “toadstool” and so on. It can be taken, dropped, looked at, looked under and so on. However, it only adds the rather plain line “There is a speckled mushroom here.” to the Forest's description. Here is a more decorative species:

    Object -> mushroom "speckled mushroom"
      with name 'speckled' 'mushroom' 'fungus' 'toadstool',
           initial
               "A speckled mushroom grows out of the sodden earth, on
               a long stalk.";

The `initial` message is used to tell the player about the mushroom when the Forest is described. (Once the mushroom has been picked or moved, the message is no longer used: hence the name ‘initial’.) The mushroom is, however, still “nothing special” when the player asks to “look at” or “examine” it. To provide a more interesting close-up view, we must give the mushroom its own `description`:

    Object -> mushroom "speckled mushroom"
      with name 'speckled' 'mushroom' 'fungus' 'toadstool',
           initial
               "A speckled mushroom grows out of the sodden earth, on
               a long stalk.",
           description
               "The mushroom is capped with blotches, and you aren't
               at all sure it's not a toadstool.",
      has  edible;

Now if we examine the mushroom, as is always wise, we get a cautionary hint. But the edible notation means that it can be eaten, so that for the first time the player can change the game state irrevocably: from a game with a forest and a mushroom into a game with just a forest.

The mushroom shows the two kinds of feature something can have: a “property” with some definite value or list of values and an “attribute”, which is either present or not but has no particular value. `name`, `initial` and `description` are all properties, while `light` and `edible` are attributes. The current state of these properties changes during play: for instance, it can be changed by code like the following.

    mushroom.description = "You're sure it's a toadstool now.";
    give mushroom light;
    if (mushroom has edible) print "It's definitely edible.^";

`light` is the attribute for “giving off light”. The `Forest` was defined as having `light` on account of daylight, so it doesn't much matter whether or not the mushroom has `light`, but for the sake of botanical verisimilitude it won't have `light` in the final game.

· · · · ·

Declaring objects has so far been a matter of filling in forms: fill some text into the box marked `description`, and so on. We could go much further like this, but for the sake of example it's time to add some rules:

    after [;
        Take: "You pick the mushroom, neatly cleaving its thin stalk.";
        Drop: "The mushroom drops to the ground, battered slightly.";
    ],

The property `after` doesn't just have a string for a value: it has a routine of its own. What happens is that after something happens to the mushroom, the library asks the mushroom if it would like to react in some way. In this case, it reacts only to `Take` and `Drop`, and the only effect is that the usual messages (“Taken.” “Dropped.”) are replaced by new ones. (It doesn't react to `Eat`, so nothing out of the ordinary happens when it's eaten.) ‘Ruins’ can now manage a briefly plausible dialogue:

“Great Plaza”
Or so your notes call this low escarpment of limestone, but the rainforest has claimed it back. Dark olive trees crowd in on all sides, the air steams with the mist of a warm recent rain, midges hang in the air. “Structure 10” is a shambles of masonry which might once have been a burial pyramid, and little survives except stone-cut steps leading down into darkness below.
A speckled mushroom grows out of the sodden earth, on a long stalk.
>`get mushroom`
You pick the mushroom, neatly cleaving its thin stalk.
>`look at it`
The mushroom is capped with blotches, and you aren't at all sure it's not a toadstool.
>`drop it`
The mushroom drops to the ground, battered slightly.

▲ Gareth Rees persuasively advocates writing this sort of transcript, of an ideal sequence of play, first, and worrying about how to code up the design afterwards. Other designers prefer to build from the bottom up, crafting the objects one at a time and finally bringing them together into the narrative.

· · · · ·

The mushroom is a little more convincing now, but still does nothing. Here is a more substantial new rule:

    before [;
        Eat: if (random(100) <= 30) {
                 deadflag = true;
                 "The tiniest nibble is enough. It was a toadstool,
                 and a poisoned one at that!";
             }
             "You nibble at one corner, but the curious taste
             repels you.";
    ],

The library consults `before` just before the player's intended action would take place. So when the player tries typing, say, “eat the mushroom", what happens is: in 30% of cases, death by toadstool poisoning; and in the other 70%, a nibble of a corner of fungus, without consuming it completely.

Like `location`, `deadflag` is a variable belonging to the library. It's normally `false`, meaning that the player is still alive and playing. Setting it to `true` thus kills the player. (Setting it to 2 causes the player to win the game and there are other uses: see §21.)

If the “tiniest nibble” text is printed, the rule ends there, and does not flow on into the second “You nibble at” text. So one and only one message is printed. Here is how this is achieved: although it's not obvious from the look of the program, the `before` routine is being asked the question “Do you want to interfere with the usual rules?”. It must reply, that is, return, either `true` or `false` meaning yes or no. Because this question is asked and answered many times in a large Inform game, there are several abbreviations for how to reply. For example,

`return true;` and `rtrue;`

both do the same thing. Moreover,

    print_ret "The tiniest nibble... ...at that!";

performs three useful tasks: prints the message, then prints a carriage return, and then returns `true`. And this is so useful that a bare string

    "The tiniest nibble... ...at that!";

is understood to mean the same thing. To print the text without returning, the statement `print` has to be written out in full. Here is an example:

    before [;
        Taste: print "You extend your tongue nervously.^";
            rfalse;
    ];

In this rule, the text is printed, but the answer to “Do you want to interfere?” is no, so the game will then go on to print something anodyne like “You taste nothing unexpected.” (In fact the `rfalse` was unnecessary, because if a rule like this never makes any decision, then the answer is assumed to be false.)

• EXERCISE 1
The present `after` routine for the mushroom is misleading, because it says the mushroom has been picked every time it's taken (which will be odd if it's taken, dropped then taken again). Correct this.

· · · · ·

The following example of “form-filling” is typical of the way that the library provides for several standard kinds of object. This one is a kind of door, which will be gone into properly in §13, but for now suffice to say that a door doesn't literally have to be a door: it can be any object which comes in between where the player is and where the player can go. Because the object is also marked as `scenery` (see §8), it isn't given any special paragraph of description when the Forest is described. Finally, it is marked as `static` to prevent the player from being able to pick it up and walk off with it.

    Object -> steps "stone-cut steps"
      with name 'steps' 'stone' 'stairs' 'stone-cut' 'pyramid' 'burial'
                'structure' 'ten' '10',
           description
               "The cracked and worn steps descend into a dim chamber.
               Yours might be the first feet to tread them for five
               hundred years.",
           door_to Square_Chamber,
           door_dir d_to
      has  scenery static door open;

We also need to add a new line to the Forest's definition to tell it that the way down is by these steps:

    Object Forest "~Great Plaza~"
           ...
           d_to steps,

Now “examine structure 10”, “enter stone-cut pyramid” and so forth will all work.

• EXERCISE 2
Except of course that now ‘Ruins’ won't compile, because Inform expects to find a room called `Square_Chamber` which the steps lead to. Design one.