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.

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.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

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

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.

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

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"

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.

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

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

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!

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

---

2.1 - Read the manual

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

---

2.3 - Use the library

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

---

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

---