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.
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.
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
alan source
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
alan intro
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
alan source -listing
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.
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.
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
arun intro
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.