9 | |CENTER| *G was a gamester, who had but ill-luck;*
10 | |CENTER| *H was a hunter, and hunted a buck.*
14 .. image:: /images/picG.png
17 |G|\oing through the design of our first game in the previous chapter has
18 introduced all sorts of Inform concepts, often without giving you much
19 detail about what's been happening. So let's review some of what we've
20 learnt so far, in a slightly more organised fashion. We'll talk about
21 :ref:`const-var`, :ref:`object-defs`, :ref:`object-tree`,
22 :ref:`things-in-quotes` and :ref:`routines-statements`.
26 Constants and variables
27 =======================
29 Superficially similar, constants and variables are actually very different
35 A :term:`constant` is a name to which a value is given once and once only;
36 you can't later use that name to stand for a different value. Think of it
37 as a stone tablet on which you carve a number: a carving can't be undone,
38 so that you see the same number every time you look at the stone.
40 So far, we've seen a ``Constant`` being set up with its value as a string
43 Constant Story "Heidi";
47 Constant MAX_CARRIED 1;
49 Those two examples represent the most common ways in which constants are
55 A :term:`variable` is a name to which a value is given, but that value can
56 be changed to a different one at any time. Think of it as a blackboard on
57 which you mark a number in chalk: whenever you need to, just wipe the board
58 and write up a new number.
60 We haven't set up any variables of our own yet, though we've used a couple
61 which the library created like this::
66 The value of a :term:`global variable` created in this way is initially 0,
67 but you can change it at any time. For example, we used the statement::
69 location = before_cottage;
71 .. Generated by autoindex
73 pair: location; library variable
75 to reset the value of the :var:`location` variable to the
76 ``before_cottage`` object, and we wrote::
78 if (nest in branch) deadflag = 2;
80 to reset the value of the :var:`deadflag` variable to 2.
82 Later, we'll talk about the :term:`local variable` (see :ref:`routines`)
83 and about using object properties as variables (see :ref:`objects`).
90 The most important information you should have gleaned from the previous
91 chapter is that your entire game is defined as a series of objects. Each
92 room is an object, each item that the player sees and touches is an object;
93 indeed the player herself is also an object (one that's automatically
94 defined by the library).
98 The set-off below needs to be tweaked or perhaps a custom lexer
99 created to get italics in the right places.
101 The general model of an :term:`object` definition looks like this::
103 Object obj_id "external_name" parent_obj_id
104 with property value ,
108 has attribute attribute ... attribute
111 The definition starts with the word ``Object`` and ends with a semicolon;
112 in between are three major blocks of information:
114 * immediately after the word ``Object`` is the header information;
115 * the word ``with`` introduces the object's :term:`properties`;
116 * the word ``has`` introduces the object's :term:`attributes`.
121 An object header comprises up to three items, all optional:
123 * An internal ``obj_id`` by which other objects refer to this object. It's
124 a single word (though it can contain digits and underscores) of up to
125 thirty-two characters, and it must be unique within the game. You can
126 omit the ``obj_id`` if this object isn't referred to by any other
129 For example: ``bird``, ``tree``, ``top_of_tree``.
131 * An ``external_name``, in double quotes, which is what the interpreter
132 uses when referring to the object. It can be one or more words, and need
133 not be unique (for instance, you might have several ``"Somewhere in the
134 desert"`` rooms). Although not mandatory, it's best to give *every*
135 object an ``external_name``. For example: ``"baby bird"``, ``"tall
136 sycamore tree"``, ``"At the top of the tree"``.
138 * The internal ``obj_id`` of another object which is the initial location
139 of this object (its "parent" -- see the next section) at the start of the
140 game. This is omitted from objects which have no initial parent; it's
141 *always* omitted from a room.
143 For example: the definition of the ``bird`` starts like this, specifying
144 that at the start of the game, it can be found in the ``forest`` room
145 (though later the player character will pick it up and move it around)::
147 Object bird "baby bird" forest
150 The ``tree`` starts like this; the only real difference is that, because
151 the player character can't move a :attr:`scenery` object, it's always
152 going to be in the ``clearing``::
154 Object tree "tall sycamore tree" clearing
159 There's an alternative method for defining an object's initial
160 location, using "arrows" rather than the parent's internal ``obj_id``.
161 For example, the definition of the bird could have started like this::
163 Object -> bird "baby bird"
166 We don't use the arrows method in this guide, though we do describe
167 how it works in :ref:`setting-up-tree`.
172 An object's property definitions are introduced by the ``with`` keyword.
173 An object can have any number of properties, and they can be defined in any
174 order. Each definition has two parts: a name, and a value; there's a space
175 between the two parts, and a comma at the end.
177 Think of each property as a variable which is specifically associated with
178 that object. The variable's initial setting is the supplied value; if
179 necessary, it can be reset to other values during play (though in fact most
180 property values don't change in this way).
182 Here are examples of the properties that we've come across so far::
184 description "The nest is carefully woven of twigs and moss.",
186 name 'baby' 'bird' 'nestling',
187 each_turn [; if (nest in branch) deadflag = 2; ],
189 By happy coincidence, those examples also demonstrate most of the different
190 types of value which can be assigned to a property. The value associated
191 with the :prop:`description` property in this particular example is a
192 string of characters in double quotes; the value associated with this
193 :prop:`e_to` property is the internal identity of an object; the
194 :prop:`name` property is a bit unusual -- its value is a list of dictionary
195 words, each in single quotes; the :prop:`each_turn` property has a value
196 which is an :term:`embedded routine` (see :ref:`embedded-routines`). The
197 only other type of value which is commonly found is a simple number; for
202 In all, the library defines around forty-eight standard properties -- like
203 :prop:`name` and :prop:`each_turn` -- which you can associate with your
204 objects; there's a complete list in :ref:`object-props`. And in :doc:`08`
205 we show you how to invent your own property variables.
210 An object's attribute list is introduced by the ``has`` keyword. An object
211 can have any number of attributes, and they can be listed in any order,
212 with a space between each.
214 As with properties, you can think of each attribute as a variable which is
215 specifically associated with that object. However, an attribute is a much
216 more limited form of variable, since it can have only two possible states:
217 present, and absent (also known as set/clear, on/off, or true/false;
218 incidentally, a two-state variable like this is often called a
219 :term:`flag`). Initially, an attribute is either present (if you mention
220 its name in the list) or absent (otherwise); if necessary, its state can
221 change during play (and this is relatively common). We often say that a
222 certain object currently *has* a certain attribute, or that conversely it
225 The attributes that we've come across so far are::
227 container light open scenery static supporter
229 Each of those answers a question: Is this object a container? Does it
230 provide light? and so on. If the attribute is present then the answer is
231 Yes; if the attribute isn't present, the answer is No.
233 The library defines around thirty standard attributes, listed in
234 :ref:`object-attrs`. Although you *can* devise additional attributes --
235 see :ref:`common-props` -- in practice you seldom need to.
239 Object relationships -- the object tree
240 =======================================
242 Not only is your game composed entirely of objects, but also Inform takes
243 great care to keep track of the relationships between those objects. By
244 "relationship" we don't mean that Walter is Wilhelm's son, while Helga and
245 Wilhelm are just good friends; it's a much more comprehensive exercise in
246 recording exactly where each object is located, relative to the other
249 Despite what we just said, Inform relationships *are* managed in terms of
250 :term:`parent` and :term:`child` objects, though in a much broader sense
251 than Wilhelm and Walter. When the player character is in a particular room
252 -- for example the forest -- we can say that:
254 * the forest object is *the* parent of the player object, or alternatively
255 * the player object is *a* child of the forest object.
257 Also, if the player is carrying an object -- for example the nest -- we say
260 * the player object is *the* parent of the nest object, or that
261 * the nest object is *a* child of the player object.
263 Note the emphasis there: an object has exactly *one* parent (or no parent
264 at all), but can have *any number* of child objects (including none).
266 For an example of an object having more than one child, think about the way
267 we defined the nest and tree objects::
269 Object nest "bird's nest" clearing
272 Object tree "tall sycamore tree" clearing
275 We used the third of the header items to say that the clearing was the
276 parent of the nest, and also that the clearing was the parent of the tree;
277 that is, both nest and tree are child objects of the clearing.
281 A "room" isn't anything magical; it's just an object which *never* has a
282 parent, and which *may* from time to time have the player object as a
285 When we defined the bird, we placed it in the forest, like so::
287 Object bird "baby bird" forest
290 We didn't place any other objects in that room, so at the start of the game
291 the forest was the parent of the bird (and the bird was the only child of
292 the forest). But what happens when the player character, initially in the
293 ``before_cottage`` room, goes EAST to the forest? Answer: the player's
294 parent is now the forest, and the forest has two children -- the bird *and*
295 the player. This is a key principle of the way Inform manages its objects:
296 the parent--child relationships between objects change continuously, often
297 dramatically, as the game progresses.
299 Another example of this: suppose the player character picks up the bird.
300 This causes another change in the relationships. The bird is now a child
301 of the player (and *not* of the forest), and the player is both a parent
302 (of the bird) and a child (of the forest).
304 Here we show how the object relationships change during the course of the
305 game. The straight lines represent parent--child relationships, with the
306 parent object at the top of the line, and the child object at the bottom.
308 1. At the start of the game:
310 .. blockdiag:: /figures/heidiobj1.diag
314 2. The player types: ``GO EAST``
316 .. blockdiag:: /figures/heidiobj2.diag
320 3. The player types: ``TAKE THE BIRD``
322 .. blockdiag:: /figures/heidiobj3.diag
326 4. The player types: ``GO NORTHEAST``
328 .. blockdiag:: /figures/heidiobj4.diag
332 5. The player types: ``PUT BIRD IN NEST``
334 .. blockdiag:: /figures/heidiobj5.diag
338 6. The player types: ``TAKE NEST``
340 .. blockdiag:: /figures/heidiobj6.diag
344 7. The player types: ``UP``
346 .. blockdiag:: /figures/heidiobj7.diag
350 8. The player types: ``PUT NEST ON BRANCH``
352 .. blockdiag:: /figures/heidiobj8.diag
356 In this short example, we've taken a lot of time and space to spell out
357 exactly how the objects relationship patterns -- generally known as the
358 :term:`object tree` -- appear at each stage. Normally you wouldn't bother
359 with this much detail (a) because the interpreter does most of the work for
360 you, and (b) because in a real game there are usually too many objects for
361 you to keep track of. What's important is that you understand the basic
362 principles: at any moment in time an object either has no parent (which
363 probably means either that it's a room, or that it's floating in hyperspace
364 and not currently part of the game) or exactly one parent -- the object
365 that it's "in" or "on" or "a part of". However, there's no restriction on
366 the number of children that an object can have.
368 There's a practical use for these relationships, covered in detail further
369 on. As a designer, you can refer to the current parent or children of any
370 given object with the ``parent``, ``child`` and ``children`` routines, and
371 this is one feature that you will be using frequently. There are also
372 other routines associated with the object tree, to help you keep track of
373 the objects or move them around. We'll see them one by one in the next
374 chapters. For a quick summary, see :ref:`objects`.
376 .. _things-in-quotes:
381 Inform makes careful distinction between double and single quotes.
386 Double quotes ``"..."`` surround a :term:`string` -- a letter, a word, a
387 paragraph, or almost any number of characters -- which you want the
388 interpreter to display while the game is being played. You can use the
389 tilde ``~`` to represent a double quote inside the string, and the
390 circumflex ``^`` to represent a newline (line break) character. Upper-case
391 and lower-case letters are treated as different.
393 A long string can be split over several lines; Inform transforms each
394 line break (and any spaces around it) into a single space (extra spaces
395 *not* at a line break are preserved, though). These two strings are
398 "This is a string of characters."
405 When the interpreter displays a long character string -- for example, while
406 describing a feature-packed room -- it employs automatic word-wrapping to
407 fit the text to the player's screen. This is where you might insert ``^``
408 characters to force line breaks to appear, thus presenting the text as a
409 series of paragraphs. So far, we've seen strings used as the value of a
413 "^A simple Inform example
414 ^by Roger Firth and Sonja Kesserich.^";
416 which could equally have been defined thus::
419 "^A simple Inform example^by Roger Firth and Sonja Kesserich.^";
421 and as the value of an object :prop:`description` property::
423 description "Too young to fly, the nestling tweets helplessly.",
425 Later, you'll find that they're also very common in ``print`` statements.
430 Single quotes ``'...'`` surround a :term:`dictionary word`. This has to be
431 a single word -- no spaces -- and generally contains only letters (and
432 occasionally numbers and hyphens), though you can use ``^`` to represent an
433 apostrophe inside the word. Upper-case and lower-case letters are treated
434 as identical; also, the interpreter normally looks only at the first nine
435 characters of each word that the player types.
437 When the player types a command, the interpreter divides what was typed
438 into individual words, which it then looks up in the dictionary. If it
439 finds all the words, and they seem to represent a sensible course of
440 action, that's what happens next.
442 .. Generated by autoindex
444 pair: name; library property
446 So far, we've seen dictionary words used as the values of an object
447 :prop:`name` property::
449 name 'bird^s' 'nest' 'twigs' 'moss',
451 and indeed that's just about the only place where they commonly occur.
452 You'll save yourself a lot of confusion by remembering the distinction:
453 Double quotes for Output, Single quotes for Input (DOSI).
455 .. _routines-statements:
457 Routines and statements
458 =======================
460 A routine is a collection of statements, which are performed (or we often
461 say "are executed") at run-time by the interpreter. There are two types of
462 routine, and about two dozen types of statement (there's a complete list in
463 :ref:`statements`; see also :doc:`/appendices/e`).
468 A :term:`statement` is an instruction telling the interpreter to perform a
469 particular task -- to "do something" -- while the game is being played. A
470 real game usually has lots and lots of statements, but so far we've
471 encountered only a few. We saw::
473 location = before_cottage;
475 which is an example of an :term:`assignment` statement, so-called because
476 the equals sign ``=`` assigns a new value (the internal ID of our
477 ``before_cottage`` room) to a variable (the global variable :var:`location`
478 which is part of the library). Later we saw::
480 if (nest in branch) deadflag = 2;
482 which is actually *two* statements: an assignment, preceded by an ``if``
485 if (nest in branch) ...
487 The ``if`` statement tests a particular condition; if the condition is
488 true, the interpreter executes whatever statement comes next; if it isn't
489 true, the interpreter ignores the next statement. In this example, the
490 interpreter is testing whether the ``nest`` object is "in" or "on" (which
491 we now know means "is a child of") the ``branch`` object. For most of the
492 game, that condition is not true, and so the interpreter ignores the
493 following statement. Eventually, when the condition becomes true, the
494 interpreter executes that statement: it performs an assignment::
498 .. Generated by autoindex
500 pair: deadflag; library variable
502 which changes the value of the library variable :var:`deadflag` from its
503 current value to 2. Incidentally, ``if`` statements are often written
504 on two lines, with the "controlled" statement indented. This makes it
505 easier to read, but doesn't change the way that it works::
510 The thing that's being controlled by the ``if`` statement doesn't have to
511 be an assignment; it can be any kind of statement. In fact, you can have
512 lots of statements, not just one, controlled by an ``if`` statement. We'll
513 talk about these other possibilities later. For now, just remember that
514 the only place where you'll find statements are within standalone routines
515 and embedded routines.
517 .. _standalone-routines:
522 A :term:`standalone routine` is a series of statements, collected together
523 and given a name. When the routine is "called" -- by its given name --
524 those statements are executed. Here's the one that we've defined::
526 [ Initialise; location = before_cottage; ];
528 Because it's such a tiny routine, we placed it all on a single line. Let's
529 rewrite it to use several lines (as with the ``if`` statement, this improves
530 the readability, but doesn't affect how it works)::
533 location = before_cottage;
536 The ``[ Initialise;`` is the start of the routine, and defines the name by
537 which it can be "called". The ``];`` is the end of the routine. In
538 between are the statements -- sometimes known as the body of the routine --
539 which are executed when the routine is called. And how is that done? By a
540 statement like this::
544 That single statement, the routine's name followed by opening and closing
545 parentheses, is all that it takes to call a routine. When it comes across
546 a line like this, the interpreter executes the statements -- in this
547 example there's only one, but there may be ten, twenty, even a hundred of
548 them -- in the body of the routine. Having done that, the interpreter
549 resumes what it was doing, on the line following the ``Initialise();``
554 You may have noticed that, although we've defined a routine named
555 ``Initialise``, we've never actually called it. Don't worry -- the
556 routine *is* called, by the Inform library, right at the start of a
559 .. _embedded-routines:
564 An :term:`embedded routine` is much like a standalone routine, though it
565 doesn't have a name and doesn't end in a semicolon. This is the one that
568 [; if (nest in branch) deadflag = 2; ]
570 except that we didn't write it in isolation like that: instead, we defined
571 it to be the value of an object property::
573 each_turn [; if (nest in branch) deadflag = 2; ],
575 which would have worked just the same if we'd written it like this::
582 All embedded routines are defined in this manner: as the value of an object
583 property. That's where they're embedded -- inside an object. The
584 introductory characters ``[;`` maybe look a little odd, but it's really
585 only the same syntax as for a standalone routine, only without a name
586 between the ``[`` and ``;``.
588 For calling an embedded routine, thus causing the statements it contains to
589 be executed, the method that we described for a standalone routine won't
590 work. An embedded routine has no name, and needs none; it's
591 *automatically* called by the library at appropriate moments, which are
592 determined by the role of the property for which it is the value. In our
593 example, that's at the end of every turn in which the player character is
594 in the same room as the branch. Later, we'll see other examples of
595 embedded routines, each designed to perform a task which is appropriate for
596 the property whose value it is; we'll also see that it is possible to call
597 an embedded routine yourself, using an ``obj_id.property()`` syntax -- in
598 this example, we could call the routine by writing ``branch.each_turn()``.
599 There's more about these topics in :ref:`routines-args`,
600 :ref:`working-with-routines` and in :ref:`routines`.
602 That ends our review of the ground covered in our first game. We'll have
603 more to say about most of this later, but we're trying not to overload you
604 with facts at this early stage. What we'd like you to do is to look back
605 at the source of the game, and ensure that you can recognise all the
606 elements which this chapter has described. Then, we'll move on to fix a
607 few of the game's more important defects.