Welcome to the TADS 3 System Manual!

TADS 3 is a programming language specially designed for creating Interactive Fiction. Since you're reading this book, it's probably safe to assume you already know a little about IF, so we won't spend time on that here. If you're looking for an introduction to IF in general, or TADS in particular, you might find it helpful to visit the TADS Web site,

The whole of TADS 3 encompasses a lot of pieces: a programming language, a compiler for the language, a byte-code interpreter that executes the programs produced by the compiler, two distinct user interfaces (one graphical, one purely textual), and a large body of standard "library" code (written in the TADS 3 language) that programmers can incorporate into their own programs. And properly speaking, there's not even just one library: there's a "system library," which provides the basic, low-level definitions that virtually every program needs, such as starting up, shutting down, and handling errors; and the "adventure game library," which provides a comprehensive framework for building the classic style of interactive text adventure.

This manual doesn't cover the whole of TADS 3. Instead, our scope here is the "system" portion - that is, the core programming system, apart from the adventure game library. Our particular focus is the TADS 3 programming language, but we also cover the tool set (the compiler, the resource bundler, the interpreter, and so on), the intrinsic (that is, built-in) functions and types, the low-level system library, and the user interface.

The main thing this manual doesn't address is the standard adventure game library, also known as "adv3." This might seem a bit strange: after all, from the perspective of someone writing IF, the library is by far the most important piece - in fact, it can seem like practically the only piece, and everything else just so many mundane details. But the TADS 3 programming language ultimately underlies everything - your game code, as well as the library itself, are all written in it - so the finer points of how the language works, while mundane, are sometimes important. This manual exists to help at those times.

Because of the nature of the material, this manual is organized as a reference. It covers the language and other system components detail by detail, to make it easy to find the full story on something when you have a particular question you need to answer.

TADS 3 vs. TADS 2

TADS has been around in one form or another for many years. The previous version, TADS 2, was first released in 1992 and has been actively supported ever since. Over that time, about 200 games written with TADS 2 have been publicly released.

TADS 2 and TADS 3 share a name, but TADS 3 isn't just a revision of TADS 2. It was built from the ground up as a completely new system. In fact, games written with TADS 2 can't be easily transferred to TADS 3, since there are some substantial differences in the language, and major changes to the adventure game framework (the "library").

Notes for TADS 2 Users

Throughout this manual, you'll find notes like this, written to help alert TADS 2 users to differences in the new system. If you're already an expert with TADS 2, you'll find these sections helpful in finding your way around the new system. A lot about the language will be familiar to you from the old version, but there are many important changes.

Our first bit of advice to TADS 2 users is this: if you already have a project under way with TADS 2, we recommend that you keep using TADS 2 for that project, since it's not straightforward to move your existing code to the new system. The time to switch to TADS 3 is when you're ready to start a new project.

There are a lot of big changes between TADS 2 and TADS 3. The basic look of the programming language hasn't changed much - both versions closely resemble C and Java - but TADS 3 has many new language elements that weren't present in TADS 2, and some of the old syntax is no longer valid. Even so, if you know the TADS 2 language, you'll find the new language very easy to pick up, since it's so similar. After you get past the initial work of learning the changes, we think you'll be happy with the new language - it's much more powerful and internally consistent than the TADS 2 language, and makes many things easier and faster to write.

The biggest differences between the systems are in the library. We completely rethought the parser and the way it interfaces with the world model to analyze and execute commands. What's more, the parser is actually part of the library itself now - in TADS 2, it was built into the interpreter, which made it impossible to customize anything that wasn't specifically exposed as a "hook" for overriding. With the parser moved into the library, you can modify anything and everything - you can even replace the entire thing with your own parser if you want.


A great many people contributed to TADS 3. I'd like to thank Neil K. Guy, Stephen Granade, Kevin Forchione, TenthStone, Adam J. Thornton, Suzanne Britton, Iain Merrick, Andrew Pontious, Dan Shiovitz, Jesse Welton, Frantisek Fuka, Sean T. Barrett, Phil Lewis, Dan Schmidt, BrenBarn, Steve Breslin, Michel Nizette, Nikos Chantziaras, Guilherme De Sousa, João Mendes, Eric Eve, M. D. Dollahite, M. Uli Kusterer, Søren J. Løvborg, and Marnie Parker for their advice and ideas, and their help testing the system, and for putting up for so long with beta software.

Special thanks to Nikos Chantziaras for QTads and FrobTADS, and generally keeping TADS alive and healthy on Unix; M. D. Dollahite for creating the very nice suite of icons for the Windows version; and to Iain Merrick, Andrew Pontious, and Chris Nebel for HyperTADS.

I owe an enormous debt of gratitude to Eric Eve for his tireless efforts to document TADS 3. Eric's Getting Started Guide, Tour Guide, and Learning TADS 3 books comprise a better TADS 3 manual than I could have written. I'm especially grateful that Eric has so graciously allowed me to include his books in the official doc set, and for his enthusiastic help integrating it all.

I'm undoubtedly leaving out others who should be included here. I hope you'll forgive me for the oversight, and I thank you all.

Palo Alto, California
September, 2006