# Introduction

Welcome to the Adv3 Version of the TADS 3 Technical Manual!

This book is a collection of technical articles about different aspects of TADS 3/Adv3Lite. The topics here overlap somewhat with the Adv3Lite Library Manual, the System Manual, and the Library Reference Manual, but our thrust here a bit different: here, we try to provide practical "how to" information, like a tutorial, but at the same time to explore the details in depth, like reference material. Hopefully, the result is the best of both worlds rather than the opposite.

The articles here are mostly self-contained, each covering a single topic in depth, so you can approach this material in any order you like. If you're just learning TADS 3/Adv3Lite, though, we recommend reading the Adv3Lite Quick Start Guide and either the Adv3Lite Tutorial or Learning TADS 3 with Adv3Lite first - the articles in the Technical Manual assume a degree of familiarity with the system, and these other guides should help greatly with that.

We've organized the material here into three sections. "Fundamentals" covers the core topics that most people using TADS 3/Adv3Lite will encounter in everyday use. "Adv3Lite In Depth" includes material that authors will find useful as they tackle particular game-development challenges; read these articles as you encounter the relevant areas in your design work. "Advanced Topics" will be especially useful to authors who want to really customize the system, and should be interesting to anyone who wants to know exactly how things work inside the library.

Many of the articles here have been previously published. Some appeared in the Technical Articles section on tads.org, and some were adapted from earlier documentation (particularly the TADS 2 Author's Manual). We've gathered them here in an effort to offer "one-stop shopping" for TADS 3 documentation.

Several of the articles herein were generously contributed by TADS users. Many thanks to Mike Roberts, Steve Breslin, Michel Nizette, and Andreas Sewe for taking the time to share their expertise and for allowing MJR to include their work in this original version of collection. Articles not explicitly attributed to anyone else were written by Mike Roberts.

One of the reasons for this manual's rather ad hoc organization is that it's designed to be a living, growing collection. It would be good to continue adding new material over time, especially in-depth "how to" articles. I'm interested in hearing your ideas for new topics that should be covered. And if you've struggled to overcome missing documentation to figure out for yourself how some part of the system works, I'd be especially grateful if you'd consider contributing an article on the subject for a future edition. A good place to offer your suggestions and contributions would be the TADS discussion forum on intfiction.org.

## A Note on Adapting the Technical Manual for Adv3Lite

The main challenges facing the adaptation of this Technical Manual for Adv3Lite have been (1) that much of its material is more closely paralleled in the Adv3Lite Library Manual than was the case for anything the original Technical Manual paralled, since there was no adv3 Library Manual equivalent; and (2) that much of the material in the original Technical Manual was specific to adv3 having been written and assembled before adv3Lite was ever even conceived. The approach taken here has been to preserve as much as possible, even at the risk of some duplication while removing information that has no applicability to adv3Lite and otherwise to adapt articles originally written for adv3 to adv3Lite wherever feasible. Sometimes the similarities between adv3 and adv3Lite have made the adaptations quite straightforward; sometimes the differences have necessitated more extensive re-writing. In each case where I have adapted another author's work (and occasionally my own), I have noted the fact at the start of the article and provided a short note about the manner and the extent of the adaptation.

The articles not carried over from the original Technical Manual are:

- "Lists and Listers": The original version was written by me, and had I adapted it for adv3Lite it would have ended up simply duplicating the identically named chapter in the Library Manual.
- "Banishing (and Changing) Awkward Messages": Most of the problems this article addresses don't really exit in adv3Lite, or at least not in the same way, and any adv3Lite-relevant material is mostly covered elsewhere.
- "Manipulating the Transcript": Adv3Lite doesn't use a transcript, so this article would have no relevance to adv3Lite.
- "Handling odd Noun Phrases": The way the adv3Lite vocab property works means that the issues addressed in this article aren't issues for adv3Lite.
- "Global Command Remapping": This is another feature not present in adv3Lite. The problem it is designed to solve in adv3 would probably be addressed in adv3Lite using Doers.

On the other hand, this edition of the Technical Manual adds a couple of new articles that weren't in the original adv3 version:

- "Customising (and Using) Existing Actions": This contains advice that may be helpful for any TADS 3 author but leans towards the adv3Lite preference for using object properties rather than modifying code wherever possible.
- "Handling TIActions with Multi-Methods": This relates to a feature of the adv3Lite library that was new at the time of writing. It would seem to belong in the "advanced" category and a detailed account of it to fit the Technical Manual better than the Library Manual.

Finally, the artice previously called "Where Mesages Come From" has not only been reworked for adv3Lite but renamed "Analysis of a Transcript", since this seems to me to be a slightly better indication of what it does (if any one can come up with a better name for it, do please let me know). This article gives the transcript of a short adv3Lite game with various parser responses linked to an explanation of where and how they are produced, which in turn link into the relevant sections of a complete listing of the adv3Lite code for game. This could be a valuable resource both for authors relatively new to TADS 3/Adv3Lite as an introduction to how the system works, and as a reference for more experienced authors interested in addressing specific problems.

I hope that where I have adapted other people's work, enough of their original voice and approach survives to give readers a valuably different perspective on material I may have covered elsewhere.

— | Eric Eve
| Oxford, England
| February, 2025

## MJR's Original Introduction

Welcome to the TADS 3 Technical Manual!

This book is a collection of technical articles about different aspects of TADS 3. The topics here overlap somewhat with Getting Started in TADS 3, the System Manual, and the Library Reference Manual, but our thrust here a bit different: here, we try to provide practical "how to" information, like a tutorial, but at the same time to explore the details in depth, like reference material. Hopefully, the result is the best of both worlds rather than the opposite.

The articles here are mostly self-contained, each covering a single topic in depth, so you can approach this material in any order you like. If you're just learning TADS 3, though, we recommend reading Getting Started in TADS 3 first - the articles in the Technical Manual assume a degree of familiarity with the system, and the Getting Started guide should help greatly with that.

We've organized the material here into three sections. "Fundamentals" covers the core topics that most people using TADS 3 will encounter in everyday use. "TADS 3 In Depth" includes material that authors will find useful as they tackle particular game-development challenges; read these articles as you encounter the relevant areas in your design work. "Advanced Topics" will be especially useful to authors who want to really customize the system, and should be interesting to anyone who wants to know exactly how things work inside the library.

Many of the articles here have been previously published. Some appeared in the Technical Articles section on tads.org, and some were adapted from earlier documentation (particularly the TADS 2 Author's Manual). We've gathered them here in an effort to offer "one-stop shopping" for TADS 3 documentation.

Several of the articles herein were generously contributed by TADS users. Many thanks to Steve Breslin, Eric Eve, Michel Nizette, and Andreas Sewe for taking the time to share their expertise and for allowing me to include their work in this collection.

One of the reasons for this manual's rather ad hoc organization is that it's designed to be a living, growing collection. I plan to continue adding new material over time, especially in-depth "how to" articles. I'm interested in hearing your ideas for new topics that should be covered. And if you've struggled to overcome missing documentation to figure out for yourself how some part of the system works, I'd be especially grateful if you'd consider contributing an article on the subject for a future edition. To facilitate user participation, I've set up a page on tads.org with a "wish list" of new articles for future editions: http://www.tads.org/t3techlist.htm.

— | MJR
| Palo Alto, California
| September, 2006

TADS 3 Technical Manual
Table of Contents | Introduction
Next: Fundamentals