This file is part of the TADS 2 Authors Manual.
Copyright © 1987 - 2002 by Michael J. Roberts. All rights reserved.
Edited by NK Guy, tela design.
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.
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 doesnt 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 youre using. You can then select your game and double-click it.
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.
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.
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 dont 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 compilers -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 wont 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 compilers -tf option, and the -ts size option limits the size of the swap file, in the same way as the compilers -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.
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 youre 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 havent 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 games 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 programmers 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 youre 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 havent done anything to TADS that changes its behavior with existing games.
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 youve 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 youre 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 wont use any low-level I/O functions, such as BIOS or memory-mapped video, but goes entirely through DOS. The runtime also wont display the status line or any highlighting. If you have a special need for DOS-only I/O (for example, if youre 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 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 runtimes 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 youve 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.
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 youll be uploading your game to the Internet or BBSs 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, theyll 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 wont 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 youll 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 wont 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 youve 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 games .EXE file. This is very important for large games, which may not be playable using the runtimes 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 elses system. For example, if you specify the swap file as D:\SWAP.DAT, then the game wont work on a system that doesnt have a D drive, since TADS will be unable to create a swap file on a drive that doesnt exist.
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. Its 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 isnt 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 youve 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 dont 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 elses system. For example, if you specify the swap file as Macintosh HD:TADS:swapfile.dat then the game wont work on a system that doesnt have a Macintosh HD drive, since TADS will be unable to create a swap file on a drive that doesnt exist.
Once you create your self-loading game, simply double-click on its icon (from the Finder) to play your game.
Andrew Plotkins MaxTADS interpreter and Stephen Granades 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|