If you are reading this text you have probably already decided that

1. You want to try your hands on writing some adventure games, a.k.a interactive fiction
2. You want to see if Alan is a suitable tool/language

So this page is about getting you setup as quickly as possible.

Making your choice

You can setup Alan in basically two different ways. Your options vary a bit 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:

1. Edit the source code
2. Compile the source code into a game
3. 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.

As we can see from the table above, AlanIDE covers all three OS:es and supports the Edit and Compile steps. This makes it a good candidate for a simple setup. It also works on all the platforms supported by Alan, so the steps to set it up are the same.

The AlanIDE is an integrated development environment where you edit your files with some extra support, like keyword highlighting and completion as well as some structural support. You can read more about it in AlanIDE, the Integrated Development Environment for Alan!. It does not yet have direct support for the Run/Debug step. You will need "external" interpreter or runner for that.

If you are starting out with the AlanIDE you probably want to use a GUI-based interpreter to run and test your game. On the Windows operating system there is a Alan provided version, WinArun. The third party, general multi-format, interpreter/runner Gargoyle also plays Alan games, and it covers all the three platforms. We will have a look at setting up AlanIDE and Gargoyle. The differences between the platforms are marginal.

Using AlanIDE is not the only way to work with Alan, so if you are familiar with software development in a command line environment, you might also want to investigate the other options to find your favourite setup.

The Simplest Setup

The simplest setup is using AlanIDE for editing and compilation and Gargoyle as your GUI runner.

Setting Up AlanIDE

AlanIDE is an "Integrated Development Environment" which you can read more about here. To get AlanIDE running you need to:

1. Download and install the appropriate AlanIDE from the Download Area
2. 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).
3. (optional) Download the Alan standard library from the Download Area and unpack it (e.g in C:\Program Files\Alan v3\lib)
4. Start the AlanIDE
5. Go to the Preferences, find the Alan settings and point the compiler preference to where you stored the Alan command line compiler
6. (optional) Point the library preference to where you stored the standard library
7. 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.

1. Download and install Gargoyle (or if you are on MacOS: from here, on Linux use your package manager)

Simple! If you managed to set up AlanIDE (or your OS) to recognize Alan game files (.a3c) you can now double-click on the resulting game file in the AlanIDE Navigator view. (If it doesn't show up there you can try updating that view using F5). You can also point Gargoyle to the resulting game, although a bit difficult to find since it is located inside the AlanIDE project structure, which might even be inside the installation, like AlanIDE.app/Content/MacOS/workspace/MyFirstProject on the Mac.

NOTE that Gargoyle is not always up-to-date with the latest Alan development and might require some extra steps to upgrade. An alternative to Gargoyle on the Windows OS is WinArun, which you can download from the interpreter download category. WinArun is always released together with any updated compiler.

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 setting up your Alan environment (not using AlanIDE, as was described earlier) you must make two choices:

1. Which text editor should I use?
2. Command line or GUI?

You type Alan source code into a texteditor and save it 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 just go with AlanIDE (which is definitely not a bad choice!).

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:

1. Download a complete package, command line version, from the Download Area
2. Extract the files in that package to a folder somewhere (like C:\Program\AlanV3 on Windows)
3. 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)
4. Try the setup by opening a command prompt and type "alan -v". If it answers with something intelligible, it works.
5. 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
6. If there was any errors discovered in your source code they will be displayed and you need to fix those by redoing step 5
7. Run the created game with "arun myfirstgame"