1 ========================
3 ========================
11 .. image:: /images/picF.png
18 inally our three example games are written; we've shown you as much of
19 the Inform language as we've needed to, and made a lot of observations
20 about how and why something should be done. Despite all that, there's
21 much that we've left unsaid, or touched on only lightly. In this chapter
22 we'll revisit key topics and review some of the more significant
23 omissions, to give you a better feel for what's important, and what can
24 be ignored for the time being; when you become an accomplished designer,
25 you will decide what matters and what can be left on the shelf.
27 We'll also talk, in :ref:`reading-other-code`, about a few ways of doing
28 things that we've chosen not to tell you about, but which you're quite
29 likely to encounter if you look at Inform code written by other designers.
31 The tone here is perhaps a little dry, but trust us: in walking this
32 dusty ground we touch on just about everything that is fundamental in
33 your overall understanding of Inform. And as always, the *Inform
34 Designer's Manual* provides rounder and more comprehensive coverage.
39 In this guide we’ve used the placeholder `{expression}` a few times;
40 here's roughly what we mean.
42 * An `{expression}` is a single `{value}`, or several `{values}`
43 combined using `{operators}` and sometimes parentheses ``(...)``.
45 * Possible `{values}` include:
47 * a literal number (-32768 to 32767)
49 * something that's represented as a number (a character ``'a'`` , a
50 dictionary word ``'aardvark'`` , a string ``"aardvark's adventure"``
51 or an action ``##Look`` )
53 * the internal identifier of a constant, an object, a class or a routine
55 * (only in a run-time statement, not in a compile-time directive) the
56 contents of a variable, or the return value from a routine.
58 * Possible `{operators}` include:
60 * an arithmetic operator: ``+ - * / % ++``
61 * a bitwise logical operator: ``& | ~``
62 * a numeric comparison operator: ``== ~= > < >= <=``
63 * an object conditional operator: ``ofclass in notin provides has hasnt``
64 * a boolean combinational operator: ``&& || ~~``
69 Many of the items which you define in your source file -- objects,
70 variables, routines, etc. -- need to be given a name so that other items
71 can refer to them. We call this name an item's internal identifier
72 (because it's used only within the source file and isn't visible to the
73 player), and we use the placeholders `{obj_id}`, `{var_id}`,
74 `{routine_id}`, etc. to represent where it's used. An internal ID
76 * can be up to thirty-two characters long
78 * must start with a letter or underscore, and then continue with letters
79 ``A-Z`` , underscore ``_`` and digits ``0-9`` (where upper-case and
80 lower-case letters are treated as indistinguishable)
82 * should generally be unique across all files: your source file, the
83 standard library files, and any library contributions which you've
84 used (except that a routine's local variables are not visible outside
94 We might need some custom syntax highlighting here.
96 A :term:`statement` is an instruction intended for the interpreter, telling
97 it what to do at run-time. It *must* be given in lower-case, and always
98 ends with a semicolon.
100 Some statements, like ``if``, control one or more other statements. We
101 use the placeholder `{statement_block}` to represent either a single
102 `{statement}`, or any number of `{statements}` enclosed in braces::
106 { statement; statement; ... statement; }
108 Statements that we've met
109 -------------------------
111 Our games have used these statements, about half of the Inform
114 give obj_id attribute;
115 give obj_id attribute attribute ... attribute;
117 if (expression) statement_block
118 if (expression) statement_block else statement_block
120 move obj_id to parent_obj_id;
122 objectloop (var_id) statement_block
125 print value, value, ... value;
128 print_ret value, value, ... value;
135 style underline; print...; style roman;
137 switch (expression) {
138 value: statement; statement; ... statement;
140 default: statement; statement; ... statement;
144 "string", value, ... value;
148 <action noun second>;
152 <<action noun second>>;
154 Statements that we've not met
155 -----------------------------
157 Although our example games haven't needed to use them, these looping
158 statements are sometimes useful::
163 do statement_block until (expression)
165 for (set_var : loop_while_expression : update_var) statement_block
167 while (expression) statement_block
169 On the other hand, we suggest that you put the following statements on
170 hold for now; they're not immediately relevant to everyday code and have
171 mostly to do with printing and formatting::
180 In particular, avoid using the deprecated jump statement if you possibly can.
185 In ``print`` and ``print_ret`` statements, each `{value}` can be:
187 * a numeric `{expression}`, displayed as a signed decimal number,
189 * a `"{string}"`, displayed literally, or
191 * a print rule. You can create your own, or use a standard one, including:
193 .. tabularcolumns:: ll
195 +-------------------------+---------------------------------------------------+
196 | `(a) {obj_id}` | the object's name, preceded by "a", "an" or "some"|
197 +-------------------------+---------------------------------------------------+
198 | `(A) {obj_id}` | as ``(a)`` but using "A", "An" or "Some" |
199 +-------------------------+---------------------------------------------------+
200 | `(the) {obj_id}` | the object's name, preceded by "the" |
201 +-------------------------+---------------------------------------------------+
202 | `(The) {obj_id}` | as ``(the)`` but using "The" |
203 +-------------------------+---------------------------------------------------+
204 | `(number) {expression}` | the numeric expression's value in words |
205 +-------------------------+---------------------------------------------------+
210 A :term:`directive` is an instruction intended for the compiler, telling it
211 what to do at compile-time, while the source file is being translated into
212 Z-code. By convention it's given an initial capital letter (though the
213 compiler doesn't enforce this) and always ends with a semicolon.
215 Directives that we've met
216 -------------------------
218 We've used all of these directives; note that for ``Class``, ``Extend``,
219 ``Object`` and ``Verb`` the full supported syntax is more sophisticated
220 than the basic form presented here::
227 has attribute attribute ... attribute;
230 Constant const_id = expression;
231 Constant const_id expression;
234 * token token ... token -> action
235 * token token ... token -> action
237 * token token ... token -> action
241 Object obj_id "external_name" parent_obj_id
246 has attribute attribute ... attribute;
255 * token token ... token -> action
256 * token token ... token -> action
258 * token token ... token -> action;
260 ! comment text which the compiler ignores
262 [ routine_id; statement; statement; ... statement; ];
264 #Ifdef any_id; ... #Endif;
266 Directives that we've not met
267 -----------------------------
269 There's only a handful of useful directives which we haven't needed to
275 Global var_id = expression;
282 but there's a whole load which are of fairly low importance for now::
305 An object is really just a collection of variables which together
306 represent the capabilities and current status of some specific component
307 of the model world. Full variables are called properties; simpler
308 two-state variables are attributes.
313 The library defines around forty-eight standard property variables (such
314 as ``before`` or ``name``), but you can readily create further ones just
315 by using them within an object definition.
317 You can create and initialise a property in an object's ``with`` segment:
319 property, ! set to zero / false
321 property value, ! set to a single value
323 property value value ... value, ! set to a list of values
325 In each case, the `{value}` is either a compile-time `{expression}`, or
326 an embedded routine::
330 property [; statement; statement; ... statement; ],
332 You can refer to the value of a property::
334 self.property ! only within that same object
336 obj_id.property ! everywhere
338 and you can test whether an object definition includes a given property::
340 (obj_id provides property) ! is true or false
347 Inform provides standalone routines and embedded routines.
352 Standalone routines are defined like this::
354 [ routine_id; statement; statement; ... statement; ];
356 and called like this::
363 These are embedded as the value of an object's property::
365 property [; statement; statement; ... statement; ],
367 and are usually called automatically by the library, or manually by::
369 self.property() ! only within that same object
371 obj_id.property() ! everywhere
373 Arguments and local variables
374 -----------------------------
376 Both types of routine support up to fifteen local variables -- variables
377 which can be used only by the statements within the routine, and which
378 are automatically initialised to zero every time that the routine is
381 [ routine_id var_id var_id ... var_id; statement; statement; ... statement; ];
383 property [ var_id var_id ... var_id; statement; statement; ... statement; ],
385 You can pass up to seven arguments to a routine, by listing those
386 arguments within the parentheses when you call the routine. The effect
387 is simply to initialise the matching local variables to the argument
388 values rather than to zero::
390 routine_id(expression, expression, ... expression)
392 Although it works, this technique is rarely used with embedded routines,
393 because there is no mechanism for the library to supply argument values
394 when calling the routine.
399 Every routine returns a single value, which is supplied either
400 explicitly by some form of return statement::
402 [ routine_id; statement; statement; ... return expr; ]; ! returns expr
404 property [; statement; statement; ... return expr; ], ! returns expr
406 or implicitly when the routine runs out of statements. If none of these
407 ``statements`` is one -- ``return``, ``print_ret``, ``"..."`` or
408 ``<<...>>`` -- that causes an explicit return, then::
410 [ routine_id; statement; statement; ... statement; ];
412 returns ``true`` and ::
414 property [; statement; statement; ... statement; ]
418 This difference is *important*. Remember it by the letter pairs STEF:
419 left to themselves, Standalone routines return True, Embedded routines
422 Here's an example standalone routine which returns the larger of its two
425 [ Max a b; if (a > b) return a; else return b; ];
427 and here are some examples of its use (note that the first example,
428 though legal, does nothing useful whatsoever)::
434 if (Max(x,7) == 7) ...
436 switch (Max(3,y)) { ...
438 Library routines versus entry points
439 ------------------------------------
441 A library routine is a standard routine, included within the library
442 files, which you can optionally call from your source file if you
443 require the functionality which the routine provides. We've mentioned
444 these library routines::
446 IndirectlyContains(parent_obj_id, obj_id)
450 PlayerTo(obj_id, flag)
457 By contrast, an entry point routine is a routine which you can provide
458 in your source file, in which case the library calls it at an
459 appropriate time. We've mentioned these optional entry point routines::
463 InScope(actor_obj_id)
465 And this, the only mandatory one::
469 There are full lists in :ref:`library-routines` and :ref:`entry-points`.
471 .. _reading-other-code:
473 Reading other people's code
474 ===========================
476 Right at the start of this guide, we warned you that we weren't setting
477 out to be comprehensive; we've concentrated on presenting the most
478 important aspects of Inform, as clearly as we can. However, when you
479 read the *Inform Designer's* Manual, and more especially when you look
480 at complete games or library extensions which other designers have
481 produced, you'll come across other ways of doing things -- and it might
482 be that you, like other authors, prefer them over our methods. Just try
483 to find a style that suits you and, this is the important bit, be
484 *consistent* about its use. In this section, we highlight some of the
485 more obvious differences which you may encounter.
490 Every designer has his or her own style for laying out their source
491 code, and they're all worse than the one you adopt. Inform's flexibility
492 makes it easy for designers to choose a style that suits them;
493 unfortunately, for some designers this choice seems influenced by the
494 Jackson Pollock school of art. We've advised you to be consistent, to
495 use plenty of white space and indentation, to choose sensible names, to
496 add comments at difficult sections, to actively *think*, as you write
497 your code, about making it as readable as you can.
499 This is doubly true if you ever contemplate sharing a library extension
500 with the rest of the community. This example, with the name changed, is
501 from a file in the Archive::
505 if (i in player) rtrue;
506 if (i has static || (i has scenery)) rtrue;
508 if (runroutines(j,before) ~= 0 || (j has static || (j has scenery))) {
509 print "You'll have to disconnect ",(the) i," from ",(the) j," first.^";
513 if (runroutines(i,before)~=0 || (i has static || (i has scenery))) {
514 print "You'll have to disconnect ",(the) i," from ",(the) j," first.^";
518 if (j hasnt concealed && j hasnt static) move j to player;
519 if (i hasnt static && i hasnt concealed) move i to player;
521 if (runroutines(j,after) ~= 0) rtrue;
522 print "You take ",(the) i," and ",(the) j," connected to it.^";
527 Here's the same routine after a few minutes spent purely on making it
528 more comprehensible; we haven't actually tested that it (still) works,
529 though that second ``else`` looks suspicious::
532 if (i in player || i has static or scenery || j == nothing) return true;
534 if (RunRoutines(j,before) || j has static or scenery)
535 "You'll have to disconnect ", (the) i, " from ", (the) j, " first.";
537 if (RunRoutines(i,before) || i has static or scenery)
538 "You'll have to disconnect ", (the) i, " from ", (the) j, " first.";
540 if (j hasnt static or concealed) move j to player;
541 if (i hasnt static or concealed) move i to player;
542 if (RunRoutines(j,after)) return true;
543 "You take ", (the) i, " and ", (the) j, " connected to it.";
547 We hope you'll agree that the result was worth the tiny extra effort.
548 Code gets written once; it gets read dozens and dozens of times.
553 There are a few statement shortcuts, some more useful than others, which
556 * These five lines all do the same thing::
562 ]; ! at the end of a standalone routine
564 * These four lines all do the same thing::
569 ]; ! at the end of an embedded routine
571 * These four lines all do the same thing::
573 print "string"; new_line; return true;
574 print "string^"; return true;
578 * These lines are the same::
580 print value1; print value2; print value3;
581 print value1, value2, value3;
583 * These lines are the same::
585 <action noun second>; return true;
586 <<action noun second>>;
588 * These lines are also the same::
593 * These ``if`` statements are equivalent::
595 if (MyVar == 1 || MyVar == 3 || MyVar == 7) ...
597 if (MyVar == 1 or 3 or 7) ...
599 * These ``if`` statements are equivalent as well::
601 if (MyVar ~= 1 && MyVar ~= 3 && MyVar ~= 7) ...
602 if (MyVar ~= 1 or 3 or 7) ...
604 * In an ``if`` statement, the thing in parentheses can be *any*
605 expression; all that matters is its value: zero (false) or anything
606 else (true). For example, these statements are equivalent::
608 if (MyVar ~= false) ...
609 if (~~(MyVar == false)) ...
611 if (~~(MyVar == 0)) ...
614 Note that the following statement specifically tests whether ``MyVar``
615 contains ``true`` (1), *not* whether its value is anything other than
618 if (MyVar == true) ...
620 * If ``MyVar`` is a variable, the statements ``MyVar++;`` and
621 ``++MyVar;`` work the same as ``MyVar = MyVar + 1;`` For example,
622 these lines are equivalent::
624 MyVar = MyVar + 1; if (MyVar == 3) ...
625 if (++MyVar == 3) ...
626 if (MyVar++ == 2) ...
628 What's the same about ``MyVar++`` and ``++MyVar`` is that they both
629 add one to ``MyVar``. What's different about them is the value to
630 which the construct itself evaluates: ``MyVar++`` returns the current
631 value of ``MyVar`` and then performs the increment, whereas
632 ``++MyVar`` does the "+1" first and then returns the incremented
633 value. In the example, if ``MyVar`` currently contains 2 then
634 ``++MyVar`` returns 3 and ``MyVar++`` returns 2, even though in both
635 cases the value of ``MyVar`` afterwards is 3. As another example,
636 this code (from Helga in "William Tell")::
638 Talk: self.times_spoken_to = self.times_spoken_to + 1;
639 switch (self.times_spoken_to) {
640 1: score = score + 1;
641 print_ret "You warmly thank Helga for the apple.";
642 2: print_ret "~See you again soon.~";
643 default: return false;
647 could have been written more succinctly like this::
649 Talk: switch (++self.times_spoken_to) {
651 print_ret "You warmly thank Helga for the apple.";
652 2: print_ret "~See you again soon.~";
653 default: return false;
657 * Similarly, the statements ``MyVar--;`` and ``--MyVar;`` work the same
658 as ``MyVar = MyVar - 1;`` Again, these lines are equivalent::
660 MyVar = MyVar - 1; if (MyVar == 7) ...
661 if (--MyVar == 7) ...
662 if (MyVar-- == 8) ...
664 "number" property and "general" attribute
665 -----------------------------------------
667 The library defines a standard ``number`` property and a standard
668 ``general`` attribute, whose roles are undefined: they are
669 general-purpose variables available within every object to designers as
670 and when they desire.
672 We recommend that you avoid using these two variables, primarily because
673 their names are, by their very nature, so bland as to be largely
674 meaningless. Your game will be clearer and easier to debug if you
675 instead create new property variables -- with appropriate names -- as
676 part of your ``Object`` and ``Class`` definitions.
680 Common properties and attributes
681 --------------------------------
683 As an alternative to creating new individual properties which apply only to
684 a single object (or class of objects), it's possible to devise properties
685 and new attributes which, like those defined by the library, are available
686 on *all* objects. The need to do this is actually quite rare, and is mostly
687 confined to library extensions (for example, the ``pname.h`` extension
688 which we encountered in :doc:`12` gives every object a ``pname`` property
689 and a ``phrase_matched`` attribute). To create them, you would use these
690 directives near the start of your source file::
696 We recommend that you avoid using these two directives unless you really
697 do need to affect every object -- or at least the majority of them -- in
698 your game. There is a limit of forty-eight attributes (of which the
699 library currently defines around thirty) and sixty-two of these common
700 properties (of which the library currently defines around forty-eight).
701 On the other hand, the number of individual properties which you can add
702 is virtually unlimited.
706 Setting up the object tree
707 --------------------------
709 Throughout this guide, we've defined the initial position of each object
710 within the overall object tree either by explicitly mentioning its
711 parent's ``obj_id`` (if any) in the first line of the object definition
712 -- what we've been calling the header information -- or, for a few
713 objects which crop up in more than one place, by using their
714 ``found_in`` properties. For example, in "William Tell" we defined
715 twenty-seven objects; omitting those which used ``found_in`` to define
716 their placement at the start of the game, we're left with object
717 definitions starting like this::
719 Room street "A street in Altdorf"
721 Room below_square "Further along the street"
722 Furniture stall "fruit and vegetable stall" below_square
723 Prop "potatoes" below_square
724 Prop "fruit and vegetables" below_square
725 NPC stallholder "Helga" below_square
727 Room south_square "South side of the square"
729 Room mid_square "Middle of the square"
730 Furniture pole "hat on a pole" mid_square
732 Room north_square "North side of the square"
734 Room marketplace "Marketplace near the square"
735 Object tree "lime tree" marketplace
736 NPC governor "governor" marketplace
740 Object quiver "quiver"
747 You'll see that several of the objects begin the game as parents:
748 ``below_square``, ``mid_square``, ``marketplace`` and ``quiver`` all
749 have child objects beneath them; those children mention their parent as
750 the last item of header information.
752 There's an alternative object syntax which is available to achieve the
753 same object tree, using "arrows". That is, we could have defined those
754 parent-and-child objects as::
756 Room below_square "Further along the street"
757 Furniture -> stall "fruit and vegetable stall"
759 Prop -> "fruit and vegetables"
760 NPC -> stallholder "Helga"
762 Room mid_square "Middle of the square"
763 Furniture -> pole "hat on a pole"
765 Room marketplace "Marketplace near the square"
766 Object -> tree "lime tree"
767 NPC -> governor "governor"
769 Object quiver "quiver"
774 The idea is that an object's header information *either* starts with an
775 arrow, or ends with an ``obj_id``, or has neither (having both isn’t
776 permitted). An object with neither has no parent: in this example,
777 that's all the ``Rooms``, and also the ``bow`` and the ``quiver`` (which
778 are moved to the player ``object`` in the ``Initialise`` routine) and
779 the apple (which remains without a parent until Helga gives it to
782 An object which starts with a single arrow ``->`` is defined to be a
783 child of the nearest previous object without a parent. Thus, for
784 example, the ``tree`` and ``governor`` objects are both children of the
785 ``marketplace``. To define a child of a child, you'd use two arrows
786 ``-> ->``, and so on. In "William Tell", that situation doesn't occur;
787 to illustrate how it works, imagine that at the start of the game the
788 potatoes and the other fruit and vegetables where actually *on* the
789 stall. Then we might have used::
791 Room below_square "Further along the street"
792 Furniture -> stall "fruit and vegetable stall"
793 Prop -> -> "potatoes"
794 Prop -> -> "fruit and vegetables"
795 NPC -> stallholder "Helga"
798 That is, the objects with one arrow (the ``stall`` and ``stallholder``)
799 are children of the nearest object without a parent (the ``Room``), and
800 the objects with two arrows (the produce) are children of the nearest
801 object defined with a single arrow (the ``stall``).
803 The advantages of using arrows include:
805 * You're forced to define your objects in a "sensible" order.
807 * Fewer ``obj_ids`` may need to be used (though in this game it would
810 The disadvantages include:
812 * The fact that objects are related by the physical juxtaposition of
813 their definitions is not necessarily intuitive to all designers.
815 * Especially in a crowded room, it’s harder to be certain exactly how
816 the various parent–child relationships are initialised, other than by
817 carefully counting lots of arrows.
819 * If you relocate the parent within the initial object hierarchy to a
820 higher or lower level, you'll need also to change its children by
821 adding or removing arrows; this isn't necessary when the parent is
822 named in the child headers.
824 We prefer to explicitly name the parent, but you'll encounter both forms
827 Quotes in "name" properties
828 ---------------------------
830 We went to some lengths, way back in :ref:`things-in-quotes`, to explain
831 the difference between double quotes ``"..."`` (strings to be output) and
832 single quotes ``'...'`` (input tokens -- dictionary words). Perhaps
833 somewhat unfortunately, Inform allows you to blur this clean distinction:
834 you can use double quotes in name properties and Verb directives::
836 NPC stallholder "Helga" below_square
837 with name "stallholder" "greengrocer" "monger" "shopkeeper" "merchant"
838 "owner" "Helga" "dress" "scarf" "headscarf",
841 Verb "talk" "t//" "converse" "chat" "gossip"
842 * "to"/"with" creature -> Talk
845 *Please* don't do this. You'll just confuse yourself: those are
846 dictionary words, not strings; it's just as easy -- and far clearer --
847 to stick rigidly to the preferred punctuation.
852 Finally, remember that Inform has been evolving since 1993. Over that
853 time, Graham has taken considerable care to maintain as much
854 compatibility as possible, so that games written years ago, for earlier
855 versions of the compiler and the library, will still compile today.
856 While generally a good thing, this brings the disadvantage that a
857 certain amount of obsolete baggage is still lying around. You may, for
858 example, see games using ``Nearby`` directives (denotes parentage,
859 roughly the same as ``->``) and ``near`` conditions (roughly, having the
860 same parent), or with ``" \ "`` controlling line breaks in long
861 ``print`` statements. Try to understand them; try *not* to use them.