How to use custom scripts in the Galaxy Editor

Status
Not open for further replies.

How to use custom scripts in the Galaxy Editor

Introduction

We all know by now that Blizzard has screwed up in their implementation of custom script in the
Galaxy Editor (GE). The “Convert to custom script” function in the World Editor (WE) that we all
grew to know and love appears to have vanished. So how the **** are we meant to use this new
awesome Galaxy script!?? This tutorial will show you how.

Prerequisites

What do you need to know to start this tutorial?
  • How to navigate around the GE.
  • How to create triggers with the Galaxy GUI.
  • How to insert actions into the Galaxy GUI.
  • And also, not strictly required, but recommended: basic knowledge of Galaxy scripting, or a
    similar language (such as C, C++, Java, etc).

The “Script Hack”

Some clever fellow at sc2mapster (if anyone knows who this is so I can give him credit, please tell
me) discovered a trick which allows us to use scripts other than the custom script actions, which are
contained inside function and hence disallow declaration of new functions, global variables or
structs. I’ll coin a name for it: the Script Hack. Here is how it works:

Step 1
Make a new trigger in GUI. Call it something like "Galaxy Main".
Trigger - Galaxy Main - 1.PNG

Step 2
Insert a Custom Script action with the following code:
Trigger - Galaxy Main - 2.PNG
This ends the function so that any following code is outside of any function.

Step 3
Insert a new Custom Script action. At the top you should probably put a comment like
// Galaxy code, so that anyone looking at the map knows that this is where your code is.
Trigger - Galaxy Main - 3.PNG

Step 4
One final Custom Action opens a new function, to avoid syntax errors caused by the compiler
automatically ending the function that you already ended. Make sure it returns a boolean, or you
will get a syntax error.
Trigger - Galaxy Main - 4.PNG

Step 5
You need to initialise your script. It can't do anything if nothing makes it run! This is as simple as
making another GUI trigger underneath the main one with a custom script action to call your script's "init" function, for
example, this could be your "init" function, placed inside the second custom script action of the
"Galaxy Main" trigger:
JASS:
void init_Galaxy_Main ()
{
	TriggerDebugOutput(1, StringToText("Initialising Galaxy Main"), true);
}
In order to call it, you simply do this:
Trigger - Galaxy Main - 5.PNG

If you run the map, you should now see the text "Initialising Galaxy Main" to the left of the screen.

Including Scripts

I could have ended the tutorial there, and you would all be happy in the knowledge that you can
do anything with your Galaxy Scripts, but you'd also be quite unoriganised, and including scripts
from outside sources might be pain. There is a simple way to solve both of these problems:
inclusion.

So how to inclusion work? First, you import a script from an oustide file into your map (or mod)
and include it into your own scripts. You can build up a file structure to enhance organisation,
and split your systems into multiple parts, which makes them easier to manage.

How do you do it? Well, first, write a script. We'll call it HelloWorld. It will contain one function,
HelloWorld, which will print, you guessed it: "Hello World!" to the screen. Here is the code for
that script, which you should save into a file called "helloworld.galaxy".
JASS:
void HelloWorld ()
{
	TriggerDebugOutput(1, StringToText("Hello World!"), true);
}

The next stage is to import it into your map. Go into the import manager and import
"helloworld.galaxy" to "Scripts/helloworld.galaxy" by right-clicking on the "Document Files" area
and choosing Import Files. Click "browse", navigate to the containing directory, and click ok.
Your script should appear there. Make sure nothing else is ticked before selecting ok, or you may
end up importing much more than you intended to. If the file is not already in a "Scripts" folder, you
can make one by right-clicking on it and selecting "Move Files". In the "New Folder" box, type
"Scripts". After pressing ok, your script should be in the correct folder.
Import Manager.PNG

Congratulations on importing the script. Now you need to include this script into your
"Custom Script Trigger" by going into the "Galaxy Script" action and typing the line
include "scripts/helloworld.galaxy". Notice how it is all in lower case. For some bizarre
reason, all names are converted to lower case for the purpose of including, and any capitals cause a
"File cannot be found" syntax error.

Finally, you must call the function from your script:
Trigger - Galaxy Main - 6.PNG

Tips 'n' Tricks

This is a short list of things to do when using custom galaxy scripts to make your life, and the lives of
others, much easier:
  • Always prefix every function, struct and variable that your script uses with a standard prefix, such
    as "EoWSys_" (Element of Water's system) to avoid collisions.
  • Organise your files in the import manager, and always make sure all scripts are in some subdirectory
    of the "Scripts" directory.

Credits

  • that guy from sc2mapster.com who discovered the "Script Hack" (please let me know who he is)
  • Mooglefrooglian and several other people who didn't know how to do this, and inspired me to create
    this tutorial.

I hope you found this tutorial helpful. You will find a map containing all of the material used attached to
this post.
 

Attachments

  • Galaxy Demo.SC2Map
    33.8 KB · Views: 375
Level 8
Joined
Nov 20, 2008
Messages
445
Instead of all the shizzle with creating gui triggers with lame custom script things you could just explain how to modify the maps main script and then include and initialize all your libraries from there. Unless ofc you don't know how to do that. If that's the case PM me and I can explain how to do it to you so you can add it to the tutorial. Imo its the proper way of writing pure galaxy code.
 
Instead of all the shizzle with creating gui triggers with lame custom script things you could just explain how to modify the maps main script and then include and initialize all your libraries from there. Unless ofc you don't know how to do that. If that's the case PM me and I can explain how to do it to you so you can add it to the tutorial. Imo its the proper way of writing pure galaxy code.

Err... no. That way, every time you save your map you have to re-import your map script with an MPQ editor, so you have to close the map (the GE "locks" the files so nothing else can access them) and re-open it to test it, and my way GUI triggers can work too in case you have lots of people working on the map (remember, in SC2 the only advantages pure code have over GUI are readability and speed (of input / typing)). Seriously, importing your own MapScript.galaxy is not the way to do it.

Besides, if you wanted to do something like that you could just import a file that acts as your main map script and just call its main function with the GUI triggers, which has all the advantages of both ways.
 
Level 8
Joined
Nov 20, 2008
Messages
445
It still feeld uncomplete without adding that to the tutorial. And what MPQ editors are you talking about ? You just import the MapScript(named something else for example MainScript) into the map then rename it to MapScript.galaxy then hit save and it will automaticly overwrite the map generated one. And you have to do that only when you do something in the trigger editor(which will be never if you're using this way) or if you have changes to your main script.
 
Oh, I thought some file names were held (as in you can't import files by that name), including MapScript.galaxy, but I must be wrong. Maybe it's a bug?

I was referring to Ladik's MPQ Editor, which is what i used to put my map script into my maps before the Galaxy Editor was out, but I guess that's obsolete for this purpose now.

I still don't think I should put that into the tutorial considering the fact that my current method can do something very similar but without any of the drawbacks.
 
Level 11
Joined
Aug 1, 2009
Messages
963
Eh, bit of a necro, but I felt I should point this out.

You could just omit the last } and not include the end galaxy main part. Seems easier.

Oh, also, kinda odd, but you can't declare variables in custom script in normal GUI triggers. Kinda lame.
 
You could just omit the last } and not include the end galaxy main part. Seems easier.
Yes, you could do that, but the way I do it more organised; all of your main code is in one custom script action.

About declaring variables: that's probably because the script builder puts code at the top of the function automatically, and local variables must be declared at the top of a function.
 
Level 11
Joined
Aug 1, 2009
Messages
963
It isn't much different than JASS.

Basically the main difference is that you don't use any useless keywords like call, local, set, etc, you use { and } for all blocks (ie functions, if/thens, structs), and then you put a semicolon after each line or whatever.
 
Status
Not open for further replies.
Top