Help Topics > Table of Contents

# TADS Workbench

## Overview

TADS Workbench is an integrated environment for writing TADS games. TADS Workbench lets you run the compiler, resource bundler, executable builder, and debugger, all with simple menu commands, eliminating the need to enter complex command lines to run the compiler and other tools. TADS Workbench also lets you view and edit your source files with a full-featured built-in text editor.

## Starting a New Game

TADS Workbench includes a "Wizard" that creates a starter game for you automatically. All you have to do is answer a few questions to tell TADS where to put your game files. See Creating a New Game for step-by-step instructions.

## Loading an Existing Game

If you've already created your game's source files, you can load the game into TADS Workbench from either the source file or the compiled game file:

- Open TADS Workbench.
- At the "Welcome" dialog, select "Open an Existing Game." (If you've disabled the Welcome dialog, open the "File" menu, then select "Load Game.")
- Select either your game's source file (which usually ends in ".T") or your game's compiled game file (which usually ends in ".GAM").
  - If you select a .GAM file, TADS Workbench will load the game and you'll be ready to start working.
  - If you select a source file, TADS Workbench will ask you to identify the compiled game file. The saved configuration for your game always goes with your compiled game file, not your source file, so TADS Workbench can't identify your game's configuration based on the source file alone.
- If your game doesn't already have a configuration file, TADS Workbench will create one.

## Editing Source Code

Workbench has a built-in text editor that you can use to edit your source code. The integrated editor is a popular programmer's text editor called Scintilla, which has all the features you'd expect from a programmer's editor: multi-level undo, syntax coloring, automatic indenting, and much more.

Remember that when you make changes to your source code, you must always save and compile before the changes will take effect. If you run without recompiling, you'll still be running the old version of your game.

If you prefer to use a separate text editor application to edit your source code, you can use the "External Editor" page of the Options dialog to tell Workbench how to open your editor program. Refer to Using an External Editor for details.

## Searching the Documentation

The Search toolbar lets you search for keywords in the TADS documentation. This works a lot like a Web search - you just type the keywords you want to find and press Return. Workbench will open a window showing the documentation pages that match your search, showing the "best" (most relevant) matches first.

Note that the Search toolbar has a little button next to the search box that lets you change the type of search it performs. Use the drop-down menu to change the search type. Make sure that "Search User's Manuals" is selected when you want to perform a documentation search.

The doc search system has some special syntax that you can use to customize the search. By default, the search system looks for pages that contain every word you enter, allowing for common variations in the words - for example, if you type `operator`, the search will also match variations like operators, operating, operated, and so on.

If you want to look for pages that contain any of several words, you can separate the words with the keyword OR. (The keyword must be entered in all upper case letters.) For example, if you type `operator OR expression`, the search will find pages that contain either of those words (again, including common variations on the words).

You can also exclude words from the search, by preceding each word you want to exclude with the keyword NOT (which must be in all upper case letters). For example, if you type `operator NOT expression`, the search will find pages that contain "operator" (and common variations), and will exclude any pages that also contain "expression" (or variations).

If you want to search for an exact word, without allowing the search system to look for common variations of the word, enclose the word in double quotes. For example, `"operator"` will find only that word, not variations like operators, operated, etc.

You can also use quotes to look for an exact phrase, in cases where you want to find two or more words in a particular order. For example, `"addition operator"` would find only pages containing that exact phrase.

## Searching in Files

Workbench provides several ways to search for text in a file.

The Search bar lets you perform a quick search of the current text editor window. Use the drop-down menu next to the search box to select "Search Current File," then type the text you'd like to find and press Return. Workbench will simply highlight the next instance of the text in the file.

Unlike the Documentation search system, File search does not use the "keyword" search system. So, these searches don't look for variations on the words you type, and they don't allow the OR or NOT keywords or the quoting syntax. Instead, the File search simply looks for the literal text you enter. The search is case-insensitive (meaning that it ignores upper-case and lower-case differences in the text), but otherwise looks for exactly the text you enter.

If you want more File search options, use the Find command on the Edit menu. This lets you perform regular-expression searches (these are like "wildcard" searches, but more powerful - you can use the full TADS 3 regular expression syntax, which you can read about in the TADS 3 manuals if you search for "regular expressions"), case-sensitive matching, and whole-word matching.

## Compiling

TADS Workbench offers a graphical interface to the TADS compiler, resource bundler, and executable builder. To compile your game, first configure your compilation options by opening the "Build" menu and selecting "Settings," then compile by opening the "Build" menu and selecting the appropriate "Compile" command. See Compiling with TADS Workbench for details.

## Debugging

The core of TADS Workbench is the TADS Debugger. After you've compiled your game, you can run it within TADS Workbench by using the "Go" command (on the toolbar or in the "Debug" menu). The Debugger Overview describes the debugger in greater detail.

## Configuration Files (.TDC)

TADS Workbench stores information on your game in a special file called a "configuration file." A configuration file contains information of interest only to TADS Workbench; you don't need to edit this file directly.

Each game has its own separate configuration file, because the information in the file is specific to the game. The configuration file for a game always has the same name as the compiled game file, with the ".GAM" suffix replaced by the ".TDC" suffix, and is always in the same directory as the compiled game file.

The configuration file contains information on the window layout, debugger breakpoints, option settings, and build parameters.

TADS Workbench will always create a new configuration file for you when you open a game that doesn't already have a configuration file. You don't need to do anything special to create or manage configuration files; TADS Workbench handles them automatically without requiring any action on your part.

Note that, when loading a game, you can load the .TDC file or the .GAM file; the two are interchangeable for the purposes of loading a game into TADS Workbench.

Help Topics > Table of Contents
Copyright ©1999, 2007 by Michael J. Roberts.