Functions

A function is declared in the following manner:

function func_name takes param_list returns return_type
     variable_declaration
     variable_declaration
     ...
     statement
     statement
     statement
     ...
endfunction

See Global Declarations for more information. Remember that you can not call functions you have not yet declared (no forward references), but you can call a function within itself (i.e., recursion is legal).

If a function declaration is prefixed with constant, like the following:

constant function const_func takes integer a returns nothing
     ...
endfunction

Parameters

As noted in the Globals Section, a function is declared with a comma separated parameter list which parameterizes the types of the arguments it takes. When calling a function, the caller passes in a list of argument expressions which evaluate to values of types conforming to the list of parameters. See Types for more information.

All integer, real, and boolean arguments have pass-by-value semantics. Because string and code values are immutable (can not be modified after creation), arguments with these types can be thought of as having pass by value semantics also. In other words:

function Foo takes integer a, string b returns nothing
     set a = 10
     set b = b + " is a dummy"
     // a == 10 and b == "joe is a dummy"
     // but the original arguments passed in are NOT modified
endfunction

...
     local integer i = 5
     local string  j = "joe"

     call Foo(i, j)
     // i is still == 5, and j is still == "joe"

However, all handle arguments (and handle subtypes) have roughly pass-by-reference semantics. In other words, modifying the "internals" of a handle variable, like a unit, passed to a function as an argument will alter the variable both within the callee function and the caller. For example:

function Bar takes unit u returns nothing
     call PauseUnit(u, true)
     // the unit u is paused, but u and y refer to the same
     // data structure so y is also paused
endfunction

...
     local unit y = GetTriggeringUnit()

     call Bar(y)
     // the unit y is paused

function Goo takes unit u returns nothing
     set u = CreateUnit(player1, 'hC00', 100, 100, 90)
     // u now refers to the newly created unit
     // but y still refers to the triggering unit
endfunction

...
     local unit y = GetTriggeringUnit()

     call Goo(y)
     // y still refers to the trigger unit

Local Variables

The first part of a function body consists of local variable declarations. These are variables which are initialized each time we enter the function and can only be referenced within the function. They are declared in the following manner:

     local type name = expression

This is similar to the global variable declaration. The expression is optional. There may be no local variables, in which case the function body only consists of statements (or is empty). Local variable names should not be identical to function parameter names.

Within a function, expressions can reference local variables, the names of function parameters, as well as global variables.

Statements

After the list of local variables is a list of statements which performs the actions the function wants to execute. See Statements for more information.

If the function returns a value, then every execution path in the function must reach a return statement which returns a value of the appropriate type.

Return Value

A function may be declared to return a value (if the return type is not nothing). In this case, calling the function as an expression will evaluate to a value. See Expressions for more information.

Return values have the same by-value/by-reference semantics as arguments (see above).

Entry Point Functions

AI scripts require a user-defined main function, while map trigger scripts require a main function and a config function. The config function is run before the game starts initializing the map. The main function is the entry point for execution when the game begins.

These must have the following prototypes, respectively:

function main takes nothing returns nothing

function config takes nothing returns nothing