Appendix D

This section describes the TADS Run-Time system that players use to run your adventure. The run-time system is very simple, so players can learn to run your games very easily.

After you have compiled your game with the TADS Compiler, and you have tested the resulting program thoroughly, you are ready to give it to players. They are, after all, the reason you wrote the game.

Fortunately, to play the game, a player doesn't need to learn nearly as much as you did to write it. A simple run-time module is used to execute your game, called tr for TADS Run-time.

This program, when run without parameters, looks for a file called tads.gam in the current directory; if it finds it, the game is loaded and executed. Hence, players need only install two files on their computer in order to play your game: the tr program file, and the tads.gam data file.

On systems with a command line, you can specify the name of a game to run. For example, to execute sample.gam, you would type:

  tr sample 

However, in finished games, many authors may wish to create "self-loading" game files for distribution. A self-loading file contains the game data file (in this case, sample.gam) in the same file with the run-time executable, so only one file is needed to play the game. The process of building a self-loading game file is described later in this chapter.

By using TADS, your game is immediately portable to every system on which the TADS Compiler has been implemented. You do not need to change your source file at all. In addition, since the TADS version 2 binary game file is fully portable, you can simply transfer your binary files to other computer systems and run them without recompilation.

The TADS run-time system offers players many sophisticated features, many of which are not at all typical of text adventures. By using TADS, your game automatically supports all of these features without any work on your part. In addition, your game is immediately portable to every system on which the TADS Compiler has been implemented.

• Sophisticated command-line parsing, allowing multiple commands on a line, multiple direct objects, use of "all" and "except," and full support for adjectives, prepositions, nouns, and verbs. The parser can also automatically prompt for more information when needed, saving the player the trouble of retyping an entire command when something was left out.
  
• Operating-system specific file dialogs, simplifying the task of selecting files for saving and restoring games, and making the game consistent with the operating system's look and feel.
  
• On many systems, command line editing and recall is supported. Command line editing allows a player to edit the current command with arrow keys and other editing keys such as "delete," "home," and "end," making it easy to correct errors. Command line recall saves the most recent commands, and allows the player to recall them using editing keys (generally, several thousand characters of past commands can be saved, so practically an entire game can be recalled). Once recalled, a command can be edited and entered again. This is often a time-saving feature, and one that will be appreciated by regular computer users who are accustomed to such features in their operating system command shell.
  
• On many systems, TADS saves text that has scrolled off the screen, and allows the player to recall the text by using "review mode." After pressing a special key, the player can use arrow and paging keys to look through the most recent screens of text. Generally, dozens of pages of text are saved, allowing the player to review well back into the game.

The run-time system has several options, although they will generally not be needed by people who play your game.

First, the run-time has a set of memory size options. The -m size option specifies a maximum size (in bytes) for the virtual object cache at run-time; this works exactly the same as the compiler's -m size switch. This will generally not be necessary at run-time, because the run-time system does not usually need to allocate memory outside of the cache while the game is being played. However, if you run into a low-memory problem during game play, you can use -m to limit the cache size.

Two other memory options specify the size of run-time memory areas. The -mh size option specifies the size (in bytes) of the run-time heap, and the -ms size option specifies the size (in stack elements) of the run-time stack. Under normal circumstances, it won't be necessary to specify either of these parameters; however, if your game encounters run-time errors related to these two sizes, you can use these options to increase the limits.

The -u size option specifies the size (in bytes) of the undo log, which is a memory area that records the information necessary to undo player actions. The default size for this memory area is large enough to hold information to undo about a hundred turns in a typical game.

The -tf file option specifies the location of the swap file, in the same manner as the compiler's -tf option, and the -ts size option limits the size of the swap file, in the same way as the compiler's -ts option.

The remaining options are related to game testing, and are described in the next section.

The TADS run-time provides a facility that allows you to test your game to make sure it runs the same way after a change. First, you write a "script" file, which is simply a list of commands for your game - exactly the same as commands that a user would type while playing the game. Next, you use a special option that tells the run-time system to read commands from this script file rather than from the keyboard. Then, you use another special option that captures all of the output of your game into a file rather than sending it to the screen.

The run-time has a special option that makes it easy to create a script file. Run your game with the -o file option: this will run the game as normal, with input coming from the keyboard and output going to the screen, but will also write every command you type to the file you specified. Play through your game as normal, typing the set of commands you want to be able to test later. When you're done, quit the game. The file you specified with the -o option now contains an input script consisting of all of the commands you typed while playing.

Next, you can generate a "reference log." This is a file that contains all of the output from your game using the input script. Use the -i file option to tell the run-time system to read commands from your script file, specifying the name of the script file you generated with the -o option above. Also specify the -l logfile option; this will redirect all output from your game to the log file. Save this log file; this is your reference log, which is the output of the game that you consider to be correct. For example:

  tr -i walkthru.in -l walkthru.log mygame 

In the future, when you make changes to your game, you can check that you haven't done anything to change the game in unexpected ways. Run your game just as above, but use a different file for the new log file:

  tr -i walkthru.in -l new.log mygame 

Now, using a "diff" utililty (a program that compares two text files and displays differences), you can easily find changes you have made to your game's behavior:

  diff walkthru.log new.log 

(The "diff" utility is not something that is provided with TADS, but good public-domain file difference utilities are available for most systems. In addition, many commercial programming language systems provide some sort of diff utility, and some of the better programmer's text editors have this capability built-in.) Inspect the differences between the new and old logs, and make sure that all of the changes are desirable. Once you're satisfied that the new log is correct, you can simply delete the original reference log, and rename the new log as the new reference log.

Incidentally, we use this facility to test TADS itself. Using a number of games, such as Deep Space Drifter, we run a series of input scripts through each new version of TADS, verifying that we haven't done anything to TADS that changes its behavior with existing games.

When your game is completely finished, and you want to distribute it to friends (or even make it widely available through computer networks), you may wish to package your game as a "self-loading" executable. This means that you combine your .GAM file (the binary compiled version of your game program) and the TADS Run-Time module into a single executable file.

Making your game into a self-loading executable has some advantages and some disadvantages. The disadvantages are that your game will be larger and less portable if you package it as an executable. If you distribute only the .GAM file, you save about 160,000 bytes, which could be important if you'll be uploading your game to BBS's or commercial on-line systems; you can simply tell users that the TADS run-time module is necessary to run your game, and provide directions on where they can find TADS. If players of your game play other TADS games as well, they'll only need to download the TADS run-time once, rather than along with every game. In addition, since the .GAM file is portable between operating systems, you only need to make one version of your .GAM file available, and anyone with TADS on any system can play your game.

On the other hand, combining the TADS run-time and your .GAM file into a single executable makes your game much simpler to install and play, and gives it a more professional appearance. A self-loading executable game is much easier for players, since only a single file is needed, and players won't need to look for TADS (or even know anything about it) before playing your game. In addition, the command to play your game is simply the name of your game.

If you do choose to create a self-loading game, the actual process varies by operating system. You need the TADS run-time itself, plus a special program called MAKETRX that combines the run-time and your binary game program. On most command-line systems, such as MS-DOS, you build your game with a command like this:

  maketrx tr.exe mygame.gam mygame.exe 

In this command, you tell MAKETRX three things. First, tr.exe specifies the name and location of the TADS run-time executable. Second, mygame.gam is your compiled game. Both of these files must already exist; if they're on a different disk, or in a different directory, simply specify their locations with normal file syntax. Finally, mygame.exe is the name of the self-loading version of your game that you wish to create. The MAKETRX program combines tr.exe and mygame.gam, creating a self-loading executable game in mygame.exe. To run your game, you simply type "mygame" at the DOS prompt.

On Macintosh systems, the process is very similar, except that you use the standard file selectors to select the three files. In addition, you must specify an "owner ID," which is a special code that the operating system uses to associate your executable game with saved games that it creates. You can choose just about any four-letter sequence for the owner ID; it's supposed to be unique among all applications (that is, you should choose a four-letter code that no other application uses as its owner ID), although there is no way to be sure that some other application somewhere isn't using the same ID. Once you create your self-loading game, simply double-click on its icon (from the Finder) to play your game.