If you are reading this text you have probably already decided that
- You want to try your hands on writing some adventure games, a.k.a interactive fiction
- You want to see if Alan is a suitable tool/language
So this page is about getting you started as quickly as possible.
Making your choice
There are a couple of different ways to setup Alan. Your options also vary depending on your platform. In the following we will be covering the three most common today - Windows, MacOSX and Linux, and describe the steps to set up a working Alan environment.
Basically, there are three separate steps that you repeat (over and over) when you develop an Alan game:
- Edit the source code
- Compile the source code into a game
- Run the game
There are a couple of different ways to perform each step. The table below indicates for each platform what options you have for each of these steps. But basically, all you need to decide is if you want to go the "flexible" or the "integrated" way.
As we can see from the table above, AlanIDE covers the 6 gray cells (Edit and Compile for the three platforms). The AlanIDE does not yet cover the Run/Debug step natively, meaning that you can also run your game in the IDE. So you need to add something to be able to run the game produced by editing and compiling using the AlanIDE. On some platforms you can even set it up so that you can double-click on the game file in the AlanIDE navigator view to start the game with the default external runner.
If you are starting out with AlanIDE you probably want to use a GUI-based interpreter to run your game. On the Windows operating system there is a Alan provided version, WinArun. The third part, general multi-format, interpreter/runner Gargoyle also plays Alan games, and it covers all the three platforms in that respect (the 3 blue cells). So we will have a look at setting up AlanIDE and Gargoyle on the three platforms. The differences between the platforms are marginal.
You should remember that the "integrated" way (using AlanIDE) is not the only way to work with Alan, so once you have become accustomed with Alan and want to do some serious work, you might want to investigate the other options to find your favourite setup.
The Simplest Setup
Setting Up AlanIDE
AlanIDE is an "Integrated Development Environment" which you can read more about here. So to get AlanIDE running you:
- Download and install the appropriate AlanIDE from the Download Area
- Download the command line complete Alan package for your platform from the Download Area which you unpack in some suitable folder (C:\Program Files\Alan v3\bin is a suggestion for Windows).
- Download the Alan standard library from the Download Area and unpack it (e.g in C:\Program Files\Alan v3\lib)
- Start the AlanIDE
- Go to the Preferences, find the Alan settings and point the compiler preference to where you stored the Alan command line compiler
- Point the library preference to where you stored the standard library
- Follow the videos from the AlanIDE page (of which the first shows items 5-6 above, and the second takes you through the creation of a small game)
Setting Up Gargoyle
Gargoyle is a multi-platform, multi-gameformat adventure runner/interpreter. With it you can run almost any type of adventure game available in the community for interactive fiction.
- Download and install Gargoyle
The Flexible Setup
Flexibility comes with a price: you need to take many more decisions and you need to do more work. When it comes to installing Alan you must make two more choices:
- Which text editor should I use?
- Command line or GUI?
Alan source code is typed into an editor and saved in a text file. Your choice of text editors are plenty, from Notepad to more programmer-friendly ones. This page will help you make your long-term selection, but if you are just making a quick trial run of Alan you can get by with the text editor delivered with your platform (Notepad for Windows, TextEdit for MacOSX). Just remember to save your source code as "pure text" (and no, you can't use Wordpad, Microsoft Word or LibreOffice). The Alan compiler don't understand formatting. Steve Griffiths has also a few tips on the subject.
The GUI choice
The choice of "command line or GUI" might seem confusing to you. If so, I recommend going for the "GUI". This means that you should make sure to download the GUI-version of the complete distribution, if one is available for your platform. If there is not, you either have to settle for the command line approach or skip to the "integrated" setup.
GUI-versions of the compiler and interpreter are run from your windowing environment in some manner. E.g. on Windows you can double click on the compiler, or start it from the Windows menu, and it will prompt you with a file selection dialog in which you can select which file to compile. You can even double-click on the source file and the GUI-version of the Alan compiler will compile it. After compiling, a window will be showing any possible errors, which you need to fix by editing the source code. GUI-versions of the interpreter work much the same way: start it and it will prompt you for a game to run/play.
The Command Line Choice
Going for the "command line" means that you need to open up a command line prompt to start your compiles and runs using textual commands. This might seem daunting but there are only a few that you need to use in the beginning. On Windows this means opening up a Command Prompt and navigate to the folder where your source files are. Once there, you must type "alan" (the name of the alan compiler program) followed by the name of your main source file to compile the source file into a game. Likewise, to run your game you type "arun" followed by the game name.
Difficulties of the command line approach include:
- Harder to get installation to work smoothly
- Interpreters don't support all features (like images and output formatting)
A middle ground is definitely to run the command line version of the compiler and the GUI-version of the interpreter or Gargoyle.
The "full Monty" of the command line setup includes:
- Download a complete package, command line version, from the Download Area
- Extract the files in that package to a folder somewhere (like C:\Program\AlanV3 on Windows)
- Set the path to include that folder (the "path" is a set of folders where the command line looks for the programs you ask it to run and here's some instructions on how to do that)
- Try the setup by opening a command prompt and type "alan -v". If it answers with something intelligible, it works.
- Now you can edit an Alan source file ("myfirstgame.alan") in some directory (~/IFWriting/MyFirstGame, perhaps) and try to compile it using the "alan" command
- If there where errors discovered in your source code they will be displayed and you need to fix those by redoing step 5
- Run the created game with "arun myfirstgame"