-===================
-Debugging your game
-===================
+=====================
+ Debugging your game
+=====================
.. only:: html
.. image:: /images/picN.png
:align: left
-.. raw:: latex
-
- \dropcap{n}
-
-obody understands the phrase *errare humanum est* quite in the same way
-as a programmer does. Computers are highly efficient machines capable of
-wondrous calculations, but they lack imagination and insist that every
-single item thrown at them must be presented according to certain rules
-previously defined. You can't negotiate with a computer; you either bow
-in submission or bite the dust.
+|N|\obody understands the phrase *errare humanum est* quite in the same
+way as a programmer does. Computers are highly efficient machines
+capable of wondrous calculations, but they lack imagination and insist
+that every single item thrown at them must be presented according to
+certain rules previously defined. You can't negotiate with a computer;
+you either bow in submission or bite the dust.
Inform behaves no differently. If you make a typing or syntax mistake,
the compiler will send you back to revise your work. "It was just a
can't find the mistake. Don't worry, it's there somewhere. Persistence
always pays off in the end.)
-To help you out in this daunting task, Inform has a stock of special
-actions: the debugging verbs. They become available at run-time when the
-source file is compiled in **Debug mode** (``-D switch``). When you are
-ready to release your game, you’ll have to recompile, switching off
-Debug to avoid allowing the players to benefit from the debugging verbs.
+To help you out in this daunting task, Inform has a stock of special
+actions: the debugging verbs. They become available at run-time when the
+source file is compiled in :term:`Debug mode` (:option:`-D` switch). When
+you are ready to release your game, you’ll have to recompile, switching off
+Debug to avoid allowing the players to benefit from the debugging verbs.
We'll cover briefly a few of these actions, and tell you what they do.
-
Command lists
=============
TRACE (or TRACE ON ), TRACE *number* and TRACE OFF
- If you turn on this powerful verb, you'll be able to follow the
- activity of the **parser** -- that part of the library which tries to
- make sense of what the player types -- and this will indeed be a
- wonderful moment of gratitude that someone else took the trouble of
- writing it. Since the parser does so many things, you can decide the
- level of detail about the displayed information with the *number*
- parameter, which can go from 1 (minimum info) to 5 (maximum info). By
- default, TRACE ON and TRACE with no number sets level 1. Trace level
- 1 shows the grammar line that the parser is thinking about, while
- level 2 shows each individual token on each grammar line that it
- tries. The information displayed with higher levels may become quite
- hacky, and you are advised to use this feature only if nothing else
- helps.
-
+ If you turn on this powerful verb, you'll be able to follow the activity
+ of the :term:`parser` -- that part of the library which tries to make
+ sense of what the player types -- and this will indeed be a wonderful
+ moment of gratitude that someone else took the trouble of writing
+ it. Since the parser does so many things, you can decide the level of
+ detail about the displayed information with the *number* parameter, which
+ can go from 1 (minimum info) to 5 (maximum info). By default, TRACE ON
+ and TRACE with no number sets level 1. Trace level 1 shows the grammar
+ line that the parser is thinking about, while level 2 shows each
+ individual token on each grammar line that it tries. The information
+ displayed with higher levels may become quite hacky, and you are advised
+ to use this feature only if nothing else helps.
Super-powers
============
PURLOIN *object*
+ .. Generated by autoindex
+ .. index::
+ pair: scenery; library attribute
+ pair: static; library attribute
+
PURLOIN works exactly as TAKE , with the nice addition that it doesn't
matter where the object is: in another room, inside a locked
container, in the claws of the bloodthirsty dragon. More dangerously,
it doesn't matter if the object is takeable, so you may purloin
- ``static`` or ``scenery`` objects. PURLOIN is useful in a variety of
+ :attr:`static` or :attr:`scenery` objects. PURLOIN is useful in a variety of
situations, basically when you want to test a particular feature of
the game that requires the player character to have some objects
handy. Instead of tediously collecting them, you may simply PURLOIN
ABSTRACT *object* TO *object*
+ .. Generated by autoindex
+ .. index::
+ pair: animate; library attribute
+ pair: container; library attribute
+ pair: supporter; library attribute
+
This verb enables you to move the first *object* to the second
*object*. As with PURLOIN , both objects can be anywhere in the game.
Bear in mind that the second object should logically be a
- ``container``, a ``supporter`` , or something ``animate``.
+ :attr:`container`, a :attr:`supporter` , or something :attr:`animate`.
-Infix: the harlot's perogative
-==============================
+Infix: the harlot's prerogative
+===============================
-The basic debugging verbs are fairly versatile, easy to use, and don't
-consume a lot of memory. Occasionally though, you'll meet a bug which
-you simply can't catch using regular techniques, and that’s when you
-might want to investigate the Infix debugger. You'll need to compile
-using the ``-X`` switch, and you'll then be able to monitor and modify
-almost all of your game’s data and objects. For instance, you can use
-";" to inspect -- and change -- a variable:
+The basic debugging verbs are fairly versatile, easy to use, and don't
+consume a lot of memory. Occasionally though, you'll meet a bug which you
+simply can't catch using regular techniques, and that’s when you might want
+to investigate the Infix debugger. You'll need to compile using the
+:option:`-X` switch, and you'll then be able to monitor and modify almost
+all of your game’s data and objects. For instance, you can use ";" to
+inspect -- and change -- a variable:
.. code-block:: transcript
In that game you scored 0 out of a possible 2, in 2 turns.
It's often quite maddening to realise that some variable is still
-``false`` because the Chalk puzzle didn't work properly, and that you
-can't test the Cheese puzzle until the variable becomes ``true``. Rather
+:const:`false` because the Chalk puzzle didn't work properly, and that you
+can't test the Cheese puzzle until the variable becomes :const:`true`. Rather
than quit, fix the Chalk, recompile, play back to the current position
and only *then* tackle the Cheese, how much easier to just change the
variable in mid-stream, and carry right on.
"OK, Herr Tell, now you're in real trouble.
...
-.. todo:: "Herr" above is italicized. Was that a mistake in the original text?
-
Infix is quite complex -- there are more commands than those we have
shown you -- so while it's good to have available, it's not really a
tool for novices. If you do use it, be careful: you get a lot of runtime
You won't need it often, but Infix can sometimes provide quick answers
to tricky problems.
-
No matter what
==============
* Benny will force the player back into the cafe even when the key is
dropped in the café, or put on the counter (in Benny's plain sight!).
-Of course, the code we've offered you in this edition takes care of
+Of course, the code we've offered you in *this* edition takes care of
those embarrassing issues, but it might very well happen that a few more
undetected absurdities pop up from now on.
+.. Generated by autoindex
+.. index::
+ single: RAIF
+
The final stage of debugging must happen elsewhere, at the hands of some
wilful, headstrong and determined beta-testers; these are the people
who, if you’re lucky, will methodically tear your game to shreds and
ask in RAIF for kind souls willing to have a go at your game. Remember
the golden rules:
- * **Expect no mercy**. Although it hurts, a merciless approach is what
- you need at this time; much better to discover your errors and
- oversights now, before you release the game more widely. And don't
- forget to acknowledge your testers' assistance somewhere within the
- game.
-
- * **Never say never**. If your testers suggest that the game should
- respond better to an attempted action, don't automatically respond
- with "No one's going to try that!" They already have, and will again
- -- be grateful for your testers' devious minds and twisted psyches.
- Although a normal player won't try all of those oddball things,
- every player is bound to try at least one, and their enjoyment will
- be greater, the reality enhanced, if the game "understands".
-
- * **Ask for more**. Don't treat your testers simply as validators of
- your programming skills, but rather as reviewers of your
- storytelling abilities. Encourage them to comment on how well the
- pieces fit together, and to make suggestions -- small or radical --
- for improvement; don't necessarily reject good ideas just because
- implementing them "will take too long". For example: "the scene in
- the Tower of London doesn't somehow seem to belong in an Arabian
- Nights game", or "having to solve three puzzles in a row just to
- discover the plate of sheep's eyes is a little over the top", or
- "this five-room trek across the desert really is a bit dull;
- perhaps you could add a quicksand or something to liven it up?", or
- "the character of the eunuch in the harem seems to be lacking in
- something". That is, view the testers collectively not as simple
- spell-checkers, but rather as collaborative editors on your latest
- novel.
+* **Expect no mercy**. Although it hurts, a merciless approach is what you
+ need at this time; much better to discover your errors and oversights
+ now, before you release the game more widely. And don't forget to
+ acknowledge your testers' assistance somewhere within the game.
+
+* **Never say never**. If your testers suggest that the game should
+ respond better to an attempted action, don't automatically respond with
+ "No one's going to try that!" They already have, and will again -- be
+ grateful for your testers' devious minds and twisted psyches. Although a
+ normal player won't try *all* of those oddball things, every player is
+ bound to try at least *one*, and their enjoyment will be greater, the
+ reality enhanced, if the game "understands".
+
+* **Ask for more**. Don't treat your testers simply as validators of your
+ programming skills, but rather as reviewers of your storytelling
+ abilities. Encourage them to comment on how well the pieces fit together,
+ and to make suggestions -- small or radical -- for improvement; don't
+ necessarily reject good ideas just because implementing them "will take
+ too long". For example: "the scene in the Tower of London doesn't somehow
+ seem to belong in an Arabian Nights game", or "having to solve three
+ puzzles in a row just to discover the plate of sheep's eyes is a little
+ over the top", or "this five-room trek across the desert really is a bit
+ dull; perhaps you could add a quicksand or something to liven it up?", or
+ "the character of the eunuch in the harem seems to be lacking in
+ something". That is, view the testers collectively not as simple
+ spell-checkers, but rather as collaborative editors on your latest novel.