-
Notifications
You must be signed in to change notification settings - Fork 11
Installing and Using Adv3Lite
The most up-to-date versions of the adv3Lite source files and documentation may be downloaded directly from this repository, with the proviso that these are pre-release versions and that (for reasons of space) they currently don't include the Library Reference Manual (which most users of adv3Lite are likely to find highly useful sooner rather than later once they get beyond learning the basics to start developing their own games/works of interactive fiction).
Prospective users may therefore prefer to download a zip file of the latest release of adv3Lite 1.6.2. This contains the Library Reference Manual along with all the other documentation.
Instructions on installing adv3Lite and getting it up and running are included with the documentation that you'd download alongside the adv3Lite library, but are reproduced below for your convenience. They are written on the assumption that adv3Lite will have been downloaded in a zip file, but apart from any references to unzipping they will apply equally well to any download direct from this repository.
The adv3Lite library comes in a zip archive containing an adv3Lite folder/directory and a number of subfolders. A good place to unzip this into is the extensions folder/directory under the folder/directory in which you keep, or plan to keep, your TADS 3 game source code. On a Windows system this will typically be under My Documents\TADS 3; the TADS 3 author's kit setup program should create both this folder and the extensions folder under it. On a non-Windows system you may need to create these directories manually yourself. You should therefore end up with all the adv3Lite material in a folder somewhere like ...\My Documents\extensions\adv3Lite (where ... is the path to your My Documents folder or its equivalent on a non-Windows system). If you need to reinstall adv3Lite (for example, because you want to update to a newer version) I recommend that you first delete the existing extensions\adv3Lite folder/directory before unzipping the new adv3Lite folder to the same location; this should avoid any problems that might arise from remnants of an older version interfering with the newer version.
If you're using Windows, run TADS 3 Workbench (by selecting it from the "Start" menu group you selected during the installation process). The first time you use adv3Lite, select Tools -> Options from the Workbench menu. Scroll down to the System -> Library Paths section of the dialog box that should then appear. Add the full path to the directory where you installed adv3Lite (e.g. C:\Users\Eric\Documents\TADS 3\extensions\adv3Lite) to the list (click the Add Folder button and navigate to the folder you want and then select it). You may need to close Workbench and reopen it for the change to take effect, but once you've followed this step once you shouldn't ever need to do it again (at least, not on the same machine, assuming you don't move things around).
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.
If you've turned off the "welcome" dialog, then select "New Project" from the Workbench "File" menu.
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:
In the dialog that should then appear, simply click Next to continue to the second page of the Wizard.
In the second page of the Dialog, type "Burglar" (without the quotation marks, and using a name appropriate for your own game if it's not "Burglar") in the upper (Project Name) box, then click in the lower(Folder location) box. From there you can select an existing folder, but for a new project you should create a new one, so click the Make New Folder button and then enter a name for your new folder, such as burglar (making sure you create it under the ..\My Documents\TADS 3\ folder). Then click OK followed by Next.
In the third page of the Dialog, scroll down the list of Project Types until you get to Adv3Lite. Click on Adv3Lite to select it and then click Next. Fill in the information on the final (Bibliography) page of the wizard (e.g. with the name Burglar, your own name and email address, and a brief description like "A small tutorial game") and then click Next to complete the wizard. Your new adv3Lite game (or at least the beginnings of it) will then be created for you.
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.
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.)
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.
To set everything up to create a new game (which we're calling "Burglar" in preparation for the next section, although the same principles apply whatever you're calling it) carry out the following steps:
This assumes you've placed the adv3Lite directory under an extensions directory under your TADS directory, and that you'll create your Burglar directory in the next step under the same TADS directory.
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 Burglar. Locate adv3Lite/template directory and copy (don't move) its entire contents (but not the directory itself) into your newly-created Burglar directory. Navigate back to the Burglar directory.
In the Burglar directory, rename the file adv3Ltemplate.t3m to burglar.t3m.
In the Burglar directory, delete the file adv3Ltemplate.tdbconfig (if you're not using Workbench, you don't need it).
In the Burglar directory, create a subdirectory called obj (if it isn't there already).
Now open the burglar.t3m file in a text editor and edit it to read:
-D LANGUAGE=english
-Fy obj -Fo obj
-o burglar.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.
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. 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/Burglar' and then hit Return.
While the Terminal is logged into this directory, you can compile your game using this command:
t3make -d -f burglar
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 Burglar 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 buglar.t3' and hitting Return. 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.).
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, and of course you should replace "mygame" with the name you actually gave your game, such as "burglar".