7 | *G was a gamester, who had but ill-luck;*
8 | *H was a hunter, and hunted a buck.*
10 .. image:: /images/picG.png
13 oing through the design of our first game in the previous chapter has
14 introduced all sorts of Inform concepts, often without giving you much
15 detail about what's been happening. So let's review some of what we've
16 learnt so far, in a slightly more organised fashion. We'll talk about
17 "Constants and variables" on page 49, "Object definitions" on page 50,
18 "Object relationships -- the object tree" on page 52, "Things in quotes" on
19 page 55, and "Routines and statements" on page 56.
21 Constants and variables
22 =======================
24 Superficially similar, constants and variables are actually very different
29 A **constant** is a name to which a value is given once and once only; you
30 can't later use that name to stand for a different value. Think of it as a
31 stone tablet on which you carve a number: a carving can't be undone, so
32 that you see the same number every time you look at the stone.
34 So far, we've seen a ``Constant`` being set up with its value as a string
37 Constant Story "Heidi";
41 Constant MAX_CARRIED 1;
43 Those two examples represent the most common ways in which constants are
48 A **variable** is a name to which a value is given, but that value can be
49 changed to a different one at any time. Think of it as a blackboard on
50 which you mark a number in chalk: whenever you need to, just wipe the board
51 and write up a new number.
53 We haven't set up any variables of our own yet, though we've used a couple
54 which the library created like this::
59 The value of a **global variable** created in this way is initially 0, but
60 you can change it at any time. For example, we used the statement::
62 location = before_cottage;
64 to reset the value of the location variable to the ``before_cottage``
65 object, and we wrote::
67 if (nest in branch) deadflag = 2;
69 to reset the value of the ``deadflag`` variable to 2.
71 Later, we'll talk about the **local variable** (see "Routines" on page 179)
72 and about using object properties as variables (see "Objects" on page 177).
77 The most important information you should have gleaned from the previous
78 chapter is that your entire game is defined as a series of objects. Each
79 room is an object, each item that the player sees and touches is an object;
80 indeed the player herself is also an object (one that's automatically
81 defined by the library).
83 The general model of an **object** definition looks like this::
85 Object obj_id "external_name" parent_obj_id
90 has attribute attribute ... attribute
93 The definition starts with the word ``Object`` and ends with a semicolon;
94 in between are three major blocks of information:
96 * immediately after the word ``Object`` is the header information;
97 * the word ``with`` introduces the object's **properties**;
98 * the word ``has`` introduces the object's **attributes**.
100 .. rubric:: Object headers
102 An object header comprises up to three items, all optional:
104 * An internal ``obj_id`` by which other objects refer to this object. It's
105 a single word (though it can contain digits and underscores) of up to
106 thirty-two characters, and it must be unique within the game. You can
107 omit the ``obj_id`` if this object isn't referred to by any other
110 For example: ``bird``, ``tree``, ``top_of_tree``.
112 * An ``external_name``, in double quotes, which is what the interpreter
113 uses when referring to the object. It can be one or more words, and need
114 not be unique (for instance, you might have several ``"Somewhere in the
115 desert"`` rooms). Although not mandatory, it's best to give *every*
116 object an ``external_name``. For example: ``"baby bird"``, ``"tall
117 sycamore tree"``, ``"At the top of the tree"``.
119 * The internal ``obj_id`` of another object which is the initial location
120 of this object (its "parent" -- see the next section) at the start of the
121 game. This is omitted from objects which have no initial parent; it's
122 *always* omitted from a room.
124 For example: the definition of the ``bird`` starts like this, specifying
125 that at the start of the game, it can be found in the ``forest`` room
126 (though later the player character will pick it up and move it around)::
128 Object bird "baby bird" forest
131 The ``tree`` starts like this; the only real difference is that, because
132 the player character can't move a ``scenery`` object, it's always going
133 to be in the ``clearing``::
135 Object tree "tall sycamore tree" clearing
140 There's an alternative method for defining an object's initial
141 location, using "arrows" rather than the parent's internal ``obj_id``.
142 For example, the definition of the bird could have started like this::
144 Object -> bird "baby bird"
147 We don't use the arrows method in this guide, though we do describe
148 how it works in "Setting up the object tree" on page 185.
150 .. rubric:: Object properties
152 An object's property definitions are introduced by the ``with`` keyword.
153 An object can have any number of properties, and they can be defined in any
154 order. Each definition has two parts: a name, and a value; there's a space
155 between the two parts, and a comma at the end.
157 Think of each property as a variable which is specifically associated with
158 that object. The variable's initial setting is the supplied value; if
159 necessary, it can be reset to other values during play (though in fact most
160 property values don't change in this way).
162 Here are examples of the properties that we've come across so far::
164 description "The nest is carefully woven of twigs and moss.",
166 name 'baby' 'bird' 'nestling',
167 each_turn [; if (nest in branch) deadflag = 2; ],
169 By happy coincidence, those examples also demonstrate most of the different
170 types of value which can be assigned to a property. The value associated
171 with the ``description`` property in this particular example is a string of
172 characters in double quotes; the value associated with this ``e_to``
173 property is the internal identity of an object; the ``name`` property is a
174 bit unusual -- its value is a list of dictionary words, each in single
175 quotes; the ``each_turn`` property has a value which is an **embedded
176 routine** (see "Embedded routines" on page 58). The only other type of
177 value which is commonly found is a simple number; for example::
181 In all, the library defines around forty-eight standard properties -- like
182 ``name`` and ``each_turn`` -- which you can associate with your objects;
183 there's a complete list in "Object properties" on page 266. And in
184 "William Tell: in his prime" on page 91 we show you how to invent your own
187 .. rubric:: Object attributes
189 An object's attribute list is introduced by the ``has`` keyword. An object
190 can have any number of attributes, and they can be listed in any order,
191 with a space between each.
193 As with properties, you can think of each attribute as a variable which is
194 specifically associated with that object. However, an attribute is a much
195 more limited form of variable, since it can have only two possible states:
196 present, and absent (also known as set/clear, on/off, or true/false;
197 incidentally, a two-state variable like this is often called a **flag**).
198 Initially, an attribute is either present (if you mention its name in the
199 list) or absent (otherwise); if necessary, its state can change during play
200 (and this is relatively common). We often say that a certain object
201 currently *has* a certain attribute, or that conversely it *hasn't* got it.
203 The attributes that we've come across so far are::
205 container light open scenery static supporter
207 Each of those answers a question: Is this object a container? Does it
208 provide light? and so on. If the attribute is present then the answer is
209 Yes; if the attribute isn't present, the answer is No.
211 The library defines around thirty standard attributes, listed in "Object
212 attributes" on page 269. Although you *can* devise additional attributes
213 -- see "Common properties and attributes" on page 185 -- in practice you
216 Object relationships -- the object tree
217 =======================================
219 Not only is your game composed entirely of objects, but also Inform takes
220 great care to keep track of the relationships between those objects. By
221 "relationship" we don't mean that Walter is Wilhelm's son, while Helga and
222 Wilhelm are just good friends; it's a much more comprehensive exercise in
223 recording exactly where each object is located, relative to the other
226 Despite what we just said, Inform relationships *are* managed in terms of
227 **parent** and **child** objects, though in a much broader sense than
228 Wilhelm and Walter. When the player character is in a particular room --
229 for example the forest -- we can say that:
231 * the forest object is *the* parent of the player object, or alternatively
232 * the player object is *a* child of the forest object.
234 Also, if the player is carrying an object -- for example the nest -- we say
237 * the player object is *the* parent of the nest object, or that
238 * the nest object is *a* child of the player object.
240 Note the emphasis there: an object has exactly *one* parent (or no parent
241 at all), but can have *any number* of child objects (including none).
243 For an example of an object having more than one child, think about the way
244 we defined the nest and tree objects::
246 Object nest "bird's nest" clearing
249 Object tree "tall sycamore tree" clearing
252 We used the third of the header items to say that the clearing was the
253 parent of the nest, and also that the clearing was the parent of the tree;
254 that is, both nest and tree are child objects of the clearing.
258 A "room" isn't anything magical; it's just an object which *never* has a
259 parent, and which *may* from time to time have the player object as a
262 When we defined the bird, we placed it in the forest, like so::
264 Object bird "baby bird" forest
267 We didn't place any other objects in that room, so at the start of the game
268 the forest was the parent of the bird (and the bird was the only child of
269 the forest). But what happens when the player character, initially in the
270 ``before_cottage`` room, goes EAST to the forest? Answer: the player's
271 parent is now the forest, and the forest has two children -- the bird *and*
272 the player. This is a key principle of the way Inform manages its objects:
273 the parent--child relationships between objects change continuously, often
274 dramatically, as the game progresses.
276 Another example of this: suppose the player character picks up the bird.
277 This causes another change in the relationships. The bird is now a child
278 of the player (and *not* of the forest), and the player is both a parent
279 (of the bird) and a child (of the forest).
281 In this diagram, we show how the object relationships change during the
282 course of the game. The straight lines represent parent--child
283 relationships, with the parent object at the top of the line, and the child
284 object at the bottom.
290 - At the start of the game:
291 - .. image:: /images/heidiobj1.*
294 - The player types: ``GO EAST``
295 - .. image:: /images/heidiobj2.*
298 - The player types: ``TAKE THE BIRD``
299 - .. image:: /images/heidiobj3.*
302 - The player types: ``GO NORTHEAST``
303 - .. image:: /images/heidiobj4.*
306 - The player types: ``PUT BIRD IN NEST``
307 - .. image:: /images/heidiobj5.*
310 - The player types: ``TAKE NEST``
311 - .. image:: /images/heidiobj6.*
314 - The player types: ``UP``
315 - .. image:: /images/heidiobj7.*
318 - The player types: ``PUT NEST ON BRANCH``
319 - .. image:: /images/heidiobj8.*
321 In this short example, we've taken a lot of time and space to spell out
322 exactly how the objects relationship patterns -- generally known as the
323 **object tree** -- appear at each stage. Normally you wouldn't bother with
324 this much detail (a) because the interpreter does most of the work for you,
325 and (b) because in a real game there are usually too many objects for you
326 to keep track of. What's important is that you understand the basic
327 principles: at any moment in time an object either has no parent (which
328 probably means either that it's a room, or that it's floating in hyperspace
329 and not currently part of the game) or exactly one parent -- the object
330 that it's "in" or "on" or "a part of". However, there's no restriction on
331 the number of children that an object can have.
333 There's a practical use for these relationships, covered in detail further
334 on. As a designer, you can refer to the current parent or children of any
335 given object with the ``parent``, ``child`` and ``children`` routines, and
336 this is one feature that you will be using frequently. There are also
337 other routines associated with the object tree, to help you keep track of
338 the objects or move them around. We'll see them one by one in the next
339 chapters. For a quick summary, see "Objects" on page 177.
344 Inform makes careful distinction between double and single quotes.
346 .. rubric:: Double quotes
348 Double quotes "..." surround a **string** -- a letter, a word, a paragraph,
349 or almost any number of characters -- which you want the interpreter to
350 display while the game is being played. You can use the tilde ``~`` to
351 represent a double quote inside the string, and the circumflex ``^`` to
352 represent a newline (line break) character. Upper-case and lower-case
353 letters are treated as different.
355 A long string can be split over several lines; Inform transforms each line
356 break (and any spaces around it) into a single space (extra spaces not at a
357 line break are preserved, though). These two strings are equivalent::
359 "This is a string of characters."
366 When the interpreter displays a long character string -- for example, while
367 describing a feature-packed room -- it employs automatic word-wrapping to
368 fit the text to the player's screen. This is where you might insert ``^``
369 characters to force line breaks to appear, thus presenting the text as a
370 series of paragraphs. So far, we've seen strings used as the value of a
374 "^A simple Inform example
375 ^by Roger Firth and Sonja Kesserich.^";
377 which could equally have been defined thus::
380 "^A simple Inform example^by Roger Firth and Sonja Kesserich.^";
382 and as the value of an object description property::
384 description "Too young to fly, the nestling tweets helplessly.",
386 Later, you'll find that they're also very common in ``print`` statements.
388 .. rubric:: Single quotes
390 Single quotes '...' surround a **dictionary word**. This has to be a
391 single word -- no spaces -- and generally contains only letters (and
392 occasionally numbers and hyphens), though you can use ``^`` to represent an
393 apostrophe inside the word. Upper-case and lower-case letters are treated
394 as identical; also, the interpreter normally looks only at the first nine
395 characters of each word that the player types.
397 When the player types a command, the interpreter divides what was typed
398 into individual words, which it then looks up in the dictionary. If it
399 finds all the words, and they seem to represent a sensible course of
400 action, that's what happens next.
402 So far, we've seen dictionary words used as the values of an object
405 name 'bird^s' 'nest' 'twigs' 'moss',
407 and indeed that's just about the only place where they commonly occur.
408 You'll save yourself a lot of confusion by remembering the distinction:
409 Double quotes for Output, Single quotes for Input (DOSI).
411 Routines and statements
412 =======================
414 A routine is a collection of statements, which are performed (or we often
415 say "are executed") at run-time by the interpreter. There are two types of
416 routine, and about two dozen types of statement (there's a complete list in
417 "Statements" on page 174; see also "Inform language" on page 257).
419 .. rubric:: Statements
421 A **statement** is an instruction telling the interpreter to perform a
422 particular task -- to "do something" -- while the game is being played. A
423 real game usually has lots and lots of statements, but so far we've
424 encountered only a few. We saw::
426 location = before_cottage;
428 which is an example of an **assignment** statement, so-called because the
429 equals sign ``=`` assigns a new value (the internal ID of our
430 ``before_cottage`` room) to a variable (the global variable ``location``
431 which is part of the library). Later we saw::
433 if (nest in branch) deadflag = 2;
435 which is actually *two* statements: an assignment, preceded by an ``if``
438 if (nest in branch) ...
440 The ``if`` statement tests a particular condition; if the condition is
441 true, the interpreter executes whatever statement comes next; if it isn't
442 true, the interpreter ignores the next statement. In this example, the
443 interpreter is testing whether the ``nest`` object is "in" or "on" (which
444 we now know means "is a child of") the ``branch`` object. For most of the
445 game, that condition is not true, and so the interpreter ignores the
446 following statement. Eventually, when the condition becomes true, the
447 interpreter executes that statement: it performs an assignment::
451 which changes the value of the library variable ``deadflag`` from its
452 current value to 2. Incidentally, if statements are often written on two
453 lines, with the "controlled" statement indented. This makes it easier to
454 read, but doesn't change the way that it works::
459 The thing that's being controlled by the ``if`` statement doesn't have to
460 be an assignment; it can be any kind of statement. In fact, you can have
461 lots of statements, not just one, controlled by an ``if`` statement. We'll
462 talk about these other possibilities later. For now, just remember that
463 the only place where you'll find statements are within standalone routines
464 and embedded routines.
466 .. rubric:: Standalone routines
468 A **standalone routine** is a series of statements, collected together and
469 given a name. When the routine is "called" -- by its given name -- those
470 statements are executed. Here's the one that we've defined::
472 [ Initialise; location = before_cottage; ];
474 Because it's such a tiny routine, we placed it all on a single line. Let's
475 rewrite it to use several lines (as with the ``if`` statement, this improves
476 the readability, but doesn't affect how it works)::
479 location = before_cottage;
482 The ``[ Initialise;`` is the start of the routine, and defines the name by
483 which it can be "called". The ``];`` is the end of the routine. In
484 between are the statements -- sometimes known as the body of the routine --
485 which are executed when the routine is called. And how is that done? By a
486 statement like this::
490 That single statement, the routine's name followed by opening and closing
491 parentheses, is all that it takes to call a routine. When it comes across
492 a line like this, the interpreter executes the statements -- in this
493 example there's only one, but there may be ten, twenty, even a hundred of
494 them -- in the body of the routine. Having done that, the interpreter
495 resumes what it was doing, on the line following the ``Initialise();``
500 You may have noticed that, although we've defined a routine named
501 ``Initialise``, we've never actually called it. Don't worry -- the
502 routine is called, by the Inform library, right at the start of a game.
504 .. rubric:: Embedded routines
506 An **embedded routine** is much like a standalone routine, though it
507 doesn't have a name and doesn't end in a semicolon. This is the one that
510 [; if (nest in branch) deadflag = 2; ]
512 except that we didn't write it in isolation like that: instead, we defined
513 it to be the value of an object property::
515 each_turn [; if (nest in branch) deadflag = 2; ],
517 which would have worked just the same if we'd written it like this::
524 All embedded routines are defined in this manner: as the value of an object
525 property. That's where they're embedded -- inside an object. The
526 introductory characters ``[;`` maybe look a little odd, but it's really
527 only the same syntax as for a standalone routine, only without a name
528 between the ``[`` and ``;``.
530 For calling an embedded routine, thus causing the statements it contains to
531 be executed, the method that we described for a standalone routine won't
532 work. An embedded routine has no name, and needs none; it's
533 *automatically* called by the library at appropriate moments, which are
534 determined by the role of the property for which it is the value. In our
535 example, that's at the end of every turn in which the player character is
536 in the same room as the branch. Later, we'll see other examples of
537 embedded routines, each designed to perform a task which is appropriate for
538 the property whose value it is; we'll also see that it is possible to call
539 an embedded routine yourself, using an ``obj_id.property()`` syntax -- in
540 this example, we could call the routine by writing ``branch.each_turn()``.
541 There's more about these topics in "Routines and arguments" on page 67, "A
542 diversion: working with routines" on page 104 and in "Routines" on
545 That ends our review of the ground covered in our first game. We'll have
546 more to say about most of this later, but we're trying not to overload you
547 with facts at this early stage. What we'd like you to do is to look back
548 at the source of the game, and ensure that you can recognise all the
549 elements which this chapter has described. Then, we'll move on to fix a
550 few of the game's more important defects.