If you've used past versions of TADS, you are familiar with the command-line tools that TADS uses for building your game: the compiler, the resource bundler, the executable file builder, and the installer maker. Because these tools were operable only from the command line, you had to leave the TADS Debugger environment and open a DOS command shell (a "DOS box") to build your game.
TADS Workbench lets you run all of these tools directly from the graphical Workbench environment, without ever opening a DOS command shell. In addition, TADS Workbench lets you select the numerous options and parameters that the build commands use through dialogs, rather than through command lines.
Before you build your game, you must select your build settings: these settings specify your source files, output files, and build options. Once you specify your settings, TADS Workbench stores them in your game's configuration file (the .TDC file corresponding to your game's compiled .GAM file), then uses these stored settings whenever you build the game. You can of course edit the dialog settings at any time; but in most cases you need only set up the options once, when you first start working on your game, and then forget about them.
Because the build options are stored with your game's configuration, building your game after each change to your source files is extremely simple: just open the "Build" menu and select the appropriate "Compile" command. Unlike the command-line interface to the tools, the TADS Workbench interface does not make you enter all of the build options each time you build; you set your options once, and TADS Workbench remembers them whenever you compile.
To compile your game, you must first configure the build settings for your game. Once you configure the settings, TADS Workbench will remember them in your game's configuration (.TDC) file, so you won't need to enter any settings when you actually compile your game.
There are four ways to compile your game, all accessed using the "Build" menu:
The debug log window will display the build status, including the program command lines and any error messages from the compiler and other tools. The build proceeds in the background, so you can continue with other work while the build is running. If you're compiling the debugging version of your game, you cannot, of course, run the game until the build completes, and you cannot start a new build while another build is running.
The debug log window shows any error messages that the compiler produces as it compiles your source code. If the compiler does find errors, you can jump directly to the line containing the error in your source file by double-clicking on the error message in the debug log window.
Before you build for the first time, you must configure the build settings for your game. Open the "Build" menu, and select "Settings" to open the Build Settings dialog.
The Build Settings dialog is organized into several pages, arranged by function. In most cases, you can use the default settings, but you should scan each page to make sure the settings are suitable for your game.
Source file: This is your game's primary source file. You can organize your game into multiple source files, but you must always designate one source file as the primary source file; your primary source file includes all of the other source files with #include preprocessor directives.
Graphics and sound resource files: List all of the graphics and sound resources that your game uses here. You can include any files here; the multimedia versions of TADS at present support JPEG, PNG, and MNG images; MIDI music; and MP3, WAV, and Ogg Vorbis digitized audio formats. You can also include entire directories here, using the "Add Folder" button. The files you list here are bundled into the Release Game file and the Executable Game application; since the executable game is included in the installer package, the resource files are included there as well.
As an alternative to adding files with the "Add File" or "Add Folder" button, you can drop files directly from a Windows desktop or Explorer window. Navigate using the Windows desktop or Explorer to the folder containing the files or folders you wish to add, then select the files, drag them to the list, and drop the files.
Note: to comply with the resource naming conventions used in the multimedia TADS interpreters, you should always put your resource files in the same directory that contains your Debugging Game file, or in subdirectories thereof. See the suggested directory layout for more information.
Using external resource files: By default, all of the resources you add to the list go under the "Compiled game file (.gam)" tree. All of these resources are added to your .GAM file. You can also create external resource files, allowing you to group resources into different bundles.
External resource files always have the same name as your game file, but the ".gam" suffix is replaced with ".rs0" for the first external resource file, ".rs1" for the second, and so on. To add an external resource file, click the "Add .RSn File" button; this will add the new file after the current selection in the list. To add resources to the file, select it in the list, then add files as normal; each file you add will be placed under the currently selected ".RSn" file in the list.
If you create external resource files, TADS Workbench will automatically build the ".RSn" files when you compile for release, compile an application, or build an installer.
Directories to search for #include files: This is the list of directories that the compiler will search for files included with #include directives. Normally, this list should include the directory that contains your game's source files plus the TADS program directory itself. You should usually include the TADS program directory, because this is where the standard library files (adv.t and std.t) can be found. If you're using any additional or alternative libraries (the WorldClass library, for example), you should add to this list the directory or directories where you've installed those library files.
Cover Art image: This lets you embed a JPEG or PNG image into your compiled game file as "cover art" for use by compatible tools. Some interpreters and browsers can access the embedded image to display when showing a catalog listing for your game. The cover art is meant to be reminiscent of what the retail box would look like if your game were on a store shelf, and the main reason to provide it is that it makes catalog listings for your game more visually appealing. If you provide cover art, it must be a JPEG or PNG image. The recommended size is 960x960 pixels, but any pixel size up to 1200x1200 is acceptable. (The covert art image is part of the cross-platform Babel bibliographic metadata system - refer to the Babel site to learn more.)
EXE file icon: You can specify a Windows Icon (.ICO) file here to use as the desktop icon for your game's executable. This applies when you use the "Compile Windows EXE" or "Compile Windows SETUP" commands to create a Windows EXE version of your game. The file given here should be a standard Windows icon file (.ICO). Since Windows uses a variety of icon sizes in different situations, your icon file should include various sizes in the first icon resource in HTMLTADS.EXE - currently, this means you should provide 32-bit color icons at 48x48, 32x32, 24x24, and 16x16 pixels. Note that you can only replace icon sizes that are already present in the HTMLTADS.EXE desktop icon - any sizes you include in your .ICO file but which aren't present in the HTMLTADS.EXE icon will be ignored.
Debugging game file: This is the compiled game file for debugging purposes. You can't change this setting, because it's always the same as the game file that you currently have loaded. This version of the compiled game contains extra information that the TADS Debugger uses to provide source-level debugging. This file is created whenever you use the "Compile for Debugging" command on the "Build" menu.
Note: the compiler does not bundle graphics and sound resources into the debugging version of the game. This makes it faster to compile the debugging version, since the build process skips the resource bundling step. As a result, all of your resource files must be in the same directory as the debugging game file, so that the interpreter can find the resources as external files at run-time. Refer to resource naming conventions for information on how multimedia versions of TADS find resource files.
Release .GAM file: This is the compiled game file that you can release to players. This version of the game file does not contain any symbolic debugging information, so it cannot be used with the debugger; as a result, it's smaller and runs more quickly than the debugging version. This version includes the resources that you named in the resources list bundled into the file, so that you need only distribute this single file to players; the only other thing needed to play your game is the TADS Interpreter. This file is portable to all platforms that have a TADS Interpreter; you don't need to recompile your game to run it on other types of computers. This version of the file is created whenever you use the "Compile for Release" command on the "Build" menu.
Note: This file must use a different name than the debugging game file, so that you don't overwrite the debugging version with the release version when you build the latter.
Executable file: This is an executable application (.EXE) file that contains your release .GAM file, including the bundled resources, bound together with the HTML TADS Interpreter for Windows. You can distribute this single file to players; nothing else is needed to play your game. You might prefer to distribute this form of your game to players who are using Windows, rather than the release .GAM file, because players won't need to install a separate TADS Interpreter. For players who aren't using Windows, however, you'll want to distribute the release .GAM file, because that file is portable to all platforms with a TADS Interpreter; the executable version only works on Windows machines. To build the executable file, open the "Build" menu and select "Compile Application (.EXE)."
Symbols to #define: This is a list of preprocessor symbols to define when compiling your game. Use the "Add" button to add a new symbol to the list. Each symbol listed here is defined as though you had used a #define preprocessor directive just before the first line of your primary source file.
Symbols to #undef: This is a list of pre-defined preprocessor symbols that you want to undefine. This lets you remove symbols that the compiler normally defines for you. The effect is the same as though you had used an #undef directive just before the first line of your primary source file.
Ignore case: Check this box if you want the compiler to treat upper-case and lower-case letters as equivalent in symbolic names in your source code, such as object, function, property, and local variable names. Normally, the TADS compiler treats upper-case letters as distinct from their lower-case equivalents, so the compiler would treat "fred" and "Fred" as distinct symbols. If you check this box, "fred", "Fred", and "FRED" would all be equivalent.
C-style Operators:: Check this box if you want the compiler to interpret your source code using "=" (a single equals sign) as the assignment operator, and "==" (double equals) as the equality comparison operator. Normally, the compiler interprets "=" as the equality comparison operator, and uses ":=" (colon-equals) as the assignment operator.
Character Mapping File: Check this box and fill in the field if you want to use a character-map file (a .TCP file). The TADS compiler lets you specify a character mapping file to determine how characters in the extended character set (above ASCII 127) will be interpreted at run-time.
Additional command-line options: If you need to specify any command-line options that cannot be specified elsewhere in the dialog box, you can enter the text of the options here. Look here for the full set of compiler options. (In most cases, you won't need to put anything here, since all of the common compiler options are all accessible through the dialog without resorting to typing them in here directly.)
This section lets you specify the configuration for the SETUP program created when you use the "Compile Windows SETUP" command.
Building an installer for your game has several advantages over simply distributing the game executable file or the release .GAM file. Like a game executable, you can distribute the installer as a single, self-contained, stand-alone file, so players won't need to download or install any additional software (in particular, they won't need to install a separate TADS interpreter). Unlike the game executable, you can include additional files, such as a license text file, or a hint file, with the installer; these additional files are bundled into the installer executable, then extracted and installed on the player's computer when the player runs the installer. With the installer version, you can specify a special desktop icon for your game, and the game will be set up in the player's Windows "Start" menu for easy access and better integration into the Windows desktop. Finally, the installer automatically sets up an "uninstall" utility that lets the player easily remove the game when they're finished with it.
To build the installer, after configuring the installer options, open the "Build" menu and select "Compiler Installer."
Setup Program: This is the name of the executable application file that will contain the installer for your game. This will be a self-contained .EXE file that you can distribute to players - this is the only file you need to give them, since it will contain everything needed to install your game.
Installer options: This section lets you customize the installer that Workbench creates for you. This box shows the installer script entries, which are specified as "Name=Value" pairs. You can edit this list manually, but it's a little easier to use the field-by-field Edit dialog, which you can open by clicking the Edit button. The settings in the Edit dialog are:
Display Name: This is the name of your game that is displayed to the player during the installation process.
Saved Game Extension: This is the file suffix that your game's saved position files will use. With the standard TADS Interpreter, the suffix is always "SAV". By using a unique suffix for your game, you'll make it possible for the player to restore a saved position and start the game all at once simply by double-clicking on a saved position file on the Windows desktop. To make this possible, the installer will create a file type association for the suffix you specify, so that the Windows desktop will launch your game's executable when the player double-clicks on one of your game's saved position files.
Default Program Directory: This specifies the default directory in which your game will be installed on the player's computer. Most people use a subdirectory of "C:\Program Files" for the default value here. The player will be able to override this during installation, but you can make installation much easier and faster for most people by suggesting a suitable default here.
Default Start Menu Folder: This specifies the default name of the Windows "Start" menu folder that the installer will create for your game. As with the default program directory, the player can override this during installation, but a good default will make things easier for most people.
License File: You can specify a text file here. The installer will include this file in your installation package, and display the file to the player during the installation process.
Read-Me file: You can specify a text or HTML file here. The installer will include this file in your installation package, and will automatically open this file for the user to view immediately after the user completes the installation process. You can use this file for any notes or information that you want the user to see right after installing your game. In addition to opening this file after the installation is completed, the installer places an icon for this file in the "Start" menu program group that it creates for your game.
Read-Me Title: If you specify a read-me file, you can use this field to enter the title that you want the installer to display in the "Start" menu for the read-me file. If you don't enter this field, but you do specify a read-me file, the installer will use the name of the read-me file (minus its ".txt" or ".htm" suffix) as the menu name.
Adding extra files: The "Edit" dialog doesn't provide a means to add extra files to the installer. If you want to include any extra files (for example, you might want to include a text file with hints, or a PDF file showing a map), you must close the Edit dialog and manually edit the Installer Options text box. For each extra file, add an extra line in the Installer Options text box, using this format:
FILE=file_to_add
Include the full path to each file. Note that the order of the lines in the Installer Options box doesn't matter, so you can add your FILE=xxx lines at the beginning or end of the list. Just make sure that each option is on a separate line.
Specifying the desktop icon: You set set the desktop icon for your game's program file in the Files/Special section of the Project & Build Settings dialog. (This option is on the separate Special page of the dialog because it also applies to the "Build Windows EXE" command. The same icon is used for the EXE build and for the SETUP build.)
You can arrange your source files and compiled game files into any set of directories that suit your working style. We have some guidelines, however, that you might wish to consider:
The easiest way to conform to these guidelines is simply to put all of your files (sources, resources, and compiled games) into a single directory, separate from the TADS program directory. However, some people prefer to organize their files into subdirectories to make them easier to manage; so, we offer this suggested directory layout:
TADS program directory:
C:\Program Files\TADS ToolkitMain game directory:
C:\Games\MyGameSource file directory:
C:\Games\MyGame\sourceCompiled game directory:
C:\Games\MyGame\GAMImage resources (JPEG, PNG, and MNG files):
C:\Games\MyGame\GAM\imagesSound resources (MIDI, WAV, MP3, and Ogg Vorbis files):
C:\Games\MyGame\GAM\sounds