-.. raw:: latex
-
- \newpage
-
=================
Heidi revisited
=================
.. epigraph::
- | *I was an innkeeper, who loved to carouse;*
- | *J was a joiner, and built up a house.*
+ | |CENTER| *I was an innkeeper, who loved to carouse;*
+ | |CENTER| *J was a joiner, and built up a house.*
.. only:: html
.. image:: /images/picI.png
:align: left
-.. raw:: latex
-
- \dropcap{i}
-
-n even the simplest story, there's bound to be scope for the player to
+|I|\n even the simplest story, there's bound to be scope for the player to
attempt activities that you hadn't anticipated. Sometimes there may be
alternative ways of approaching a problem: if you can't be sure which
approach the player will take, you really ought to allow for all
need to substitute a more relevant response after LISTEN TO BIRD. Here's
how we do it:
-.. code-block:: inform6
+.. code-block:: inform
Object bird "baby bird" forest
with description "Too young to fly, the nestling tweets helplessly.",
We'll go through this a step at a time:
-#. We've added a new ``before`` property to our bird object. The
+.. Generated by autoindex
+.. index::
+ pair: before; library property
+
+#. We've added a new :prop:`before` property to our bird object. The
interpreter looks at the property *before* attempting to perform any
action which is directed specifically at this object::
print "It sounds scared and in need of assistance.^";
return true;
-#. The label is the name of an action, in this case ``Listen``. What we're
- telling the interpreter is: if the action that you're about to perform
- on the bird is a ``Listen``, execute these statements first; if it's any
- other action, carry on as normal. So, if the player types EXAMINE BIRD,
- PICK UP BIRD, PUT BIRD IN NEST, HIT BIRD or FONDLE BIRD, then she'll get
- the standard response. If she types LISTEN TO BIRD, then our two
- statements get executed before anything else happens. We call this
- "trapping" or "intercepting" the action of Listening to the bird.
+.. Generated by autoindex
+.. index::
+ pair: Listen; library action
+
+#. The label is the name of an action, in this case :act:`Listen`. What
+ we're telling the interpreter is: if the action that you're about to
+ perform on the bird is a :act:`Listen`, execute these statements first;
+ if it's any other action, carry on as normal. So, if the player types
+ EXAMINE BIRD, PICK UP BIRD, PUT BIRD IN NEST, HIT BIRD or FONDLE BIRD,
+ then she'll get the standard response. If she types LISTEN TO BIRD,
+ then our two statements get executed before anything else happens. We
+ call this "trapping" or "intercepting" the action of Listening to the
+ bird.
#. The two statements that we execute are, first::
return true;
which tells the interpreter that it doesn't need to do anything else,
- because we've handled the ``Listen`` action ourselves. And the game now
- behaves like this -- perfect:
+ because we've handled the :act:`Listen` action ourselves. And the game
+ now behaves like this -- perfect:
.. code-block:: transcript
>
The use of the ``return true`` statement probably needs a bit more
-explanation. An object's ``before`` property traps an action aimed at that
-object right at the start, before the interpreter has started to do
+explanation. An object's :prop:`before` property traps an action aimed at
+that object right at the start, before the interpreter has started to do
anything. That's the point at which the statements in the embedded routine
are executed. If the last of those statements is ``return true`` then the
interpreter assumes that the action has been dealt with by those
though it hadn't been intercepted. Sometimes that's what you want it to
do, but not here: if instead we'd written this:
-.. code-block:: inform6
+.. code-block:: inform
Object bird "baby bird" forest
with description "Too young to fly, the nestling tweets helplessly.",
Entering the cottage
====================
-At the start of the game the player character stands "outside a cottage", which
-might lead her to believe that she can go inside:
+At the start of the game the player character stands "outside a cottage",
+which might lead her to believe that she can go inside:
.. code-block:: transcript
Again, that isn't perhaps the most appropriate response, but it's easy to
change:
-.. code-block:: inform6
+.. code-block:: inform
Object before_cottage "In front of a cottage"
with description
cant_go "The only path lies to the east.",
has light;
-The ``in_to`` property would normally link to another room, in the same way
-as the ``e_to`` property contain the internal ID of the ``forest`` object.
-However, if instead you set its value to be a string, the interpreter
-displays that string when the player tries the IN direction. Other --
-unspecified -- directions like NORTH and UP still elicit the standard "You
-can't go that way" response, but we can change that too, by supplying a
-``cant_go`` property whose value is a suitable string. We then get this
-friendlier behaviour:
+The :prop:`in_to` property would normally link to another room, in the same
+way as the :prop:`e_to` property contain the internal ID of the ``forest``
+object. However, if instead you set its value to be a string, the
+interpreter displays that string when the player tries the IN direction.
+Other -- unspecified -- directions like NORTH and UP still elicit the
+standard "You can't go that way" response, but we can change that too, by
+supplying a :prop:`cant_go` property whose value is a suitable string. We
+then get this friendlier behaviour:
.. code-block:: transcript
to represent the cottage, a perfectly reasonable EXAMINE COTTAGE command
receives the obviously nonsensical reply "You can't see any such thing".
That's easy to fix; we can add a new ``cottage`` object, making it a piece
-of ``scenery`` just like the ``tree``:
+of :attr:`scenery` just like the ``tree``:
-.. code-block:: inform6
+.. code-block:: inform
Object cottage "tiny cottage" before_cottage
with description "It's small and simple, but you're very happy here.",
The situation here is similar to our LISTEN TO BIRD problem, and the
solution we adopt is similar as well:
-.. code-block:: inform6
+.. code-block:: inform
Object cottage "tiny cottage" before_cottage
with description "It's small and simple, but you're very happy here.",
],
has scenery;
-We use a ``before`` property to intercept the ``Enter`` action applied to
-the cottage object, so that we can display a more appropriate message.
-This time, however, we've done it using one statement rather than two. It
-turns out that the sequence "``print`` a string which ends with a newline
-character, and then ``return true``" is so frequently needed that there's a
-special statement which does it all. That is, this single statement (where
-you'll note that the string doesn't need to end in ``^``)::
+We use a :prop:`before` property to intercept the :act:`Enter` action
+applied to the cottage object, so that we can display a more appropriate
+message. This time, however, we've done it using one statement rather than
+two. It turns out that the sequence "``print`` a string which ends with a
+newline character, and then ``return true``" is so frequently needed that
+there's a special statement which does it all. That is, this single
+statement (where you'll note that the string *doesn't* need to end in
+``^``)::
print_ret "It's such a lovely day -- much too nice to go inside.";
In the clearing, holding the nest and looking at the tree, the player is
meant to type UP. Just as likely, though, she'll try CLIMB TREE (which
currently gives the completely misleading response "I don't think much is
-to be achieved by that"). Yet another opportunity to use a ``before``
+to be achieved by that"). Yet another opportunity to use a :prop:`before`
property, but now with a difference.
-.. code-block:: inform6
+.. code-block:: inform
Object tree "tall sycamore tree" clearing
with description
],
has scenery;
-This time, when we intercept the ``Climb`` action applied to the ``tree``
-object, it's not in order to display a better message; it's because we want
-to move the player character to another room, just as if she'd typed UP.
-Relocating the player character is actually quite a complex business, but
-fortunately all of that complexity is hidden: there's a standard **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 **argument**.
+This time, when we intercept the :act:`Climb` action applied to the
+``tree`` object, it's not in order to display a better message; it's
+because we want to move the player character to another room, just as if
+she'd typed UP. Relocating the player character is actually quite a
+complex business, but fortunately all of that complexity is hidden: there's
+a standard :term:`library routine` to do the job, not one that we've
+written, but one that's provided as part of the Inform system.
+
+.. index::
+ single: arguments (of a routine)
+
+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
-tell the interpreter that we've dealt with the action, and so we don't want
-the standard rejection message to be displayed. The ``return true``
+the middle of the intercepted :act:`Climb` action. As previously, we need
+to tell the interpreter that we've dealt with the action, and so we don't
+want the standard rejection message to be displayed. The ``return true``
statement does that, as usual.
Dropping objects from the tree
land nearby might seem a bit improbable; much more likely that it would
fall to the clearing below.
-It looks like we might want to intercept the ``Drop`` action, but not quite
-in the way we've been doing up until now. For one thing, we don't want to
-complicate the definitions of the ``bird`` and the ``nest`` and any other
-objects we may introduce: much better to find a general solution that will
-work for all objects. And second, we need to recognise that not all
+.. Generated by autoindex
+.. index::
+ pair: Drop; library action
+
+It looks like we might want to intercept the :act:`Drop` action, but not
+quite in the way we've been doing up until now. For one thing, we don't
+want to complicate the definitions of the ``bird`` and the ``nest`` and any
+other objects we may introduce: much better to find a general solution that
+will work for all objects. And second, we need to recognise that not all
objects are droppable; the player can't, for example, DROP THE BRANCH.
-The best approach to the second problem is to intercept the ``Drop`` action
-*after* it has occurred, rather than beforehand. That way, we let the
-library take care of objects which aren't being held or which can't be
-dropped, and only become involved once a ``Drop`` has been successful. And
-the best approach to the first problem is to do this particular
+The best approach to the second problem is to intercept the :act:`Drop`
+action *after* it has occurred, rather than beforehand. That way, we let
+the library take care of objects which aren't being held or which can't be
+dropped, and only become involved once a :act:`Drop` has been successful.
+And the best approach to the first problem is to do this particular
interception not on an object-by-object basis, as we have been doing so
-far, but instead for every ``Drop`` which takes place in our troublesome
+far, but instead for every :act:`Drop` which takes place in our troublesome
``top_of_tree`` room. This is what we have to write:
-.. code-block:: inform6
+.. code-block:: inform
Object top_of_tree "At the top of the tree"
with description "You cling precariously to the trunk.",
Let's again take it a step at a time:
-#. We've added a new ``after`` property to our ``top_of_tree`` object. The
- interpreter looks at the property *subsequent to* performing any action in
- this room::
+.. Generated by autoindex
+.. index::
+ pair: after; library property
+
+#. We've added a new :prop:`after` property to our ``top_of_tree`` object.
+ The interpreter looks at the property *subsequent to* performing any
+ action in this room::
after [; ... ],
move noun to clearing;
return false;
-#. The label is the name of an action, in this case ``Drop``. What we're
- telling the interpreter is: if the action that you've just performed
- here is a ``Drop``, execute these statements before telling the player
- what you've done; if it's any other action, carry on as normal.
+#. The label is the name of an action, in this case :act:`Drop`. What
+ we're telling the interpreter is: if the action that you've just
+ performed here is a :act:`Drop`, execute these statements before telling
+ the player what you've done; if it's any other action, carry on as
+ normal.
#. The two statements that we execute are first::
move noun to clearing;
- which takes the object which has just been moved from the ``player``
- object to the ``top_of_tree`` object (by the successful ``Drop`` action)
- and moves it again so that its parent becomes the ``clearing`` object.
- That ``noun`` is a library variable that always contains the internal ID
- of the object which is the target of the current action. If the player
- types DROP NEST, ``noun`` contains the internal ID of the ``nest``
- object; if she types DROP NESTLING then ``noun`` contains the internal
- ID of the ``bird`` object. Second, we execute::
+ which takes the object which has just been moved from the :var:`player`
+ object to the ``top_of_tree`` object (by the successful :act:`Drop`
+ action) and moves it again so that its parent becomes the ``clearing``
+ object. That :var:`noun` is a library variable that always contains the
+ internal ID of the object which is the target of the current action. If
+ the player types DROP NEST, :var:`noun` contains the internal ID of the
+ ``nest`` object; if she types DROP NESTLING then :var:`noun` contains
+ the internal ID of the ``bird`` object. Second, we execute::
return false;
unhelpful in these non-standard circumstances. If you prefer to hint at
what's just happened, you could use this alternative solution:
-.. code-block:: inform6
+.. code-block:: inform
Object top_of_tree "At the top of the tree"
with description "You cling precariously to the trunk.",
has light;
The ``print_ret`` statement does two things for us: displays a more
-informative message, and returns ``true`` to tell the interpreter that
+informative message, and returns :const:`true` to tell the interpreter that
there's no need to let the player know what's happened -- we've handled
that ourselves.
checked for the bird actually being in the nest; fortunately, that's easy
to do:
-.. code-block:: inform6
+.. code-block:: inform
Object branch "wide firm bough" top_of_tree
with description "It's flat enough to support a small object.",
if (bird in nest && nest in branch) deadflag = 2;
+.. Generated by autoindex
+.. index::
+ pair: deadflag; library variable
+
should now be read as: "Test whether the ``bird`` is currently in (or on)
-the ``nest``, and whether the ``nest`` is currently on (or in) the
-``branch``; if both parts are ``true``, set the value of ``deadflag`` to 2;
-otherwise, do nothing".
+the ``nest``, *and* whether the ``nest`` is currently on (or in) the
+``branch``; if both parts are :const:`true`, set the value of
+:var:`deadflag` to 2; otherwise, do nothing".
Summing up
==========
The new topics that we've encountered here include these:
-.. rubric:: 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
-object. Similarly, you can provide an ``after`` property, which the
-interpreter looks at *after* performing an action but before telling the
-player what's happened. Both ``before`` and ``after`` properties can be
-used not only with tangible objects like the ``bird``, ``cottage`` and
-``tree`` (when they intercept actions aimed at that particular object) but
-also with rooms (when they intercept actions aimed at any object in that
-room).
-
-The value of each ``before`` and ``after`` property is an embedded routine.
-If such a routine ends with ``return false``, the interpreter then carries
-on with the next stage of the action which has been intercepted; if it ends
-with ``return true``, the interpreter does nothing further for that action.
-By combining these possibilities, you can supplement the work done by a
-standard action with statements of your own, or you can replace a standard
-action completely.
+Object properties
+-----------------
+
+.. Generated by autoindex
+.. index::
+ pair: before; library property
+
+Objects can have a :prop:`before` property -- if there is one, the
+interpreter looks at it *before* performing an action which in some way
+involves that object. Similarly, you can provide an :prop:`after`
+property, which the interpreter looks at *after* performing an action but
+before telling the player what's happened. Both :prop:`before` and
+:prop:`after` properties can be used not only with tangible objects like
+the ``bird``, ``cottage`` and ``tree`` (when they intercept actions aimed
+at that particular object) but also with rooms (when they intercept actions
+aimed at any object in that room).
+
+.. Generated by autoindex
+.. index::
+ pair: after; library property
+
+The value of each :prop:`before` and :prop:`after` property is an embedded
+routine. If such a routine ends with ``return false``, the interpreter
+then carries on with the next stage of the action which has been
+intercepted; if it ends with ``return true``, the interpreter does nothing
+further for that action. By combining these possibilities, you can
+supplement the work done by a standard action with statements of your own,
+or you can replace a standard action completely.
+
+.. Generated by autoindex
+.. index::
+ pair: cant_go; library property
Previously, we've seen connection properties used with the internal ID of
the room to which they lead. In this chapter, we showed that the value
could also be a string (explaining why movement in that direction isn't
-possible). Here are examples of both, and also of the ``cant_go`` property
-which provides just such an explanation for *all* connections that aren't
-explicitly listed::
+possible). Here are examples of both, and also of the :prop:`cant_go`
+property which provides just such an explanation for *all* connections that
+aren't explicitly listed::
e_to forest,
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.
+.. index::
+ single: arguments (of a routine)
+
When calling ``PlayerTo``, we had to tell the library which room is the
destination. We did this by supplying that room's internal ID within
parentheses, thus::
PlayerTo(clearing);
-A value given in parentheses like that is called an **argument** of the
+A value given in parentheses like that is called an :term:`argument` of the
routine. In fact, a routine can have more than one argument; if so,
they're separated by commas. For example, to move the player character to
a room *without* displaying that room's description, we could have supplied
In this example, the effect of the ``1`` is to prevent the description
being displayed.
-.. rubric:: Statements
+Statements
+----------
We encountered several new statements:
.. rubric:: Actions
-We've talked a lot about intercepting actions like ``Listen``, ``Enter``,
-``Climb`` and ``Drop``. An action is a generalised representation of
-something to be done, determined by the verb which the player types. For
-example, the verbs HEAR and LISTEN are ways of saying much the same thing,
-and so both result in the same action: ``Listen``. Similarly, verbs like
-ENTER, GET INTO, SIT ON and WALK INSIDE all lead to an action of ``Enter``,
-CLIMB and SCALE lead to Climb, and DISCARD, DROP, PUT DOWN and THROW all
-lead to ``Drop``. This makes life much easier for the designer; although
-Inform defines quite a lot of actions, there are many fewer than there are
-ways of expressing those same actions using English verbs.
+.. Generated by autoindex
+.. index::
+ pair: Climb; library action
+ pair: Drop; library action
+ pair: Enter; library action
+ pair: Listen; library action
+
+We've talked a lot about intercepting actions like :act:`Listen`,
+:act:`Enter`, :act:`Climb` and :act:`Drop`. An action is a generalised
+representation of something to be done, determined by the verb which the
+player types. For example, the verbs HEAR and LISTEN are ways of saying
+much the same thing, and so both result in the same action: :act:`Listen`.
+Similarly, verbs like ENTER, GET INTO, SIT ON and WALK INSIDE all lead to
+an action of :act:`Enter`, CLIMB and SCALE lead to Climb, and DISCARD,
+DROP, PUT DOWN and THROW all lead to :act:`Drop`. This makes life much
+easier for the designer; although Inform defines quite a lot of actions,
+there are many fewer than there are ways of expressing those same actions
+using English verbs.
+
+.. Generated by autoindex
+.. index::
+ pair: action; library variable
+ pair: second; library variable
Each action is represented internally by a number, and the value of the
-current action is stored in a library variable called, erm, ``action``.
-Two more variables are also useful here: ``noun`` holds the internal ID of
-the object which is the focus of the action, and ``second`` holds the
+current action is stored in a library variable called, erm, :var:`action`.
+Two more variables are also useful here: :var:`noun` holds the internal ID
+of the object which is the focus of the action, and :var:`second` holds the
internal ID of the secondary object (if there is one). Here are some
examples of these:
PUT NEST ON BRANCH PutOn nest branch
=============================== ====== ======= =======
-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.
+.. Generated by autoindex
+.. index::
+ pair: false; library constant
+ pair: true; library constant
+
+The value ``nothing`` is a built-in constant (like :const:`true` and
+:const:`false`) which means, well, there isn't any object to refer to.
+There's a list of 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.
projects / ibg.git / blobdiff