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 The library defines around forty-eight standard property variables (such
310 as ``before`` or ``name``), but you can readily create further ones just
311 by using them within an object definition.
313 You can create and initialise a property in an object's ``with`` segment:
315 property, ! set to zero / false
317 property value, ! set to a single value
319 property value value ... value, ! set to a list of values
321 In each case, the `{value}` is either a compile-time `{expression}`, or
322 an embedded routine::
326 property [; statement; statement; ... statement; ],
328 You can refer to the value of a property::
330 self.property ! only within that same object
332 obj_id.property ! everywhere
334 and you can test whether an object definition includes a given property::
336 (obj_id provides property) ! is true or false
343 Inform provides standalone routines and embedded routines.
348 Standalone routines are defined like this::
350 [ routine_id; statement; statement; ... statement; ];
352 and called like this::
359 These are embedded as the value of an object's property::
361 property [; statement; statement; ... statement; ],
363 and are usually called automatically by the library, or manually by::
365 self.property() ! only within that same object
367 obj_id.property() ! everywhere
369 Arguments and local variables
370 -----------------------------
372 Both types of routine support up to fifteen local variables -- variables
373 which can be used only by the statements within the routine, and which
374 are automatically initialised to zero every time that the routine is
377 [ routine_id var_id var_id ... var_id; statement; statement; ... statement; ];
379 property [ var_id var_id ... var_id; statement; statement; ... statement; ],
381 You can pass up to seven arguments to a routine, by listing those
382 arguments within the parentheses when you call the routine. The effect
383 is simply to initialise the matching local variables to the argument
384 values rather than to zero::
386 routine_id(expression, expression, ... expression)
388 Although it works, this technique is rarely used with embedded routines,
389 because there is no mechanism for the library to supply argument values
390 when calling the routine.
395 Every routine returns a single value, which is supplied either
396 explicitly by some form of return statement::
398 [ routine_id; statement; statement; ... return expr; ]; ! returns expr
400 property [; statement; statement; ... return expr; ], ! returns expr
402 or implicitly when the routine runs out of statements. If none of these
403 ``statements`` is one -- ``return``, ``print_ret``, ``"..."`` or
404 ``<<...>>`` -- that causes an explicit return, then::
406 [ routine_id; statement; statement; ... statement; ];
408 returns ``true`` and ::
410 property [; statement; statement; ... statement; ]
414 This difference is *important*. Remember it by the letter pairs STEF:
415 left to themselves, Standalone routines return True, Embedded routines
418 Here's an example standalone routine which returns the larger of its two
421 [ Max a b; if (a > b) return a; else return b; ];
423 and here are some examples of its use (note that the first example,
424 though legal, does nothing useful whatsoever)::
430 if (Max(x,7) == 7) ...
432 switch (Max(3,y)) { ...
434 Library routines versus entry points
435 ------------------------------------
437 A library routine is a standard routine, included within the library
438 files, which you can optionally call from your source file if you
439 require the functionality which the routine provides. We've mentioned
440 these library routines::
442 IndirectlyContains(parent_obj_id, obj_id)
446 PlayerTo(obj_id, flag)
453 By contrast, an entry point routine is a routine which you can provide
454 in your source file, in which case the library calls it at an
455 appropriate time. We've mentioned these optional entry point routines::
459 InScope(actor_obj_id)
461 And this, the only mandatory one::
465 There are full lists in :ref:`library-routines` and :ref:`entry-points`.
467 .. _reading-other-code:
469 Reading other people's code
470 ===========================
472 Right at the start of this guide, we warned you that we weren't setting
473 out to be comprehensive; we've concentrated on presenting the most
474 important aspects of Inform, as clearly as we can. However, when you
475 read the *Inform Designer's* Manual, and more especially when you look
476 at complete games or library extensions which other designers have
477 produced, you'll come across other ways of doing things -- and it might
478 be that you, like other authors, prefer them over our methods. Just try
479 to find a style that suits you and, this is the important bit, be
480 *consistent* about its use. In this section, we highlight some of the
481 more obvious differences which you may encounter.
486 Every designer has his or her own style for laying out their source
487 code, and they're all worse than the one you adopt. Inform's flexibility
488 makes it easy for designers to choose a style that suits them;
489 unfortunately, for some designers this choice seems influenced by the
490 Jackson Pollock school of art. We've advised you to be consistent, to
491 use plenty of white space and indentation, to choose sensible names, to
492 add comments at difficult sections, to actively *think*, as you write
493 your code, about making it as readable as you can.
495 This is doubly true if you ever contemplate sharing a library extension
496 with the rest of the community. This example, with the name changed, is
497 from a file in the Archive::
501 if (i in player) rtrue;
502 if (i has static || (i has scenery)) rtrue;
504 if (runroutines(j,before) ~= 0 || (j has static || (j has scenery))) {
505 print "You'll have to disconnect ",(the) i," from ",(the) j," first.^";
509 if (runroutines(i,before)~=0 || (i has static || (i has scenery))) {
510 print "You'll have to disconnect ",(the) i," from ",(the) j," first.^";
514 if (j hasnt concealed && j hasnt static) move j to player;
515 if (i hasnt static && i hasnt concealed) move i to player;
517 if (runroutines(j,after) ~= 0) rtrue;
518 print "You take ",(the) i," and ",(the) j," connected to it.^";
523 Here's the same routine after a few minutes spent purely on making it
524 more comprehensible; we haven't actually tested that it (still) works,
525 though that second ``else`` looks suspicious::
528 if (i in player || i has static or scenery || j == nothing) return true;
530 if (RunRoutines(j,before) || j has static or scenery)
531 "You'll have to disconnect ", (the) i, " from ", (the) j, " first.";
533 if (RunRoutines(i,before) || i has static or scenery)
534 "You'll have to disconnect ", (the) i, " from ", (the) j, " first.";
536 if (j hasnt static or concealed) move j to player;
537 if (i hasnt static or concealed) move i to player;
538 if (RunRoutines(j,after)) return true;
539 "You take ", (the) i, " and ", (the) j, " connected to it.";
543 We hope you'll agree that the result was worth the tiny extra effort.
544 Code gets written once; it gets read dozens and dozens of times.
549 There are a few statement shortcuts, some more useful than others, which
552 * These five lines all do the same thing::
558 ]; ! at the end of a standalone routine
560 * These four lines all do the same thing::
565 ]; ! at the end of an embedded routine
567 * These four lines all do the same thing::
569 print "string"; new_line; return true;
570 print "string^"; return true;
574 * These lines are the same::
576 print value1; print value2; print value3;
577 print value1, value2, value3;
579 * These lines are the same::
581 <action noun second>; return true;
582 <<action noun second>>;
584 * These lines are also the same::
589 * These ``if`` statements are equivalent::
591 if (MyVar == 1 || MyVar == 3 || MyVar == 7) ...
593 if (MyVar == 1 or 3 or 7) ...
595 * These ``if`` statements are equivalent as well::
597 if (MyVar ~= 1 && MyVar ~= 3 && MyVar ~= 7) ...
598 if (MyVar ~= 1 or 3 or 7) ...
600 * In an ``if`` statement, the thing in parentheses can be *any*
601 expression; all that matters is its value: zero (false) or anything
602 else (true). For example, these statements are equivalent::
604 if (MyVar ~= false) ...
605 if (~~(MyVar == false)) ...
607 if (~~(MyVar == 0)) ...
610 Note that the following statement specifically tests whether ``MyVar``
611 contains ``true`` (1), *not* whether its value is anything other than
614 if (MyVar == true) ...
616 * If ``MyVar`` is a variable, the statements ``MyVar++;`` and
617 ``++MyVar;`` work the same as ``MyVar = MyVar + 1;`` For example,
618 these lines are equivalent::
620 MyVar = MyVar + 1; if (MyVar == 3) ...
621 if (++MyVar == 3) ...
622 if (MyVar++ == 2) ...
624 What's the same about ``MyVar++`` and ``++MyVar`` is that they both
625 add one to ``MyVar``. What's different about them is the value to
626 which the construct itself evaluates: ``MyVar++`` returns the current
627 value of ``MyVar`` and then performs the increment, whereas
628 ``++MyVar`` does the "+1" first and then returns the incremented
629 value. In the example, if ``MyVar`` currently contains 2 then
630 ``++MyVar`` returns 3 and ``MyVar++`` returns 2, even though in both
631 cases the value of ``MyVar`` afterwards is 3. As another example,
632 this code (from Helga in "William Tell")::
634 Talk: self.times_spoken_to = self.times_spoken_to + 1;
635 switch (self.times_spoken_to) {
636 1: score = score + 1;
637 print_ret "You warmly thank Helga for the apple.";
638 2: print_ret "~See you again soon.~";
639 default: return false;
643 could have been written more succinctly like this::
645 Talk: switch (++self.times_spoken_to) {
647 print_ret "You warmly thank Helga for the apple.";
648 2: print_ret "~See you again soon.~";
649 default: return false;
653 * Similarly, the statements ``MyVar--;`` and ``--MyVar;`` work the same
654 as ``MyVar = MyVar - 1;`` Again, these lines are equivalent::
656 MyVar = MyVar - 1; if (MyVar == 7) ...
657 if (--MyVar == 7) ...
658 if (MyVar-- == 8) ...
660 "number" property and "general" attribute
661 -----------------------------------------
663 The library defines a standard ``number`` property and a standard
664 ``general`` attribute, whose roles are undefined: they are
665 general-purpose variables available within every object to designers as
666 and when they desire.
668 We recommend that you avoid using these two variables, primarily because
669 their names are, by their very nature, so bland as to be largely
670 meaningless. Your game will be clearer and easier to debug if you
671 instead create new property variables -- with appropriate names -- as
672 part of your ``Object`` and ``Class`` definitions.
676 Common properties and attributes
677 --------------------------------
679 As an alternative to creating new individual properties which apply only to
680 a single object (or class of objects), it's possible to devise properties
681 and new attributes which, like those defined by the library, are available
682 on *all* objects. The need to do this is actually quite rare, and is mostly
683 confined to library extensions (for example, the ``pname.h`` extension
684 which we encountered in :doc:`12` gives every object a ``pname`` property
685 and a ``phrase_matched`` attribute). To create them, you would use these
686 directives near the start of your source file::
692 We recommend that you avoid using these two directives unless you really
693 do need to affect every object -- or at least the majority of them -- in
694 your game. There is a limit of forty-eight attributes (of which the
695 library currently defines around thirty) and sixty-two of these common
696 properties (of which the library currently defines around forty-eight).
697 On the other hand, the number of individual properties which you can add
698 is virtually unlimited.
702 Setting up the object tree
703 --------------------------
705 Throughout this guide, we've defined the initial position of each object
706 within the overall object tree either by explicitly mentioning its
707 parent's ``obj_id`` (if any) in the first line of the object definition
708 -- what we've been calling the header information -- or, for a few
709 objects which crop up in more than one place, by using their
710 ``found_in`` properties. For example, in "William Tell" we defined
711 twenty-seven objects; omitting those which used ``found_in`` to define
712 their placement at the start of the game, we're left with object
713 definitions starting like this::
715 Room street "A street in Altdorf"
717 Room below_square "Further along the street"
718 Furniture stall "fruit and vegetable stall" below_square
719 Prop "potatoes" below_square
720 Prop "fruit and vegetables" below_square
721 NPC stallholder "Helga" below_square
723 Room south_square "South side of the square"
725 Room mid_square "Middle of the square"
726 Furniture pole "hat on a pole" mid_square
728 Room north_square "North side of the square"
730 Room marketplace "Marketplace near the square"
731 Object tree "lime tree" marketplace
732 NPC governor "governor" marketplace
736 Object quiver "quiver"
743 You'll see that several of the objects begin the game as parents:
744 ``below_square``, ``mid_square``, ``marketplace`` and ``quiver`` all
745 have child objects beneath them; those children mention their parent as
746 the last item of header information.
748 There's an alternative object syntax which is available to achieve the
749 same object tree, using "arrows". That is, we could have defined those
750 parent-and-child objects as::
752 Room below_square "Further along the street"
753 Furniture -> stall "fruit and vegetable stall"
755 Prop -> "fruit and vegetables"
756 NPC -> stallholder "Helga"
758 Room mid_square "Middle of the square"
759 Furniture -> pole "hat on a pole"
761 Room marketplace "Marketplace near the square"
762 Object -> tree "lime tree"
763 NPC -> governor "governor"
765 Object quiver "quiver"
770 The idea is that an object's header information *either* starts with an
771 arrow, or ends with an ``obj_id``, or has neither (having both isn’t
772 permitted). An object with neither has no parent: in this example,
773 that's all the ``Rooms``, and also the ``bow`` and the ``quiver`` (which
774 are moved to the player ``object`` in the ``Initialise`` routine) and
775 the apple (which remains without a parent until Helga gives it to
778 An object which starts with a single arrow ``->`` is defined to be a
779 child of the nearest previous object without a parent. Thus, for
780 example, the ``tree`` and ``governor`` objects are both children of the
781 ``marketplace``. To define a child of a child, you'd use two arrows
782 ``-> ->``, and so on. In "William Tell", that situation doesn't occur;
783 to illustrate how it works, imagine that at the start of the game the
784 potatoes and the other fruit and vegetables where actually *on* the
785 stall. Then we might have used::
787 Room below_square "Further along the street"
788 Furniture -> stall "fruit and vegetable stall"
789 Prop -> -> "potatoes"
790 Prop -> -> "fruit and vegetables"
791 NPC -> stallholder "Helga"
794 That is, the objects with one arrow (the ``stall`` and ``stallholder``)
795 are children of the nearest object without a parent (the ``Room``), and
796 the objects with two arrows (the produce) are children of the nearest
797 object defined with a single arrow (the ``stall``).
799 The advantages of using arrows include:
801 * You're forced to define your objects in a "sensible" order.
803 * Fewer ``obj_ids`` may need to be used (though in this game it would
806 The disadvantages include:
808 * The fact that objects are related by the physical juxtaposition of
809 their definitions is not necessarily intuitive to all designers.
811 * Especially in a crowded room, it’s harder to be certain exactly how
812 the various parent–child relationships are initialised, other than by
813 carefully counting lots of arrows.
815 * If you relocate the parent within the initial object hierarchy to a
816 higher or lower level, you'll need also to change its children by
817 adding or removing arrows; this isn't necessary when the parent is
818 named in the child headers.
820 We prefer to explicitly name the parent, but you'll encounter both forms
823 Quotes in "name" properties
824 ---------------------------
826 We went to some lengths, way back in :ref:`things-in-quotes`, to explain
827 the difference between double quotes ``"..."`` (strings to be output) and
828 single quotes ``'...'`` (input tokens -- dictionary words). Perhaps
829 somewhat unfortunately, Inform allows you to blur this clean distinction:
830 you can use double quotes in name properties and Verb directives::
832 NPC stallholder "Helga" below_square
833 with name "stallholder" "greengrocer" "monger" "shopkeeper" "merchant"
834 "owner" "Helga" "dress" "scarf" "headscarf",
837 Verb "talk" "t//" "converse" "chat" "gossip"
838 * "to"/"with" creature -> Talk
841 *Please* don't do this. You'll just confuse yourself: those are
842 dictionary words, not strings; it's just as easy -- and far clearer --
843 to stick rigidly to the preferred punctuation.
848 Finally, remember that Inform has been evolving since 1993. Over that
849 time, Graham has taken considerable care to maintain as much
850 compatibility as possible, so that games written years ago, for earlier
851 versions of the compiler and the library, will still compile today.
852 While generally a good thing, this brings the disadvantage that a
853 certain amount of obsolete baggage is still lying around. You may, for
854 example, see games using ``Nearby`` directives (denotes parentage,
855 roughly the same as ``->``) and ``near`` conditions (roughly, having the
856 same parent), or with ``" \ "`` controlling line breaks in long
857 ``print`` statements. Try to understand them; try *not* to use them.