Most of the guide's text appears in this typeface, except where we're using
words which are part of the Inform system (like ``print``, ``Include``,
``VerbLib``) or are extracted from one of our games (like ``bird``,
-``nest``, ``top_of_tree``). Terms in **bold type** are included in the
-glossary -- Appendix G on page 273. We switch to italic type for a
-placeholder: for example you should read the Inform statement:
+``nest``, ``top_of_tree``).
+
+.. only:: html
+
+ Terms that are included in the :doc:`Glossary <appendices/g>` appear as
+ links to that glossary entry.
+
+.. only:: latex
+
+ Terms that are included in the :doc:`Glossary <appendices/g>` appear in
+ blue italic. In the PDF version, these are links to the glossary entry.
+
+We switch to italic type for a placeholder: for example you should read the
+Inform statement:
:samp:`print "{string}";`
.. [#play]
If you feel confused about IF in general or about this distinction
- between writing and playing in particular, try glancing ahead at "Just
- what is interactive fiction?" on page 13 and at "How to play an IF game"
- on page 209; also, you may find the Ifaq at
- http://www.plover.net/~textfire/raiffaq/ifaq/ helpful.
+ between writing and playing in particular, try glancing ahead at
+ :doc:`chapters/01` and at :doc:`appendices/a`; also, you may find the
+ Ifaq at http://www.plover.net/~textfire/raiffaq/ifaq/ helpful.
.. literalinclude:: /examples/Tell.inf
:language: inform6
+.. _compile-as-you-go:
+
Compile-as-you-go
=================
`wn`
The input stream word number, counting from 1.
+.. _library-routines:
+
Library routines
================
Returns the type of its `{arg}` : 3 for a string address, 2 for a routine
address, 1 for an object number, or 0 otherwise.
+.. _object-props:
+
Object properties
=================
For a `lockable` object: the `{obj_id}` (generally some kind of key)
needed to lock and unlock the object, or `nothing` if no key fits.
+.. _object-attrs:
+
Object attributes
=================
`worn`
For a `clothing` object: is being worn.
+.. _entry-points:
+
Optional entry points
=====================
`UnknownVerb()`
Called when an unusual verb is encountered.
+.. _group-1-actions:
+
Group 1 actions
===============
`XTree` "`TREE`"
=============== ===================================================
+.. _group-2-actions:
+
Group 2 actions
===============
`Wear` "`DON`", "`PUT ON`", "`WEAR`"
============= =============================================================
+.. _group-3-actions:
+
Group 3 actions
===============
And now an extract from the same tale, this time in the form of a tiny text
adventure game. If you're new to interaction with text adventures you'll
-find some general instructions in "How to play an IF game" on page 209, and
-you can see a complete transcript of the game in the "William Tell" story
-on page 219::
+find some general instructions in :doc:`/appendices/a`, and you can see a
+complete transcript of the game in :doc:`/appendices/c`. ::
A street in Altdorf
The narrow street runs north towards the town square. Local folk are
* How do I work this thing?
Whereas the presence of Helga is an elaboration of the folk tale, the
- shooting of the arrow (it's in the transcript in "William Tell" story
- on page 219, not in the extract above) illustrates the opposite
- principle: simplification. The tale builds dramatic tension by
- describing each step as Wilhelm prepares to shoot the apple. That's
- OK; he's been an archer all his life, and knows how to do it. You, on
- the other hand, probably know little about archery, and shouldn't be
- expected to guess at the process and vocabulary. Let's hope you know
- that you need to shoot at the apple -- and that's all it takes. The
- game explains what was involved, but doesn't force you through each
- mundane step.
+ shooting of the arrow (it's in the transcript in :doc:`/appendices/c`,
+ not in the extract above) illustrates the opposite principle:
+ simplification. The tale builds dramatic tension by describing each
+ step as Wilhelm prepares to shoot the apple. That's OK; he's been an
+ archer all his life, and knows how to do it. You, on the other hand,
+ probably know little about archery, and shouldn't be expected to guess
+ at the process and vocabulary. Let's hope you know that you need to
+ shoot at the apple -- and that's all it takes. The game explains what
+ was involved, but doesn't force you through each mundane step.
Of course, all of these are generalisations, not universal truths; you
could find fine works of IF which contradict each observation. However,
0000000000000000000000000000168F000000000000010200000000362E3231
...
-but, as you'll notice from the full transcript in "William Tell" story on
-page 219, the player will see the following::
+but, as you'll notice from the full transcript in :doc:`/appendices/c`, the
+player will see the following::
The place: Altdorf, in the Swiss canton of Uri. The year is 1307, at
which time Switzerland is under rule by the Emperor Albert of
embedded graphics; it simply enables you to type lines of text, which is
exactly what's needed to create an IF game.
-If you look at the game source on the previous page, or in the "William
-Tell" story on page 219, you'll notice ``Include "Parser";`` and ``Include
+If you look at the game source on the previous page, or in
+:doc:`/appendices/c`, you'll notice ``Include "Parser";`` and ``Include
"VerbLib";`` a few lines down from the top of the file. These are
instructions to the Inform compiler to "include" -- that is, to merge in
the contents -- of files called ``Parser.h`` and ``VerbLib.h``. These are
find it easier to download a complete package containing everything that
you need to get started.
+.. _inform-windows:
+
Inform on an IBM PC (running Microsoft Windows)
===============================================
interpreter with similar ease. The convenience of doing this far outweighs
the small amount of time needed to obtain and configure TextPad.
+.. _inform-apple:
+
Inform on an Apple Macintosh (running OS X)
===========================================
learn, but just as easy to break, and all Inform designers inadvertently do
so on a regular basis. There's some additional information about dealing
with these mistakes, and about controlling how the compiler behaves, in
-"Compiling your game" on page 189.
+:doc:`15`.
.. rubric:: More about the interpreter
containing two files: ``Heidi.inf`` and either ``Heidi.bat`` or
``Heidi.command``.
-#. Compile the source file ``Heidi.inf``; refer back to "Inform on an IBM
- PC (running Microsoft Windows)" on page 19 or "Inform on an Apple
- Macintosh (running OS X)" on page 24 for guidance. If the compilation
- works, a story file ``Heidi.z5`` appears in the folder. If the
- compilation *doesn't* work, you've probably made a typing mistake; check
- everything until you find it.
+#. Compile the source file ``Heidi.inf``; refer back to
+ :ref:`inform-windows` or :ref:`inform-apple` for guidance. If the
+ compilation works, a story file ``Heidi.z5`` appears in the folder. If
+ the compilation *doesn't* work, you've probably made a typing mistake;
+ check everything until you find it.
#. You can run the story file in your Inform interpreter; you should see
this (except that the Serial number will be different -- it's based on
introduced all sorts of Inform concepts, often without giving you much
detail about what's been happening. So let's review some of what we've
learnt so far, in a slightly more organised fashion. We'll talk about
-"Constants and variables" on page 49, "Object definitions" on page 50,
-"Object relationships -- the object tree" on page 52, "Things in quotes" on
-page 55, and "Routines and statements" on page 56.
+:ref:`const-var`, :ref:`object-defs`, :ref:`object-tree`,
+:ref:`things-in-quotes` and :ref:`routines-statements`.
+
+.. _const-var:
Constants and variables
=======================
Superficially similar, constants and variables are actually very different
beasts.
-.. rubric:: Constants
+Constants
+---------
A :term:`constant` is a name to which a value is given once and once only;
you can't later use that name to stand for a different value. Think of it
Those two examples represent the most common ways in which constants are
used in Inform.
-.. rubric:: Variables
+Variables
+---------
A :term:`variable` is a name to which a value is given, but that value can
be changed to a different one at any time. Think of it as a blackboard on
to reset the value of the ``deadflag`` variable to 2.
-Later, we'll talk about the :term:`local variable` (see "Routines" on
-page 179) and about using object properties as variables (see "Objects" on
-page 177).
+Later, we'll talk about the :term:`local variable` (see :ref:`routines`)
+and about using object properties as variables (see :ref:`objects`).
+
+.. _object-defs:
Object definitions
==================
* the word ``with`` introduces the object's :term:`properties`;
* the word ``has`` introduces the object's :term:`attributes`.
-.. rubric:: Object headers
+Object headers
+--------------
An object header comprises up to three items, all optional:
...
We don't use the arrows method in this guide, though we do describe
- how it works in "Setting up the object tree" on page 185.
+ how it works in :ref:`setting-up-tree`.
-.. rubric:: Object properties
+Object properties
+-----------------
An object's property definitions are introduced by the ``with`` keyword.
An object can have any number of properties, and they can be defined in any
property is the internal identity of an object; the ``name`` property is a
bit unusual -- its value is a list of dictionary words, each in single
quotes; the ``each_turn`` property has a value which is an :term:`embedded
-routine` (see "Embedded routines" on page 58). The only other type of
-value which is commonly found is a simple number; for example::
+routine` (see :ref:`embedded-routines`). The only other type of value
+which is commonly found is a simple number; for example::
capacity 10,
In all, the library defines around forty-eight standard properties -- like
``name`` and ``each_turn`` -- which you can associate with your objects;
-there's a complete list in "Object properties" on page 266. And in
-"William Tell: in his prime" on page 91 we show you how to invent your own
-property variables.
+there's a complete list in :ref:`object-props`. And in :doc:`08` we show
+you how to invent your own property variables.
-.. rubric:: Object attributes
+Object attributes
+-----------------
An object's attribute list is introduced by the ``has`` keyword. An object
can have any number of attributes, and they can be listed in any order,
provide light? and so on. If the attribute is present then the answer is
Yes; if the attribute isn't present, the answer is No.
-The library defines around thirty standard attributes, listed in "Object
-attributes" on page 269. Although you *can* devise additional attributes
--- see "Common properties and attributes" on page 185 -- in practice you
-seldom need to.
+The library defines around thirty standard attributes, listed in
+:ref:`object-attrs`. Although you *can* devise additional attributes --
+see :ref:`common-props` -- in practice you seldom need to.
+
+.. _object-tree:
Object relationships -- the object tree
=======================================
this is one feature that you will be using frequently. There are also
other routines associated with the object tree, to help you keep track of
the objects or move them around. We'll see them one by one in the next
-chapters. For a quick summary, see "Objects" on page 177.
+chapters. For a quick summary, see :ref:`objects`.
+
+.. _things-in-quotes:
Things in quotes
================
Inform makes careful distinction between double and single quotes.
-.. rubric:: Double quotes
+Double quotes
+-------------
Double quotes ``"..."`` surround a :term:`string` -- a letter, a word, a
paragraph, or almost any number of characters -- which you want the
Later, you'll find that they're also very common in ``print`` statements.
-.. rubric:: Single quotes
+Single quotes
+-------------
Single quotes ``'...'`` surround a :term:`dictionary word`. This has to be
a single word -- no spaces -- and generally contains only letters (and
You'll save yourself a lot of confusion by remembering the distinction:
Double quotes for Output, Single quotes for Input (DOSI).
+.. _routines-statements:
+
Routines and statements
=======================
A routine is a collection of statements, which are performed (or we often
say "are executed") at run-time by the interpreter. There are two types of
routine, and about two dozen types of statement (there's a complete list in
-"Statements" on page 174; see also "Inform language" on page 257).
+:ref:`statements`; see also :doc:`/appendices/e`).
-.. rubric:: Statements
+Statements
+----------
A :term:`statement` is an instruction telling the interpreter to perform a
particular task -- to "do something" -- while the game is being played. A
the only place where you'll find statements are within standalone routines
and embedded routines.
-.. rubric:: Standalone routines
+.. _standalone-routines:
+
+Standalone routines
+-------------------
A :term:`standalone routine` is a series of statements, collected together
and given a name. When the routine is "called" -- by its given name --
routine *is* called, by the Inform library, right at the start of a
game.
-.. rubric:: Embedded routines
+.. _embedded-routines:
+
+Embedded routines
+-----------------
An :term:`embedded routine` is much like a standalone routine, though it
doesn't have a name and doesn't end in a semicolon. This is the one that
the property whose value it is; we'll also see that it is possible to call
an embedded routine yourself, using an ``obj_id.property()`` syntax -- in
this example, we could call the routine by writing ``branch.each_turn()``.
-There's more about these topics in "Routines and arguments" on page 67, "A
-diversion: working with routines" on page 104 and in "Routines" on
-page 179.
+There's more about these topics in :ref:`routines-args`,
+:ref:`working-with-routines` and in :ref:`routines`.
That ends our review of the ground covered in our first game. We'll have
more to say about most of this later, but we're trying not to overload you
:term:`library routine` to do the job, not one that we've written, but one
that's provided as part of the Inform system.
-You'll remember that, when we first mentioned routines (see "Standalone
-routines" on page 57), we used the example of ``Initialise()`` and said
-that "the routine's name followed by opening and closing parentheses is all
-that it takes to call a routine". That was true for ``Initialise()``, but
-not quite the whole story. To move the player character, we've got to
-specify where we want her to go, and we do that by supplying the internal
-ID of the destination room within the opening and closing parentheses.
-That is, instead of just ``PlayerTo()`` we call ``PlayerTo(top_of_tree)``,
-and we describe ``top_of_tree`` as the routine's :term:`argument`.
+You'll remember that, when we first mentioned routines (see
+:ref:`standalone-routines`), we used the example of ``Initialise()`` and
+said that "the routine's name followed by opening and closing parentheses
+is all that it takes to call a routine". That was true for
+``Initialise()``, but not quite the whole story. To move the player
+character, we've got to specify where we want her to go, and we do that by
+supplying the internal ID of the destination room within the opening and
+closing parentheses. That is, instead of just ``PlayerTo()`` we call
+``PlayerTo(top_of_tree)``, and we describe ``top_of_tree`` as the routine's
+:term:`argument`.
Although we've moved the player character to another room, we're still in
the middle of the intercepted ``Climb`` action. As previously, we need to
The new topics that we've encountered here include these:
-.. rubric:: Object properties
+Object properties
+-----------------
Objects can have a ``before`` property -- if there is one, the interpreter
looks at it *before* performing an action which in some way involves that
in_to "It's such a lovely day -- much too nice to go inside.",
cant_go "The only path lies to the east.",
-.. rubric:: Routines and arguments
+.. _routines-args:
+
+Routines and arguments
+----------------------
The library includes a number of useful routines, available to perform
-certain common tasks if you require them; there's a list in "Library
-routines" on page 264. We used the ``PlayerTo`` routine, which moves the
+certain common tasks if you require them; there's a list in
+:ref:`library-routines`. We used the ``PlayerTo`` routine, which moves the
player character from her current room to another one -- not necessarily
adjacent to the first room.
In this example, the effect of the ``1`` is to prevent the description
being displayed.
-.. rubric:: Statements
+Statements
+----------
We encountered several new statements:
The value ``nothing`` is a built-in constant (like ``true`` and ``false``)
which means, well, there isn't any object to refer to. There's a list of
-standard library actions in "Group 1 actions" on page 270, "Group 2
-actions" on page 271 and "Group 3 actions" on page 271.
+standard library actions in :ref:`group-1-actions`, :ref:`group-2-actions`
+and :ref:`group-3-actions`.
We've now reached the end of our first game. In these three chapters we've
shown you the basic principles on which almost all games are based, and
introduced you to many of the components that you'll need when creating
more interesting IF. We suggest that you take one last look at the source
-code (see "Heidi" story on page 213), and then move on to the next stage.
+code (see :doc:`/appendices/b`), and then move on to the next stage.
objects which we haven't yet defined. In any case, we don't intend to
build up the game in layers as we did last time, but rather to talk about
it in logically related chunks. To see (and if you wish, to type) the
-complete source, go to "William Tell" story on page 219.
+complete source, go to :doc:`/appendices/c`.
Object classes
==============
which terminates its definition simply moves to the end of its last
property.
-.. rubric:: A class for props
+.. _props-class:
+
+A class for props
+-----------------
We use the ``Room`` class in "William Tell", and a few other classes
besides. Here's a ``Prop`` class (that's "Prop" in the sense of a
increased realism, while clearly hinting to players that trying other verbs
would be a waste of time.
-.. rubric:: A class for furniture
+A class for furniture
+---------------------
The last class for now -- we'll talk about the ``Arrow`` and ``NPC``
classes in the next chapter -- is for furniture-like objects. If you label
Now that most of our class definitions are in place, we can get on with
defining some real rooms and objects. First, though, if you're typing in
the "William Tell" game as you read through the guide, you'd probably like
-to check that what you've entered so far is correct; "Compile-as-you-go" on
-page 233 explains how to compile the game in its current -- incomplete --
-state.
+to check that what you've entered so far is correct;
+:ref:`compile-as-you-go` explains how to compile the game in its current --
+incomplete -- state.
*forget* to change it, the game will still work -- but not in the way you'd
intended, and the resulting bug will be quite difficult to track down.
+.. _adding-props:
+
Adding some props
=================
we introduce the ``or`` keyword, which is a more succinct way of achieving
exactly the same result.
+.. _possessions:
+
The player's possessions
========================
``before`` -- can be defined to intercept them. Here we use it to trap
speech-related commands such as ASK HELGA ABOUT APPLE and TELL WALTER ABOUT
BABIES, telling players that in this game we've implemented only a simpler
-TALK verb (which we describe in "Verbs, verbs, verbs" on page 111).
+TALK verb (which we describe in :ref:`verbs`).
Based on the NPC class we've created, here's Helga::
"Your score has just gone up by one point".
There are also ``life`` and ``times_spoken_to`` properties (which we'll
-talk about in "William Tell: the end is nigh" on page 103) and an
-``initial`` property.
+talk about in :doc:`09`) and an ``initial`` property.
``initial`` is used when the interpreter is describing a room and listing
the objects initial you can see there. If we *didn't* define it, you'd get
We've done a lot of scene-setting, but the real action is still to come.
Next, it's time to define the town square, and create a confrontation
between Wilhelm and the vogt's soldiers. (But first, see again
-"Compile-as-you-go" on page 233 if you're typing in the game as you read
-through the guide.)
+:ref:`compile-as-you-go` if you're typing in the game as you read through
+the guide.)
approach to the hat on the pole -- does he salute it, or does he remain
proudly defiant?
+.. _south-side:
+
The south side of the square
============================
there, but they don't do much. Their most interesting characteristic is
probably that they trap two actions -- ``FireAt`` and ``Talk`` -- which are
*not* part of the library, but instead new actions that we've defined
-specially for this game. We'll talk about those actions in "Verbs, verbs,
-verbs" on page 111, at which time the role of this ``before`` property will
-make more sense.
+specially for this game. We'll talk about those actions in :ref:`verbs`,
+at which time the role of this ``before`` property will make more sense.
The middle of the square
========================
Creating new property variables like this -- at the drop of a hat, as it
were -- is the recommended approach, but it isn't the only possibility.
- We briefly mention some alternative approaches in "Reading other
- people's code" on page 181.
+ We briefly mention some alternative approaches in
+ :ref:`reading-other-code`.
Back to the ``mid_square`` room. We've said that we need to detect Wilhelm
trying to leave this room, which we can do by trapping the ``Go`` action in
sensible to write a routine to do the job. Which we'll do shortly -- but
first, a general introduction to working with routines.
+.. _working-with-routines:
+
A diversion: working with routines
==================================
``rfalse`` statement, or by the the ``]`` marking the routine's end (in
which case the default STEF rule applies: Standalone routines return
True, Embedded routines return False). We gave this example of an
- embedded routine in "Adding some props" on page 81. The ``return
- false`` statement is redundant: we could remove it without affecting the
- routine's behaviour, because the ``]`` acts like a ``return false``::
+ embedded routine in :ref:`adding-props`. The ``return false`` statement
+ is redundant: we could remove it without affecting the routine's
+ behaviour, because the ``]`` acts like a ``return false``::
found_in [;
if (location == street or below_square or south_square or
========================= ===========================
For full details on which library property values can be embedded routines,
-and which return values are significant, see "Object properties" on page
-266 and Appendix §A2 of the *Inform Designer's Manual*.
+and which return values are significant, see :ref:`object-props` and
+Appendix §A2 of the *Inform Designer's Manual*.
Return to the marketplace
=========================
a whole load of new nouns and adjectives to the game's dictionary, but no
verbs. That's the final task.
+.. _verbs:
+
Verbs, verbs, verbs
===================
anything to say".
That's the end of our little fable; you'll find a transcript and the full
-source in "William Tell" story on page 219. And now, it's time to meet --
-Captain Fate!
+source in :doc:`/appendices/c`. And now, it's time to meet -- Captain
+Fate!
minimally at first and then adding complexity as need arises. Again,
this means that you won't be able to compile for testing purposes after
the addition of every code snippet, so, if you're typing in the game as
-you read, you’ll need to check the advice in "Compile-as-you-go" on page
-255.
+you read, you’ll need to check the advice in :ref:`compile-as-you-go`.
A lot of what goes into this game we have already seen; you may deduce
from this that the game design business is fairly repetitious and that
n_to [; <<Enter outside_of_cafe>>; ],
-You may think that this is unnecessary madness, but a word to the wise:
-in a large game, you want action handling going on just in one place
-when possible, because it will help you to keep track of where things
-are a-happening if something goes *ploof* (as, believe us, it will; see
-"Debugging your game" on page 197). You don't need to be a
-perfectionist, just cautious.
-
-A booth in this kind of situation is an open invitation for the player
-to step inside and try to change into Captain Fate's costume. We won't
-let this happen -- the player isn't Clark Kent, after all; later we'll
-explain how we forbid this action -- and that will force the player to
-go inside the café, looking for a discreet place to disrobe; but first,
-let''s freeze John Covarth outside Benny''s and reflect about a
-fundamental truth.
+You may think that this is unnecessary madness, but a word to the wise: in
+a large game, you want action handling going on just in one place when
+possible, because it will help you to keep track of where things are
+a-happening if something goes *ploof* (as, believe us, it will; see
+:doc:`16`). You don't need to be a perfectionist, just cautious.
+
+A booth in this kind of situation is an open invitation for the player to
+step inside and try to change into Captain Fate's costume. We won't let
+this happen -- the player isn't Clark Kent, after all; later we'll explain
+how we forbid this action -- and that will force the player to go inside
+the café, looking for a discreet place to disrobe; but first, let's freeze
+John Covarth outside Benny's and reflect about a fundamental truth.
A hero is not an ordinary person
================================
your library file will probably not be right for the next game. Use of
the ``LibraryMessages`` object is strongly advised.
-If you're typing in the game, you'll probably want to read the brief
-section on "Compile-as-you-go" on page 255 prior to performing a test
-compile. Once everything's correct, it’s time that our hero entered that
-enticing café.
+If you're typing in the game, you'll probably want to read the brief
+section on :ref:`compile-as-you-go` prior to performing a test compile.
+Once everything's correct, it’s time that our hero entered that enticing
+café.
images, but the main focus of the room isn't the decor: it's the door
leading to the toilet -- and, perhaps, privacy?
+.. _homely-atmos:
+
A homely atmosphere
===================
.. note::
- in "William Tell" we defined the ``quiver``, way back in "The
- player's possessions" on page 83, as an ``open container``. As things
- stand, the player can put *any* held object, however inappropriate,
- into it. We could have trapped the Receive action to ensure that
- arrows are the only acceptable contents (recollect that ``~~``, to be
- read as "not", turns true into false and vice versa):
+ in "William Tell" we defined the ``quiver``, way back in
+ :ref:`possessions`, as an ``open container``. As things stand, the player
+ can put *any* held object, however inappropriate, into it. We could have
+ trapped the Receive action to ensure that arrows are the only acceptable
+ contents (recollect that ``~~``, to be read as "not", turns true into
+ false and vice versa):
.. code-block:: inform
.. note::
- what's displayed if there isn't an external name in an object's
- header? If you've read the section "Compile-as-you-go" on page 233,
- you'll recall that the interpreter simply uses the internal
- identifier within parentheses; that is, with no external name and no
- ``short_name`` property, we might see:
+ what's displayed if there isn't an external name in an object's header?
+ If you've read the section :ref:`compile-as-you-go`, you'll recall that
+ the interpreter simply uses the internal identifier within parentheses;
+ that is, with no external name and no ``short_name`` property, we might
+ see:
.. code-block:: inform
"Benny is trusting you to look after that key.";
];
-All of the ``before`` properties that we've so far created have
-contained one or more labels specifying the actions which they are to
-intercept; you'll remember that in "William Tell" we introduced the
-``default`` action (see "A class for props" on page 74) to mean "any
-value not already catered for". There's one of those labels here, for
-the Drop action, but that's preceded by a piece of code that will be
-executed at the start of *every* action directed at the key. If it’s
-still in Benny’s possession, we display a polite refusal; if the player
-has it then we prevent careless disposal; otherwise, the action
-continues unhindered.
-
-(In fact, the hat-on-a-pole ``Prop`` introduced on page 91 had this
-all-exclusive ``before`` property:
+All of the ``before`` properties that we've so far created have contained
+one or more labels specifying the actions which they are to intercept;
+you'll remember that in "William Tell" we introduced the ``default`` action
+(see :ref:`props-class`) to mean "any value not already catered
+for". There's one of those labels here, for the Drop action, but that's
+preceded by a piece of code that will be executed at the start of *every*
+action directed at the key. If it’s still in Benny’s possession, we display
+a polite refusal; if the player has it then we prevent careless disposal;
+otherwise, the action continues unhindered.
+
+(In fact, the hat-on-a-pole ``Prop`` introduced in :ref:`south-side` had
+this all-exclusive ``before`` property:
.. code-block:: inform
your source code. It is not unusual to find other suggestions and
warnings.
-To help us out of the disambiguation problem with the word TOILET, we
-are going to use Neil Cerutti's extension ``pname.h``, which is designed
-for situations precisely like this. First, we follow the link to the IF
-archive and download the compressed file ``pname.zip``, which contains
-two more files: ``pname.h`` and ``pname.txt``. We place these files in
-the folder where we are currently developing our game or, if using the
-environment we proposed in "Tools of the trade" on page 17, in the
-``Inform\Lib\Contrib`` folder. The text file offers instructions about
-installation and usage. Here we find a warning:
+To help us out of the disambiguation problem with the word TOILET, we are
+going to use Neil Cerutti's extension ``pname.h``, which is designed for
+situations precisely like this. First, we follow the link to the IF archive
+and download the compressed file ``pname.zip``, which contains two more
+files: ``pname.h`` and ``pname.txt``. We place these files in the folder
+where we are currently developing our game or, if using the environment we
+proposed in :doc:`02`, in the ``Inform\Lib\Contrib`` folder. The text file
+offers instructions about installation and usage. Here we find a warning:
This version of pname.h is recommended for use only with version 6/10
of the Inform Library.
if (noun == clothes) { whatever };
!...
-We won't let players give away their clothes or their costume (yes, an
-improbable action, but you never know). The toilet key and the coin are
-successfully transferred. The property ``key_not_returned`` will be set
-to true when we receive the toilet key from Benny (we have not coded
-that bit yet), and now, when we give it back, it's reset to ``false``.
-The ``move`` statement is in charge of the actual transfer of the object
-from the player's inventory to Benny, and we finally display a
-confirmation message. With the coin, we find a new statement:
-``remove``. This extracts the object from the object tree, so that it
-now has no parent. The effect is to make it disappear from the game
-(though you are not destroying the object permanently -- and indeed you
-could return it to the object tree using the ``move`` statement); as far
-as the player is concerned, there isn’t a COIN to be found anywhere. The
-``coffee_not_paid`` property will be set to true when Benny serves us
-the cup of coffee (again, we’ll see that in a moment); now we reset it
-to ``false``, which liberates the player from debt. This culminates with
-the ``"..."`` print-and-return statement, telling the player that the
-action was successful. In passing, remember that in "A homely
-atmosphere" on page 131 we defined the counter such that PUT KEY ON
+We won't let players give away their clothes or their costume (yes, an
+improbable action, but you never know). The toilet key and the coin are
+successfully transferred. The property ``key_not_returned`` will be set to
+true when we receive the toilet key from Benny (we have not coded that bit
+yet), and now, when we give it back, it's reset to ``false``. The ``move``
+statement is in charge of the actual transfer of the object from the
+player's inventory to Benny, and we finally display a confirmation
+message. With the coin, we find a new statement: ``remove``. This extracts
+the object from the object tree, so that it now has no parent. The effect
+is to make it disappear from the game (though you are not destroying the
+object permanently -- and indeed you could return it to the object tree
+using the ``move`` statement); as far as the player is concerned, there
+isn’t a COIN to be found anywhere. The ``coffee_not_paid`` property will be
+set to true when Benny serves us the cup of coffee (again, we’ll see that
+in a moment); now we reset it to ``false``, which liberates the player from
+debt. This culminates with the ``"..."`` print-and-return statement,
+telling the player that the action was successful. In passing, remember
+that in :ref:`homely-atmos` we defined the counter such that PUT KEY ON
COUNTER is automatically translated into GIVE KEY TO BENNY .
Why move the key to Benny but remove the coin instead? Once players
-======================
-Some last lousy points
-======================
+========================
+ Some last lousy points
+========================
.. only:: html
be ignored for the time being; when you become an accomplished designer,
you will decide what matters and what can be left on the shelf.
-We'll also talk, in "Reading other people's code" on page 181, about a
-few ways of doing things that we've chosen not to tell you about, but
-which you're quite likely to encounter if you look at Inform code
-written by other designers.
+We'll also talk, in :ref:`reading-other-code`, about a few ways of doing
+things that we've chosen not to tell you about, but which you're quite
+likely to encounter if you look at Inform code written by other designers.
The tone here is perhaps a little dry, but trust us: in walking this
dusty ground we touch on just about everything that is fundamental in
your overall understanding of Inform. And as always, the *Inform
Designer's Manual* provides rounder and more comprehensive coverage.
-
Expressions
===========
used (except that a routine's local variables are not visible outside
that routine).
+.. _statements:
Statements
==========
{ statement; statement; ... statement; }
-.. rubric:: Statements that we've met
+Statements that we've met
+-------------------------
Our games have used these statements, about half of the Inform
possibilities:
<<action noun>>;
<<action noun second>>;
-
-.. rubric:: Statements that we've not met
+Statements that we've not met
+-----------------------------
Although our example games haven't needed to use them, these looping
statements are sometimes useful:
In particular, avoid using the deprecated jump statement if you possibly can.
-.. rubric:: Print rules
+Print rules
+-----------
In ``print`` and ``print_ret`` statements, each ``value`` can be:
Z-code. By convention it's given an initial capital letter (though the
compiler doesn't enforce this) and always ends with a semicolon.
-.. rubric:: Directives that we've met
+Directives that we've met
+-------------------------
We've used all of these directives; note that for ``Class``, ``Extend``,
``Object`` and ``Verb`` the full supported syntax is more sophisticated
#Ifdef any_id; ... #Endif;
-.. rubric:: Directives that we've not met
+Directives that we've not met
+-----------------------------
There's only a handful of useful directives which we haven't needed to
use:
System_file
Zcharacter
+.. _objects:
+
Objects
=======
of the model world. Full variables are called properties; simpler
two-state variables are attributes.
-.. rubric:: Properties
+Properties
+----------
The library defines around forty-eight standard property variables (such
as ``before`` or ``name``), but you can readily create further ones just
(obj_id provides property) ! is true or false
+.. _routines:
Routines
========
Inform provides standalone routines and embedded routines.
-.. rubric:: Standalone routines
+Standalone routines
+-------------------
Standalone routines are defined like this:
routine_id()
-.. rubric:: Embedded routines
+Embedded routines
+-----------------
These are embedded as the value of an object's property:
obj_id.property() ! everywhere
-.. rubric:: Arguments and local variables
+Arguments and local variables
+-----------------------------
Both types of routine support up to fifteen local variables -- variables
which can be used only by the statements within the routine, and which
because there is no mechanism for the library to supply argument values
when calling the routine.
-
-.. rubric:: Return values
+Return values
+-------------
Every routine returns a single value, which is supplied either
explicitly by some form of return statement:
switch (Max(3,y)) { ...
-
-.. rubric:: Library routines versus entry points
-
+Library routines versus entry points
+------------------------------------
A library routine is a standard routine, included within the library
files, which you can optionally call from your source file if you
Initialise()
-There are full lists in "Library routines" on page 264 and "Optional
-entry points" on page 270.
+There are full lists in :ref:`library-routines` and :ref:`entry-points`.
+.. _reading-other-code:
Reading other people's code
===========================
*consistent* about its use. In this section, we highlight some of the
more obvious differences which you may encounter.
-.. rubric:: Code layout
+Code layout
+-----------
Every designer has his or her own style for laying out their source
code, and they're all worse than the one you adopt. Inform's flexibility
We hope you'll agree that the result was worth the tiny extra effort.
Code gets written once; it gets read dozens and dozens of times.
-.. rubric:: Shortcuts
+Shortcuts
+---------
There are a few statement shortcuts, some more useful than others, which
you'll come across.
if (--MyVar == 7) ...
if (MyVar-- == 8) ...
-.. rubric:: "number" property and "general" attribute
+"number" property and "general" attribute
+-----------------------------------------
The library defines a standard ``number`` property and a standard
``general`` attribute, whose roles are undefined: they are
instead create new property variables -- with appropriate names -- as
part of your ``Object`` and ``Class`` definitions.
-.. rubric:: Common properties and attributes
+.. _common-props:
-As an alternative to creating new individual properties which apply only
-to a single object (or class of objects), it's possible to devise
-properties and new attributes which, like those defined by the library,
-are available on *all* objects. The need to do this is actually quite
-rare, and is mostly confined to library extensions (for example, the
-``pname.h`` extension which we encountered in "Captain Fate: take 3" on
-page 147 gives every object a ``pname`` property and a
-``phrase_matched`` attribute). To create them, you would use these
+Common properties and attributes
+--------------------------------
+
+As an alternative to creating new individual properties which apply only to
+a single object (or class of objects), it's possible to devise properties
+and new attributes which, like those defined by the library, are available
+on *all* objects. The need to do this is actually quite rare, and is mostly
+confined to library extensions (for example, the ``pname.h`` extension
+which we encountered in :doc:`12` gives every object a ``pname`` property
+and a ``phrase_matched`` attribute). To create them, you would use these
directives near the start of your source file:
.. code-block:: inform
On the other hand, the number of individual properties which you can add
is virtually unlimited.
-.. rubric:: Setting up the object tree
+.. _setting-up-tree:
+
+Setting up the object tree
+--------------------------
Throughout this guide, we've defined the initial position of each object
within the overall object tree either by explicitly mentioning its
We prefer to explicitly name the parent, but you'll encounter both forms
very regularly.
-.. rubric:: Quotes in "name" properties
+Quotes in "name" properties
+---------------------------
-We went to some lengths, way back in "Things in quotes" on page 55, to
-explain the difference between double quotes ``"..."`` (strings to be
-output) and single quotes ``'...'`` (input tokens -- dictionary words).
-Perhaps somewhat unfortunately, Inform allows you to blur this clean
-distinction: you can use double quotes in name properties and Verb
-directives:
+We went to some lengths, way back in :ref:`things-in-quotes`, to explain
+the difference between double quotes ``"..."`` (strings to be output) and
+single quotes ``'...'`` (input tokens -- dictionary words). Perhaps
+somewhat unfortunately, Inform allows you to blur this clean distinction:
+you can use double quotes in name properties and Verb directives:
.. code-block:: inform
dictionary words, not strings; it's just as easy -- and far clearer --
to stick rigidly to the preferred punctuation.
-.. rubric:: Obsolete usages
+Obsolete usages
+---------------
Finally, remember that Inform has been evolving since 1993. Over that
time, Graham has taken considerable care to maintain as much
.. rubric:: Warnings
-Warnings are not immediately catastrophic, but you should get rid of
-them to ensure a good start at finding run-time mistakes (see "Debugging
-your game" on page 197). You may declare a variable and then not use it;
-you may mistake assignment and arithmetic operators (``=`` instead of
-``==``); you may forget the comma that separates properties, etc. For
-all these and many other warnings, Inform has found something which is
-legal but doubtful.
+Warnings are not immediately catastrophic, but you should get rid of them
+to ensure a good start at finding run-time mistakes (see :doc:`16`). You
+may declare a variable and then not use it; you may mistake assignment and
+arithmetic operators (``=`` instead of ``==``); you may forget the comma
+that separates properties, etc. For all these and many other warnings,
+Inform has found something which is legal but doubtful.
One common incident is to return in the middle of a statement block,
before the rest of statements can be reached. This is not always as
happen. Inform detects the fault and warns you. Probably the designer's
intention was:
-
Compiling *à la carte*
======================
-
One of the advantages of Inform is its portability between different
systems and machines. Specific usage of the compiler varies accordingly,
but some features should be in all environments. To obtain precise
information about any particular version, run the compiler with the
-``-h1`` switch -- see "Switches" on page 193.
+``-h1`` switch -- see :ref:`switches`.
Often the compiler is run with the name of your source file as its only
parameter. This tells the compiler to "read this file using Strict mode and
!============================================================================
+.. _switches:
Switches
========
:samp:`-D -X`
Include respectively the debugging verbs and the Infix debugger in the
- story file (see "Debugging your game" on page 197).
+ story file (see :doc:`16`).
:samp:`-h1 -h2`
Display help information about the compiler. ``-h1`` produces
#latex_use_parts = False
# If true, show page references after internal links.
-latex_show_pagerefs = False
+latex_show_pagerefs = True
# If true, show URL addresses after external links.
#latex_show_urls = False
projects / ibg.git / commitdiff