Andromeda:Installation and Usage Guide

This document explains how to get Andromeda to run on your machine and where to write the Andromeda code for your maps.

Installation

Installing Andromeda is very easy. Since it is a full java program, it should work on all systems that have support for the latest Java Runtime Environment (JRE). So it should run on Windows, Mac OS X, and other Unix derivates.

The first thing you need is to install the latest JRE on your machine. If you have any java programs, you have probably already installed it. If not, get it at SUNs download page (now Oracle ;() and install it. Reboot your PC afterwards.

Now download the latest version of Andromeda. You can get it in SC2Mod's resource database. Unzip the zip file to any location where you want to have Andromeda. You do NOT need to run any installer, Andromeda works right away.

Now double click Andromeda.jar in Andromeda's main folder. You should see a window popping up.

What does Andromeda do exactly?

When you compile a map file and additional script files, either using the command line or the GUI (both explained later), the program reads all script files and all Andromeda code embedded into your map. It parses and checks your code and aborts if there is an error in it. If there isn't in compiles your code to Galaxy and injects it into your map (into an own file). It then modifies the MapScript.galaxy (the main script file of your map, generated by the editor), so that the injected file is included and executed when you run your map.

Writing Andromeda code

If the program is working, the next step in your Andromeda development is to decide where to write the code for your maps. You basically have two options (you can also mix them):

• Write your code into dedicated script files.
• Embed your code into your map. Both options have advantages and disadvantages which are discussed here.

Embedding Galaxy into your Map

You can simply write Andromeda code in the trigger editor of your map. To create a pseudo Andromeda file in your map where you can write your code, do the following:

• Open your map and open the trigger editor for it.
• Create a new action definition.
• Give the action definition a name (the name will be taken as "filename" for the pseudofile and be displayed when an error is in the code in it).
• Go to the options of your action definition and check the following entries:
  • Custom Script
  • Hidden
  • Andromeda will treat all such action definitions with those two entries checked as containers for Andromeda code
  • Select the custom script section of your action defintion. You can enter your Andromeda code here.
• This method has the advantage that it is quick and the code is automatically attached to your map without having to include it. However it has some drawbacks:[list][*]Only Galaxy code highlighting
• No code completion

Using dedicated files

You can write your code into normal text files. These files need to have the extension .a (for Andromeda). But how to attach those files to a map, so they get compiled with it? Easy:

• Place the files into the same folder where your map is located or into a subfolder.
• You can then include them with a normal Galaxy include directive (in Andromeda code in your map)
• The include must have the relative path from the map to the file. The extension .a is omitted.

So if you created a script file named foo.a and placed it in the subfolder bar then the correct include is: include "bar/foo" Dedicated files have the following advantages:

• You don't need the Galaxy Editor to edit them
• You can use editors or IDEs with correct code highlighting and auto completion

Of course you can mix both ways.

Library files

If you have files that you need in more than one map, you don't want to copy those files for each map. The solution to this problem is to put those files into a subfolder of Andromeda's lib folder and using < > to include them (library include).

Example (assuming your file foo.a is located in the folder lib/bar):[galaxy]include <bar/foo>[/galaxy]

Executing maps containing Andromeda code

Since Andromeda code has to be compiled before you can test your map, you somehow have to execute Andromeda onto your map. There are two main options:

• Using the GUI
• Calling Andromeda via command line[/list]While the GUI might be more convenient, the command line can be used to execute Andromeda automatically. This can be done by writing batch/shell files with the correct command line execution in them or by having other programs call Andromeda (your favorite editor hack, for example).

Using the GUI

By just double-clicking your map in the GUI, its Andromeda code gets compiled. You can then test it with SC2. (The GUI will get test functionality soon, so this section is rather a stub at the moment)

Calling Andromeda via command line

If you have java in your PATH, you can start Andromeda by executing java -jar Andromeda.jar <options> <source files> Source files is just a list of Andromeda (or Galaxy) files you want to add to your compilation, seperated with spaces. Options can be the following:

• == Misc ==
  • --help Display usage help
  • '-r'<RUN CONFIGURATION> Specify which run configuration to use. (Defined in the config file)
  • --run Run map if compilation was successful (requires to set SC2 path in conf file)
• == I/O ==
  • '-i'<INPUT MAP FILE> Specify an input map file. The generated code will be merged with the script of this map and all Andromeda action definitions code will be included into the compilation (see documentation for how to make an action definition recognized as Andromeda)
  • '-m'<INPUT MapScript.galaxy> Specify an input MapScript.galaxy in case you have extracted this file from a map with another tool. Note that you cannot use -i and -m together
  • '-t'<INPUT triggers> Specify an input triggers file in case you have extracted it from a map with another tool. Note that you cannot use -i and -t together
  • '-o'<OUTPUT MAP FILE> Specify an output map file. Can only be used if -i was specified. If -o is not set, the code will not be injected into a map. You can set this to the same file as -i to overwrite the old file with the compiled version
  • '-d'<OUTPUT DIRECTORY> Specify an output directory for the generated Galaxy source file (not the output map). By default, the source is generated in the ./out folder[/list]
• == XML Output ==
  • --nocode Suppress code production, in case you only want the XML output
  • '-s'<OUTPUT XML FILE> Outputs the code structure (functions, classes, variables...) to the specified xml file
  • --xmlnatives Also include native SC2 library files into the xml structure output
• '-e'<OUTPUT XML FILE> Outputs the result of the parsing run (messages, warnings, errors) to the specified xml file

Example: If you want to compile the map foo.SC2Map in the folder C:\bar and save it to the same path and want to add the script file C:\xyz.a, then use the following command (assuming that you are currently in your Andromeda folder):[code]java -jar Andromeda.jar -i"C:\bar\foo.SC2Map" -o"C:\bar\foo.SC2Map" C:\xyz.a[/code]