TADS 3 Quick Start Guide

Welcome to TADS 3! This Quick Start Guide is designed to get you up and running as quickly as possible. It contains three sections:

  1. Instructions on installing the system and creating and compiling a minimal game (as a basis for further work).
  2. A guide to the other documentation to help you choose which manual to look at first and which you can leave till later.
  3. Instructions on creating a sample game for people who want to leap right in and try out something hands-on before starting to read the other manuals.

Enjoy!

1. Installing TADS 3 and Creating a Project

1a. Windows Users: Installing and Creating a Project in Windows Workbench

  1. If you're using Windows, there's almost nothing to installing TADS 3 — just download the TADS 3 Author's Kit, which consists of a single .EXE file that installs everything. Open the installer executable (by double-clicking on it from wherever you downloaded it to), and step through the install screens. Everything should be self-explanatory. When the install is finished, you're all set.
  2. If you're using Windows, run TADS 3 Workbench (by selecting it from the "Start" menu group you selected during the installation process).
  3. By default, Workbench will show you a "welcome" dialog asking you if you want to open an existing game or create a new one. Click on the button for creating a new game.
  4. If you've turned off the "welcome" dialog, then select "New Project" from the Workbench "File" menu.
  5. In either case, this will display the New Project Wizard. Just step through the wizard screens to tell Workbench the name and location for your new project files. Workbench will automatically create all of the necessary files for your project, and it'll even compile it for you right away.

The steps you’d typically follow once the wizard is launched would be:

  1. Click the ‘Browse’ button on the first page of the Wizard.
  2. Use the file dialog that appears to create a new folder (e.g. ‘MyNewGame’) in a TADS 3 folder in your My Documents folder.
  3. Navigate to the new directory you have just created and enter a filename for your new game (e.g. ‘MyNewGame’) into the File Name field of the dialog, and then click the ‘Save’ button.
  4. Click the ‘Next’ button on the wizard.
  5. Click the ‘Next’ button again. On the next page of the wizard select the ‘Advanced’ radio button (for the purposes of this Guide you don’t want the ‘Introductory’ option).
  6. Click the ‘Next’ button again. On the next page of the wizard leave the ‘Standard’ radio button selected (the WebUI is a topic beyond the scope of this Guide).
  7. Fill in the four fields on the next page of the Wizard. Under ‘Story Title’ put the full name of your game (‘My New Game’ or whatever you want to call it; later on in this Guide it will be ‘The Best Burglar’ for example). Then fill in the next two fields with your own name and email address. The final field can be used to give a brief description of the game (e.g. ‘This is simply a tutorial game I’m using to learn TADS 3 with’).
  8. Click ‘Next’ and then click ‘Finish’.
  9. Wait until TADS 3 Workbench has finished created and compiling the new skeleton game (you should see a message saying ‘Build successfully completed' followed by the date and time). In the left-hand pane of Workbench (headed ‘Project’) look for the section (near the top) that says ‘Source Files’ and double-click on the icon representing the file you asked the Wizard to create at Step 3 above (e.g. ‘MyNewGame.t’); it should be the third one down. You will then see your new game source file open in the Workbench editing window.
  10. To compile the project again when you’ve made changes to it, just press the F7 key. (You can also select the "Compile for Debugging" command on the "Build" menu, or click the equivalent toolbar button.)

1b. Installing the Compiler and Creating a Project Manually (for non-Windows Users)

If you're not using Workbench (which at this stage should only be because you're not using Windows), you'll have to create your project files manually. Fortunately, this isn't very hard - you just need to create two files and one subdirectory.

Jim Aikin suggests the following steps for setting up TADS 3 and creating a project on a Macintosh (these should also work for other non-Windows systems with a little adaptation):

  1. Download FrobTADS, double-click on the .dmg file, and run the installer.

  2. Create a directory to hold your projects, and a subdirectory within it to hold your first project. For example, in Documents, create TADS. In TADS, create a MyGame folder.

  3. In the folder for your first project, create a folder called obj. This will hold the object files created by the compiler while it's running. You won't need to be concerned about anything in this folder; it will take care of itself.

  4. Using a text editor (not a word processor), create a .t3m file. For convenience, give the .t3m file the same name as the project, perhaps MyGame.t3m. Copy the following text into your new .t3m file and save the file to the project folder:
    
         -D LANGUAGE=en_us
         -D MESSAGESTYLE=neu
         -Fy obj -Fo obj
         -o MyGame.t3
         -lib system
         -lib adv3/adv3
         -source MyGame
    
    Replace "MyGame" in the code above with the name of your actual game, if it's different.

  5. Open a Terminal window. The Terminal program is located in Applications > Utilities. You may want to make an alias for it and drag it into your Dock.

  6. Create a starter game file, again as a text file, and save it to the MyGame directory. Your starter game should look more or less like this:
    
         #include <adv3.h>
         #include <en_us.h>
    
         gameMain: GameMainDef
           initialPlayerChar = me
         ;
    
         versionInfo: GameID
           name = 'My First Game'
           byline = 'by Bob Author'
           authorEmail = 'Bob Author <bob@myisp.com>'
           desc = 'This is an example of how to start a new game project. '
           version = '1'
           IFID = 'b8563851-6257-77c3-04ee-278ceaeb48ac'
         ;
    
         firstRoom: Room 'Starting Room'
           "This is the boring starting room."
         ;
    
         +me: Actor
         ; 
    
    Fill in those quoted parts under the line reading "versionInfo:GameID" with your own information. Everything should beself-explanatory, except that last line that starts "IFID =". That long, random-looking string of letters and numbers is exactly what it appears to be - a long, random string of letters and numbers. Well, almost: it's actually composed of random "hexadecimal", or base-16, digits, i.e. 0 to 9 plus A to F. The purpose of this random number is to serve as a unique identifier for your game when you upload it to the IF Archive. The format is important, but the individual digits should simply be chosen randomly. For your convenience, tads.org provides an on-line IFID generator at
    http://www.tads.org/ifidgen/ifidgen.

  7. In the Terminal, use the cd (change directory) command to navigate to the folder where your game files are stored. For instance, you might type 'cd Documents/TADS/MyGame' and then hit Return.

  8. While the Terminal is logged into this directory, you can compile your game using this command:
         t3make -d -f MyGame
    
    If all goes well, you should see a string of messages in the Terminal window, and a new file (MyGame.t3) will appear in the MyGame directory. This is your compiled game file. If you've installed an interpreter program that can run TADS games, you'll be able to double-click the .t3 file and launch the game to test your work.

    Alternatively, you can run the game directly in the Terminal by typing 'frob MyGame.t3' and hitting Return.

  9. Instead of typing the t3make command every time you want to compile your game, you can create a .command file in your project folder and then double-click this file. Double-clicking the .command file will launch Terminal and pass the text in the .command file to Terminal.

    However, when you try this, the Macintosh is quite likely to object that you don't have permission to execute the .command file. There seems to be no way to fix this using the Info box (which is opened using Cmd-I). You'll have to do it from the Terminal. Navigate, as before, to the directory where your .command file is located, and type this into the Terminal:
         chmod +x MyGame.command
    
    Again, substitute the name of your actual .command file. The chmod instruction with a +x flag will make the .command file executable. Now you can double-click it to compile your game, but only if Terminal is already logged into the game's directory. If no Terminal window is open, that won't be the case. To remedy this problem, add a cd line to the beginning of the .command file, so that the .command file looks something like this (substituting the name of your directory and game file):
         cd Documents/TADS/MyGame
         t3make -d -f MyGame
    

1c. Running Your Game

If you're running Workbench, once again, this is easy - press the F5 key (or select the "Go" command on the "Debug" menu, or click the equivalent toolbar button).

If you're not running Workbench, at your system command prompt, type

   t3run mygame

But you should check the README file that came with your system's download package - the program name might not be the same everywhere.

2. Where to Go Next: Navigating the Documentation

TADS 3 comes with a number of different guides and manuals. Which of them should you start with?

The first thing to be aware of is that three of the manuals are intended as tutorials (for use when learning TADS 3) and three are intended for reference (for use when writing your own games once you've mastered the most common features of TADS 3). There is overlap between the contents of these two groups of manuals, since you may well want to use the reference material to remind you of material you first encountered in a tutorial, but they have quite different functions.

The three tutorial manuals are Getting Started in TADS 3, Learning TADS 3 , and TADS 3 Tour Guide. Only the first two of these are intended as introductory; the TADS 3 Tour Guide is primarily intended as a follow-on to Getting Started in TADS 3 for people who want further tutorial material. So your choice of an introductory tutorial is between Getting Started in TADS 3 and Learning TADS 3. So why are there two introductory tutorials and which of them should you choose?

There are two because people have different learning styles and different needs and come to a system like TADS 3 from different backgrounds and with different previous knowledge and experience. Different people will therefore benefit from different approaches.

For most new users the answer to the question "Where do I go next?" is either Getting Started in TADS 3 or Learning TADS 3. If you're still unsure which to start off with, take a quick look (by skimming) through the first couple of chapters of each and then choose the one you feel more comfortable with.

2a. The Getting Started Guide

Getting Started in TADS 3 walks you through the creation of two TADS 3 games (one very short, one quite a bit bigger), explaining features of the system as it goes along but not presenting them in a particularly systematic fashion (the order of presentation is dictated by the order in which the games are developed). Completing the Getting Started tutorial will introduce you to the process of writing Interactive Fiction in TADS 3 and in doing so will introduce you to many of the features of the system, but not in a very systematic fashion. It is the manual you should begin with if you prefer a hands-on, inductive learning style or if you feel more comfortable being walked through the creation of a couple of games before trying to branch out on your own.

2b. Learning TADS 3

Learning TADS 3, on the other hand, takes a far more systematic approach, and aims to introduce you to all the most commonly-used features of TADS 3. It makes no attempt to walk you through the creation of a game, although it does provide a number of exercises you can try out for yourself (in the form of descriptions of mini-games you can try to write together with heavily-commented sample code you can download to compare with your efforts). This might be the tutorial manual you would choose to begin with if you're reasonably confident about programming or writing Interactive Fiction in another system and you want to see how it's done in TADS 3, or if you prefer to be introduced to the material in an orderly, systematic fashion and you don't particularly need or want to be hand-held through the creation of a couple of tutorial games.

2c. The Tour Guide

The TADS 3 Tour Guide was originally intended as a sequel to Getting Started in TADS 3 for people who want a more systematic and comprehensive tour of the TADS 3 library than Getting Started in TADS 3 gives them, though it could also be used as a sequel to Learning TADS 3 for someone who wants to work through a substantial tutorial game after mastering (or at least, being introduced to) the principal features of TADS 3 introduced in Learning TADS 3. The TADS 3 Tour Guide is not intended as an introductory tutorial nor is it primarily intended as a reference manual (the TADS 3 Library Reference Manual provides the definitive reference to the TADS 3 Library). What the Tour Guide does is to walk you through the creation of a (fairly substantial) game, introducing nearly all the main TADS 3 library features in a reasonably systematic fashion. Many TADS 3 users have found the Tour Guide helpful, but you don't have to use it if you don't want to. You may prefer to try to strike out on your own and start working on your own game once you've completed either Getting Started in TADS 3 or Learning TADS 3. You could then come back to the Tour Guide only if and when you felt a further tutorial might be helpful.

2d. The Reference Manuals

The three reference manuals are the TADS 3 System Manual, the TADS 3 Technical Manual and the TADS 3 Library Reference Manual. These are the three manuals you will probably find yourself consulting most frequently once you have mastered the basics of TADS 3 from one or more of the tutorial manuals and are writing your own game(s), but for most people, they are not the best place to start.

That said, the TADS 3 System Manual does contain a lot of material that might be of interest to confident beginners with a strong programming background (whether professional, amateur or hobbyist) who want to see how things are done in TADS 3, and the earlier sections of the TADS 3 Technical Manual do contain a number of "how-to" articles that might be of interest to beginners. Nevertheless, for most new users of TADS 3 these two reference manuals will not be the best place to start; for one thing in addition to the more basic information they cover, they both contain quite a bit of more advanced and complex information that is likely to be not only unnecessary but also potentially quite confusing to new users of TADS 3; for another while the Technical Manual contains a lot of useful how-to information, it is anything but systematic or comprehensive in the topics it covers, and is much more useful as a reference for reasonably experienced users than as an introduction. You will also find the TADS 3 Library Reference Manual an absolutely essential tool once you start working on your own games, and Learning TADS 3 will introduce you to its use, but it's certainly not the place to begin. Please be assured that you absolutely do not have to master the material in these three reference manuals in order to start using (or even continue using) TADS 3, although you will eventually find them helpful when you want to achieve something beyond the basics.

2e. Using the Library Reference Manual

When you first gaze upon the TADS 3 Library Reference Manual (LRM), it may appear to be an impenetrable tangle, but in fact it's an extremely useful resource. To use it, you need to be aware of the following basic ideas:

3. Jumping Right In: A Sample Game

The sensible and logical thing to do at this point would be to start reading one of the manuals suggested immediately above and, frankly, that's what we recommend. But maybe you're thinking that having got as far as installing TADS 3 and being shown how to compile a minimal game, you'd like to actually try doing something with the system before reading a whole lot of text. So, if you're the sort of person that wants to jump right in, you might want to try entering and compiling the sample game shown below. Few explanations are given — that's what the manuals are for, after all — mainly just the source code which you can either copy and paste into the Workbench editor (if you're using Windows) or whatever other text editor/programming editor you're using (if you're not on Windows) and then try compiling and running it.

If you do decide to type the code rather than copying and pasting, be very careful to copy it exactly. (However, feel free to ignore the comments in the code when retyping it. The comments are bracketed by the symbols /* and */, and are included here to give you a better idea what you're seeing.) TADS 3 isn't too fussy about the amount of white space you use or where you put line breaks, but it can be very fussy about other things, and even the tiniest error can confuse it. In particular:

The sample game given below is given in three versions, each fuller and more sophisticated than the last, so you can start from something very simple and see how it might be built up into something more complex. Don't worry if you don't understand too much of what's going on — at this point you can hardly expect to, after all — just try copying and compiling the code and then playing the resulting game to see what happens. You may learn something from this approach, and you should at least start to get some kind of feel for what writing a TADS 3 game looks like. If you find at any stage that this approach is simply confusing and frustrating, then give it up and go and start reading Getting Started in TADS 3 or Learning TADS 3 instead. But if you feel you're beginning to deduce how at least some of it works, then feel free to experiment (but don't try anything too ambitious, you're probably not ready for it yet).

I repeat, there is absolutely no need to carry out any of this exercise at all; it's simply provided for people who are anxious to dive straight in and try something practical before turning to the manuals. For some people this approach may be helpful (as a kind of inductive learning which will then help make the manuals make more sense); for many others it probably won't help at all.

Version 1

The plot of the game (such as it is) consists of the player character entering a house, stealing the Orb of Ultimate Satisfaction, and then escaping with it. We start with an absolutely basic bare bones implementation.


#charset "us-ascii"
#include <adv3.h>
#include <en_us.h>

/* The header, shown above, tells TADS to include some essential files. */

versionInfo: GameID
    IFID = '558c20af-6559-477a-9f98-b7b4274cd304'
    name = 'The Best Burglar'
    byline = 'by Eric Eve'
    htmlByline = 'by <a href="mailto:eric.eve@hmc.ox.ac.uk">
                  Eric Eve</a>'
    version = '1'
    authorEmail = 'Eric Eve <eric.eve@hmc.ox.ac.uk>'
    desc = 'You are the world\'s best burglar faced with the greatest challenge
        of your felonious career.'
    htmlDesc = 'You are the world\'s best burglar faced with the greatest
        challenge of your felonious career.'
;

/* Notice that each object definition, including versionInfo, ends with a semicolon. */

gameMain: GameMainDef
    /* The initial player character is an object called 'me', which will be defined shortly. */
    initialPlayerChar = me
;

/* Objects in the game are created by giving the object a name that can be referred to in
   your game code, then by stating what class the object is (in the case below, it's an
   OutdoorRoom), and then giving it a name that will be displayed when the game is running. */

startRoom: OutdoorRoom 'Driveway'
    "The great house stands before you to the north. "
    north = hallway
    
    roomAfterAction()
    {
        if(orb.isIn(me))
        {
            "Congratulations! You have just got away with the Orb of Ultimate
            Satisfaction! ";
            finishGameMsg(ftVictory, [finishOptionUndo]);
        }
    }
;

/* The plus sign on the first line of an object declaration tells TADS that this object
   will be located inside of the previous object. */

+ me: Actor
;

/* Another room. Notice how the exits from the room are listed. The text in
   double-quotes is the description of the room, and will be displayed when the player
   enters the room or types 'look'. Notice also that text in TADS generally ends with
   a space after the final period and before the closing quotation mark. */

hallway: Room 'Hallway'
    "This hall is pretty bare, but there are exits to west and south. "
    south = startRoom
    west = study
;

study: Room 'Study'
    "This study is much as you would expect. A desk stands in the middle of the
    room. The way out is to the east. "
    east = hallway
;

/* The desk object has two single-quoted strings in its declaration. The first creates
   some vocabulary words that the player can use to refer to the desk. The second is how
   the game will refer to it when assembling text to show to the player. */

+ desk: Heavy, Platform 'plain wooden desk' 'desk'
    "It's a plain wooden desk; nothing fancy, just a horizontal surface on legs
    but no drawers or anything like that. "    
;

/* Notice that the orb is defined starting with TWO + signs. This will cause it to show
   up on the desk.
*/

++ orb: Thing 'ultimate orb/satisfaction' 'Orb of Ultimate Satisfaction'
    "It's -- well how can you describe such a thing? -- it's simply the most
    valuable and desirable object in the known universe!"
;

The particular points to note here are the way rooms and other objects are defined, and the way the + sign is used to locate some objects inside others (such as rooms). Note also how the direction properties of rooms (north, south, east, west) are used to provide the interconnections between rooms. If you feel you can deduce how it's done, you could try adding other basic objects and more rooms, with connections between them, but if you don't feel confident about experimenting, then by all means leave it and go on to the next version.

Version 2

The first version wasn't much of a game. In the second we'll complicate things a little by putting the orb in a locked safe to which the player has to find the combination, and we'll provide the house with a locked front door. While we're at it, we'll also define an object to represent the house from the outside. We'll put the combination in a notebook in a locked desk drawer, which means adding a drawer to the desk and providing a key for it somewhere; we'll hide it in a vase in the hall. We'll also make the hall look a bit more like it belongs in a big house by adding a couple of fake exits that don't go anywhere but look as if they do. And, of course, we need a key to the front door which for now we'll just leave lying around in the drive. Finally, we'll provide a proper introduction to the game and make it so that the game ends (either in success or failure) when the player tries to return to the road.

Once again, if you want to try this version out be very careful to copy everything exactly, or it probably won't work. If you already have some experienced with programming, especially in another IF authoring system, you may be able to work out at least some of what's going on in the code below, but if it totally baffles you it may be time to start reaching for the manuals!


#charset "us-ascii"
#include <adv3.h>
#include <en_us.h>

versionInfo: GameID
    IFID = '558c20af-6559-477a-9f98-b7b4274cd304'
    name = 'The Best Burglar'
    byline = 'by Eric Eve'
    htmlByline = 'by <a href="mailto:eric.eve@hmc.ox.ac.uk">
                  Eric Eve</a>'
    version = '2'
    authorEmail = 'Eric Eve <eric.eve@hmc.ox.ac.uk>'
    desc = 'You are the world\'s best burglar faced with the greatest challenge
        of your felonious career.'
    htmlDesc = 'You are the world\'s best burglar faced with the greatest
        challenge of your felonious career.'
;

gameMain: GameMainDef
    /* the initial player character is 'me' */
    initialPlayerChar = me
    
    showIntro()
    {
        "<b>The Best Burglar</b>\nWell, you've got this far. Now it's just a
        quick nip inside the house and out again carrying the Orb of Ultimate
        Satisfaction, an object that no burglar has ever managed to steal
        before. If you can pull it off you're sure to win the Burglar of the
        Year Award, putting you at the pinnacle of your profession.\b";
    }
;

/* The asExit line in the room below will cause TADS to interpet the command 'in' exactly
   as if the player had typed 'north'. */

startRoom: OutdoorRoom 'Driveway'
    "Here you are in the drive of Number 305 Erehwon Avenue, with the great 
    house you've come to burgle standing just before you to the north. The
    drive back to the road where you left your getaway vehicle runs off
    to the southwest. "
    north = frontDoor
    in asExit(north)
    southwest = drive
;

+ me: Actor
    pcDesc = "You're Alexis Lightfinger, burglar extraordinaire, the most
        professional thief in the known universe; but you're on a job now, so
        you don't have time for the narcissistic indulgence of admiring your own
        appearance. You're far too professional not to have come fully prepared,
        so there's no practical need to look yourself over again. "
;

++ Container 'large white swag bag*bags' 'swag bag'
    "It's a large white bag with <q>SWAG</q> printed on it in very large
    letters. Everyone knows that no real burglar would ever carry such a thing,
    so by carrying it you know no one will take you for a real burglar. Cunning,
    eh? "
;

/* The frontDoor object is in the same location as me and the brassKey. TADS understands
   that doors are usually scenery, so no special effort is needed to prevent the game from
   reporting, "You can see a front door here." */

+ frontDoor: LockableWithKey, Door 'front door*doors' 'front door'
    keyList = [brassKey]
;

+ brassKey: Key 'small brass key*keys' 'small brass key'
    "It's an ordinary enough small brass key. "
    initSpecialDesc = "A small brass key lies on the ground near the door. "
;

/* The next object is an anonymous object. That is, it has no in-code name of its own,
   because the game code never needs to refer to it. The arrow pointing to frontDoor
   tells TADS where to send the player if he should type 'enter the house'. As you can
   see from the description, this object is the exterior of the house. */
   
+ Enterable -> frontDoor 'large tudor house/mansion*houses*buildings' 'house'
    "It's a large Tudor house with mullioned windows. "
;

+ drive: PathPassage 'drive/path' 'drive'
    "The drive leading back to the road runs off to the southwest. "
    
    dobjFor(TravelVia)
    {
        action()
        {
            "You retrace your steps back to the road, where your trusty unmarked
            burglarmobile is still parked, ready for your quick getaway. ";
            
            if(orb.isIn(me))
            {
                "Congratulations! You have got away with the Orb of Ultimate
                Satisfaction, a feat never before performed. As you slip the orb
                onto the back seat of your car and climb into the driver's seat
                you tell yourself that you're now absolutely certain to win
                the Burglar of the Year Award!\b";
                
                finishGameMsg(ftVictory, [finishOptionUndo]);
            }
            else
            {
                "It's a shame you didn't manage to steal the orb, though.
                Without it you'll never win the Burglar of the Year Award
                now.\b";
                
                finishGameMsg(ftFailure, [finishOptionUndo]);
            }
        }
    }
;

hallway: Room 'Hallway'
    "This hall is or grand proportions but pretty bare. The front door lies to
    the south and other exits lead east, north and west. "
    
    south = hallDoor
    out asExit(south)
    west = study
    north: FakeConnector { "You're pretty sure that only leads to the kitchen,
        and you haven't come here to cook a meal. " }
    
    east: DeadEndConnector { 'the living room' "You <<one of>>walk through the
        doorway and find yourself in<<or>>return to<<stopping>> the living room
        where you take <<one of>> a <<or>>another<<stopping>> quick look around,
        but <<one of>><<or>> once again<<stopping>> failing to find anything of
        interest you quickly return to the hall. "}
;

+ hallDoor: Lockable, Door -> frontDoor 'front door*doors' 'front door'
;

+ table: Surface 'small wooden mahogany side table/legs*tables' 'small table'
    "It's a small mahogany table standing on four thin legs. "
    initSpecialDesc = "A small table rests by the east wall. "  
;

++ vase: Container 'cheap china floral vase/pattern' 'vase'
    "It's only a cheap thing, made of china but painted in a tasteless floral
    pattern using far too many primary colours. "    
;

/* An object of the Hidden class will show up only when the player thinks to search its
   container. */
   
+++ silverKey: Hidden, Key 'small silver key*keys' 'small silver key'
;

study: Room 'Study'
    "This study is much as you would expect: somewhat spartan. A desk stands in
    the middle of the room with a chair placed just behind it. The way out is to
    the east. "
    east = hallway
    out asExit(east)
;

+ desk: Heavy, Platform 'plain wooden desk' 'desk'
    "It's a plain wooden desk with a single drawer. "          
;

++ drawer: KeyedContainer, Component '(desk) drawer*drawers' 'drawer'
    "It's an ordinary desk drawer with a small silver lock. "
    keyList = [silverKey]
;

/* The notebook object needs some special code for the command 'open notebook'. The
   dobjFor macro creates some code for the Open action, and the asDobjFor(Read) code
   causes 'open notebook' to have the same result as 'read notebook. */

+++ notebook: Readable 'small bright red notebook/book/cover/pages' 
    'small red notebook'
    "It's a small notebook with a bright red cover. "
    
    readDesc = "You open the notebook and flick through its pages. The only
        thing you find of any interest is a page with 1589 scrawled across it.
        After satisfying yourself that the notebook contains nothing else of
        any potential relevance you snap it shut again. "
    
    dobjFor(Open) asDobjFor(Read)
    cannotCloseMsg = 'It\'s already closed. '
;

+ CustomImmovable, Chair 'red office swivel chair' 'chair'
    "It's a typical office swivel chair, covered in red fabric. "
    cannotTakeMsg = 'You see no reason to burden yourself with such a useless
        object; that would be quite unprofessional. '
;
    
+ safe: CustomFixture, IndirectLockable, OpenableContainer 
    'sturdy steel safe' 'safe'
    "It's a sturdy steel safe with a single dial on its door. "
    specialDesc = "A safe is built into one wall. "
    cannotTakeMsg = 'It's firmly built into the wall; you can't budge it. '
;

++ orb: Thing 'ultimate battered dull metal orb/sphere/ball/satisfaction' 
    'Orb of Ultimate Satisfaction'
    "It doesn't look much be honest, just a battered sphere made of some dull
    metal, but you've been told it's the most valuable and desirable object 
    in the known universe! "
    
    aName = (theName)
;

/* Notice how the double angle brackets are used to let the description of the safe
   refer to the properties of the object. This is an extremely common and useful
   technique in TADS. */

+ safeDial: NumberedDial, CustomFixture 'dial*dials' 'dial'
    "The dial can be turned to any number between <<minSetting>> and
    <<maxSetting>>. It's currently at <<curSetting>>. "
    
    minSetting = 0
    maxSetting = 99
    curSetting = '35'
    
    num1 = 0
    num2 = 0
    correctCombination = 1589
    
    makeSetting(val)
    {
        inherited(val);
        num2 = num1;
        num1 = toInteger(val);
        if(100 * num2 + num1 == correctCombination)
        {
            "You hear a slight <i>click</i> come from the safe door. ";
            safe.makeLocked(nil);
        }
        else if(!safe.isOpen)
            safe.makeLocked(true);
    }
    
    cannotTakeMsg = 'It's firmly attached to the safe. '
;

There are too many new features to discuss in detail here, but one or two of them are worth briefly pointing out. Note how the front door to the house is implemented as two objects, each representing one side of the door, and how they are linked by having one side point to the other (-> frontDoor). Note also how the north and south properties of the driveway and the hall now point to one or other side of the door. You may also have noticed how objects can be defined as belonging to more than one class (e.g. the safeDial immediately above is both a NumberedDial so we can turn it to a particular number and a CustomFixture so we can't pick it up and walk away with it; likewise making the silverKey a Hidden as well as a Key means the player actually has to look inside the vase to find it). You'll probably have worked out that a Surface is something you can put things on and a Container is something you can put things inside. A Platform is something you can stand, sit or lie on as well (we make the desk a Platform because it's presumably big enough and sturdy enough to get on).

At this point you may want to experiment with adding or changing a few things to see how they work, or you may think you've had enough of copying code you don't understand (in which case it's probably time to head for the manuals) or you may want to go on and try out the third and final version of "The Best Burglar".

Version 3

We'll make the third and final version of The Best Burglar just a little more challenging by hiding the front door key under a flowerpot, hiding the safe behind a picture, and making the clue to the combination in the notebook a bit more cryptic. We'll also make the Orb of Ulimate Satisfaction a tad more interesting by making it do something (albeit not that much) when it's rubbed, which means we'll also need to define a new RUB verb. We'll add a few decoration objects to field commands directed at things mentioned in room descriptions and the like, and we'll tidy up a couple of things, by, for example, defining the bulk and bulk capacity of various objects so the player can't put something obviously bigger inside something obviously smaller, and, for example, by preventing the player picking up the hall table when there's something still on it. Finally, we'll add some scoring and hints to the game.


#charset "us-ascii"
#include <adv3.h>
#include <en_us.h>

versionInfo: GameID
    IFID = '558c20af-6559-477a-9f98-b7b4274cd304'
    name = 'The Best Burglar'
    byline = 'by Eric Eve'
    htmlByline = 'by <a href="mailto:eric.eve@hmc.ox.ac.uk">
                  Eric Eve</a>'
    version = '3'
    authorEmail = 'Eric Eve <eric.eve@hmc.ox.ac.uk>'
    desc = 'You are the world\'s best burglar faced with the greatest challenge
        of your felonious career.'
    htmlDesc = 'You are the world\'s best burglar faced with the greatest
        challenge of your felonious career.'
;

gameMain: GameMainDef
    /* the initial player character is 'me' */
    initialPlayerChar = me
    
    showIntro()
    {
        "<b>The Best Burglar</b>\nWell, you've got this far. Now it's just a
        quick nip inside the house and out again carrying the Orb of Ultimate
        Satisfaction, an object that no burglar has ever managed to steal
        before. If you can pull it off you're sure to win the Burglar of the
        Year Award, putting you at the pinnacle of your profession.\b";
    }
    
    showGoodbye()
    {
        "Thanks for playing! ";
    }
;

startRoom: OutdoorRoom 'Driveway'
    "The large red-brick Tudor house stands immediately to the north of this end
    of the driveway, while the drive back to the road where you left your
    getaway vehicle runs off though a belt of trees to the southwest."
    
    roomFirstDesc = "Here you are in the drive of Number 305 Erehwon Avenue,
        with the great house you've come to burgle standing just before you to
        the north. The drive back to the road where you left your getaway
        vehicle runs off though a belt of trees to the southwest."
    
    north = frontDoor
    in asExit(north)
    southwest = drive    
;

+ me: Actor
    pcDesc = "You're Alexis Lightfinger, burglar extraordinaire, the most
        professional thief in the known universe; but you're on a job now, so
        you don't have time for the narcissistic indulgence of admiring your own
        appearance. You're far too professional not to have come fully prepared,
        so there's no practical need to look yourself over again. "
;

++ Container 'large white swag bag*bags' 'swag bag'
    "It's a large white bag with <q>SWAG</q> printed on it in very large
    letters. Everyone knows that no real burglar would ever carry such a thing,
    so by carrying it you know no one will take you for a real burglar. Cunning,
    eh? "
;

+ frontDoor: LockableWithKey, Door 'solid oak front door*doors' 'front door'
    "The lintel above the front door is carved with the date 1589, presumably
    the date the house was built. The door itself is made of solid oak. "
    keyList = [brassKey]
    
    makeOpen(stat)
    {
        inherited(stat);
        if(stat)
            achievement.awardPointsOnce();
    }
    
    achievement: Achievement { +10 "opening the front door" }
        
;

+ flowerPot: ComplexContainer 'terracotta small flower flowerpot/pot*pots' 
    'flower pot'
    "It's a perfectly ordinary small terracota pot, though it looks like no
    one's got round to putting a plant in it yet. "
    subContainer: ComplexComponent, Container { bulkCapacity = 3}
    subUnderside: ComplexComponent, Underside { }
    
    initSpecialDesc = "A small flower pot rests on the ground not far from the
        front door. "
    
    bulk = 3
    bulkCapacity = 3
;

++ brassKey: Hidden, Key 'small brass key*keys' 'small brass key'
    "It's an ordinary enough small brass key. " 
    subLocation = &subUnderside 
;

+ Enterable -> frontDoor 'large red red-brick tudor house/mansion/front
    *houses*buildings' 'house'
    "It's a large red-brick Tudor house with mullioned windows, climbing
    creepers and the date 1589 carved over the door. "
;

++ Component '(door) carved lintel' 'lintel'
    "Its most noteworthy feature is the date 1589 carved into it. "
;

+ Decoration 'mullioned windows' 'windows'
    "They're architecturally attractive, no doubt, but not especially helpful to
    burglars. "
    
    notImportantMsg = 'It\'s a matter of professional pride with you never to
        mess with windows. '
    isPlural = true
;

+ Decoration 'green climbing ivy/creepers/creeper' 'creepers'
    "The front of the house is festooned with green creepers -- ivy, perhaps,
    but botany was never your strong point since in the main plants aren't
    worth burgling. "
    
    notImportantMsg = 'The creepers can\'t help you burgle the house -- they\'re
        certainly not strong enough to climb and they\'re certainly not worth
        stealing -- so you may as well leave them alone. '
    isPlural = true
;

+ drive: PathPassage 'drive/path/avenue' 'drive'
    "The drive leading back to the road runs off through a belt of trees to the
    southwest. "
    
    dobjFor(TravelVia)
    {
        action()
        {
            "You retrace your steps back to the road, where your trusty unmarked
            burglarmobile is still parked, ready for your quick getaway. ";
            
            if(orb.isIn(me))
            {
                "Congratulations! You have got away with the Orb of Ultimate
                Satisfaction, a feat never before performed. As you slip the orb
                onto the back seat of your car and climb into the driver's seat
                you tell yourself that you're now absolutely certain to win
                the Burglar of the Year Award!\b";
                
                achievement.awardPointsOnce();
                
                finishGameMsg(ftVictory, [finishOptionUndo,
                    finishOptionFullScore]);
            }
            else
            {
                "It's a shame you didn't manage to steal the orb, though.
                Without it you'll never win the Burglar of the Year Award
                now.\b";
                
                finishGameMsg(ftFailure, [finishOptionUndo]);
            }
        }
    }
    
    okayRubMsg = 'What -- all of it? That may take a while! '
    achievement: Achievement { +10 "getting away with the orb" }
;

+ Decoration 'belt/trees' 'trees'
    "The trees are in full leaf, which is good, because they hide what you're
    doing from the road. "
    
    notImportantMsg = 'The trees are doing a good job of hiding you from the
        road, so you may as well leave them alone. It\'s not as if they\'re
        something you could steal, after all. '
;
    
hallway: Room 'Hallway'
    "This hall is or grand proportions but pretty bare. The front door lies to
    the south and other exits lead east, north and west. "
    
    south = hallDoor
    out asExit(south)
    west = study
    north: FakeConnector { "You're pretty sure that only leads to the kitchen,
        and you haven't come here to cook a meal. " }
    
    east: DeadEndConnector { 'the living room' "You <<one of>>walk through the
        doorway and find yourself in<<or>>return to<<stopping>> the living room
        where you take <<one of>> a <<or>>another<<stopping>> quick look around,
        but <<one of>><<or>> once again<<stopping>> failing to find anything of
        interest you quickly return to the hall. "}
;

+ hallDoor: Lockable, Door -> frontDoor 'front door*doors' 'front door'
;

+ table:Surface 'small wooden mahogany side table/legs*tables' 'small table'
    "It's a small mahogany table standing on four thin legs. "
    initSpecialDesc = "A small table rests by the east wall. "  
    bulk = 5
    
    dobjFor(Take)
    {
        check()
        {
            if(contents.length > 0)
                failCheck('It\'s probably not a very good idea to try picking
                    up the table while <<contents[1].nameIs>> still on it. ');
        }
    }
;

++ vase: Container 'cheap china floral vase/pattern' 'vase'
    "It's only a cheap thing, made of china but painted in a tasteless floral
    pattern using far too many primary colours. "    

    bulk = 3
    bulkCapacity = 3
;

+++ silverKey: Hidden, Key 'small silver key*keys' 'small silver key'
;

study: Room 'Study'
    "This study is much as you would expect: somewhat spartan. A desk stands in
    the middle of the room with a chair placed just behind it. A <<if
      picture.moved>>safe is built into <<else>> rather bland painting hangs on
    <<end>> the west wall. The way out is to the east. "
    east = hallway
    out asExit(east)
;

+ desk: Heavy, Platform 'plain wooden desk' 'desk'
    "It's a plain wooden desk with a single drawer. "    
    dobjFor(Open) remapTo(Open, drawer)
    dobjFor(Close) remapTo(Close, drawer)
    dobjFor(LookIn) remapTo(LookIn, drawer)
    dobjFor(UnlockWith) remapTo(UnlockWith, drawer, IndirectObject)
    dobjFor(LockWith) remapTo(LockWith, drawer, IndirectObject)
    dobjFor(Lock) remapTo(Lock, drawer)
    dobjFor(Unlock) remapTo(Unlock, drawer)
;

++ drawer: KeyedContainer, Component '(desk) drawer*drawers' 'drawer'
    "It's an ordinary desk drawer with a small silver lock. "
    keyList = [silverKey]
;

+++ notebook: Readable 'small bright red notebook/book/cover/pages' 
    'small red notebook'
    "It's a small notebook with a bright red cover. "
    
    readDesc = "You open the notebook and flick through its pages. The only
        thing you find of any interest is a page with <q>SAFE DATE</q> scrawled
        across it. After satisfying yourself that the notebook contains nothing
        else of any potential relevance you snap it shut again. <.reveal
        safe-date>"
    
    dobjFor(Open) asDobjFor(Read)
    dobjFor(LookIn) asDobjFor(Read)
    
    dobjFor(Read)
    {
        action()
        {
            inherited;
            achievement.awardPointsOnce();
        }
    }
    
    cannotCloseMsg = 'It\'s already closed. '
    achievement: Achievement { +5 "reading the notebook" }
;

+ CustomImmovable, Chair 'red office swivel chair' 'chair'
    "It's a typical office swivel chair, covered in red fabric. "
    
    cannotTakeMsg = 'You see no reason to burden yourself with such a useless
        object; that would be quite unprofessional. '

;
    
+ picture: RoomPartItem, Thing 'rather bland picture/painting/landscape' 
    'picture'
    "It's a landscape, pleasantly executed enough, but of no great distinction
    and definitely not worth the bother of stealing. "
    
    initNominalRoomPartLocation = defaultWestWall
    initSpecialDesc = "A rather bland painting hangs on the west wall. "
    isListed = (moved)
    
    bulk = 8
    
    dobjFor(LookBehind)
    {
        action()
        {
            if(moved)
                inherited;
            else
            {
                safe.discover();
                "Behind the picture is a safe built into the wall. ";
            }
        }
    }
    
    moveInto(newDest)
    {
        if(!safe.discovered)
        {
            "Removing the painting from the wall reveals a safe behind. ";
            safe.discover();
        }
        inherited(newDest);
    }
;

+ safe: RoomPartItem, Hidden, CustomFixture, ComplexContainer 
    'sturdy steel safe' 'safe'
    "It's a sturdy steel safe with a single dial on its door. "
    
    subContainer: ComplexComponent, IndirectLockable, OpenableContainer 
    { 
        bulkCapacity = 5 
        makeOpen(stat)
        {
            inherited(stat);
            if(stat)
                achievement.awardPointsOnce();
        }
        
        achievement: Achievement { +10 "opening the safe" }        
    }
    
    specialDesc = "A safe is built into the west wall. "
    specialNominalRoomPartLocation = defaultWestWall
    cannotTakeMsg = 'It's firmly built into the wall; you can't budge it. '
    
    discover()
    {
        if(!discovered)
        {
            foreach(local cur in allContents)
                cur.discover();
            
            achievement.awardPointsOnce();
        }
        inherited();
    }
    
    achievement: Achievement { +5 "finding the safe" }
;

++ safeDoor:  Hidden, ContainerDoor '(safe) door' 'safe door'
    "It has a circular dial attached to its centre. "         
;

+++ safeDial: Hidden, Component,  NumberedDial 'circular dial*dials' 'dial'
    "The dial can be turned to any number between <<minSetting>> and
    <<maxSetting>>. It's currently at <<curSetting>>. "
    
    minSetting = 0
    maxSetting = 99
    curSetting = '35'
    
    num1 = 0
    num2 = 0
    correctCombination = 1589
    
    makeSetting(val)
    {
        inherited(val);
        num2 = num1;
        num1 = toInteger(val);
        if(100 * num2 + num1 == correctCombination)
        {
            "You hear a slight <i>click</i> come from the safe door. ";
            safe.makeLocked(nil);
        }
        else if(!safe.isOpen)
            safe.makeLocked(true);
    }
;

++ orb: Thing 'ultimate battered dull metal orb/sphere/ball/satisfaction' 
    'Orb of Ultimate Satisfaction'
    "It doesn't look much be honest, just a battered sphere made of some dull
    metal, but you've been told it's the most valuable and desirable object 
    in the known universe! "
    
    aName = (theName)
    
    subLocation = &subContainer
    
    okayRubMsg = 'As {you/he} rub{s} {the dobj/him} a shimmering djiin suddenly
        appears in the air before you!\b 
        <q>Hello, you have reached the automated holographic answering service
        of Jeannie the Genie,</q> she announces. <q>I\'m sorry I\'m not
        available to respond to your rub in person right now, but my hours of
        activity have been heavily curtailed by the European Working Time
        Directive. Before making a wish, please make sure that you have
        conducted a full risk assessment in line with the latest Health and
        Safety Guidelines. Also, please note that before any wish can be granted
        you must sign a Form P45/PDQ/LOL indemnifying this wish-granting agency
        against any consequential loss or damage arising from the fulfilment of
        your desires. Thank you for rubbing. Have a nice day!</q>\b
        Her message complete, the holographic djiin fades away into
        non-existence. '
    
    moveInto(dest)
    {
        inherited(dest);
        if(dest.isOrIsIn(me))
            achievement.awardPointsOnce();
    }
    
    achievement: Achievement { +10 "taking the orb" }
;

//------------------------------------------------------------------------------

/* DEFINE A NEW VERB */

DefineTAction(Rub)
;

VerbRule(Rub)
    'rub' dobjList
    : RubAction
    verbPhrase = 'rub/rubbing (what)'
;

/* When creating a new verb, you'll want to modify the Thing class so as to provide
   default handling for the command. The defaults specified here will be used except
   on objects for which you define explicit handling of the command. */
   
modify Thing
    dobjFor(Rub)
    {
        preCond = [touchObj]
        action() { mainReport(okayRubMsg); }        
    }
    
    okayRubMsg = '{You/he} rub{s} {the dobj/him} but not much happens as a
        result. '
    
    shouldNotBreakMsg = 'Only amateurs go round breaking things unnecessarily. '    
;

//------------------------------------------------------------------------------

/* HINTS */

TopHintMenu;

+ Goal -> (frontDoor.achievement)
    'How do I get into the house?'
    [
        'Well, the windows don\'t seem a good way in. ',
        'So perhaps you\'d better try the front door. ',
        'Could someone have left a key around somewhere? ',
        'Is there anything lying around where someone could have hidden a key? ',
        'What about that flowerpot? ',
        'Try looking under the flowerpot. '
    ]
    
    goalState = OpenGoal
;

/* The closeWhenSeen property of the following Goal object is an example of how to
   make your hint menu respond dynamically to the player's current situation. */
    
+ Goal 'Where can I find the orb? '
    [
        'Something like that is bound to be kept safe. ',
        'So it\'s probably inside the house. '              
    ]
    
    goalState = OpenGoal
    closeWhenSeen = hallway
;

+ Goal 'Where can I find the orb?'
    [
        'It\'s sure to be kept somewhere safe. ',
        'You\'d better hunt around. ',
        'Somewhere in the study seems the most likely place. ',
        deskHint,
        'But it should be safely locked in a safe ',
        'Where might someone hide a safe in this study? ',
        'What could be behind that picture on the wall? ',
        'Try looking behind the picture (or simply taking the picture). '
    ]
    
    openWhenSeen = hallway
    closeWhenSeen = orb
;

++ deskHint: Hint 'Have you tried looking in the desk drawer? '
    [deskGoal]
;

+ deskGoal: Goal 'How do I get the desk drawer open?'
    [
        'Have you examined the drawer? ',
        'What might you need to unlock it? ',
        'Where might you find such a thing? ',
        'What have you seen that a small key might be hidden in? ',
        'How carefully have you searched the hall? ',
        'What is (or was) on the hall table? ',
        'What might that vase be for? ',
        'Try looking in the vase. '
    ]
    closeWhenSeen = notebook
;

+ Goal 'How do I get the safe open?'
    [
        'How carefully have you examined the safe? ',
        'Where might someone leave a clue to the combination? ',
        deskHint,
        'Make sure you read the notebook. ',
        'Once you\'ve found the combination you need to use the dial. ',
        'If the combination is a number larger than 99 you\'ll need to enter it
        in stages. ',
        'For example, if the combination were 1234 you\'d first need to turn the
        dial to 12 and then turn it to 34. '
    ]
    
    openWhenSeen = safe
    closeWhenAchieved = (safe.subContainer.achievement)
;

+ Goal 'What does the clue in the notebook mean?'
    [
        'Well, <q>SAFE</q> might refer to something you want to open. ',
        'Have you seen a date round here? ',
        'When was this house built? ',
        'Where might you find the year in which this house was built? ',
        'How carefully have you looked at the front of the house? ',
        'Did you examine the door? '
    ]
    
    openWhenRevealed = 'safe-date'
    closeWhenAchieved = (safe.subContainer.achievement)
;


+ Goal 'What do I do with the orb now I\'ve got it?'
    [
        'Well, you could try rubbing it. ',
        'But the main thing to do now is to escape with it. '
    ]
    openWhenSeen = orb
;

Doubtless there a great many more things that could be done to improve this game, but it has now served its purpose.

Once again, there are far too many features here to discuss in a Quick Start Guide. One thing in particular to note is the use of the ComplexContainer class. We use it for the flowerpot because the pot is something we put the key under but it would also be possible to put things inside. We also use it for the safe — and this is a more important case — because we have now made the safe door a Component of the safe and the combination dial a Component of the safe door. If we had left the safe as an OpenableContainer (as in version 2), the safe door and the combination dial would have been locked inside the safe along with the orb, and the safe would have been impossible to open (a mistake it's very easy to make, so this is worth noting). Another thing worth noting is the use of RemapTo() to redirect certain actions that the player might reasonably try on the desk to its drawer. Finally it's worth pointing out that there's more than one way we could have implemented many of the things shown above.

There are plenty of other feature of TADS 3 that haven't been introduced yet. In particular this example doesn't even begin to touch on the creation of NPCs (other characters in your game — the fleeting appearance of Jeannie the Genie doesn't really count). But the three versions of the game shown above should have illustrated quite a few of the most common features of TADS 3 used in developing TADS 3 games, and depending on your background and inclinations you may have learned something by studying the sample code and trying it out. If you feel confident enough to experiment a little more on your own, by all means do so, but at this stage it's getting pretty near the point when you will need to move on to Getting Started in TADS 3 or Learning TADS 3.

Eric Eve — May 2012