After you have finished writing your game it is important to test it thoroughly before it is released. In a game of any real size, many bugs exist and will only be discovered through extensive beta testing. This chapter covers some tools and techniques for debugging a piece of interactive fiction written using JACL.
The most immediate indication you will get of a problem with your game is an error message while trying to load the game. Errors with the definition of data (such as objects and variables) that are detected while loading your game will specify the line number the error occurred on. The line numbers specified are those from the .j2 file created in the temp directory. If the only files you include in your game (using the #include directive) are at the very end, the line numbers specified in the error messages will be equivalent to the lines in your original .jacl source file. If you include files at various points before the end of your game, the line numbers specified will not be equivalent. In order to investigate the offending line of code in this situation you will need to look directly at the processed .j2 file.
The walkthru command allows you to specify the name of a text file that contains a list of moves to process as though they were typed by the player. The text file must contain one command per line and may contain as many commands as you would like. The default name for a walkthru file is GameName.walkthru. It is common for this default file to issue all the commands required to get from the beginning of the game to end. This can vary from the most direct path using the minimum commands to the most thorough path visiting every part of the game along the way. Other shorter walkthru files may also be created that take the player from one specific point in the game to another.
Walkthru files have two advantages over saved game files. The first is that as soon as you add or remove an object or variable to a game, saved game files made using a previous version of the game can no longer be loaded. This means that without the use of a walkthru file, play testing the end of the game would involve tediously playing the beginning of the game over and over again as it grows. The second advantage is that a walkthru file shows all the output from every command rather than just instantly teleporting you to a future (or past) point in the game. This makes walkthru files useful for regression testing. By running through a walkthru file after changing some code in your game, you are able to test that everything that previously works still works as expected by quickly scanning the transcript.
When a walkthru script is running, no [MORE] prompts will be displayed, including those explicitly displayed by a more command. Below is a sample of a walkthru file, being the top ten lines from grail.walkthru:
w n turn off lights close blinds examine screen s s take gps n w
As you can see, walkthru files are of a simple format that can be created with any text editor.
The JACL interpreter provides a mechanism for recording a transcript of a game while it is being played. Recording is started by using the script command then entering a filename to save the transcript to.
As well as being interesting records to keep of your playing, transcripts are an enormously useful way of receiving feedback from people who beta test your games. While recording a transcript it is possible to insert a comment by typing an asterisk as the first character at the command prompt then following it with the comment you would like to add. For example, the in-game command:
>*It is possible to open the door even when it is locked.will appear in the currently active transcript with only the following response:
Comment ignored.
You stop a transcript from being recorded by using the command unscript.
The library debug.library contains a set of JACL verbs that are useful for testing your game during development. This library should be included using the #debug directive so that it is not included in the release version of your game (see below).
The inspect command displays the label, attribute and element values of the object passed as a parameter. Two special verbs in debug.library allows an object to be inspected while playing a game, these are inspect and inspectobj. Below is some sample output of the inspect verb from The Unholy Grail:
>inspect drawer label: compartment has object attributes: CLOSED CLOSABLE CONTAINER has user attributes: parent: device (112) capacity: 6 mass: 100 bearing: 0 velocity: 0 next: 0 previous: 0 child: 0 index: 0 status: 0 counter: 0 points: 0 class: 0 x: 0 y: 0
The above output is a dump of the current values of all of the object's properties, including attributes. The object chosen by the inspect verb is determined using the standard rules for object resolution based on the names provided. In this case, the single name drawer has uniquely identified an object with the label compartment.
It is also possible to use the command inspectobj to give the same details as above for whichever object an expression resolves to. For example, the follow two commands will show the detail of the player's current location:
>inspectobj player(parent) >inspectobj here
The valueof verb is a way of displaying the current integer value of any resolveable container. This includes an object label, an object element and an integer variable or constant. Below is an example of the valueof command being used while playing The Unholy Grail:
>valueof report(parent) report(parent) = 44
Where the verb inspect is a way of accessing the JACL command inspect during game play, fetch is simply a convenience verb to move an object to the current location and remove the attribute OUT_OF_REACH from that object should it have it. The verb is handy when you need to test a puzzle that involves the use or one or move objects that are time consuming to obtain manually.
For thorough testing it is preferable to use the walkthru verb to test all the steps normally taken to obtain the object or objects, but fetch can still be of use when testing small parts of your game in isolation.
Once you have completed your game and all known bugs are fixed you will want to release it to the public to be played. Although it is possible to simply distribute the .jacl file you have been working on (presuming only standard JACL libraries are used), it is often preferable to distribute the .j2 file. This file is created in the temp subdirectory when the game is run. This file can be thought of a statically-linked version of your game, with all #included files appended to the game file. In addition to appending all the required library files, unnecessary whitespace is removed from the beginning of each line to reduce file size and improve run-time performance.
Although a .j2 file is created each time your game is run, it is possible to use the -release argument when running jacl to produce a file more suitable for distribution. The argument will cause the .j2 to be encrypted (mildly), and to only contain files included with the #include directive, not the #debug directive.
If you wish to create a .j2 file that does not include the #debug files, but is not encrypted, you can supply the arguments -release -noencrypt.