Add illuminated letters to some sections.
[ibg.git] / chapters / 03.rst
1 ==============================
2  Heidi: our first Inform game
3 ==============================
4
5 .. epigraph::
6
7    | *E was an esquire, with pride on his brow;*
8    | *F was a farmer, and followed the plough.*
9
10 .. image:: /images/picE.png
11    :align: left
12
13 ach of the three games in this guide is created step by step; you'll get
14 most benefit (especially to begin with) if you take an active part, typing
15 in the source code on your computer.  Our first game, described in this
16 chapter and the two which follow, tells this sentimental little story:
17
18     "Heidi lives in a tiny cottage deep in the forest.  One sunny day,
19     standing before the cottage, she hears the frenzied tweeting of baby
20     bird; its nest has fallen from the tall tree in the clearing!  Heidi
21     puts the bird into the nest, and then climbs the tree to place the nest
22     back on its branch."
23
24 It's a very simple tale, but even so we'll cover quite a lot of ground
25 before we have a finished Inform game.  We'll get there in stages, first
26 making a very rough approximation of the story, and then successively
27 refining the details until it's good enough for an initial attempt (there's
28 time later for more advanced stuff).
29
30 Creating a basic source file
31 ============================
32
33 The first task is to create an Inform source file template.  Every game
34 that we design will start out like this.  Follow these steps:
35
36 #. Create an ``Inform\Games\Heidi`` folder (maybe by copying ``Inform\Games\MyGame1``).
37
38    .. note::
39
40       In this guide, we use the PC convention of placing a backslash
41       between folder names.  On a Macintosh, use a regular slash:
42       ``Inform/Games/Heidi``.
43
44 #. In that folder, use your text editor to create this source file
45    ``Heidi.inf``:
46
47    .. code-block:: inform6
48
49       !% -SD
50       !============================================================================
51       Constant Story "Heidi";
52       Constant Headline
53                   "^A simple Inform example
54                    ^by Roger Firth and Sonja Kesserich.^";
55
56       Include "Parser";
57       Include "VerbLib";
58
59       !============================================================================
60       ! The game objects
61
62       !============================================================================
63       ! Entry point routines
64
65       [ Initialise; ];
66
67       !============================================================================
68       ! Standard and extended grammar
69
70       Include "Grammar";
71
72       !============================================================================
73
74    Soon, we'll explain what this means.  For now, just type it all in,
75    paying particular attention to those seven semicolons, and ensuring that
76    the double quotes "..." always come in pairs.  The first line beginning
77    with "``!%``" is special, and we'll talk about it in a moment; the
78    remaining exclamation mark lines, on the other hand, are purely
79    decorative; they just make the file's structure a little easier to
80    understand.
81
82    Ensure the file is named ``Heidi.inf``, rather than ``Heidi.txt`` or
83    ``Heidi.inf.txt``.
84
85    Remember that, throughout this guide, we place the "TYPE" symbol
86    alongside pieces of code that we recommend you to type into your own
87    game files as you read through the examples (which, conversely, means
88    that you don't need to type the unmarked pieces of code).  You'll learn
89    Inform more quickly by trying it for yourself, rather than just taking
90    our word for how things work.
91
92    .. todo::
93
94       Again, revisit the TYPE symbol.  Maybe a standard indicator above
95       each snippet?
96
97 #. In the same folder, use your text editor to create the compilation
98    support file ``Heidi.bat`` (on a PC)::
99
100        ..\..\Lib\Base\Inform Heidi
101                    +include_path=.\,..\..\Lib\Base,..\..\Lib\Contrib | more
102
103        pause "at end of compilation"
104
105    or ``Heidi.command`` (on a Macintosh)::
106
107        cd ~/Inform/Games/Heidi/
108
109        ../../Lib/Base/inform30_macosx Heidi
110                        +include_path=./,../../Lib/Base,../../Lib/Contrib
111
112    Remember that there's just one space between "``Heidi``" and
113    "``+include_path``".
114
115    Type in the file from scratch, or copy and edit ``MyGame1.bat`` (or
116    ``MyGame1.command``).  At this point, you should have a ``Heidi`` folder
117    containing two files: ``Heidi.inf`` and either ``Heidi.bat`` or
118    ``Heidi.command``.
119
120 #. Compile the source file ``Heidi.inf``; refer back to "Inform on an IBM
121    PC (running Microsoft Windows)" on page 19 or "Inform on an Apple
122    Macintosh (running OS X)" on page 24 for guidance.  If the compilation
123    works, a story file ``Heidi.z5`` appears in the folder.  If the
124    compilation *doesn't* work, you've probably made a typing mistake; check
125    everything until you find it.
126
127 #. You can run the story file in your Inform interpreter; you should see
128    this (except that the Serial number will be different -- it's based on
129    the date):
130
131    .. code-block:: transcript
132
133       Heidi
134       A simple Inform example
135       by Roger Firth and Sonja Kesserich.
136       Release 1 / Serial number 040804 / Inform v6.30 Library 6/11 SD
137
138       Darkness
139       It is pitch dark, and you can't see a thing.
140
141       >
142
143 When you get that far, your template source file is correct.  Let's explain
144 what it contains.
145
146 Understanding the source file
147 =============================
148
149 Although we've got a certain amount of freedom of expression, source files
150 tend to conform to a standard overall structure: these lines at the start,
151 that material next, those pieces coming at the end, and so on.  What we're
152 doing here is mapping out a structure that suits us, giving ourselves a
153 clear framework onto which the elements of the game can be fitted.  Having
154 a clear (albeit sparse) map at the start will help us to keep things
155 organised as the game evolves.  We can infer several Inform rules just by
156 looking at the source file.
157
158 * If the *very first line* (or lines) of the source file begin with the
159   characters "``!%``", then the compiler treats what follows on those lines
160   as control instructions to itself rather than as part of the game's
161   source.  The instructions most commonly placed here are compiler
162   switches, a way of controlling detailed aspects of how the compiler
163   operates.  These particular switches, two of many, are turning on
164   **Strict mode**, which makes the game less likely to misbehave when being
165   played, and **Debug mode**, which provides some extra commands which can
166   be helpful when tracking down problems.
167
168   .. note::
169
170      Actually, the ``-S`` is redundant, since Strict mode is already on by
171      default.  We include it here as a reminder that (a) to turn Strict
172      mode *off*, you change this setting to ``-~S``, and (b) alphabetic
173      case matters here: ``-s`` causes a display of compiler statistics (and
174      ``-~s`` does nothing at all).
175
176 * Otherwise, when the compiler comes across an exclamation mark, it ignores
177   the rest of the line.  If the ``!`` is at the start of a line, the whole
178   line is ignored; if the ``!`` is halfway along a line, the compiler takes
179   note of the first half, and then ignores the exclamation mark and
180   everything after it on that line.  We call material following an
181   exclamation mark, not seen by anybody else, a **comment**; it's often a
182   remark that we write to remind ourselves of how something works or why we
183   tackled a problem in a particular way.  There's nothing special about
184   those equals signs: they just produce clear lines across the page.
185
186   It's always a good idea to comment code as you write it, for later it
187   will help you to understand what was going on at a particular spot.
188   Although it all seems clear in your head when you first write it, in a
189   few months you may suspect that a totally alien mind must have produced
190   that senseless gibberish.
191
192   By the way, the compiler *doesn't* give special treatment to exclamation
193   marks in quoted text: ``!`` within quotes "..." is treated as a normal
194   character.  On this line, the first ``!`` is part of the sequence (or
195   string) of characters to be displayed:
196
197   .. code-block:: inform6
198
199      print "Hello world!";         ! <- is the start of this comment
200
201 * The compiler ignores blank lines, and treats lots of space like a single
202   space (except when the spaces are part of a character string).  So, these
203   two rules tell us that we *could* have typed the source file like this:
204
205   .. code-block:: inform6
206
207      Constant Story "Heidi";
208      Constant Headline
209      "^A simple Inform example^by Roger Firth and Sonja Kesserich.^";
210      Include "Parser";Include "VerbLib";
211      [ Initialise; ];
212      Include "Grammar";
213
214   We didn't type it that way because, though shorter, it's much harder to
215   read.  When designing a game, you'll spend a lot of time studying what
216   you've typed, so it's worthwhile taking a bit of care to make it as
217   readable as possible.
218
219 * Every game should have the **constant** definitions for ``Story`` (the
220   game's name) and ``Headline`` (typically, information on the game's
221   theme, copyright, authorship and so on).  These two **string** values,
222   along with a release number and date, and details of the compiler,
223   compose the **banner** which is displayed at the start of each game.
224
225 * Every game needs the three lines which ``Include`` the standard library
226   files -- that is, they merge those files' contents into your source file:
227
228   .. code-block:: inform6
229
230      Include "Parser";
231      Include "VerbLib";
232      ! ...
233      Include "Grammar";
234
235   They always have to be in this order, with ``Parser`` and ``VerbLib``
236   near the start of the file, and ``Grammar`` near the end.
237
238 * Every game needs to define an ``Initialise`` routine (note the British
239   spelling):
240
241   .. code-block:: inform6
242
243      [ Initialise; ];
244
245   The **routine** that we've defined here doesn't do anything useful, but
246   it still needs to be present.  Later, we'll come back to ``Initialise``
247   and explain what a routine is and why we need this one.
248
249 * You'll notice that each of the items mentioned in the previous three
250   rules ends with a semicolon.  Inform is very fussy about its punctuation,
251   and gets really upset if you forget a terminating semicolon.  In fact,
252   the compiler just keeps reading your source file until it finds one;
253   that's why we were able to take three lines to define the ``Headline``
254   constant
255
256   .. code-block:: inform6
257
258      Constant Headline
259            "^A simple Inform example
260             ^by Roger Firth and Sonja Kesserich.^";
261
262 Just to repeat what we said earlier: every game that you design will start
263 out from a basic source file like this (in fact, it might be sensible to
264 keep a copy of this template file in a safe place, as a starting point for
265 future games).  Think of this stuff as the basic preparation which you'll
266 quickly come to take for granted, much as a landscape artist always begins
267 by sizing the canvas before starting to paint.  So, now that we've taken a
268 quick tour of Inform's general needs, we can start thinking about what this
269 particular game requires.
270
271 Defining the game's locations
272 =============================
273
274 A good starting point in any game is to think about the locations which are
275 involved: this sketch map shows the four that we'll use:
276
277 .. image:: /images/heidi1.*
278    :align: center
279
280 In IF, we talk about each of these locations as a **room**, even though in
281 this example none of them has four walls.  So let's use Inform to define
282 those rooms.  Here's a first attempt:
283
284 .. code-block:: inform6
285
286    Object   "In front of a cottage"
287      with   description
288                 "You stand outside a cottage. The forest stretches east.",
289       has   light;
290
291    Object   "Deep in the forest"
292      with   description
293                "Through the dense foliage, you glimpse a building to the west.
294                 A track heads to the northeast.",
295       has   light;
296
297    Object   "A forest clearing"
298      with   description
299                "A tall sycamore stands in the middle of this clearing.
300                 The path winds southwest through the trees.",
301       has   light;
302
303    Object   "At the top of the tree"
304      with   description "You cling precariously to the trunk.",
305       has   light;
306
307 Again, we can infer some general principles from these four examples:
308
309 * A room definition starts with the word ``Object`` and ends, about four
310   lines later, with a semicolon.  Each of the components that appears in
311   your game -- not only the rooms, but also the people, the things that you
312   see and touch, intangibles like a sound, a smell, a gust of wind -- is
313   defined in this way; think of an "object" simply as the general term for
314   the myriad thingies which together comprise the model world which your
315   game inhabits.
316
317 * The phrase in double quotes following the word ``Object`` is the name
318   that the interpreter uses to provide the player character with a list of
319   the objects around her: where she is, what she can see, what she's
320   holding, and so on.
321
322   .. note::
323
324      We're using the word "player" to mean both the person who is playing
325      the game, and the principal protagonist (often known as the player
326      character) within the game itself.  Since the latter -- Heidi -- is
327      female, we'll refer to the player as "she" while discussing this game.
328
329 * A keyword ``with`` follows, which simply tells the compiler what to
330   expect next.
331
332 * The word ``description``, introducing another piece of text which gives
333   more detail about the object: in the case of a room, it's the appearance
334   of the surrounding environment when the player character is in that room.
335   The textual description is given in double quotes, and is followed by a
336   comma.
337
338 * Near the end, the keyword ``has`` appears, which again tells the compiler
339   to expect a certain kind of information.
340
341 * The word ``light`` says that this object is a source of illumination, and
342   that therefore the player character can see what's happening here.  There
343   has to be at least one light source in every room (unless you want the
344   player to be told that "It's pitch dark and you can't see a thing"); most
345   commonly, that light source is the room itself.
346
347 A smidgeon of background may help set this into context (there's more in
348 the next chapter).  An object can have both **properties** (introduced by
349 the keyword ``with``) and **attributes** (written after the word ``has``).
350 A property has both a name (like ``description``) and a value (like the
351 character string "``You stand outside a cottage.  The forest stretches
352 east.``"); an attribute has merely a name.
353
354 In a little while, when you play this game, you'll observe that it starts
355 like this:
356
357 .. code-block:: transcript
358
359    In front of a cottage
360    You stand outside a cottage. The forest stretches east.
361
362 And here you can see how the room's name (``In front of a cottage``) and
363 description (``You stand outside a cottage.  The forest stretches east.``)
364 are used.
365
366 Joining up the rooms
367 ====================
368
369 We said that this was a first attempt at defining the rooms; it's fine as
370 far as it goes, but a few bits of information are missing.  If you look at
371 the game's sketch map, you can see how the rooms are intended to be
372 connected; from "Deep in the forest", for example, the player character
373 should be able to move west towards the cottage, or northeast to the
374 clearing.  Now, although our descriptions mention or imply these available
375 routes, we also need to explicitly add them to the room definitions in a
376 form that the game itself can make sense of.  Like this:
377
378 .. code-block:: inform6
379
380    Object   before_cottage "In front of a cottage"
381      with   description
382                 "You stand outside a cottage. The forest stretches east.",
383             e_to forest,
384      has    light;
385
386    Object   forest "Deep in the forest"
387      with   description
388                 "Through the dense foliage, you glimpse a building to the west.
389                  A track heads to the northeast.",
390             w_to before_cottage,
391             ne_to clearing,
392      has    light;
393
394    Object   clearing "A forest clearing"
395      with   description
396                 "A tall sycamore stands in the middle of this clearing.
397                  The path winds southwest through the trees.",
398             sw_to forest,
399             u_to top_of_tree,
400      has    light;
401
402    Object   top_of_tree "At the top of the tree"
403      with   description "You cling precariously to the trunk.",
404             d_to clearing,
405      has    light;
406
407 We've made two changes to the room objects.
408
409 * First, between the word ``Object`` and the object's name in double
410   quotes, we've inserted a different type of name: a private, internal
411   identification, never seen by the player; one that we can use *within*
412   the source file when one object needs to refer to another object.  For
413   example, the first room is identified as ``before_cottage``, and the
414   second as ``forest``.
415
416   Unlike the external name contained in double quotes, the internal
417   identifier has to be a single word -- that is, without spaces.  To aid
418   readability, we often use an underscore character to act as sort of
419   pseudo-space: ``before_cottage`` is a bit clearer than ``beforecottage``.
420
421 * Second, we've added lines after the object descriptions which use those
422   internal identifiers to show how the rooms are connected; one line for
423   each connection.  The ``before_cottage`` object has this additional
424   line::
425
426      e_to forest,
427
428   This means that a player standing in front of the cottage can type GO
429   EAST (or EAST, or just E), and the game will transport her to the room
430   whose internal identification is ``forest``.  If she tries to move in any
431   other direction from this room, she'll be told "You can't go that way".
432
433   What we've just defined is a *one-way* easterly connection:
434   ``before_cottage`` → ``forest``.  The forest object has two additional
435   lines::
436
437      w_to before_cottage,
438      ne_to clearing,
439
440   The first line defines a westerly connection ``forest`` →
441   ``before_cottage`` (thus enabling the player character to return to the
442   cottage), and the second defines a connection ``forest`` → ``clearing``
443   which heads off to the northeast.
444
445   Inform provides for eight "horizontal" connections (``n_to``, ``ne_to``,
446   ``e_to``, ``se_to``, ``s_to``, ``sw_to``, ``w_to``, ``nw_to``) two
447   "vertical" ones (``u_to``, ``d_to``) and two specials ``in_to``, and
448   ``out_to``.  You'll see some of these used for the remaining inter-room
449   connections.
450
451 There's one last detail to attend to before we can test what we've done.
452 You'll recollect that our story begins with Heidi standing in front of her
453 cottage.  We need to tell the interpreter that ``before_cottage`` is the room
454 where the game starts, and we do this in the ``Initialise`` routine::
455
456     [ Initialise; location = before_cottage; ];
457
458 ``location`` is a **variable**, part of the library, which tells the
459 interpreter in which room the player character currently is.  Here, we're
460 saying that, at the start of the game, the player character is in the
461 ``before_cottage`` room.
462
463 Now we can add what we've done to the ``Heidi.inf`` source file template.
464 At this stage, you should study the four room definitions, comparing them
465 with the sketch map until you're comfortable that you understand how to
466 create simple rooms and define the connections between them.
467
468 .. code-block:: inform6
469
470    !============================================================================
471    Constant Story "Heidi";
472    Constant Headline
473                "^A simple Inform example
474                 ^by Roger Firth and Sonja Kesserich.^";
475
476    Include "Parser";
477    Include "VerbLib";
478
479    !============================================================================
480    ! The game objects
481
482    Object   before_cottage "In front of a cottage"
483      with   description
484                 "You stand outside a cottage. The forest stretches east.",
485             e_to forest,
486      has    light;
487
488    Object   forest "Deep in the forest"
489      with   description
490                 "Through the dense foliage, you glimpse a building to the west.
491                  A track heads to the northeast.",
492             w_to before_cottage,
493             ne_to clearing,
494      has    light;
495
496    Object   clearing "A forest clearing"
497      with   description
498                 "A tall sycamore stands in the middle of this clearing.
499                  The path winds southwest through the trees.",
500             sw_to forest,
501             u_to top_of_tree,
502      has    light;
503
504    Object   top_of_tree "At the top of the tree"
505      with   description "You cling precariously to the trunk.",
506             d_to clearing,
507      has    light;
508
509    !============================================================================
510    ! Entry point routines
511
512    [ Initialise; location = before_cottage; ];
513
514    !============================================================================
515    ! Standard and extended grammar
516
517    Include "Grammar";
518
519    !============================================================================
520
521 Type this in, as always taking great care with the punctuation -- watch
522 those commas and semicolons.  Compile it, and fix any mistakes which the
523 compiler reports.  You can then play the game in its current state.
524 Admittedly, you can't do very much, but you should be able to move freely
525 among the four rooms that you've defined.
526
527 .. note::
528
529    In order to minimise the amount of typing that you have to do, the
530    descriptive text in this game has been kept as short as possible.  In a
531    real game, you would typically provide more interesting descriptions
532    than these.
533
534 Adding the bird and the nest
535 ============================
536
537 Given what we said earlier, you won't be surprised to hear that both the
538 bird and its nest are Inform objects.  We'll start their definitions like
539 this:
540
541 .. code-block:: inform6
542
543    Object  bird "baby bird"
544      with  description "Too young to fly, the nestling tweets helplessly.",
545       has  ;
546
547    Object  nest "bird's nest"
548      with  description "The nest is carefully woven of twigs and moss.",
549       has  ;
550
551 You can see that these definitions have exactly the same format as the
552 rooms we defined previously: a one-word internal identifier (``bird``,
553 ``nest``), and a word or phrase naming the object for the player's benefit
554 (``baby bird``, ``bird's nest``).  They both have some descriptive detail:
555 for a room this is printed when the player first enters, or when she types
556 LOOK; for other objects it's printed when she EXAMINEs that object.  What
557 they *don't* have are connections (``e_to``, ``w_to``, etc.  apply only to
558 rooms) or ``light`` (it's not necessary -- the rooms ensure that light is
559 available).
560
561 When the game is running, the player will want to refer to these two
562 objects, saying for instance EXAMINE THE BABY BIRD or PICK UP THE NEST.
563 For this to work reliably, we need to specify the word (or words) which
564 relate to each object.  Our aim here is flexibility: providing a choice of
565 relevant vocabulary so that the player can use whatever term seems
566 appropriate to her, with a good chance of it being understood.  We add a
567 line to each definition:
568
569 .. code-block:: inform6
570
571    Object  bird "baby bird"
572      with  description "Too young to fly, the nestling tweets helplessly.",
573            name 'baby' 'bird' 'nestling',
574       has  ;
575
576    Object  nest "bird's nest"
577      with  description "The nest is carefully woven of twigs and moss.",
578            name 'bird^s' 'nest' 'twigs' 'moss',
579       has  ;
580
581 The ``name`` introduces a list in single quotes '...'.  We call each of
582 those quoted things a **dictionary word**, and we do mean "word", not
583 "phrase" (``'baby'``\ ``'bird'`` rather than ``'baby bird'``); you can't
584 uses spaces, commas or periods in dictionary words, though there's a space
585 *between* each one, and the whole list ends with a comma.  The idea is that
586 the interpreter decides which object a player is talking about by matching
587 what she types against the full set of all dictionary words.  If the player
588 mentions BIRD, or BABY BIRD, or NESTLING, it's the ``baby bird`` that she
589 means; if she mentions NEST, BIRD'S NEST or MOSS, it's the ``bird's nest``.
590 And if she types NEST BABY or BIRD TWIGS, the interpreter will politely say
591 that it doesn't understand what on earth she's talking about.
592
593 .. note::
594
595    You'll notice the use of ``'bird^s'`` to define the dictionary word
596    BIRD'S; this oddity is necessary because the compiler expects the single
597    quotes in the list always to come in pairs -- one at the start of the
598    dictionary word, and one at the end.  If we had typed ``'bird's'`` then
599    the compiler would find the opening quote, the four letters ``b``,
600    ``i``, ``r`` and ``d``, and what looks like the closing quote.  So far
601    so good; it's read the word BIRD and now expects a space before the next
602    opening quote... but instead finds ``s'`` which makes no sense.  In
603    cases like this we must use the circumflex ``^`` to *represent* the
604    apostrophe, and the compiler then treats ``bird's`` as a dictionary
605    word.
606
607 You may be wondering why we need a list of ``name`` words for the bird and
608 its nest, yet we didn't when we defined the rooms?  It's because the player
609 can't interact with a room in the same way as with other objects; for
610 example, she doesn't need to say EXAMINE THE FOREST -- just being there and
611 typing LOOK is sufficient.
612
613 The bird's definition is complete, but there's an additional complexity
614 with the nest: we need to be able to put the bird into it.  We do this by
615 labelling the nest as a ``container`` -- able to hold other objects -- so
616 that the player can type PUT (or INSERT) BIRD IN (or INTO) NEST.
617 Furthermore, we label it as ``open``; this prevents the interpreter from
618 asking us to open it before putting in the bird.
619
620 .. code-block:: inform6
621
622    Object   nest "bird's nest"
623      with   description "The nest is carefully woven of twigs and moss.",
624             name 'bird^s' 'nest' 'twigs' 'moss',
625      has    container open;
626
627 Both objects are now defined, and we can incorporate them into the game.
628 To do this, we need to choose the locations where the player will find
629 them.  Let's say that the bird is found in the forest, while the nest is in
630 the clearing.  This is how we set this up:
631
632 .. code-block:: inform6
633
634    Object   bird "baby bird" forest
635      with   description "Too young to fly, the nestling tweets helplessly.",
636             name 'baby' 'bird' 'nestling',
637      has    ;
638
639    Object   nest "bird's nest" clearing
640      with   description "The nest is carefully woven of twigs and moss.",
641             name 'bird^s' 'nest' 'twigs' 'moss',
642      has    container open;
643
644 Read that first line as: "Here's the definition of an object which is
645 identified within this file as ``bird``, which is known to the player as
646 ``baby bird``, and which is initially located inside the object identified
647 within this file as ``forest``."
648
649 Where in the source file do these new objects fit?  Well, anywhere really,
650 but you'll find it convenient to insert them following the rooms where
651 they're found.  This means adding the bird just after the forest, and the
652 nest just after the clearing.  Here's the middle piece of the source file:
653
654 .. code-block:: inform6
655
656    !============================================================================
657    ! The game objects
658
659    Object  before_cottage "In front of a cottage"
660      with  description
661                 "You stand outside a cottage. The forest stretches east.",
662            e_to forest,
663       has  light;
664
665    Object  forest "Deep in the forest"
666      with  description
667                 "Through the dense foliage, you glimpse a building to the west.
668                  A track heads to the northeast.",
669            w_to before_cottage,
670            ne_to clearing,
671       has  light;
672
673    Object  bird "baby bird" forest
674      with  description "Too young to fly, the nestling tweets helplessly.",
675            name 'baby' 'bird' 'nestling',
676       has  ;
677
678    Object  clearing "A forest clearing"
679      with  description
680                 "A tall sycamore stands in the middle of this clearing.
681                  The path winds southwest through the trees.",
682            sw_to forest,
683            u_to top_of_tree,
684       has  light;
685
686    Object  nest "bird's nest" clearing
687      with  description "The nest is carefully woven of twigs and moss.",
688            name 'bird^s' 'nest' 'twigs' 'moss',
689       has  container open;
690
691    Object  top_of_tree "At the top of the tree"
692      with  description "You cling precariously to the trunk.",
693            d_to clearing,
694       has  light;
695
696    !============================================================================
697
698 Make those changes, recompile the game, play it and you'll see this:
699
700 .. code-block:: transcript
701
702    Deep in the forest
703    Through the dense foliage, you glimpse a building to the west. A track heads
704    to the northeast.
705
706    You can see a baby bird here.
707
708    >
709
710 Adding the tree and the branch
711 ==============================
712
713 The description of the clearing mentions a tall sycamore tree, up which the
714 player character supposedly "climbs".  We'd better define it:
715
716 .. code-block:: inform6
717
718    Object   tree "tall sycamore tree" clearing
719      with   description
720                 "Standing proud in the middle of the clearing,
721                  the stout tree looks easy to climb.",
722             name 'tall' 'sycamore' 'tree' 'stout' 'proud',
723      has    scenery;
724
725 Everything there should be familiar, apart from that ``scenery`` at the
726 end. We've already mentioned the tree in the description of the forest
727 clearing, so we don't want the interpreter adding "You can see a tall
728 sycamore tree here" afterwards, as it does for the bird and the nest.  By
729 labelling the tree as ``scenery`` we suppress that, and also prevent it
730 from being picked up by the player character.  One final object: the branch
731 at the top of the tree.  Again, not many surprises in this definition:
732
733 .. code-block:: inform6
734
735    Object   branch "wide firm bough" top_of_tree
736      with   description "It's flat enough to support a small object.",
737             name 'wide' 'firm' 'flat' 'bough' 'branch',
738      has    static supporter;
739
740 The only new things are those two labels.  ``static`` is similar to
741 ``scenery``: it prevents the branch from being picked up by the player
742 character, but *doesn't* suppress mention of it when describing the
743 setting.  And ``supporter`` is rather like the ``container`` that we used
744 for the nest, except that this time the player character can put other
745 objects *onto* the branch.  (In passing, we'll mention that an object can't
746 normally be both a ``container`` and a ``supporter``.)  And so here are our
747 objects again:
748
749 .. code-block:: inform6
750
751    !============================================================================
752    ! The game objects
753
754    Object   before_cottage "In front of a cottage"
755      with   description
756                 "You stand outside a cottage. The forest stretches east.",
757             e_to forest,
758      has    light;
759
760    Object   forest "Deep in the forest"
761      with   description
762                 "Through the dense foliage, you glimpse a building to the west.
763                  A track heads to the northeast.",
764             w_to before_cottage,
765             ne_to clearing,
766      has    light;
767
768    Object   bird "baby bird" forest
769      with   description "Too young to fly, the nestling tweets helplessly.",
770             name 'baby' 'bird' 'nestling',
771      has    ;
772
773    Object   clearing "A forest clearing"
774      with   description
775                 "A tall sycamore stands in the middle of this clearing.
776                  The path winds southwest through the trees.",
777             sw_to forest,
778             u_to top_of_tree,
779      has    light;
780
781    Object   nest "bird's nest" clearing
782      with   description "The nest is carefully woven of twigs and moss.",
783             name 'bird^s' 'nest' 'twigs' 'moss',
784       has   container open;
785
786    Object   tree "tall sycamore tree" clearing
787      with   description
788                 "Standing proud in the middle of the clearing,
789                  the stout tree looks easy to climb.",
790             name 'tall' 'sycamore' 'tree' 'stout' 'proud',
791       has   scenery;
792
793    Object   top_of_tree "At the top of the tree"
794      with   description "You cling precariously to the trunk.",
795             d_to clearing,
796       has   light;
797
798    Object   branch "wide firm bough" top_of_tree
799      with   description "It's flat enough to support a small object.",
800             name 'wide' 'firm' 'flat' 'bough' 'branch',
801       has   static supporter;
802
803    !============================================================================
804
805 Once again, make the changes, recompile, and investigate what you can do in
806 your model world.
807
808 Finishing touches
809 =================
810
811 Our first pass at the game is nearly done; just two more changes to
812 describe.  The first is easy: Heidi wouldn't be able to climb the tree
813 carrying the bird and the nest separately: we want the player character to
814 put the bird into the nest first.  One easy way to enforce this is by
815 adding a line near the top of the file:
816
817 .. code-block:: inform6
818
819    !============================================================================
820    Constant Story "Heidi";
821    Constant Headline
822                "^A simple Inform example
823                 ^by Roger Firth and Sonja Kesserich.^";
824
825    Constant MAX_CARRIED 1;
826
827 The value of ``MAX_CARRIED`` limits the number of objects that the player
828 character can be holding at any one time; by setting it to 1, we're saying
829 that she can carry the bird or the nest, but not both.  However, the limit
830 ignores the contents of ``container`` or ``supporter`` objects, so the nest
831 with the bird inside it is still counted as one object.
832
833 The other change is slightly more complex and more important: there's
834 currently no way to "win" the game!  The goal is for the player character
835 to put the bird in the nest, take the nest to the top of the tree, and
836 place it on the branch; when that happens, the game should be over.  This
837 is one way of making it happen:
838
839 .. code-block:: inform6
840
841    Object  branch "wide firm bough" top_of_tree
842      with  description "It's flat enough to support a small object.",
843            name 'wide' 'firm' 'flat' 'bough' 'branch',
844            each_turn [; if (nest in branch) deadflag = 2; ],
845       has  static supporter;
846
847 .. note::
848
849    Here's an explanation of what's going on.  If you find this difficult to
850    grasp, don't worry.  It's the hardest bit so far, and it introduces
851    several new concepts all at once.  Later in the guide, we'll explain
852    those concepts more clearly, so you can just skip this bit if you want.
853
854    The variable ``deadflag``, part of the library, is normally 0.  If you set
855    its value to 2, the interpreter notices and ends the game with "You have
856    won".  The statement::
857
858          if (nest in branch) deadflag = 2;
859
860    should be read as: "Test whether the ``nest`` is currently in the
861    ``branch`` (if the branch is a ``container``) or on it (if the
862    ``branch`` is a supporter); if it is, set the value of ``deadflag`` to
863    2; if it isn't, do nothing."  The surrounding part::
864
865          each_turn [; ... ],
866
867    should be read as: "At the end of each turn (when the player is in the
868    same room as the branch), do whatever is written inside the square
869    brackets".  So, putting that all together:
870
871    * At the end of each turn (after the player has typed something and
872      pressed the Enter key, and the interpreter has done whatever was
873      requested) the interpreter checks whether the player and the
874      ``branch`` are in the same room.  If not, nothing happens.  If they're
875      together, it looks to see where the nest is.  Initially it's in the
876      ``clearing``, so nothing happens.
877
878    * Also at the end of each turn, the interpreter checks the value of
879      ``deadflag``.  Usually it's 0, so nothing happens.
880
881    * Finally the player character puts the ``nest`` on the ``branch``.
882      "Aha!"  says the interpreter (to itself, of course), and sets the
883      value of ``deadflag`` to 2.
884
885    * Immediately afterwards, (another part of) the interpreter checks and
886      finds that the value of ``deadflag`` has changed to 2, which means
887      that the game is successfully completed; so, it says to the player,
888      "you've won!"
889
890 That's as far as we'll take this example for now.  Make those final
891 changes, recompile, and test what you've achieved.  You'll probably find a
892 few things that could be done better -- even on a simple game like this
893 there's considerable scope for improvement -- so we'll revisit Heidi in her
894 forest shortly.  First, though, we'll recap what we've learnt so far.