Galaxy++ editor by Beier will start downloading in 5 seconds...
Description
The program is now only released on my ftp server - see the thread linked below. http://forums.sc2mapster.com/resources/third-party-tools/19619-galaxy-editor/#p1
Documentation
General
Galaxy++
is a programming language that extends upon the original galaxy language, adding a lot more features. This means that any galaxy code you have should run exactly the same way when feeding it to the galaxy++
compiler.
Like most other programming languages, comments and whitespace is ignored by the compiler, so they can be placed pretty much anywhere without changing the behavior of the program.
If you feel some of your questions still go unanswered after reading this, or you find errors in the documentation, please pm me or post a reply. I will get back to you, and perhaps add to the documentation.
Compiler options
Although they might not classify as a language feature, I feel it's relevant to highlight some of the options in the compiler.
Obfuscation
There are a couple of tools for obfuscating the code. One is to rename everything to short names such as a, b, c. The other is to obfuscate string literals. What this will do is to "encrypt" every string so it is not readable by humans, and "decrypt" them when starting the map.
Please note that no code obfuscation can completely prevent others from reading, understanding and stealing your code. It just makes it difficult.
Declarations
Namespaces
There are multiple ways of defining namespaces.
namespace a.b.c //This way, everything in the file will be in the namespace a.b.c using a.b.c//The whole file can directly reference declarations in the namespace a.b.c int field1; namespace d.e { //Stuff in here will be in the a.b.c.d.e namespace int field2; } namespace d { int field3; namespace e { //Stuff in here will also be in the a.b.c.d.e namespace int field4; void method() { a.b.c.d.field3 = 1;//Have to make an absolute naming field1 = 2;//Can be referenced directly due to the using declaration. field2 = field4;//Both declarations are in the current namespace } } } void method() { field1 = 2;//You can directly reference declarations in your current namespace d.field3 = 3;//You can reference namespaces in your current namespace directly a.b.c.d.e.field4 = 4;//You can also choose to write the whole namespace }
Initializers and Library definitions
Initializes are basically methods that are run at first, when the map loads. Unless you made your own call to initialize the standard library, this call will be inserted before calling the initializers. You can make a simple initialize with
Initializer { [statements] }
The initializers can also contain data about a library you are defining. There are 4 different library fields: LibraryName, LibraryVersion, SupportedVersions and RequiredLibraries. An example of a library initializer is
Initializer ( LibraryName = "my library" LibraryVersion = "enterprise", SupportedVersions = "trial, basic" RequiredLibraries = "other lib 1:version2, (otherLib2:v1.7.4)" ) { [statements] }
All the library fields are optional, except you need both a name and a version in order for others to add it as a requirement. If your library version is not on the list of supported versions, it will be added. You may not use “:”, “(“, “)” or “,” in the name or versions, and all leading and trailing whitespace is ignored.
The method block is optional. It can be replaced with a semicolon.
If an initializer has defined any required libraries, the initializers of those libraries will be called first. In case of cyclic dependencies, a warning is reported, and as few dependencies as possible are ignored.
Includes
Any custom includes are ignored. Includes will be inserted by the compiler as needed, but all code except for the standard libraries are required in the project.
Methods
Unlike normal galaxy, it is not needed to have defined the method before using it.
Inline methods
Inline methods are marked with the keyword inline. When compiling a call to an inline method, the contents of the method is inserted instead of calling the actual method. This is done in a way so that there is no semantic difference to calling the method instead.
inline int method(...) { ... }
Note that inline methods may not be recursive i.e. they may not be called from themselves.
Trigger methods
The Trigger can be put infront of methods, but it no longer has any effect. It was previously used to identify methods that were triggers, but this is now done by searching for a string in a call to TriggerCreate. The keyword is kept for backward compatibility.
Reference parameters and extra return values
You can mark parameters with the ref or out keywords. Arguments passed to parameters marked with one of these must be variables. The effect of ref is that any changes done to the variable during the method call is reflected back in the calling method after the call. out is similar. Like with ref the changes done to this variable will also be done after the call, but unlike ref, it is required that the called method assigns a value to an out parameter, and he cannot read the parameter before he assigns a value to it. After compilation, an out parameter is not actually passed to the function, it is only returned, so it can be used as extra return values.
string[17] strings; string Next(ref int i, out bool hasNext) { hasNext = i + 1 < strings.length; if (hasNext) return strings[++i]; return ""; }
Passing bulkcopy data
Another thing to not is that it is now possible to pass types that would otherwise result in a bulk copy error between methods. This includes struct types and arrays. From your point of view, they are passed in exactly the same way as normal types. The compiler will send them via the data table instead.
Fields
Fields are pretty much what they are in galaxy, except that you don't have to have defined them above where you use them.
Visibility modifiers
You can mark global methods, fields and properties as public or private. By default, they will be set to public. If you mark them as private, they can only be accessed from inside the current namespace.
For methods, fields and properties inside structs, you can mark them as public, private and protected.
Like above, marking them with public is the same as not marking them at all.
If you set them to private, they can only be used from within the current struct.
If you set them to protected, they can only be used from within the current struct, or some other struct that enherit from it.
namespace myNS private int privateField; struct Str { private int privateProp { get { return 2; } } protected void protectedMethod() { } }
Structs
Like with fields and methods, you don't have to define structs above where you use them.
A new thing in galaxy++
is that structs can now contain methods. Simply place a method inside a struct, and that method will be a struct method. Struct methods will always be called with a specific instance of the struct. It is possible to directly refer to the members of the struct that is being called on by just typing the name of the member.
struct Foo { int[10] elements; int GetSum() { int sum = 0; for (int i = 0; i < elements.length; i++) sum += elements[i]; return sum; } } ... void Method(Foo foo) { if (foo.GetSum() > 9000) ... ... }
Classes
Classes are defined in the same way as structs. They are added to be purely dynamic types.
class Foo { int a; int DoSomething() { return a++; } }
The differences between classes and structs are
- The this keyword can not be used in struct methods (but can be used in constructors).
- It is not possible to make a non pointer variable of a class.
- There are some extra work that needs to be done for structs when calling a method on a pointer type (var->method()). For class types, the pointer is simply sent to the method. See the generated code. In short, if you only use your type in a dynamic context, use classes instead of structs.
Generics
You can make generic structs or classes.
struct Pair<T, G> { T p1; G p2; } Pair<int, bool> field;
In the example above, a copy of Str is made, where all T in the struct are replaced with integer types, and all G are replaced with boolean types.
It's possible to nest the types, but be aware that if you type >> it will be taken as the bit shift operator.
Pair<unit, Pair<int, fixed>> field;//This won't parse Pair<unit, Pair<int, fixed> > field;//This will
The transformation are done before everything is type checked. As a result, you can do stuff like this
struct Str { void foo() { } } struct Gen<T> { void bar(T item) { //This looks fishy - no garuantee that T has a foo method. item.foo(); } } Gen<Str> field1;//Will be okay Gen<int> field2;//Will cause a type checking error
Enums
You can create an enum with the following syntax
enum Days { Monday = 1, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday }
You can define an integer literal value for each of the elements. If you don't, they automatically get an integer value one higher than the previous element. If the first element hasn't been given a value, it will recieve the value 0. Two elements may not have the same value.
You can cast enums to/from int and byte, as well as to string.
Days myDay = Days.Thursday; int dayNr = (int)myDay;//Will get the value 4 dayNr++; myDay = (Days)dayNr;//Will get the element Friday string dayName = (string)myDay;//Will get the string "Friday"
Enrichments
Enrichments is a way to add properties and methods to non struct/class type variables. You can also use it to make a non struct type pointer be handeled in an array. See Array based pointers.
enrich unit { fixed HP { get { return UnitGetPropertyFixed(this, c_unitPropLife, true); } set { UnitSetPropertyFixed(this, c_unitPropLife, value); } } inline void Select(int player) { UnitClearSelection(player); UnitSelect(this, 1, true); } } void foo(unit u) { u.Select(1); u.HP++; }
You can enrich any type except structs or classes. So also pointers and arrays.
Constructors
It is now possible to define constructors in structs and classes.
They are defined like methods, except they have no return type, and they must have the same name as the enclosing struct/class.
class Foo { int A; Foo(int a) { A = a; } } void method() { Foo* foo = new Foo(2); ... }
Deconstructors
In addition to constructors, you can also define deconstructors. Theese will be called just before an object is deleted with the delete statement.
You can define them in both enrichments, structs and classes. In structs and classes, they must have the same name as the enclosing struct or class.
In enrichments, they can have any name.
class Foo { private Bar* b; //This is a deconstructor for Foo ~Foo() { //In this case, when foo is deleted, so is the variable b delete b; } }
You can also mark them as public/private/protected.
Array based pointers
With version 2.2.0, I added struct based pointers. Previously, all pointers was based on the data table, which means that all the values was entries in the data table.
Now you can specify that you want the struct/class pointers to be in a global array instead.
The advantage of having array based pointers is that they are faster than the data table.
On the downside however, you must specify an upper bound on the ammount of pointers you will have allocated at one time. This number will be the dimensions of a global array.
That means that the memory required by the entire array will be reserved all the time. That is a problem, because a map can't use more than 2mb of memory for the script.
So, keep this number as low as you can, while you are sure that you won't ever need more pointers than that.
You can define the bound with the following code.
struct[42] Str { int i; bool b; }
It works the same way for classes and enrichments.
Enheritance
Structs and classes can enherit all fields properties and methods of another struct or class with the following syntax.
struct Super { int i; Super(int a) { this->i = a; } void foo(int a) { i = a; } } struct Sub : Super { int j; Sub(int a, int b) : base(a)//Call to the constructor in Super { this->j = b; } void bar(int a) { foo(a); j = i; } }
You can refference all fields, methods and properties from a supertype in a struct.
It is not possible to cast a type to a type that enherits it, however you can assign a struct type to a variable of a supertype.
void foo() { Sub sub; Super super; super = sub;//Allowed sub = (Sub) super;//Not allowed }
It is also not possible to override anything in the subtype.
Properties
Properties are basically a convinient way of making a getter and setter method, but use them as a single variable.
Like fields, properties can be defined either globally, or as a memeber of a struct/class.
fixed radians; fixed Degrees { get { return radians*180/3.14159; } set { radians = value/(180/3.14159); } }
Both the get block or the set block are optional, and the order in which they apear makes no diffrence.
Note that in the setter, the keyword value is used to refere to the value that is being assigned to the property.
You use the property just as you would use a field.
void m() { for(Degrees = 0; Degrees < 360; Degrees++) { FireProjectileOfDeath(radians); } }
You can also create array properties, which means you can do stuff like this.
enrich unitgroup { unit this[int index] { get { return UnitGroupUnit(this, index + 1); } } int Count { get { return UnitGroupCount(this, c_unitCountAll); } } } Initializer { unitgroup group = UnitGroup(null, c_playerAny, RegionEntireMap(), null, 0); for (int i = 0; i < group.Count; i++) { unit u = group[i]; ... } }
This type of property can only be placed inside structs and enrichments. The type of the index variable can be any type, as long as it doesn't result in a conflict with a normal array index. The property has to have the name this, but the index variable can have any name.
Bank preload statement
The preload bank statement from GUI triggers is not an actual method call in code, so I added extra functionality to call this.
PreloadBank("BankName", 2);
I felt that it would be misleading to place it inside functions, since it is not a statement which is executed there, but rather just a message to Starcraft II to load the bank when loading the map. Therefore it is placed out next to methods and fields. Note that the name and playerNr must be literals. I.e. you can not use any kind of variables or expressions other than what you see above.
Trigger declaration
There is a short way you can choose to specify triggers. Use the following notation
Trigger TriggerName { events { //Add the events the usual way TriggerAddEventMapInit(TriggerName); } conditions { if (...) return false; else if (...) return true; //Here, true is automatically returned } actions { //Add the actions of the trigger the usual way. } }
The events, conditions and actions sections are all optional. The conditions are only tested if testConds are true. The actions are only run if runActions are true, and testConds are false or the conditions return true.
If nothing is return from the conditions, true is assumed.
You can reference testConds and runActions from within the conditions and actions sections.
You can reference the trigger variable with the name of the trigger as done in the above example in events. You can also call the trigger function as you would normally be able to by typing TriggerName(<testConds>, <runActions>);
The return type in the actions section is void.
Operator overloading
You can define your own binary operators.
Initializer { point p1 = Point(1, 2); point p2 = p1 + 2.2;//p2 will then have the value (3.2, 4.2) } point operator +(point p, fixed f) { return Point(PointGetX(p) + f, PointGetY(p) + f); }
You can overload the following binary operators:
+, -, *, /, %, ==, !=, <, <=, >, >=, &, |, ^, <<, >>
Like methods, you can mark operators as public/private, as well as static.
Statements
A statement is basically the members of functions where it doesn't make sense to talk about it having a type. Examples of statements in galaxy are while statements, if statements and expression statements. In this documentation I will only cover statements that are new or have added functionality in galaxy++
.
If statements
In galaxy you were forced to place a block inside if statements, now you can also place a single statement without the block.
if (i < ar.length) i++;
For statements
I added for statements in galaxy++
.
for ([init]; [test]; [update]) [body]
Basically, what it will do is first execute the init, then for as long as the test evaluates to true, the body and then the update is executed. Like GUI for sentences.
Switch statements
I also added switch statements.
int ammount; bool isRanged = false; switch (GetUnitTypeString()) { case "Zergling": ammount = 100; break; case "Marine": isRanged = true; case "Zealot": ammount = 50; break; case GetSuperUnitName(): ammount = 1; break; default: ammount = 10; break; }
It will test the expression it gets in the first parenthesis against every case in the order they are listed. When one of them equals, it will execute the contents of the case. If no cases were equal to the expression, the contents of default will be executed. Note that it is possible to fall through to the next case if one doesn't write break, like it is done from marine to zealot. Another thing to mention is that the method GetUnitTypeString() will only be called once, no matter how many cases there are. Also, GetSuperUnitName() is only called if none of the above cases matched.
AsyncInvoke statement
The AsyncInvoke statement will call a method in a new thread, and continue its own thread. This is done by running a new trigger, so the operator stack is also reset in the process (in case you are wondering, this is a good thing :)). If you wanted to call a method like
int CallMe(int a, bool b){...}
you could write
InvokeAsync<CallMe>(2, false);
In case CallMe is in another namespace called OtherNS, you can write
InvokeAsync<OtherNS.CallMe>(2, false);
Since the target function is called in a new thread, it is not possible to return a value from it, so any return values are ignored.
Local declarations
I made it possible to make multiple local declarations in one statement as long as they are of the same type.
int a = 2, b, c = a + 1;
Array Resize statement
Dynamic arrays can be resized more quickly than deleting them and recreating them.
int[] array = new int[42](); array->Resize(20);//Will run through and delete the 22 last elements array->Resize(5912730);//Will take constant time
As can be seen from the comments, shrinking takes linear time in the number of elements removed, and extending takes constant time regardless of the new size.
Expressions
Expressions are everything that can have a type. Examples of this is method calls, references to local, global or struct variables, binary operations (+, -, *, /, %), etc. Like with statements, I won't cover the expressions that are the same in galaxy as in galaxy++
.
The ++
and --
expressions
I added support for the ++
and --
expressions. They can be placed before and after a variable, and will increment or decrement the variable. When placed after the variable, the current value of the variable is placed where the expression is, and then the variable is updated. For instance, if you write
int i = 0; ar[i++] = i;
then then you will have set the 0th index of ar to 1. Placing it before the variable will update the variable, and then the updated value is placed where the expression is. E.g.
int i = 0; ar[++i] = i;
will set the 1st index of ar to 1. This is most commonly used as a quick way of writing i = i + 1;
Invoke
Similar to the AsyncInvoke statement, this expression will call the target method via a trigger in order to reset the operator stack. Unlike AsyncInvoke however, this is not done in a separate thread. This means that all return values can still be fetched.
InvokeSync<namespace.methodName>(args);
Assignments
With galaxy++
you can now place assignments inside expressions rather than just in statements. For instance you can write
a = b = c = d = 2;
and all of them will have the value 2. Note that the type of the assignments are the type of the left side. What this means is that for instance if c is of type fixed, and b is an integer, you will get an error since fixed is not assignable to int.
Array length
You can get the length of an array by calling .length on it.
String[2] ar; return ar.length; //returns 2
Casts and implicit casts
I added cast expressions. They are a quick way of converting between types that can be converted between.
fixed f = 2.2; int i = (int) f;
I also made some implicit casts, which means that between some types the cast occurs automatically.
int i = 2; UIDisplayMessage(playergroupAll(), c_messageAreaSubtitle, "i = " + i);
In this example, the i is cast to a string, then the two strings are concatenated, and the whole string is cast to a text.
The this expression
You can use the this expression inside constructors and class methods. It is a pointer to the current class/struct.
class Foo { int* a; ... void Dispose() { delete a; delete this; } }
Expression if's
The syntax for creating an expression if is
<condition> ? <then branch> : <else branch>
If the condition is true, the expression will return the then branch, and otherwise the else branch.
Note that the types of the then and else branches must in some way be assignable to eachother. In other words, either the type of the then branch must be assignable to the type of the else branch, or the type of the else branch must be assignable to the type of the then branch.
int Tester(bool b) { return b ? 1 : 2; }
Pointers
This is placed a little out of place compared to the structure of the rest of the documentation, but I thought I would keep everything regarding pointers together.
Pointer types
You can define a type as a pointer by appending *. For instance
int* i; string** s;
Here i will be a pointer to an int, and s will be a pointer to a pointer to a string.
Dynamic array types
You can define a dynamic array type by not specifying array bounds. For instance
int[] ar1; int*[] ar2;
Here, ar1 is a dynamic array of type int, and ar2 is a dynamic array of pointers to int's.
The * expression
If you have an expression of pointer type, and you would like to get the value of that expression, you prefix it with *. For instance
void foo(string* s) { UIDisplayMessage(PlayerGroupAll(), c_messageAreaSubtitle, (text)(*s)); }
Here, the *is needed to get the actual contents of s. Also note that *s is in a parenthesis. If this was not the case the compiler would have tried to multiply a variable called text with the variable s.
The -> expression
The -> expression is really just a quick way of writing (*foo).bar.
struct Foo { int bar; } void method(Foo* foo) { foo->bar = 2; (*foo).bar = 2; }
Here, the two statements are equivalent. In both cases, bar will be set to 2.
The new expression
To create new pointers or dynamic arrays, use the new expression. For instance
int* i = new int(); int[] ar1 = new int[*i]();
Here, i is initialized to a new integer, and ar1 is initialized to a dynamic array of size *i (which will be 0 in this case).
Note that the new expression allocates a new instance in the data table. To avoid memory leaks, remember to call delete after you are done with the instance.
The delete statement
The delete expression will remove the supplied pointer or dynamic array from the data table. You should make sure that you call delete if you are done with your pointer or dynamic array. Note that the delete statement will only remove the actual pointer you supply to it. So writing
void foo(int*[] intAr) { delete intAr; }
Will remove the array, but will not remove any of the child pointers. If you wish to purge all allocated instances, you can clear the global data table with the method.
DataTableClear(true);
So, note that you shouldn't call this unless you wish to lose all pointers and dynamic arrays.
Null checks
As of 3.0.0, null checks are now reliable. What this means that if a pointer is uninitialized, pointing to a deleted object, or has been assigned null, writing (p == null) will return true.
int* p; Initializer { if (p == null) {//This will be true, since p has not been allocated yet p = new int(); } if (p == null) {//This will be false. ... } Wait(1, 0); if (p == null) {//This will be true if p was deleted during the wait ... } else { p = null;//Any null checks from here on will be true. } }
All of this is done with a constant ammount of operations (no loops).
Delegates (function pointers)
Definition
A delegate is a specification of a method. It is defined like a method, but without a body.
delegate int Comparer(MyStruct s1, MyStruct s2); ... void foo() { Comparer cmp; }
You can assign one type of delegate to another as long as the return types and parameters are explicitly assignable.
Delegate creation expression and invocation
To create a new "instance" of a delegate with the following code
MyDelegate d = delegate<MyDelegate>(MyMethod);
And then, to invoke the delegate, call .Invoke
d.Invoke(arg1, arg2);
If a delegate is called which has not been assigned a value, a runtime error will occur, and execution in that trigger will halt. Delegates are not dynamic types. There is no need to call delete for them.