GalaxyScript

GalaxyScript, or Galaxy for short, is the scripting language developed and implemented by Blizzard for use in the StarCraft II Editor. Galaxy is a C-like language, with support for procedural, event-driven imperative programming developed to be simple and easy to learn and use. It has no native support for Object-Oriented Programming (OOP).

Syntax

Major syntax features of Galaxy include:

• All executable code must be contained within functions
• Functions must be forward-declared
• Explicit, strong type system
• Automatic garbage collection (for certain types)
• Basic control statements (if...else..., while)
• Support for structs
• Support for typedefs
• Support for pointers, but no dynamic allocation
• Limited library support for thread management
• Large native library

Hello, World! Implementation

bool helloWorld(bool checkConds, bool runActions) {
     UIDisplayMessage(PlayerGroupAll(), c_messageAreaChat, StringToText("Hello, world!"));
     return true;
}

void InitTriggers() {
     TriggerAddEventMapInit(TriggerCreate("helloWorld"));
}

void InitMap() {
     InitLibs();
     InitTriggers();
}

The above is a Galaxy implementation of the traditional Hello, World! program. The map script displays the message "Hello, world!" to all players when the map finishes loading.

Differences from C

Although Galaxy is largely modeled after the C programming language, there are some important differences.

• Lack of dynamic allocation. Only certain types may be dynamically allocated through the use of native library functions.
• Numeric types are limited to signed 32-bit integers and 32-bit fixed point (Q19.12) numbers.
• No function overloading.
• No for loop.
• No nested {} blocks.
• No ++ or -- operator.
• Local variable declaration is limited to the top of functions.
• No support for function pointers.
• No preprocessor support other than basic include directives.

Use

Galaxy is almost an entirely event-driven language - most code is run in response to events that occur in the program. There is an initialization function (analogous to the main function in C) that is the first to be executed when the program (in the case of Galaxy program is synonymous with map or game) begins. Usually, this function is used only to initialize the native library and is not by default exposed to modders but nonetheless can be modified to execute arbitrary code.

Galaxy provides the trigger type to enable code to be executed in response to certain events. These events are pre-defined in the native library; users may not create new ones or modify existing ones. Functions that are executable by triggers can have any name, but must have a specific return type and argument list: bool executable(bool checkConds, bool runActions). The return type indicates whether the function successfully executed its code, and should always return true. The arguments are used by the editor's trigger editor and may be ignored by custom code.

The editor provides two ways of including custom Galaxy code in a map. The first is to use the trigger editor to create what is called Custom Scripts. Any code written into custom scripts will be injected into the map's main script file after the global variable declarations. This method usually proves to be cumbersome as the trigger editor contains very poor text-editing support. Modders also have the option of editing their code using external editors in .galaxy files, importing the files into the map, and including the files into the map script with the include directive.

Limitations

Galaxy, while a reasonably powerful scripting language, contains its share of problems. The major criticisms of Galaxy are:

• The maximum amount of memory allocated to the Galaxy virtual machine is 2 MB. This memory includes the code, global variables, and the run-time stack.
• Poor compiler implementation. The compiler that is included with the editor often generates cryptic error messages when a compile-time error arises.
• Little support for associative tables. The Data Table included in the native library only supports string keys, while many types - such as unit and trigger - offer no simple way to represent themselves as strings. Additionally, the data table only offers a thread-local and a global version. This means persistent associations must all be placed in the global version, forcing modders to take extra precautions to avoid unwanted key collision.
• Reflexive programming is implemented using string literals to reference functions with no compile-time checking of correctness.
• Structs and arrays cannot be passed into or returned from functions. Moreover, structs do not support the assignment operator; structs must be manually copied field by field. This severely limits the utility of structs.

See Also

• Triggers
• Andromeda: An improved GalaxyScript language.

Links

• A Guide to Galaxy: A beginner's tutorial on Galaxy coding.