Triggers/Definitions

Definitions

Definitions enable map makers to make their own Actions, Conditions, Events and Functions. Unlike Native definitions which interface directly with the SC2 game engine, map maker made definitions usually use a series of definitions from the Built-In trigger library to simplify complex but repetitive tasks like dialog item creation or attack wave logistics. Custom "Action Definitions" also have the advantage of being able to create new threads enabling parallel execution bypassing delays caused by what would otherwise be a series of wait actions.

Fields Description

Options

Type

What trigger sub-element this definition will be used for.

• Action: The definition will appear as an Action in the GUI
• Condition: The definition will appear as a Condition in the GUI
• Event: The definition will appear as an Event in the GUI
• Function: The definition will appear as a Function in the GUI

Options

• Create Thread: Creates a new thread when this definition is executed enabling parallel execution of actions.
  • Using Action Definitions with this flag enabled is a must if using For Each Integer actions that have a Wait action nested under them to prevent delays.
  • More information about Multithreading.
• Custom AI: (Unknown)
• Custom Script: Allows you to inject custom code in the action instances themselves. The Grammar View is replaced by an editable text box; this is where you inject the code.

• Hidden: Prevents this definition appearing in the GUI windows. Only use if this definition is extremely specialized or the GUI is becoming cluttered with low use custom definitions.
• Inline: (Unknown)
• Loop: Represents a looping operation which allows break statements. Note that this does not mean your action definition will automatically loop. All this means is that you will be able to insert break statements into your sub functions. Means nothing without the Sub-Functions option enabled.
• Native: Usually only used by the natives from the Built-In trigger library to flag that they use script directly linked to the SC2 game engine.
• No Script Prefix: Do not use any prefix for script identifier. For example, an action definition in some library could be named "lib2_gf_SomeAction", but with this option enabled, it would simply be "SomeAction".
• Operator: Represents an operation between values rather than an actual function call. Operators are useful for functions that act as dynamic or scope-specific variables. An example of this is with Pick Each Unit In Unit Group and Picked Unit, where the Picked Unit function has this option enabled.
• Restricted: Official Blizzard map only flag
• Sub-Functions: Enables Action and Condition functions to have additional definitions nested under them (like Logic conditions and Loop actions).

Event Response For

• What Native events trigger this definition if it is an Event Definition.

Return Type

The defined value of a specific Type returned by this definition if a Condition or Function definition

• Condition definitions must return a Boolean type
• The Return Type restricts what Function definitions appear as options available to define parameters of specific types belonging to other definitions (an Actor return type can only be used to define an Actor parameter).
• Share the same fields as Variables

Parameters

What values of specific Types need to be defined to use this definition within another definition or trigger.

• Used to define the parameters of definitions within this definition in the same way as a variable is able to be used.
• Share the same fields as Variables

Grammar text

• String seen in the middle of the lower right window of the GUI when using this definition
• Usually automatically generated

Hint Text

Text seen in the GUI window when browsing definitions to add a new sub-element or for functions to define a Parameter of an existing sub-element.

Custom Script Code

• Galaxy scripting language used by this definition

Local Variables

• The Local Variables used internally within this definition

Actions

• The Action Definitions performed by this definition
• Used to derive the defined Parameter values to return for Function Definitions
• Contain the If Then Else action definitions to return for Condition Definitions
• Have the list of actions that an Action Definition will perform

Advanced Concepts

Autovars

Autovars are scope-specific variables whose names are generated automatically per action/function instance. For example, one could save the value returned by a function in an Autovar, which will only be available in the scope it is created (the action, function, and sub-function scope). This is good for values that don't need to be saved in a real variable or values that will be disposed of shortly after creation and use. For example, the first line shows how to create an explicitly typed Autovar, while the second line shows how to create an implicitly typed Autovar. Note that sometimes you must use explicit types for Autovars, or the compiler will complain.

#AUTOVAR(g, string) = #PARAM(unit);
#AUTOVAR(i) = 10;

for (;; #AUTOVAR(i) -= 1) {
    DoThingsTo(#AUTOVAR(g));
}

Notice that the generated code is replacing the Autovars with generated variable names. outside of their own scope, these variables don't exist. Also note that assigning an Autovar to another Autovar is possible, but causes some issues with accessing that Autovar outside of the custom script code.

Ancestor Autovars

Ancestor Autovars are just a reference to an Autovar defined by some ancestor in the Action chain. This is how functions like Picked Unit get the current unit in the Pick Each Unit In Unit Group parent for its scope. It is called like so:

#AUTOVAR(var,ancestor:PickEachUnitInGroup)

The first parameter is the name of the Autovar in the ancestor, and the second parameter is ancestor: followed by the id of the Action to target as the ancestor. It is important to note that in order for the ancestor to be properly linked, the script identifier Based On Name option has to be Unchecked.

Parent Autovars

Parent Autovars are similar to ancestors, but they grab the direct parent in the Action chain. This is how Actions like Switch Case are able to grab the value of the parent Switch and compare it to their case value. It is called like so:

#AUTOVAR(var,parent)

The first parameter is the name of the Autovar in the ancestor, and the second parameter is simply the word **parent**.

Subfuncs

Subfuncs is a call that calls all of the actions that the user added under the specified Sub-Functions definition. For example, if you have an actions Sub-Function definition, then you would call those sub-functions like so:

#SUBFUNCS(actions)

Wherever you write this line, it is replaced in the compiled code by all the function calls the user of your action definition defined underneath that section.

Making a Custom "Pick Each X in Y" Loop

In order to make functionality similar to Pick Each Unit In Unit Group and Picked Unit, one action definition and one function definition is required. Say that you want to create a looping action that picks each field in a user type and does (Actions) for each Picked Field. Create an Action Definition with the options Action, Sub-Functions, and Loop. It is important to note that in order for the ancestor to be properly linked, the script identifier Based On Name option has to be Unchecked. Add a parameter called User Type with the type as Game Link - User Type. In custom script code, the following code would be entered:

#AUTOVAR(g, string) = #PARAM(userType);
#AUTOVAR(u) = UserDataFieldCount(#AUTOVAR(g));
for (;; #AUTOVAR(u) -= 1) {
    #AUTOVAR(var, string) = UserDataField(#AUTOVAR(g), #AUTOVAR(u));
    if (#AUTOVAR(var) == null) { break; }
    #SUBFUNCS(actions)
}

The first Autovar stores the user type as a string. The second Autovar stores how many fields are in that user type as an integer. The third Autovar stores the field as a string and if it is null, break the loop to avoid errors. After that it calls #SUBFUNCS(actions), which is whatever actions the user defined would happen for each picked field.

To create the functionality of Picked Field, the function definition needs to have the Operator option enabled and in the Custom Script Code, the following code should be added:

#AUTOVAR(var,ancestor:PickEachFieldInUserType)

Now, when you call the Picked Field function, it will grab #AUTOVAR(var) during each loop which is specific to that iteration.