-===================
-Debugging your game
-===================
+=====================
+ Debugging your game
+=====================
.. only:: html
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
============
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
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?
+.. todo::
+
+ "Herr" above is italicized. Was that a mistake in the original text?
+
+ Update: I don't think so. In 08.rst, lines 465 and 516, "Herr" is
+ explicitly underlined (which probably appears italicized on output).
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
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.
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.