Setting it all up

Once you've got up-to-date versions of the TADS 3 authoring system/compiler and the adv3Lite library you'll need to set things up so they all work together and you can set about creating your game. In what follows we'll assume your game is called "Heidi", since that's the name of the game we'll be creating in the next chapter. Obviously, when you come to create other games, you can substitute your own name for "Heidi" in what follows.

Set-up for Windows Workbench

First, before attempting to set up an individual game, open Windows Workbench, Select Tools from the Menu, then Options. Click on "Library Paths" (about three-quarters of the way down on the left-hand pane) then click on the "Add folders..." button. Navigate to the folder where you installed adv3Lite in the previous section (typically something like C:\Users\YourName\Documents\TADS 3\extensions\adv3Lite) and select it to add it to the list. This will tell Workbench where it can find the adv3Lite library; once you've done this once you shouldn't have to do it again (unless perhaps you reinstall Workbench for any reason).

Now, to set everything up to create a new game (which we're calling "Heidi" in preparation for the next section, although the same principles apply whatever you're calling it) carry out the following steps:

1. Under your My Documents\TADS 3 folder create a new folder called Heidi.
2. Locate the extensions\adv3Lite\adv3Ltemplate folder and copy (don't move) its entire contents (but not the folder itself) into your newly-created Heidi folder.
3. Navigate back to the Heidi folder.
4. In the Heidi folder, rename the file adv3Ltemplate.t3m to heidi.t3m.
5. In the Heidi folder, rename the file adv3Ltemplate.tdbconfig to heidi.tdbconfig.
6. Open the file heidi.t3m in Workbench (either by double-clicking on it in Windows Explorer, or by using the File -> Open Project option from the menu in Workbench).
7. Click the Go button (the little blue triangle at the left-hand end of the toolbar) in Workbench to compile and run the file to make sure everything's okay. You should then be in a position to start working on your new adv3Lite project.

Set-up for Mac OS X or Linux/Unix

To set everything up to create a new game (which we're calling "Heidi" in preparation for the next section, although the same principles apply whatever you're calling it) carry out the following steps:

1. Under the directory you've created to hold your TADS 3 source code (you might have called it TADS 3) create a new directory called Heidi.
2. Locate adv3Lite/adv3Ltemplate directory and copy (don't move) its entire contents (but not the directory itself) into your newly-created Heidi directory.
3. Navigate back to the Heidi directory.
4. In the Heidi directory, rename the file adv3Ltemplate.t3m to heidi.t3m.
5. In the Heidi directory, delete the file adv3Ltemplate.tdbconfig (if you're not using Workbench, you don't need it).
6. Now open the heidi.t3m folder in a text editor and edit it to read:
   

        -D LANGUAGE=english     
        -Fy obj -Fo obj
        -o heidi.t3
        -lib system
        -lib adv3Lite/adv3Lite
        -source start
   

7. 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.
8. 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/Heidi' and then hit Return.
9. While the Terminal is logged into this directory, you can compile your game using this command:

        t3make -d -f heidi
   

   If all goes well, you should see a string of messages in the Terminal window, and a new file (heidi.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 heidi.t3' and hitting Return.
10. 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 heidi.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/Heidi
         t3make -d -f heidi