This file is part of the TADS 2 Author’s Manual.
Copyright © 1987 - 2002 by Michael J. Roberts. All rights reserved.
Edited by NK Guy, tela design.


Appendix B


The TADS Interpreter

This section describes the TADS interpreter (also known as the TADS run-time system) that players use to run your adventure. The interpreter is very simple to use, so players can learn to run your games very easily. Note that in this context the names “interpreter” and “run-time” are essentially synonymous and are used interchangeably.


The TADS Interpreter

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 program, called the TADS Run-time, is used to execute your game.

Text-only versions of the 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 program file, and the tads.gam data file. On some computers the program is named tr or tadsr. Other interpreter programs for TADS include MaxTADS, WinTADS, HTML TADS and HyperTADS.

On operating systems with a command line (MS-DOS and UNIX), you can specify the name of a game to run. For example, to execute sample.gam, you would type:

tr sample or tadsr sample

For operating systems with a graphical user interface, such as the Macintosh or Windows, you would pull down the “File” menu and select “Open” or “Import TADS Game File” or whatever the game-loading command is on the interpreter you’re using. You can then select your game and double-click it.


Portability

By using TADS, your game is immediately portable to every system on which the TADS interpreter runs. 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.


Run-Time System Features

The TADS interpreter 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.


Run-Time Options

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

First, many versions of the run-time let you change a number of memory size options. Note that the ones that don’t allow you to alter these settings simply set them to their highest possible values, so you never have to worry about them at all. Changing memory size options is only important on older computers with limited memory.

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.


Testing Your Game

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.

Many versions of the interpreter have 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 such as UltraEdit and BBEdit 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.


DOS Version Special Features

The player can customize the colors used by the MS-DOS runtime. A small program, TRCOLOR, is provided to set up the runtime screen colors. The program is self-explanatory (it displays instructions on-screen, and its operations are very simple). Type TRCOLOR at the DOS prompt to run the program.

Once you’ve selected your color scheme, the TRCOLOR program will create a small file called TRCOLOR.DAT in the current directory. The runtime will read this file at the start of subsequent game sessions.

Note that you can use multiple TRCOLOR.DAT files, in the same way that you can use multiple CONFIG.TC files. The runtime looks for TRCOLOR.DAT first in the current directory; if no such file exists, the runtime uses the TRCOLOR.DAT in the directory containing TR.EXE. This allows you to set up a separate color scheme for each game you’re playing, and in addition set up a default color scheme for games with no color schemes of their own.

The DOS runtime also lets the player move the cursor to the start of the next word with control-right arrow, and to the start of the previous word with control-left arrow. This is consistent with many other DOS command-editing environments.

Finally, the DOS runtime has a plain ASCII mode, in which it uses only DOS character input/output functions. When in plain ASCII mode, the DOS runtime won’t use any low-level I/O functions, such as BIOS or memory-mapped video, but goes entirely through DOS. The runtime also won’t display the status line or any highlighting. If you have a special need for DOS-only I/O (for example, if you’re visually disabled and want to use a voice synthesizer to read the text generated by the game), you can use this mode.

To tell the runtime to use plain ASCII mode, specify -plain on the runtime command line:

  tr -plain deep

You can also specify -plain to an executable game, as long as the game executable was built using a version of the runtime (such as 2.2) that supports the plain ASCII mode:

  deep -plain


Macintosh Version Note

Macintosh files are identified by four-character creator and file type codes. Old versions of the TADS Runtime would only let you open TADS games that had the correct creator and file type settings. This was obviously a nuisance when it came to getting TADS games from other computers - over the Internet, say.

The Macintosh runtime’s initial file selector dialogue box, which lets you specify the game you want to run, now has an “All Files” button. Clicking this button makes the file selector show all files, rather than just files that have the special signature that indicates they were created by the Macintosh version of the TADS compiler. If you’ve transferred a .GAM file from a non-Macintosh system, you can use the “All Files” button to open the file - you no longer have to use ResEdit or another file utility to set the creator and type flags in the file. MaxTADS and HyperTADS, two other Macintosh interpreters, have similar functionality.


Making a Self-Loading Game

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 over 160,000 bytes, which could be important if you’ll be uploading your game to the Internet or BBS’s or commercial on-line systems; you can simply tell users that the TADS interpreter 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. Self-loading executables are forever tied to one specific operating system.

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. On text-only versions of the interpreter you’ll 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 one of these commands:

  maketrx mygame 

Converts MYGAME.GAM into MYGAME.EXE, using the copy of TR.EXE that resides in the same directory as MAKETRX.EXE.

  maketrx mygame myprog 

Converts MYGAME.GAM into MYPROG.EXE, using the copy of TR.EXE that resides in the same directory as MAKETRX.EXE.

  maketrx c:\tads2\tr.exe mygame myprog 

Converts MYGAME.GAM into MYPROG.EXE using C:\TADS2\TR.EXE as the runtime executable.

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.

Note three things. First, you can omit the extensions on all of the arguments. The extension assumed for TR.EXE is “.EXE”; for the game file it is “.GAM”; and for the output (executable) file it is “.EXE”.

Second, you can omit everything except the name of the game file, and the program will use reasonable defaults. If you omit the name of the TR.EXE program, MAKETRX attempts to find TR.EXE in the same directory as MAKETRX.EXE; so, if you simply keep all of your TADS executables in a single directory, you won’t need to specify the location of TR.EXE when running MAKETRX. If you omit the name of the destination file, MAKETRX will use the same name as the game file, with the extension replaced by “.EXE”.

Third, the MAKETRX command takes another parameter that lets you specify the run-time command options that should be used when the game is executed. MAKETRX still accepts the original command formats; using one of the old-style command formats will not bind any command options into the resulting .EXE file, in which case the game will use the default runtime settings.

To specify command options for your game executable, you must first create a file containing the command options. Use the same format as CONFIG.TR - simply enter your options into the file as you would on the TR command line; separate options by newlines or spaces. For example, to specify a minimal cache size and a swap file of SWAP.DAT, you could make your CONFIG.TR file look like this:

  -m0 -tf swap.dat

For DOS users: Once you’ve created a file with your command options, specify that file to MAKETRX by using it as the first parameter on the command line, prefixed with an “at” sign (@):

maketrx @config.tr mygame

The @config option can be used with any of the original command formats for MAKETRX. Once the options file is bound into your executable, its options will be used every time a player runs your game’s .EXE file. This is very important for large games, which may not be playable using the runtime’s default memory settings.

Note that you may should avoid specifying anything specific to your system in your options file, such as drives or directories, since doing so may prevent the game from working properly on someone else’s system. For example, if you specify the swap file as “D:\SWAP.DAT,” then the game won’t work on a system that doesn’t have a “D” drive, since TADS will be unable to create a swap file on a drive that doesn’t exist.


Graphical user interface systems

On Macintosh systems using the original TADS Runtime, the process is very similar except that you use the standard file selectors to select the three files. In addition, you must specify an “creator 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, and should not be in all lower-case. Ideally you should register your four-letter creator code with Apple directly.

Once you’ve specified the creator type and selected the files a final dialogue box appears and asks you for the options file you want to bind into your game. If you don’t want to include an options file, simply hit “Cancel.” Otherwise, select the file containing the options and hit “OK.” Note that the options file for the Macintosh version is in the same format as for the DOS version; refer to the options described earlier in this document for more information on the format of the run-time command options.

Note that you may should avoid specifying anything specific to your system in your options file, such as drives or directories, since doing so may prevent the game from working properly on someone else’s system. For example, if you specify the swap file as “Macintosh HD:TADS:swapfile.dat” then the game won’t work on a system that doesn’t have a “Macintosh HD” drive, since TADS will be unable to create a swap file on a drive that doesn’t exist.

Once you create your self-loading game, simply double-click on its icon (from the Finder) to play your game.

Andrew Plotkin’s MaxTADS interpreter and Stephen Granade’s WinTADS interpreter use a different method for binding game files to the executable. The procedure used is fully documented within the applications. Note that some versions of the runtime, such as the HyperTADS interpreter, do not support game binding.



Mind in its purest play is like some bat
That beats about in caverns all alone.
Contriving by a kind of senseless wit
Not to conclude against a wall of stone.
RICHARD PURDY WILBUR, Mind (1956)


Appendix A Table of Contents Appendix C