1 ========================
3 ========================
11 .. image:: /images/picF.png
14 |F|\inally our three example games are written; we've shown you as much of
15 the Inform language as we've needed to, and made a lot of observations
16 about how and why something should be done. Despite all that, there's much
17 that we've left unsaid, or touched on only lightly. In this chapter we'll
18 revisit key topics and review some of the more significant omissions, to
19 give you a better feel for what's important, and what can be ignored for
20 the time being; when you become an accomplished designer, you will decide
21 what matters and what can be left on the shelf.
23 We'll also talk, in :ref:`reading-other-code`, about a few ways of doing
24 things that we've chosen not to tell you about, but which you're quite
25 likely to encounter if you look at Inform code written by other designers.
27 The tone here is perhaps a little dry, but trust us: in walking this dusty
28 ground we touch on just about everything that is fundamental in your
29 overall understanding of Inform. And as always, the |DM4| provides rounder
30 and more comprehensive coverage.
35 In this guide we’ve used the placeholder `{expression}` a few times;
36 here's roughly what we mean.
38 * An `{expression}` is a single `{value}`, or several `{values}`
39 combined using `{operators}` and sometimes parentheses ``(...)``.
41 * Possible `{values}` include:
43 * a literal number (-32768 to 32767)
45 * something that's represented as a number (a character ``'a'`` , a
46 dictionary word ``'aardvark'`` , a string ``"aardvark's adventure"``
47 or an action ``##Look`` )
49 * the internal identifier of a constant, an object, a class or a routine
51 * (only in a run-time statement, not in a compile-time directive) the
52 contents of a variable, or the return value from a routine.
54 * Possible `{operators}` include:
56 * an arithmetic operator: ``+ - * / % ++``
57 * a bitwise logical operator: ``& | ~``
58 * a numeric comparison operator: ``== ~= > < >= <=``
59 * an object conditional operator: ``ofclass in notin provides has hasnt``
60 * a boolean combinational operator: ``&& || ~~``
65 Many of the items which you define in your source file -- objects,
66 variables, routines, etc. -- need to be given a name so that other items
67 can refer to them. We call this name an item's internal identifier
68 (because it's used only within the source file and isn't visible to the
69 player), and we use the placeholders `{obj_id}`, `{var_id}`,
70 `{routine_id}`, etc. to represent where it's used. An internal ID
72 * can be up to thirty-two characters long
74 * must start with a letter or underscore, and then continue with letters
75 ``A-Z`` , underscore ``_`` and digits ``0-9`` (where upper-case and
76 lower-case letters are treated as indistinguishable)
78 * should generally be unique across all files: your source file, the
79 standard library files, and any library contributions which you've
80 used (except that a routine's local variables are not visible outside
90 We might need some custom syntax highlighting here.
92 A :term:`statement` is an instruction intended for the interpreter, telling
93 it what to do at run-time. It *must* be given in lower-case, and always
94 ends with a semicolon.
96 Some statements, like ``if``, control one or more other statements. We
97 use the placeholder `{statement_block}` to represent either a single
98 `{statement}`, or any number of `{statements}` enclosed in braces::
102 { statement; statement; ... statement; }
104 Statements that we've met
105 -------------------------
107 Our games have used these statements, about half of the Inform
110 give obj_id attribute;
111 give obj_id attribute attribute ... attribute;
113 if (expression) statement_block
114 if (expression) statement_block else statement_block
116 move obj_id to parent_obj_id;
118 objectloop (var_id) statement_block
121 print value, value, ... value;
124 print_ret value, value, ... value;
131 style underline; print...; style roman;
133 switch (expression) {
134 value: statement; statement; ... statement;
136 default: statement; statement; ... statement;
140 "string", value, ... value;
144 <action noun second>;
148 <<action noun second>>;
150 Statements that we've not met
151 -----------------------------
153 Although our example games haven't needed to use them, these looping
154 statements are sometimes useful::
159 do statement_block until (expression)
161 for (set_var : loop_while_expression : update_var) statement_block
163 while (expression) statement_block
165 On the other hand, we suggest that you put the following statements on
166 hold for now; they're not immediately relevant to everyday code and have
167 mostly to do with printing and formatting::
176 In particular, avoid using the deprecated jump statement if you possibly can.
181 In ``print`` and ``print_ret`` statements, each `{value}` can be:
183 * a numeric `{expression}`, displayed as a signed decimal number,
185 * a `"{string}"`, displayed literally, or
187 * a print rule. You can create your own, or use a standard one, including:
189 .. tabularcolumns:: ll
191 +-------------------------+---------------------------------------------------+
192 | `(a) {obj_id}` | the object's name, preceded by "a", "an" or "some"|
193 +-------------------------+---------------------------------------------------+
194 | `(A) {obj_id}` | as ``(a)`` but using "A", "An" or "Some" |
195 +-------------------------+---------------------------------------------------+
196 | `(the) {obj_id}` | the object's name, preceded by "the" |
197 +-------------------------+---------------------------------------------------+
198 | `(The) {obj_id}` | as ``(the)`` but using "The" |
199 +-------------------------+---------------------------------------------------+
200 | `(number) {expression}` | the numeric expression's value in words |
201 +-------------------------+---------------------------------------------------+
206 A :term:`directive` is an instruction intended for the compiler, telling it
207 what to do at compile-time, while the source file is being translated into
208 Z-code. By convention it's given an initial capital letter (though the
209 compiler doesn't enforce this) and always ends with a semicolon.
211 Directives that we've met
212 -------------------------
214 We've used all of these directives; note that for ``Class``, ``Extend``,
215 ``Object`` and ``Verb`` the full supported syntax is more sophisticated
216 than the basic form presented here::
223 has attribute attribute ... attribute;
226 Constant const_id = expression;
227 Constant const_id expression;
230 * token token ... token -> action
231 * token token ... token -> action
233 * token token ... token -> action
237 Object obj_id "external_name" parent_obj_id
242 has attribute attribute ... attribute;
251 * token token ... token -> action
252 * token token ... token -> action
254 * token token ... token -> action;
256 ! comment text which the compiler ignores
258 [ routine_id; statement; statement; ... statement; ];
260 #Ifdef any_id; ... #Endif;
262 Directives that we've not met
263 -----------------------------
265 There's only a handful of useful directives which we haven't needed to
271 Global var_id = expression;
278 but there's a whole load which are of fairly low importance for now::
301 An object is really just a collection of variables which together
302 represent the capabilities and current status of some specific component
303 of the model world. Full variables are called properties; simpler
304 two-state variables are attributes.
309 .. Generated by autoindex
311 pair: before; library property
312 pair: name; library property
314 The library defines around forty-eight standard property variables (such
315 as :prop:`before` or :prop:`name`), but you can readily create further ones just
316 by using them within an object definition.
318 You can create and initialise a property in an object's ``with`` segment:
320 property, ! set to zero / false
322 property value, ! set to a single value
324 property value value ... value, ! set to a list of values
326 In each case, the `{value}` is either a compile-time `{expression}`, or
327 an embedded routine::
331 property [; statement; statement; ... statement; ],
333 You can refer to the value of a property::
335 self.property ! only within that same object
337 obj_id.property ! everywhere
339 and you can test whether an object definition includes a given property::
341 (obj_id provides property) ! is true or false
348 Inform provides standalone routines and embedded routines.
353 Standalone routines are defined like this::
355 [ routine_id; statement; statement; ... statement; ];
357 and called like this::
364 These are embedded as the value of an object's property::
366 property [; statement; statement; ... statement; ],
368 and are usually called automatically by the library, or manually by::
370 self.property() ! only within that same object
372 obj_id.property() ! everywhere
375 single: arguments (of a routine)
377 Arguments and local variables
378 -----------------------------
380 Both types of routine support up to fifteen local variables -- variables
381 which can be used only by the statements within the routine, and which
382 are automatically initialised to zero every time that the routine is
385 [ routine_id var_id var_id ... var_id; statement; statement; ... statement; ];
387 property [ var_id var_id ... var_id; statement; statement; ... statement; ],
389 You can pass up to seven arguments to a routine, by listing those
390 arguments within the parentheses when you call the routine. The effect
391 is simply to initialise the matching local variables to the argument
392 values rather than to zero::
394 routine_id(expression, expression, ... expression)
396 Although it works, this technique is rarely used with embedded routines,
397 because there is no mechanism for the library to supply argument values
398 when calling the routine.
403 Every routine returns a single value, which is supplied either
404 explicitly by some form of return statement::
406 [ routine_id; statement; statement; ... return expr; ]; ! returns expr
408 property [; statement; statement; ... return expr; ], ! returns expr
410 or implicitly when the routine runs out of statements. If none of these
411 ``statements`` is one -- ``return``, ``print_ret``, ``"..."`` or
412 ``<<...>>`` -- that causes an explicit return, then::
414 [ routine_id; statement; statement; ... statement; ];
416 .. Generated by autoindex
418 pair: true; library constant
420 returns :const:`true` and ::
422 property [; statement; statement; ... statement; ]
424 return :const:`false`.
426 This difference is *important*. Remember it by the letter pairs STEF:
427 left to themselves, Standalone routines return True, Embedded routines
430 Here's an example standalone routine which returns the larger of its two
433 [ Max a b; if (a > b) return a; else return b; ];
435 and here are some examples of its use (note that the first example,
436 though legal, does nothing useful whatsoever)::
442 if (Max(x,7) == 7) ...
444 switch (Max(3,y)) { ...
446 Library routines versus entry points
447 ------------------------------------
449 A library routine is a standard routine, included within the library
450 files, which you can optionally call from your source file if you
451 require the functionality which the routine provides. We've mentioned
452 these library routines::
454 IndirectlyContains(parent_obj_id, obj_id)
458 PlayerTo(obj_id, flag)
465 By contrast, an entry point routine is a routine which you can provide
466 in your source file, in which case the library calls it at an
467 appropriate time. We've mentioned these optional entry point routines::
471 InScope(actor_obj_id)
473 And this, the only mandatory one::
477 There are full lists in :ref:`library-routines` and :ref:`entry-points`.
479 .. _reading-other-code:
481 Reading other people's code
482 ===========================
484 Right at the start of this guide, we warned you that we weren't setting
485 out to be comprehensive; we've concentrated on presenting the most
486 important aspects of Inform, as clearly as we can. However, when you
487 read the *Inform Designer's* Manual, and more especially when you look
488 at complete games or library extensions which other designers have
489 produced, you'll come across other ways of doing things -- and it might
490 be that you, like other authors, prefer them over our methods. Just try
491 to find a style that suits you and, this is the important bit, be
492 *consistent* about its use. In this section, we highlight some of the
493 more obvious differences which you may encounter.
498 Every designer has his or her own style for laying out their source
499 code, and they're all worse than the one you adopt. Inform's flexibility
500 makes it easy for designers to choose a style that suits them;
501 unfortunately, for some designers this choice seems influenced by the
502 Jackson Pollock school of art. We've advised you to be consistent, to
503 use plenty of white space and indentation, to choose sensible names, to
504 add comments at difficult sections, to actively *think*, as you write
505 your code, about making it as readable as you can.
507 This is doubly true if you ever contemplate sharing a library extension
508 with the rest of the community. This example, with the name changed, is
509 from a file in the Archive::
513 if (i in player) rtrue;
514 if (i has static || (i has scenery)) rtrue;
516 if (runroutines(j,before) ~= 0 || (j has static || (j has scenery))) {
517 print "You'll have to disconnect ",(the) i," from ",(the) j," first.^";
521 if (runroutines(i,before)~=0 || (i has static || (i has scenery))) {
522 print "You'll have to disconnect ",(the) i," from ",(the) j," first.^";
526 if (j hasnt concealed && j hasnt static) move j to player;
527 if (i hasnt static && i hasnt concealed) move i to player;
529 if (runroutines(j,after) ~= 0) rtrue;
530 print "You take ",(the) i," and ",(the) j," connected to it.^";
535 Here's the same routine after a few minutes spent purely on making it
536 more comprehensible; we haven't actually tested that it (still) works,
537 though that second ``else`` looks suspicious::
540 if (i in player || i has static or scenery || j == nothing) return true;
542 if (RunRoutines(j,before) || j has static or scenery)
543 "You'll have to disconnect ", (the) i, " from ", (the) j, " first.";
545 if (RunRoutines(i,before) || i has static or scenery)
546 "You'll have to disconnect ", (the) i, " from ", (the) j, " first.";
548 if (j hasnt static or concealed) move j to player;
549 if (i hasnt static or concealed) move i to player;
550 if (RunRoutines(j,after)) return true;
551 "You take ", (the) i, " and ", (the) j, " connected to it.";
555 We hope you'll agree that the result was worth the tiny extra effort.
556 Code gets written once; it gets read dozens and dozens of times.
561 There are a few statement shortcuts, some more useful than others, which
564 * These five lines all do the same thing::
570 ]; ! at the end of a standalone routine
572 * These four lines all do the same thing::
577 ]; ! at the end of an embedded routine
579 * These four lines all do the same thing::
581 print "string"; new_line; return true;
582 print "string^"; return true;
586 * These lines are the same::
588 print value1; print value2; print value3;
589 print value1, value2, value3;
591 * These lines are the same::
593 <action noun second>; return true;
594 <<action noun second>>;
596 * These lines are also the same::
601 * These ``if`` statements are equivalent::
603 if (MyVar == 1 || MyVar == 3 || MyVar == 7) ...
605 if (MyVar == 1 or 3 or 7) ...
607 * These ``if`` statements are equivalent as well::
609 if (MyVar ~= 1 && MyVar ~= 3 && MyVar ~= 7) ...
610 if (MyVar ~= 1 or 3 or 7) ...
612 * In an ``if`` statement, the thing in parentheses can be *any*
613 expression; all that matters is its value: zero (false) or anything
614 else (true). For example, these statements are equivalent::
616 if (MyVar ~= false) ...
617 if (~~(MyVar == false)) ...
619 if (~~(MyVar == 0)) ...
622 Note that the following statement specifically tests whether ``MyVar``
623 contains :const:`true` (1), *not* whether its value is anything other than
626 if (MyVar == true) ...
628 * If ``MyVar`` is a variable, the statements ``MyVar++;`` and
629 ``++MyVar;`` work the same as ``MyVar = MyVar + 1;`` For example,
630 these lines are equivalent::
632 MyVar = MyVar + 1; if (MyVar == 3) ...
633 if (++MyVar == 3) ...
634 if (MyVar++ == 2) ...
636 What's the same about ``MyVar++`` and ``++MyVar`` is that they both
637 add one to ``MyVar``. What's different about them is the value to
638 which the construct itself evaluates: ``MyVar++`` returns the current
639 value of ``MyVar`` and then performs the increment, whereas
640 ``++MyVar`` does the "+1" first and then returns the incremented
641 value. In the example, if ``MyVar`` currently contains 2 then
642 ``++MyVar`` returns 3 and ``MyVar++`` returns 2, even though in both
643 cases the value of ``MyVar`` afterwards is 3. As another example,
644 this code (from Helga in "William Tell")::
646 Talk: self.times_spoken_to = self.times_spoken_to + 1;
647 switch (self.times_spoken_to) {
648 1: score = score + 1;
649 print_ret "You warmly thank Helga for the apple.";
650 2: print_ret "~See you again soon.~";
651 default: return false;
655 could have been written more succinctly like this::
657 Talk: switch (++self.times_spoken_to) {
659 print_ret "You warmly thank Helga for the apple.";
660 2: print_ret "~See you again soon.~";
661 default: return false;
665 * Similarly, the statements ``MyVar--;`` and ``--MyVar;`` work the same
666 as ``MyVar = MyVar - 1;`` Again, these lines are equivalent::
668 MyVar = MyVar - 1; if (MyVar == 7) ...
669 if (--MyVar == 7) ...
670 if (MyVar-- == 8) ...
672 "number" property and "general" attribute
673 -----------------------------------------
675 .. Generated by autoindex
677 pair: general; library attribute
678 pair: number; library property
680 The library defines a standard :prop:`number` property and a standard
681 :attr:`general` attribute, whose roles are undefined: they are
682 general-purpose variables available within every object to designers as
683 and when they desire.
685 We recommend that you avoid using these two variables, primarily because
686 their names are, by their very nature, so bland as to be largely
687 meaningless. Your game will be clearer and easier to debug if you
688 instead create new property variables -- with appropriate names -- as
689 part of your ``Object`` and ``Class`` definitions.
693 Common properties and attributes
694 --------------------------------
696 As an alternative to creating new individual properties which apply only to
697 a single object (or class of objects), it's possible to devise properties
698 and new attributes which, like those defined by the library, are available
699 on *all* objects. The need to do this is actually quite rare, and is mostly
700 confined to library extensions (for example, the ``pname.h`` extension
701 which we encountered in :doc:`12` gives every object a ``pname`` property
702 and a ``phrase_matched`` attribute). To create them, you would use these
703 directives near the start of your source file::
709 We recommend that you avoid using these two directives unless you really
710 do need to affect every object -- or at least the majority of them -- in
711 your game. There is a limit of forty-eight attributes (of which the
712 library currently defines around thirty) and sixty-two of these common
713 properties (of which the library currently defines around forty-eight).
714 On the other hand, the number of individual properties which you can add
715 is virtually unlimited.
719 Setting up the object tree
720 --------------------------
722 .. Generated by autoindex
724 pair: found_in; library property
726 Throughout this guide, we've defined the initial position of each object
727 within the overall object tree either by explicitly mentioning its
728 parent's ``obj_id`` (if any) in the first line of the object definition
729 -- what we've been calling the header information -- or, for a few
730 objects which crop up in more than one place, by using their
731 :prop:`found_in` properties. For example, in "William Tell" we defined
732 twenty-seven objects; omitting those which used :prop:`found_in` to define
733 their placement at the start of the game, we're left with object
734 definitions starting like this::
736 Room street "A street in Altdorf"
738 Room below_square "Further along the street"
739 Furniture stall "fruit and vegetable stall" below_square
740 Prop "potatoes" below_square
741 Prop "fruit and vegetables" below_square
742 NPC stallholder "Helga" below_square
744 Room south_square "South side of the square"
746 Room mid_square "Middle of the square"
747 Furniture pole "hat on a pole" mid_square
749 Room north_square "North side of the square"
751 Room marketplace "Marketplace near the square"
752 Object tree "lime tree" marketplace
753 NPC governor "governor" marketplace
757 Object quiver "quiver"
764 You'll see that several of the objects begin the game as parents:
765 ``below_square``, ``mid_square``, ``marketplace`` and ``quiver`` all
766 have child objects beneath them; those children mention their parent as
767 the last item of header information.
769 There's an alternative object syntax which is available to achieve the
770 same object tree, using "arrows". That is, we could have defined those
771 parent-and-child objects as::
773 Room below_square "Further along the street"
774 Furniture -> stall "fruit and vegetable stall"
776 Prop -> "fruit and vegetables"
777 NPC -> stallholder "Helga"
779 Room mid_square "Middle of the square"
780 Furniture -> pole "hat on a pole"
782 Room marketplace "Marketplace near the square"
783 Object -> tree "lime tree"
784 NPC -> governor "governor"
786 Object quiver "quiver"
791 The idea is that an object's header information *either* starts with an
792 arrow, or ends with an ``obj_id``, or has neither (having both isn’t
793 permitted). An object with neither has no parent: in this example,
794 that's all the ``Rooms``, and also the ``bow`` and the ``quiver`` (which
795 are moved to the player ``object`` in the ``Initialise`` routine) and
796 the apple (which remains without a parent until Helga gives it to
799 An object which starts with a single arrow ``->`` is defined to be a
800 child of the nearest previous object without a parent. Thus, for
801 example, the ``tree`` and ``governor`` objects are both children of the
802 ``marketplace``. To define a child of a child, you'd use two arrows
803 ``-> ->``, and so on. In "William Tell", that situation doesn't occur;
804 to illustrate how it works, imagine that at the start of the game the
805 potatoes and the other fruit and vegetables where actually *on* the
806 stall. Then we might have used::
808 Room below_square "Further along the street"
809 Furniture -> stall "fruit and vegetable stall"
810 Prop -> -> "potatoes"
811 Prop -> -> "fruit and vegetables"
812 NPC -> stallholder "Helga"
815 That is, the objects with one arrow (the ``stall`` and ``stallholder``)
816 are children of the nearest object without a parent (the ``Room``), and
817 the objects with two arrows (the produce) are children of the nearest
818 object defined with a single arrow (the ``stall``).
820 The advantages of using arrows include:
822 * You're forced to define your objects in a "sensible" order.
824 * Fewer ``obj_ids`` may need to be used (though in this game it would
827 The disadvantages include:
829 * The fact that objects are related by the physical juxtaposition of
830 their definitions is not necessarily intuitive to all designers.
832 * Especially in a crowded room, it’s harder to be certain exactly how
833 the various parent–child relationships are initialised, other than by
834 carefully counting lots of arrows.
836 * If you relocate the parent within the initial object hierarchy to a
837 higher or lower level, you'll need also to change its children by
838 adding or removing arrows; this isn't necessary when the parent is
839 named in the child headers.
841 We prefer to explicitly name the parent, but you'll encounter both forms
844 Quotes in "name" properties
845 ---------------------------
847 We went to some lengths, way back in :ref:`things-in-quotes`, to explain
848 the difference between double quotes ``"..."`` (strings to be output) and
849 single quotes ``'...'`` (input tokens -- dictionary words). Perhaps
850 somewhat unfortunately, Inform allows you to blur this clean distinction:
851 you can use double quotes in name properties and Verb directives::
853 NPC stallholder "Helga" below_square
854 with name "stallholder" "greengrocer" "monger" "shopkeeper" "merchant"
855 "owner" "Helga" "dress" "scarf" "headscarf",
858 Verb "talk" "t//" "converse" "chat" "gossip"
859 * "to"/"with" creature -> Talk
862 *Please* don't do this. You'll just confuse yourself: those are
863 dictionary words, not strings; it's just as easy -- and far clearer --
864 to stick rigidly to the preferred punctuation.
869 Finally, remember that Inform has been evolving since 1993. Over that
870 time, Graham has taken considerable care to maintain as much
871 compatibility as possible, so that games written years ago, for earlier
872 versions of the compiler and the library, will still compile today.
873 While generally a good thing, this brings the disadvantage that a
874 certain amount of obsolete baggage is still lying around. You may, for
875 example, see games using ``Nearby`` directives (denotes parentage,
876 roughly the same as ``->``) and ``near`` conditions (roughly, having the
877 same parent), or with ``" \ "`` controlling line breaks in long
878 ``print`` statements. Try to understand them; try *not* to use them.