ii - Introducing the Alan System


ii.1 - Use any wordprocessor to write an adventure

There are three components in the Alan Adventure Language system - the Alan manual, the 'Alan' compiler program and the 'Arun' game-player program.

The Alan programming language lets you write a text adventure by describing a collection of locations, objects and other items and by specifying a collection of commands the 'reader' or 'player' of your adventure can use to manipulate and move around the environment you have described.

This description can be written in any text editor or wordprocessor that can save files as plain or 'ascii' text such as Windows Notepad or DOS Edit on MSDOS PCs, vi on Unix machines or SimpleText on Apple McIntosh.

The document you create in your wordprocessor is called the 'source code' for the adventure. The text adventure's source code must of course conform to the Alan language specification or 'syntax' which is described in detail in the Alan manual. This tutorial doesn't provide the full syntax of the Alan language. The examples given illustrate just some of the features of Alan.

ii.2 - The Adventure creation process

The file containing the source code needs to be 'compiled' by the Alan program. This creates a pair of 'game files' which can then be played using the Arun program. Of course you could never write the complete source code for an adventure then compile it once and be completely satisfied with the way the game plays with Arun. You will need to write and re-write the source code over and over as you fix problems and add enhancements to your game.

ii.3 - Compiling Alan source file

The source code you write with your text editor or wordprocessor is still just a text file. To turn it into an Alan adventure game the file needs to be 'compiled.' The compile process checks that the text is written in correct Alan syntax and then converts the human-readable text file into two Alan binary code game files.

This tutorial comes with a source code file called intro.ala which you can compile now to test that you have got the Alan system set up properly. Compiling the intro.ala source file will create two game files called intro.dat and intro.acd .

The DOS Alan compile program is called alan.exe . For other computer systems the filename may be slightly different - probably just ' alan '.) The easiest way to use alan.exe is to put a copy of it in the same directory as your source files. (Note that if you're using MS-DOS but not MS Windows you'll also need a file cwsdpmi.exe - see Appendix 1.2.) Then, if you're not already there, go to your operating system's command prompt. (For example, on a MSDOS PC, if your Alan program and source files are in a directory called "AlanPrgm" on your c: disk drive go to a DOS prompt, then enter c: and then cd\alanprgm )

Then to run a source file through the Alan compiler, enter

where source is the name of the source file without the 'file extension' part of the name. Alan assumes the source file name ends in .ala (or .alan on systems that use longer filenames than MS-DOS.) In our example the file is called intro.ala so the command is

That command should display some information on the screen and create files called intro.dat and intro.acd . These are the Alan game files for our test adventure which you can now play using the Arun program.

Appendix D in the Alan manual explains the options available when you compile your source code with the Alan compiler. You can also get a summary of options by entering alan -help at the command prompt.

One particularly useful option is the -listing option. When your source file contains errors (which it no doubt will at some time) the messages scroll off the screen too fast to study. Entering

will produce a file called source.lis (or source.list) containing all the error messages which you can view to isolate where the problems are.

ii.4 - Hints to fix source code errors

The trick is to fix the first error that the Alan compiler lists and then try compiling again.

Frequently one error has a cascade effect so that once the compiler encounters an error it is unable to understand the following source code even though that code may be perfectly correct.

Also, the cause of an error may be in an earlier line than the line of code that Alan reports as having a problem.

For example, if you leave out the end of one section of code, Alan will report an error at the start of the next section saying something like "um, sorry, you can't start a section here." So, to find the cause of a problem, always look at previous lines of code as well as the line reported to contain the error.

ii.5 - Playing the compiled adventure

Having compiled a game successfully we can play it using the Arun program. The Arun program reads the .dat and .acd files created by the Alan compiler. To play the test adventure, intro, make sure you are at a command prompt and in the same directory as intro.dat and intro.acd , then enter

at the command prompt. (Appendix D of the Alan manual explains the options available with Arun. Normally you don't need to use any of the options to play a game.)

So for other people to play your completed game, they need copies of the two game files (the .dat and .acd files) and also a copy of the version of arun.exe that runs on their computer system.

A feature of the Alan language is that games can be played on a variety of operating systems. The .dat and .acd files created on one operating system can be played on any other system using the version of Arun for that other operating system. For example, if you create a game on an Apple MacIntosh, you could email the .dat and .acd files to a friend with a PC who would be able to play the game using the MS-DOS version of arun.exe.

So normally when distributing a game you would send just the .acd and dat files along with instructions on where the player can get the appropriate version of Arun for their computer.


Source code for testing Alan setup | Table of Contents | Lesson 1