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