Global Declarations

We define a JASS program or script to be a series of *.ai and *.j files that make up either a runnable map trigger script or an AI script.

• A map script is responsible for initializing callbacks or triggers that are executed when certain events occur within a game. In addition, the map script generally initializes the map by creating the initial units and setting the initial properties of the map. The files that compose a map script are common.j, Blizzard.j, and war3map.j (loaded in that order).
• An AI script is responsible for the continuous execution of building, training, and attacking commands by a single computer player within a game. The files that compose an AI script are common.j, common.ai, and a user-defined AI script (e.g., human.ai, elf.ai, etc.).

common.j, Blizzard.j, and common.ai are located in the Scripts/ directory in the MPQ, but they can be overridded by placing them within a *.w3m. We call the declarations in these files library functions (and variables) since they are loaded with every map/AI script respectively. See Library Functions for more information.

war3map.j is located in each *.w3m map file. It is automatically generated by the World Editor each time you save your map (so if you edit it directly, it will be overwritten when you edit your map again in the World Editor). However, you can edit segments of it directly in the World Editor by creating a trigger and using the "Convert to Custom Text" option in the "Edit" menu.

In addition, to quote Brett Wood, "In the Trigger Editor [of TFT], if you select the root of the tree on the left (the map name at the top), you can enter arbitrary custom script code on the right. This script code is included in the map script right before all of the trigger code. This is a good place to write custom functions, which can then be used by multiple triggers. Theoretically, you could even do all of your scripting here, and not make any 'regular triggers' (although you'd probably still need at least one to call into your script code somewhere)."

Note that variables you create with the Variable Editor in the World Editor are global variables. However, when the World Editor actually creates the map script, it will transform the variable names by prefixing udg_ and replacing spaces with underscores (_). For example, if you create a variable caled my unit group in the Variable Editor, you would actually refer to it as udg_my_unit_group in the map script.

A JASS script consists of a series of global declarations. Global declarations consist of:

• type definitions
• global variables
• native functions
• user defined functions

In each file, type declarations and global variables must be declared before all user-defined function declarations. In all cases, you can not refer to declarations made after the reference (i.e., you must declare a type on a line before you extend it; you must declare a global variable on a line before you refer to it in an expression; and you must declare a function on a line before you call it, with the exception that a function may call itself). Each declaration begins on a new line (some span multiple lines).

Type Definitions

JASS allows user-defined types to be declared with the following, where new_type is the user type being declared and parent_type is the previously defined type that this type is a subtype of. See Types for more information.

type new_type extends parent_type

In each file, these must be declared before all functions.

Global Variables

There are two scopes for variables in JASS: global and function. Variables declared in global scope can be referenced from any function; variables declared in a function and function parameters can only be referenced within that function. Global variables are declared in the following manner:

globals
     type name = expression
     type name = expression
     type name = expression
     ...
endglobals

All declarations are enclosed within a globals block, and each is on a separate line. type is the type of the variable. This may either be a basic type or an array of basic types, declared as type array name. See Types for more information. name is the name of the variable and expression is an optional value to initially assign the variable. See Expressions for more information.

A non-array variable declaration may be prefixed with constant. This means the variable contains a value that can not be changed later (e.g., you can not use set on it). Hence, constant variables must be initialized with a value.

For example, here is an integer variable initialized to the value 10:

     integer numberOfStuff = 10

A constant integer variable initialized to the product of two other variables:

     constant integer howManyUnits = numberOfGrunts * numberOfAttacks

A string variable that is not initialized:

     string someMessage

An array of units. Arrays can not be initialized.

     unit array listOfUnits

In each file, the globals block must be declared before all functions and there can only be one globals block.

Native Functions

Native functions are functions that are implemented within the Warcraft III engine. They form the API which the game exports to JASS programmers. Unless you have access to Warcraft III's source code, you probably will not be defining a new native function, but you will probably call them. Their prototypes are declared in common.j, common.ai, and Blizzard.j. The prototypes look like the following:

native func_name takes param_list returns return_type

For example, a native function that takes a string and a unit and has no return value:

native MakeUnitTalk takes string whatToSay, unit targetUnit returns nothing

Native functions may be declared with constant as a prefix. See Functions for more information.

User-Defined Functions

A user-defined function is similar to a native function but has a body consisting of its implementation (e.g., what it does). It is declared in the following manner:

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

The prototype values are the same as with native functions. The function body consists of a series of local variable declarations followed by a series of statements (either of which may be empty). See Functions for more information.

Functions may also be declared with constant as a prefix.