X-Git-Url: https://jxself.org/git/?p=ibg.git;a=blobdiff_plain;f=chapters%2F16.rst;h=702a59437b02e07efd5b6adc65ee8eb5903cfc77;hp=dbbd704b9318f14ba79a10f063d17fc4c7799449;hb=fb8b7c14f10733e913e2b87f9a82e5b44c0dc7be;hpb=a94081289bc21041a8daac44d8c8b6714a831281 diff --git a/chapters/16.rst b/chapters/16.rst index dbbd704..702a594 100644 --- a/chapters/16.rst +++ b/chapters/16.rst @@ -1,6 +1,6 @@ -=================== -Debugging your game -=================== +===================== + Debugging your game +===================== .. only:: html @@ -56,14 +56,13 @@ you must make the appropriate changes. (There is also the case when you 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 ============= @@ -237,20 +236,18 @@ TIMERS (or TIMERS ON ) and TIMERS OFF 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 ============ @@ -275,7 +272,7 @@ PURLOIN *object* 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 @@ -287,19 +284,19 @@ ABSTRACT *object* TO *object* 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 @@ -320,8 +317,8 @@ almost all of your game’s data and objects. For instance, you can use 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. @@ -374,7 +371,12 @@ change: "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 @@ -386,7 +388,6 @@ to make permanent amendments, you still need to edit the source file. You won't need it often, but Infix can sometimes provide quick answers to tricky problems. - No matter what ============== @@ -422,7 +423,7 @@ then wrote: * 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. @@ -439,32 +440,29 @@ The IF community offers some beta-testing resources, or you can always 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.