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. This assumes you've placed the adv3Lite directory under an extensions directory under your TADS directory, and that you'll create your Heidi directory in the next step under the same TADS directory.
2. 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.
3. Locate adv3Lite/adv3Ltemplate directory and copy (don't move) its entire contents (but not the directory itself) into your newly-created Heidi directory.
4. Navigate back to the Heidi directory.
5. In the Heidi directory, rename the file adv3Ltemplate.t3m to heidi.t3m.
6. In the Heidi directory, delete the file adv3Ltemplate.tdbconfig (if you're not using Workbench, you don't need it).
7. Now open the heidi.t3m file in a text editor and edit it to read:
   

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

   You can delete any instances of comments like the “warning — this file was mechanically generated” paragraph you find in the t3m file, together with any bits of executable code you find there. You can also delete the line -pre. You may need to change the penultimate line if the path to where you've stored the adv3Lite directory is different from that assumed here.
8. 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.
9. 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.
10. 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 Heidi 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.
11. Keep the Terminal window open and press the Up arrow on the keyboard each time you want to do a compile, as this will reload the last command line that you typed (t3make etc.).