.. epigraph::
- | *E was an esquire, with pride on his brow;*
- | *F was a farmer, and followed the plough.*
+ | |CENTER| *E was an esquire, with pride on his brow;*
+ | |CENTER| *F was a farmer, and followed the plough.*
-Each of the three games in this guide is created step by step; you'll get
-most benefit (especially to begin with) if you take an active part, typing
-in the source code on your computer. Our first game, described in this
-chapter and the two which follow, tells this sentimental little story:
+.. only:: html
+
+ .. image:: /images/picE.png
+ :align: left
+
+|E|\ach of the three games in this guide is created step by step; you'll
+get most benefit (especially to begin with) if you take an active part,
+typing in the source code on your computer. Our first game, described in
+this chapter and the two which follow, tells this sentimental little story:
"Heidi lives in a tiny cottage deep in the forest. One sunny day,
standing before the cottage, she hears the frenzied tweeting of baby
The first task is to create an Inform source file template. Every game
that we design will start out like this. Follow these steps:
-#. Create an ``Inform\Games\Heidi`` folder (maybe by copying ``Inform\Games\MyGame1``).
+#. Create an ``Inform\Games\Heidi`` folder (maybe by copying
+ ``Inform\Games\MyGame1``).
.. note::
Ensure the file is named ``Heidi.inf``, rather than ``Heidi.txt`` or
``Heidi.inf.txt``.
- Remember that, throughout this guide, we place the "TYPE" symbol
+ Remember that, throughout this guide, we place the "``TYPE``" symbol
alongside pieces of code that we recommend you to type into your own
game files as you read through the examples (which, conversely, means
- that you don't need to type the unmarked pieces of code). You'll learn
- Inform more quickly by trying it for yourself, rather than just taking
- our word for how things work.
+ that you *don't* need to type the unmarked pieces of code). You'll
+ learn Inform more quickly by trying it for yourself, rather than just
+ taking our word for how things work.
.. todo::
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
source. The instructions most commonly placed here are compiler
switches, a way of controlling detailed aspects of how the compiler
operates. These particular switches, two of many, are turning on
- **Strict mode**, which makes the game less likely to misbehave when being
- played, and **Debug mode**, which provides some extra commands which can
- be helpful when tracking down problems.
+ :term:`Strict mode`, which makes the game less likely to misbehave when
+ being played, and :term:`Debug mode`, which provides some extra commands
+ which can be helpful when tracking down problems.
.. note::
- Actually, the ``-S`` is redundant, since Strict mode is already on by
- default. We include it here as a reminder that (a) to turn Strict
- mode *off*, you change this setting to ``-~S``, and (b) alphabetic
- case matters here: ``-s`` causes a display of compiler statistics (and
- ``-~s`` does nothing at all).
+ Actually, the :option:`-S` is redundant, since Strict mode is already
+ on by default. We include it here as a reminder that (a) to turn
+ Strict mode *off*, you change this setting to :option:`-~S`, and (b)
+ alphabetic case matters here: :option:`-s` causes a display of
+ compiler statistics (and :option:`-~s` does nothing at all).
* Otherwise, when the compiler comes across an exclamation mark, it ignores
the rest of the line. If the ``!`` is at the start of a line, the whole
line is ignored; if the ``!`` is halfway along a line, the compiler takes
note of the first half, and then ignores the exclamation mark and
everything after it on that line. We call material following an
- exclamation mark, not seen by anybody else, a **comment**; it's often a
- remark that we write to remind ourselves of how something works or why we
- tackled a problem in a particular way. There's nothing special about
+ exclamation mark, not seen by anybody else, a :term:`comment`; it's often
+ a remark that we write to remind ourselves of how something works or why
+ we tackled a problem in a particular way. There's nothing special about
those equals signs: they just produce clear lines across the page.
It's always a good idea to comment code as you write it, for later it
By the way, the compiler *doesn't* give special treatment to exclamation
marks in quoted text: ``!`` within quotes "..." is treated as a normal
character. On this line, the first ``!`` is part of the sequence (or
- string) of characters to be displayed:
+ :term:`string`) of characters to be displayed:
.. code-block:: inform
you've typed, so it's worthwhile taking a bit of care to make it as
readable as possible.
-* Every game should have the **constant** definitions for ``Story`` (the
- game's name) and ``Headline`` (typically, information on the game's
- theme, copyright, authorship and so on). These two **string** values,
- along with a release number and date, and details of the compiler,
- compose the **banner** which is displayed at the start of each game.
+* Every game should have the :term:`constant` definitions for ``Story``
+ (the game's name) and ``Headline`` (typically, information on the game's
+ theme, copyright, authorship and so on). These two :term:`string`
+ values, along with a release number and date, and details of the
+ compiler, compose the :term:`banner` which is displayed at the start of
+ each game.
* Every game needs the three lines which ``Include`` the standard library
files -- that is, they merge those files' contents into your source file:
Include "Parser";
Include "VerbLib";
- ! ...
+ ...
Include "Grammar";
They always have to be in this order, with ``Parser`` and ``VerbLib``
[ Initialise; ];
- The **routine** that we've defined here doesn't do anything useful, but
- it still needs to be present. Later, we'll come back to ``Initialise``
- and explain what a routine is and why we need this one.
+ The :term:`routine` that we've defined here doesn't do anything useful,
+ but it still needs to be present. Later, we'll come back to
+ ``Initialise`` and explain what a routine is and why we need this one.
* You'll notice that each of the items mentioned in the previous three
rules ends with a semicolon. Inform is very fussy about its punctuation,
.. image:: /images/heidi1.*
:align: center
-In IF, we talk about each of these locations as a **room**, even though in
-this example none of them has four walls. So let's use Inform to define
+In IF, we talk about each of these locations as a :term:`room`, even though
+in this example none of them has four walls. So let's use Inform to define
those rooms. Here's a first attempt:
.. code-block:: inform
* A keyword ``with`` follows, which simply tells the compiler what to
expect next.
-* The word ``description``, introducing another piece of text which gives
- more detail about the object: in the case of a room, it's the appearance
- of the surrounding environment when the player character is in that room.
- The textual description is given in double quotes, and is followed by a
- comma.
+* The word :prop:`description`, introducing another piece of text which
+ gives more detail about the object: in the case of a room, it's the
+ appearance of the surrounding environment when the player character is in
+ that room. The textual description is given in double quotes, and is
+ followed by a comma.
* Near the end, the keyword ``has`` appears, which again tells the compiler
to expect a certain kind of information.
-* The word ``light`` says that this object is a source of illumination, and
- that therefore the player character can see what's happening here. There
- has to be at least one light source in every room (unless you want the
- player to be told that "It's pitch dark and you can't see a thing"); most
- commonly, that light source is the room itself.
+* The word :attr:`light` says that this object is a source of illumination,
+ and that therefore the player character can see what's happening here.
+ There has to be at least one light source in every room (unless you want
+ the player to be told that "It's pitch dark and you can't see a thing");
+ most commonly, that light source is the room itself.
A smidgeon of background may help set this into context (there's more in
-the next chapter). An object can have both **properties** (introduced by
-the keyword ``with``) and **attributes** (written after the word ``has``).
-A property has both a name (like ``description``) and a value (like the
-character string "``You stand outside a cottage. The forest stretches
-east.``"); an attribute has merely a name.
+the next chapter). An object can have both :term:`properties` (introduced
+by the keyword ``with``) and :term:`attributes` (written after the word
+``has``). A property has both a name (like :prop:`description`) and a
+value (like the character string "``You stand outside a cottage. The
+forest stretches east.``"); an attribute has merely a name.
In a little while, when you play this game, you'll observe that it starts
like this:
cottage), and the second defines a connection ``forest`` → ``clearing``
which heads off to the northeast.
- Inform provides for eight "horizontal" connections (``n_to``, ``ne_to``,
- ``e_to``, ``se_to``, ``s_to``, ``sw_to``, ``w_to``, ``nw_to``) two
- "vertical" ones (``u_to``, ``d_to``) and two specials ``in_to``, and
- ``out_to``. You'll see some of these used for the remaining inter-room
- connections.
+ Inform provides for eight "horizontal" connections (:prop:`n_to`,
+ :prop:`ne_to`, :prop:`e_to`, :prop:`se_to`, :prop:`s_to`, :prop:`sw_to`,
+ :prop:`w_to`, :prop:`nw_to`) two "vertical" ones (:prop:`u_to`,
+ :prop:`d_to`) and two specials :prop:`in_to`, and :prop:`out_to`. You'll
+ see some of these used for the remaining inter-room connections.
There's one last detail to attend to before we can test what we've done.
You'll recollect that our story begins with Heidi standing in front of her
-cottage. We need to tell the interpreter that ``before_cottage`` is the room
-where the game starts, and we do this in the ``Initialise`` routine::
+cottage. We need to tell the interpreter that ``before_cottage`` is the
+room where the game starts, and we do this in the ``Initialise`` routine::
[ Initialise; location = before_cottage; ];
-``location`` is a **variable**, part of the library, which tells the
+:var:`location` is a :term:`variable`, part of the library, which tells the
interpreter in which room the player character currently is. Here, we're
saying that, at the start of the game, the player character is in the
``before_cottage`` room.
(``baby bird``, ``bird's nest``). They both have some descriptive detail:
for a room this is printed when the player first enters, or when she types
LOOK; for other objects it's printed when she EXAMINEs that object. What
-they *don't* have are connections (``e_to``, ``w_to``, etc. apply only to
-rooms) or ``light`` (it's not necessary -- the rooms ensure that light is
-available).
+they *don't* have are connections (:prop:`e_to`, :prop:`w_to`, etc. apply
+only to rooms) or :attr:`light` (it's not necessary -- the rooms ensure
+that light is available).
When the game is running, the player will want to refer to these two
objects, saying for instance EXAMINE THE BABY BIRD or PICK UP THE NEST.
name 'bird^s' 'nest' 'twigs' 'moss',
has ;
-The ``name`` introduces a list in single quotes '...'. We call each of
-those quoted things a **dictionary word**, and we do mean "word", not
+The :prop:`name` introduces a list in single quotes '...'. We call each of
+those quoted things a :term:`dictionary word`, and we do mean "word", not
"phrase" (``'baby'``\ ``'bird'`` rather than ``'baby bird'``); you can't
-uses spaces, commas or periods in dictionary words, though there's a space
-*between* each one, and the whole list ends with a comma. The idea is that
-the interpreter decides which object a player is talking about by matching
-what she types against the full set of all dictionary words. If the player
-mentions BIRD, or BABY BIRD, or NESTLING, it's the ``baby bird`` that she
-means; if she mentions NEST, BIRD'S NEST or MOSS, it's the ``bird's nest``.
-And if she types NEST BABY or BIRD TWIGS, the interpreter will politely say
-that it doesn't understand what on earth she's talking about.
+uses spaces, commas or periods *in* dictionary words, though there's a
+space *between* each one, and the whole list ends with a comma. The idea
+is that the interpreter decides which object a player is talking about by
+matching what she types against the full set of all dictionary words. If
+the player mentions BIRD, or BABY BIRD, or NESTLING, it's the ``baby bird``
+that she means; if she mentions NEST, BIRD'S NEST or MOSS, it's the
+``bird's nest``. And if she types NEST BABY or BIRD TWIGS, the interpreter
+will politely say that it doesn't understand what on earth she's talking
+about.
+
+.. index::
+ single: apostrophes
.. note::
apostrophe, and the compiler then treats ``bird's`` as a dictionary
word.
-You may be wondering why we need a list of ``name`` words for the bird and
-its nest, yet we didn't when we defined the rooms? It's because the player
-can't interact with a room in the same way as with other objects; for
-example, she doesn't need to say EXAMINE THE FOREST -- just being there and
-typing LOOK is sufficient.
+You may be wondering why we need a list of :prop:`name` words for the bird
+and its nest, yet we didn't when we defined the rooms? It's because the
+player can't interact with a room in the same way as with other objects;
+for example, she doesn't need to say EXAMINE THE FOREST -- just being there
+and typing LOOK is sufficient.
The bird's definition is complete, but there's an additional complexity
with the nest: we need to be able to put the bird into it. We do this by
-labelling the nest as a ``container`` -- able to hold other objects -- so
-that the player can type PUT (or INSERT) BIRD IN (or INTO) NEST.
-Furthermore, we label it as ``open``; this prevents the interpreter from
-asking us to open it before putting in the bird.
+labelling the nest as a :attr:`container` -- able to hold other objects --
+so that the player can type PUT (or INSERT) BIRD IN (or INTO) NEST.
+Furthermore, we label it as :attr:`open`; this prevents the interpreter
+from asking us to open it before putting in the bird.
.. code-block:: inform
name 'tall' 'sycamore' 'tree' 'stout' 'proud',
has scenery;
-Everything there should be familiar, apart from that ``scenery`` at the
+Everything there should be familiar, apart from that :attr:`scenery` at the
end. We've already mentioned the tree in the description of the forest
clearing, so we don't want the interpreter adding "You can see a tall
sycamore tree here" afterwards, as it does for the bird and the nest. By
-labelling the tree as ``scenery`` we suppress that, and also prevent it
+labelling the tree as :attr:`scenery` we suppress that, and also prevent it
from being picked up by the player character. One final object: the branch
at the top of the tree. Again, not many surprises in this definition:
name 'wide' 'firm' 'flat' 'bough' 'branch',
has static supporter;
-The only new things are those two labels. ``static`` is similar to
-``scenery``: it prevents the branch from being picked up by the player
+The only new things are those two labels. :attr:`static` is similar to
+:attr:`scenery`: it prevents the branch from being picked up by the player
character, but *doesn't* suppress mention of it when describing the
-setting. And ``supporter`` is rather like the ``container`` that we used
-for the nest, except that this time the player character can put other
-objects *onto* the branch. (In passing, we'll mention that an object can't
-normally be both a ``container`` and a ``supporter``.) And so here are our
-objects again:
+setting. And :attr:`supporter` is rather like the :attr:`container` that
+we used for the nest, except that this time the player character can put
+other objects *onto* the branch. (In passing, we'll mention that an object
+can't normally be both a :attr:`container` *and* a :attr:`supporter`.) And
+so here are our objects again:
.. code-block:: inform
The value of ``MAX_CARRIED`` limits the number of objects that the player
character can be holding at any one time; by setting it to 1, we're saying
that she can carry the bird or the nest, but not both. However, the limit
-ignores the contents of ``container`` or ``supporter`` objects, so the nest
-with the bird inside it is still counted as one object.
+ignores the contents of :attr:`container` or :attr:`supporter` objects, so
+the nest with the bird inside it is still counted as one object.
The other change is slightly more complex and more important: there's
currently no way to "win" the game! The goal is for the player character
several new concepts all at once. Later in the guide, we'll explain
those concepts more clearly, so you can just skip this bit if you want.
- The variable ``deadflag``, part of the library, is normally 0. If you set
- its value to 2, the interpreter notices and ends the game with "You have
- won". The statement::
+ The variable :var:`deadflag`, part of the library, is normally 0. If
+ you set its value to 2, the interpreter notices and ends the game with
+ "You have won". The statement::
if (nest in branch) deadflag = 2;
should be read as: "Test whether the ``nest`` is currently in the
- ``branch`` (if the branch is a ``container``) or on it (if the
- ``branch`` is a supporter); if it is, set the value of ``deadflag`` to
- 2; if it isn't, do nothing." The surrounding part::
+ ``branch`` (if the branch is a :attr:`container`) or on it (if the
+ ``branch`` is a supporter); if it is, set the value of :var:`deadflag`
+ to 2; if it isn't, do nothing." The surrounding part::
each_turn [; ... ],
``clearing``, so nothing happens.
* Also at the end of each turn, the interpreter checks the value of
- ``deadflag``. Usually it's 0, so nothing happens.
+ :var:`deadflag`. Usually it's 0, so nothing happens.
* Finally the player character puts the ``nest`` on the ``branch``.
"Aha!" says the interpreter (to itself, of course), and sets the
- value of ``deadflag`` to 2.
+ value of :var:`deadflag` to 2.
* Immediately afterwards, (another part of) the interpreter checks and
- finds that the value of ``deadflag`` has changed to 2, which means
+ finds that the value of :var:`deadflag` has changed to 2, which means
that the game is successfully completed; so, it says to the player,
"you've won!"
projects / ibg.git / blobdiff