The 'ALAN Adventure Language' logo  


Stop Press! New Software!
"The Alan Development Environment for Windows"

I've written a free, self-installing, package called "The ALAN Development Environment for Windows" which makes it even easier to set up ALAN on your PC than manually following the steps described on this page. "ADE/w" is a Windows menu program which brings together all the Alan software and manuals into one self-installing download. I'll leave this page up anyway as there's weblinks to it and the information might still be of interest. See my Home Page  for information about "ADE/w".

Okay then, having presented the news, now here's that old information ....
 


Writing Interactive Fiction with ALAN and MS Windows

0 - Introduction

Screen shot of an ALAN game being played.
(Click graphic to Enlarge)

The ALAN Adventure Language is a programming system for writing and playing text adventure games. ALAN was created by Thomas Nilsson. His ALAN webpage has lots of detailed information about the ALAN system.

There are several different versions of ALAN and it is available for many different computer systems including MS Windows, Apple Macintosh and Linux. There are many different sources of information. All the available options and information sources may be a little overwhelming for someone first looking at writing a game with the ALAN system.

text adventure screenshot

Furthermore, some of the ALAN game-writing software is MSDOS-based which can force the uninformed MS Windows user to encounter the Windows' DOS commandline for the first time - an experience that can be frustrating for the uninitiated and can be avoided completely if ALAN and Windows are set up the right way.

So this page is intended to provide simple 'getting started' information for a beginner who is accustomed to the Microsoft Windows way of doing things.

(You might like to print this page or save it onto your own PC so you can refer to it easily while you are setting up ALAN.)


1 - Getting Started with ALAN

The process of writing an ALAN game involves three steps (the steps being repeated many times.) The game writer types a description (using the ALAN programming language) of the elements of the game world into a text file. The writer then runs the "ALAN compiler" program which reads that text file and converts it into a playable text adventure game. That adventure game, contained in two component "game files", can then be played using the ALAN "runtime interpreter" program. (The writer then goes back to the text file and fixes the errors and adds new elements to the game and repeats the compiling and test-playing and re-writing until they are happy with the resulting game.)

So to get started writing ALAN games you need four things - instructions about the ALAN language so you know what to write, a text editing program to write with, an ALAN compiler program to convert your text into a game and an ALAN interpreter program to play the game.

I suggest that the four items recommended in the next section are all that are necessary for a new writer to get started with ALAN. Once the new writer has spent some time with ALAN then I would recommend downloading some additional things but to begin with these four items provide all the essentials.


1.1 - What to Download

Note that all four items recommended below are freeware - which means they are all items of copyrighted software but are intended by their authors to be freely available for download, free of charge, to anyone that wants to use them.

The items listed below are all compressed files which need to be uncompressed with a program like PKZip for Windows or WinZip. (Those programs are great and I recommend them. However they are both shareware - whcih means they can be downloaded for free but you should pay for them if you use them for longer than a specified trial period. If you want a freeware program visit a download site like "Tucows" where there are many free compression programs listed - one example is 'Zip Central.')

Use the Windows "My Computer" or Windows Explorer to create a new folder on your hard disk called Alan. (Click on the "C:\" then select File-New-Folder from the menu.) Within that 'Alan' folder you can uncompress the downloaded files into several sub-folders - read the next section 'Setting Up' for details.


1.1.1 - The ALAN Tutorial (The ALAN system has a very good manual which you'll need to read and understand later in order to master all the features of the ALAN system but, to get started, I suggest you first work through the lessons and exercises in this tutorial - I'm not recommending the tutorial just because I wrote it. Other people, including the author of ALAN have endorsed it too so I immodestly recommend it to you as the best introduction to ALAN available! :-)


1.1.2 - The PFE programmer's text editor (You can write your ALAN game description text file using any wordprocessor or text editor but I don't recommend this. The big advantage of a "programmer's editor" such as the PFE editor is that it can be configured to automatically run your text file through the ALAN compiler program and report any errors. This avoids the need to manually run the ALAN compiler program from the DOS commandline and all the mastering of MSDOS mysteries that that implies.)


1.1.3 - The ALAN compiler (This is an MSDOS version for the ALAN compiler program. There is no MS Windows version. But this doesn't matter as we are going to configure the PFE text editor to run the compiler program for us.)


1.1.4 - The Windows ALAN game player program (There is an MSDOS-based ALAN 'runtime interpreter' - i.e. game playing program - included with the ALAN compiler download mentioned in the last paragraph. But its nicer to use this pretty new MS Windows-based program for testing and playing your ALAN games.)


1.2 - Setting up the Downloaded Programs

If you have not done so as you downloaded them, you should now uncompress the four downloaded programs. I suggest putting the uncompressed tutorial and PFE files into individual folders within your 'Alan' folder and putting the ALAN compiler and game player programs into one other, shared, folder. You can also create an empty folder now to store your own files once you start writing them. For example -

	c:\

- Alan
-- MyGames (empty)
-- PFE
-- Programs (contains both compiler and player programs)
-- Tutorial

Note that you should make sure all your ALAN folders and games have names of eight or fewer characters. This is because the ALAN compiler is an MSDOS program and can only handle filenames up to eight characters long.


1.2.1 - Creating a Windows 'file association' for ALAN source code files

Windows determines what program to use to process a file that is 'double-clicked' by reading the file 'extension' - that's the characters in the file's name after the last dot in the name. If Windows doesn't have a file association entry for a file's extension then it pops up a dialog box to ask you what to do with the file.

So double-click on an ALAN source code '.ala' file - eg: 'jungle.ala', which is an example game that should be in your Alan\Programs folder as Jungle is included in the ALAN compiler download. A dialog box should pop up as Windows won't know what to do with '.ala' files yet. Make sure the 'Always use this program' box is ticked. Then click the Browse button in the dialog box and hunt down the file pfe32.exe in your Alan\PFE folder. Then click OK. From now on Windows should use the PFE Editor to open a ".ala" file whenever you double-click on it.


1.2.2 - Configuring the PFE Text Editor

There is a huge range of options and preferences which can be configured within the PFE Text Editor program. The settings described in the following sections are the minimum changes to configure PFE for working with ALAN game source code files. Once you get accustomed to using PFE you might like to explore the other options you can configure to your own requirements.


1.2.2.1 - Configuring PFE to Edit ALAN files
The first task is to configure PFE so that it uses wordwrap and indents lines properly for editing Alan source code files. This is done by setting a couple of options in the “Default Modes…” item of the PFE Options menu.
PFE Options Menu

Select the “Files whose name is not in any mode group” option from the dialog box that pops up and click the “Edit Modes…” button.
Default Modes

The "Edit Default Modes" dialog box is then displayed. We need to make changes in the "Input" and "Text Formatting" Mode subsections.

Select the "Input" Mode from the list on the left and then turn on the following items on the right of the dialog box
- autoindent new lines
- strip trailing spaces when newline typed
Input Mode Menu

Now select the "Text Formatting" mode from the list on the left of the dialog box. Then change the following items on the right
- select "Tab with TAB Characters (Hard tabs)"
- set Tab stops every 4 characters
- set Text wrapping to "Enabled"
Formatting Mode Menu


1.2.2.2 - Configuring PFE to Compile ALAN files
Now you can configure PFE to 'compile' an ALAN source code file into an ALAN game.

Open an ALAN source code file, such as jungle.ala, in PFE - double-clicking on the jungle.ala file in Explorer or My Computer should work now.

Then select Execute from the PFE menu. Select the first option - DOS Command to Window. An 'Execute DOS Command and Capture Output' dialog box pops up. Click the button with three dots at the right of the 'Command' field - the three-dot button lets you 'browse' your folders for a specific file. Hunt down the file alan.exe in your \Alan\Programs directory. Then click 'Open'.

The text in the Command field should now be something like "c:\Alan\Programs\alan.exe". Go to the end of that text and type a space and then %n -LIST

(The "%n" tells PFE to put the name of the file currently being edited at the end of the commandline. The "-LIST" tells the ALAN compiler to lists its messages into a text file. In this example the command will become "c:\Alan\Programs\alan.exe jungle -LIST" which will cause the ALAN compiler to compile the file jungle.ala into an ALAN game consisting of two game files - jungle.dat and jungle.acd - and to list any compiler error or informational messages to a file called jungle.lis which may come in handy but isn't really necessary as PFE will display the errors on-screen anyway.)

In the Directory field you should type %u\%d

This obscure little string of characters tells PFE to switch its current 'working' disk-drive and directory (or 'folder') to the location containing the file you're trying to compile. Setting the working directory ensures that the ALAN compiler program will be able to find the file to compile. Also, you might as well turn on the 'Use DOS 8.3 names in substitions' option which means the compiler will be able to find the file even if you forget to keep its name to eight characters or less.

PFE 'DOS Execute' dialog box

Now click the OK button in the 'Execute DOS Command' dialog box to run the command. There'll now be much whirring of disks and flashing of appearing and disappearing windows. Then all going well a new 'document' will open in PFE called CommandOutput1. This document probably won't tell you anything useful unless it says something like 'command not found' - in which case something was wrong with the commandline entered in your Execute DOS Command' dialog box. When you're compiling your own games you can expect to see many errors listed here - part of the fun of writing adventure games is nutting out what the compiler is complaining about. (Hint: always fix the first reported error first because often a whole list of errors all relate to one small mistake like a missing quote-mark or something similar.)


1.2.3 - Creating a Windows 'file association' for ALAN game files

All going well, you should have now compiled the Jungle example game. A compiled ALAN game consists of two files - a .acd file and a .dat file. So you should find a 'jungle.acd' file and a 'jungle.dat' file in the \Alan\Programs folder now.

Double-click on the jungle.acd file. A dialog box should pop up as Windows doesn't know what to do with '.acd' files yet. Click the Browse button and hunt down the winarun.exe file (in \Alan\Programs) to associate the .acd file extension with the Windows ALAN game player program. Click OK. From now on (as long as you remembered to tick the 'Always use this program' box in the dialog box, of course) you will be able to play an ALAN game just by double-clicking on the game's .'acd' file in Explorer or My Computer.

(Note that unfortunately there's currently a bug in the ALAN game player program which causes it to ask you again for the name of the game you want to play when it first opens. So when winarun first starts, type in the word jungle and press Enter. Hopefully a new version of winarun will be released soon which fixes this little inconvenience.)


1.2.4 - Creating Start Menu items and Desktop shortcuts

The new file associations you've just created mean you don't really need Start Menu items or Desktop shortcuts as you can edit ALAN source-code or play ALAN games by double-clicking on the appropriate file in My Computer or Windows Explorer. But, if you're like me, you will probably like to have shortcuts to the PFE editor (pfe32.exe in your PFE folder) and the ALAN tutorial (tutor.htm in the Tutorial folder.)

You can create Desktop shortcuts easily by right-clicking on any blank space on the Desktop and selecting New Shortcut from menu that pops up. Then click the Browse button and hunt down the file you want your shortcut to load for you.

Firstly,create a shortcut to pfe32.exe in your PFE folder. Then repeat the process to create a shortcut to tutor.htm in your Tutorial folder - you will need to pick the 'All Files' option in the Files of Type option box so that the .htm files are displayed in the Browse dialog box.

To create a Start Menu item right-click on the Start button then select open or explore from the menu that pops up. Create a new folder called Alan in an appropriate spot (using the File-New-Folder menu option.) You can then click-and-drag or cut-and-paste the Desktop shortcut you've created to your new Alan folder in the My Computer or Windows Explorer window displaying the Start Menu items.


1.2.5 - Play someone else's ALAN games

I also suggest downloading some ALAN games to experience what playing ALAN games is like. A good sample might be the ALAN games from the 1999 'RAIF' IF Competition - Mikko Vourinen's King Arthur's Night Out and Eric Mayer's The HeBGB Horror. Put these games into another folder under /Alan - perhaps /Games. You could also create Start Menu or Desktop shortcuts for them (use the technique in 1.2.4 - you will need to pick the 'All Files' option in the Files of Type option box so that the .acd files are displayed in the Browse dialog box.)


1.3 - All set to learn!

You've now got all the components configured that you need to work your way through the ALAN tutorial - you can edit and compile ALAN source code files in PFE; you can read the compiler message output in PFE and you can test your ALAN games by playing them with winarun.

I suggest you now work through the tutorial making your own simple ALAN game as you go. (You can save your game files in the Alan\MyGames folder you created earlier.) By the end of the tutorial you'll have been introduced to many of the basic features of ALAN and be ready to tackle the detail in the ALAN manual. You'll also hopefully be fairly comfortable with using PFE. (PFE has a lot of features and so there's a lot to learn if you want to. Take some time to read some of the comprehensive Help information that comes with PFE.)


2 - Getting Serious with ALAN

I suggest you spend a few days or weeks working through the tutorial before downloading anything else. There's quite a lot of other ALAN stuff at the ALAN webpage and the IF Archive but during the initial learning period I think the downloads mentioned above are quite sufficient. If you want to keep working with ALAN after you've finished the tutorial then I suggest downloading the following items. (And don't forget to register your copy of the ALAN software - its free - by sending an email to Thomas Nilsson.)


2.1 - Read the manual

Once you finished the tutorial you'll need to read the ALAN manual. The tutorial leaves out a lot ALAN features as it is only a basic introduction. So a thorough reading of the ALAN manual is essential once you have mastered the basics covered in the tutorial.

The manual can be browsed on-line at the ALAN webpage or downloaded for off-line reading or printing in Adobe Acrobat pdf format or in HTML format.

The downloadable HTML-format manual is stored in an unusual compressed file format - it is in a "Gzipped tar" file. Either PKZip for Windows or WinZip can uncompress such files so I suggest you use either one of these programs. There's probably freeware Gzip and Tar utilities for Windows available but I haven't looked for them myself. As a last resort, there's freeware MSDOS Gzip and Tar utilities in the if-archive/download-tools/pc directory at the IF Archive.


2.2 - Study the examples

Download and look through the sample game source code available from the Examples page at the ALAN Web site and the programming/alan/examples directory at the IF Archive.


2.3 - Use the library

Also download the latest version of the 'proposed standard library' from the Download page at the ALAN webpage. See the readme file with that download to see how to use the library. I've uploaded two little ALAN games to the IF Archive that may help while learning about the library. The 'score notification' example uses the library in a very basic way without modifying any of the library code. The source code to my "WackyComp" game 'Skipping Breakfast' illustrates the full use of the library with some library files replaced by versions adapted for the specific game. (Also download the compiled version of 'Skipping Breakfast' so you can see how it plays.)

The ALAN source code files in the library have the filename extension of '.i' so you'll need to create a new file association between the '.i' extension and PFE so you can conveniently edit the library files just by double-clicking on them.

You'll also need to modify the compiler commandline in PFE so that it specifies the folder where you've placed the uncompressed library files. I suggest putting the library files in a folder called 'Library' within your Alan folder. If you follow that example you should add -include 'c:\Alan\Library' to the Execute Dos Command to Window command line in the PFE menu.


2.4 - Ask questions

You can contact other people using ALAN through the ALAN email list - there's a link to it on the ALAN webpage - or through the Usenet newsgroup rec.arts.int-fiction. If you don't have a newsgroups connection set up on your PC you can use a newsgroup Website such as Google Groups.

(Home Page)
alan9598.htm Last updated 9th November, 2001.
Please email any comments or corrections to Stephen Griffiths (stephen.griffiths "AT" xtra.co.nz)