appendices/c.rst

   1 ======================================
   2  Appendix C -- "William Tell" story
   3 ======================================
   4
   5 .. highlight:: transcript
   6
   7 .. only:: html
   8
   9   .. image:: /images/picW.png
  10      :align: left
  11
  12 .. raw:: latex
  13
  14     \dropcap{w}
  15
  16 illiam Tell, our second game, is also very straightforward. See "William
  17 Tell: a tale is born" on page 69, "William Tell: the early years" on
  18 page 79, "William Tell: in his prime" on page 91 and "William Tell: the
  19 end is nigh" on page 103.
  20
  21 Transcript of play
  22 ==================
  23
  24 .. literalinclude:: /examples/Tell.txt
  25    :language: transcript
  26
  27 Game source code
  28 ================
  29
  30 .. literalinclude:: /examples/Tell.inf
  31    :language: inform6
  32
  33 .. _compile-as-you-go:
  34
  35 Compile-as-you-go
  36 =================
  37
  38 Your understanding of how the "William Tell" game works will be
  39 considerably enhanced if you type in the code for yourself as you read
  40 through the guide. However, it takes us four chapters to describe the
  41 game, which isn't complete and playable until the end of Chapter 9. Even
  42 if you make no mistakes in your typing, the game won't compile without
  43 errors before that point, because of references in earlier chapters to
  44 objects which aren't presented until later chapters (for example,
  45 Chapter 6 mentions the ``bow`` and ``quiver`` objects, but we don't
  46 define them until Chapter 7). This is a bit of a nuisance, because as a
  47 general rule we advise you to compile frequently -- more or less after
  48 every change you make to a game -- in order to detect syntax and
  49 spelling mistakes as soon as possible.
  50
  51 Fortunately, there's a fairly easy way round the difficulty, though it
  52 involves a little bit of cheating. The trick is temporarily to add
  53 minimal definitions -- often called "stubs" -- of the objects whose full
  54 definitions have yet to be provided.
  55
  56 For example, if you try to compile the game in the state that it's
  57 reached by the end of Chapter 6, you’ll get this::
  58
  59         Tell.inf(16): Warning: Class "Room" declared but not used
  60         Tell.inf(19): Warning: Class "Prop" declared but not used
  61         Tell.inf(27): Warning: Class "Furniture" declared but not used
  62         Tell.inf(44): Error: No such constant as "street"
  63         Tell.inf(46): Error: No such constant as "bow"
  64         Tell.inf(47): Error: No such constant as "quiver"
  65         Compiled with 3 errors and 3 warnings
  66
  67 However, by adding these lines to the end of your game file:
  68
  69 .. code-block:: inform
  70
  71         ! ===============================================================
  72         ! TEMPORARY DEFINITIONS NEEDED TO COMPILE AT THE END OF CHAPTER 6
  73
  74         Room    street;
  75         Object  bow;
  76         Object  quiver;
  77
  78 a compilation should now give only this::
  79
  80         Tell.inf(19): Warning: Class "Prop" declared but not used
  81         Tell.inf(27): Warning: Class "Furniture" declared but not used
  82         Compiled with 2 warnings
  83
  84 That's a lot better. It's not worth worrying about those warnings, since
  85 it's easy to understand where they come from; anyway, they'll go away
  86 shortly. More important, there are no errors, which means that you've
  87 probably not made any major typing mistakes. It also means that the
  88 compiler has created a story file, so you can try "playing" the game. If
  89 you do, though, you'll get this::
  90
  91         William Tell
  92         A simple Inform example
  93         by Roger Firth and Sonja Kesserich.
  94         Release 3 / Serial number 040804 / Inform v6.30 Library 6/11 SD
  95
  96         (street)
  97         ** Library error 11 (27,0) **
  98         ** The room "(street)" has no "description" property **
  99         >
 100
 101 Whoops! We've fallen foul of Inform's rule saying that every room must
 102 have a ``description`` property, to be displayed by the interpreter when
 103 you enter that room. Our ``street`` stub hasn't got a ``description``,
 104 so although the game compiles successfully, it still causes an error to
 105 be reported at run-time.
 106
 107 The best way round this is to extend the definition of our ``Room``
 108 class, thus:
 109
 110 .. code-block:: inform
 111
 112         Class  Room
 113           with description "UNDER CONSTRUCTION",
 114           has  light;
 115
 116 By doing this, we ensure that *every* room has a description of some
 117 form; normally we'd override this default value with something
 118 meaningful -- "The narrow street runs north towards the town square..."
 119 and so on -- by including a ``description`` property in the object's
 120 definition. However, in a stub object used only for testing, a default
 121 description is sufficient (and less trouble)::
 122
 123         William Tell
 124         A simple Inform example
 125         by Roger Firth and Sonja Kesserich.
 126         Release 3 / Serial number 040804 / Inform v6.30 Library 6/11 SD
 127
 128         (street)
 129         UNDER CONSTRUCTION
 130
 131         >INVENTORY
 132         You are carrying:
 133           a (quiver) (being worn)
 134           a (bow)
 135
 136         >EXAMINE QUIVER
 137         You can't see any such thing.
 138
 139         >
 140
 141 You'll notice a couple of interesting points. Because we didn't supply
 142 external names with our ``street`` , ``bow`` and ``quiver`` stubs, the
 143 compiler has provided some for us -- ``(street)`` , ``(bow)`` and
 144 ``(quiver)`` -- simply by adding parentheses around the internal IDs
 145 which we used. And, because our ``bow`` and ``quiver`` stubs have no
 146 ``name`` properties, we can't actually refer to those objects when
 147 playing the game. Neither of these points would be acceptable in a
 148 finished game, but for testing purposes at this early stage -- they'll
 149 do.
 150
 151 So far, we've seen how the addition of three temporary object
 152 definitions enables us to compile the incomplete game, in its state at
 153 the end of Chapter 6. But once we reach the end of Chapter 7, things
 154 have moved on, and we now need a different set of stub objects. For a
 155 test compilation at this point, remove the previous set of stubs, and
 156 instead add these -- ``south_square`` and ``apple`` objects, and a dummy
 157 action handler to satisfy the ``Talk`` action in Helga’s life property:
 158
 159 .. code-block:: inform
 160
 161         ! ===============================================================
 162         ! TEMPORARY DEFINITIONS NEEDED TO COMPILE AT THE END OF CHAPTER 7
 163
 164         Room    south_square;
 165         Object  apple;
 166
 167         [ TalkSub; ];
 168
 169 Similarly, at the end of Chapter 8, replace the previous stubs by these
 170 if you wish to check that the game compiles:
 171
 172 .. code-block:: inform
 173
 174         ! ===============================================================
 175         ! TEMPORARY DEFINITIONS NEEDED TO COMPILE AT THE END OF CHAPTER 8
 176         Room    marketplace;
 177         Object  apple;
 178         NPC     son;
 179
 180         [ TalkSub; ];
 181         [ FireAtSub; ];
 182         [ SaluteSub; ];
 183
 184 Finally, by the end of Chapter 9 the game is complete, so you can delete
 185 the stubs altogether.
 186
 187 Used with care, this technique of creating a few minimal stub objects
 188 can be convenient -- it enables you to "sketch" a portion of your game
 189 in outline form, and to compile and test the game in that state, without
 190 needing to create complete object definitions. However, you've got very
 191 little interaction with your stubs, so don't create too many of them.
 192 And of course, never forget to flesh out the stubs into full definitions
 193 as soon as you can.