JASS

JASS, J-Asynchronous Scripting SyntaxFact|date=September 2008 , is an event driven scripting language used in Blizzard Entertainment's "Warcraft III" game. Map creators can use it in the World Editor to create triggers and AI scripts.

Features

The language provides an extensive API that gives programmers control over nearly every aspect of the game world. It can, for example, give orders to units, change the weather and time of day, play sounds and display text to the player, and manipulate the terrain. It has a syntax similar to Turing and Delphi, although, unlike those languages, it is case sensitive. JASS primarily uses procedural programming concepts, though popular user-made mods to Blizzard's World Editor program have since added C++-like object-oriented programming features to JASS's syntax.

Sample code

The following function creates a string containing the message "Hello, world!" and displays it to all players:

function Trig_JASS_test_Actions takes nothing returns nothing call DisplayTextToPlayer(GetLocalPlayer(), 0, 0, "Hello, world!") endfunction

or if you want this only for one player:

function Trig_JASS_test_Actions takes player p returns nothing call DisplayTextToPlayer(p, 0,0, "Hello, world!") endfunction

And if you want to print the message 90 times and show the iterator:

function Trig_JASS_test_Actions takes player p returns nothing local integer i=0 loop exitwhen i=90 call DisplayTextToPlayer(p, 0,0, "Hello, world! "+I2S(i)) set i=i+1 endloop endfunction

Basic Syntax

JASS's syntax is similar to Turing. It is context free. Examples of basic syntax are shown below:

function syntax_Example_Sum takes integer i, real r returns real //function declaration must include: the keyword "function", //the function name, parameters (if any) and return type (if //it returns something) return i + r //return statements must begin with the keyword "return" endfunction //the keyword "endfunction" signals the end of a function block function syntax_Example takes nothing returns nothing local integer i //declaring a local variable requires the modifier "local", the variable's data type, and the variable name local real r = 5.0 //local variable declarations must come before anything else in a function and variables may be //initialized on declaration //separated statements MUST be placed on separate lines set i = 6 //the keyword "set" is used to rebind variables call syntax_Example_Sum( i, r ) //function calls must be preceded by the keyword "call" set r = syntax_Example_Sum( i, r ) //the "call" keyword is omitted when accessing a function's return value endfunction

Types

JASS is statically-typed, and its types can be separated into two classes: natives and handles. The native types are:
* integer (32-bit signed)
* real (32-bit floating point numbers, similar to the float type in Java)
* boolean
* code

All other types are considered non-native. The native types behave very similarly to primitive types in other programming languages. Handle types, however, behave more like objects. Handle types often represent an "object" within the game (units, players, special effects, etc.). Similarly to how Java treats Objects, all variables and parameters in JASS of handle types are treated as values, but in reality those values are nothing but references to the handle objects. This becomes important when dealing with garbage collection because handles, if not properly cleaned up, can cause significant performance issues. Additionally, any references to handles themselves take up memory space and if they are not nullified can also reduce performance, though on a much smaller scale.

function garbage_Collection_Example takes string effectPath, real x, real y returns nothing local effect specialEffect = AddSpecialEffect( effectPath, x, y ) //uncleaned handle types will continue to take up system resources endfunction function garbage_Collection_Example2 takes string effectPath, real x, real y returns nothing local effect specialEffect = AddSpecialEffect( effectPath, x, y ) set specialEffect = null //setting the variable to null is not enough, since it is only a reference to the handle; //the handle still exists endfunction function garbage_Collection_Example3 takes string effectPath, real x, real y returns nothing local effect specialEffect = AddSpecialEffect( effectPath, x, y ) call DestroyEffect( specialEffect ) //we destroy (clean up) the handle to free up memory set specialEffect = null endfunction function garbage_Collection_Example4 takes effect e returns nothing //do stuff call DestroyEffect( e ) //parameters do not have to be nullified endfunction

Another property of handle types worth noting is that all handle types are treated as if they were children of the "handle" type. Some of these children types have their own children types, and so on. Handle variables may reference its own specific handle type or any children type. For example:

function Trig_JASS_handle_Example_Child takes widget w, widget w2 returns nothing //do stuff endfunction function handle_Example takes real x, real y returns nothing local widget w //widget is a handle type with children type unit and destructible local unit u = CreateUnit( 'hfoo', x, y ) local destructible d = CreateDestructible( 'ATtr', x, y ) set w = u //acceptable call Trig_JASS_handle_Example_Child( w, d ) //acceptable endfunction

Type Casting

Of the primitive types, type casting between integer, real, and string is officially supported by the language. JASS supports both implicit and explicit type casting.

Implicit casting only occurs from real to integer. For example:

function type_Casting_Example takes nothing returns real local integer i = 4 local real r = 5 //implicit cast of 5 to real to satisfy variable type if ( i < r ) then //implicit cast of i to real set r = r / i //implicit cast of i to real in order to carry out real division endif return i //XXX: NOT allowed; JASS does not allow implicit casting from integer to real to satisfy return types endfunction

The JASS library provides several functions for explicit type casting:

*I2R(): casts integer to real
*R2I(): casts real to integer
*I2S(): casts integer to string
*R2S(): casts real to string

An important property of handle types related to type casting is that since all variables of handles are just references, they can all be treated (and are treated) as integers. Each instance of a handle is assigned a unique integer value that essentially acts as an identifier for the handle. Therefore, type casting from handles to integers, although technically not supported by JASS, is possible in practice because implicit casting from handle types to integer can and will occur if the code is written in a certain way, for example:

function H2I takes handle h returns integer return h endfunction

If the game ever reached the line "return h", it would in fact actually cast the handle to an integer and return the value. However, Blizzard never intended for JASS to be used this way, and so the JASS compiler will actually throw an error, warning the programmer that the function isn't returning the correct type. However, JASS programmers have found and exploited a now famous bug in the JASS compiler's syntax checker: the so-called "return bug". Essentially, the compiler will only make sure that the last return statement in a function returns the correct type. Therefore, the following code compiles without error and can be used to cast handles to integers

function H2I takes handle h returns integer return h //the function will stop executing after the first return statement, i.e. this one return 0 //the compiler will only check this statement for syntax accuracy, but it is in reality unreachable code endfunction

Arrays

Java supports one-dimensional arrays of any type. The syntax to declare arrays and access members in an array is outlined in the code below.

function array_Example takes nothing returns nothing //arrays cannot be initialized at declaration and their members will hold arbitrary values local integer array numbers local unit array units local boolean array booleans local integer i = 1 set numbers [0] = 1 //the syntax to initialize an array member is identical to that for any other variable, only a set of //brackets: [] must immediately follow the variable name with the index value of the specific member //to initialize inside the brackets set units [0] = CreateUnit( 'hfoo', 0, 0 ) //indexes for arrays always start at 0 loop exitwhen ( i > 8191 ) //the maximum size for arrays in JASS is 8192, which means that the last index of any array can //only be 8191 set numbers [i] = i //variables can substitute for constants when specifying the index value in the brackets set units [numbers [i] = null //array members can also substitute set boolean [i-1] = true //arithmetic (or functional) operations are also acceptable endloop if ( boolean [200] = true ) then //to access an array member, again the syntax is the same as for normal variables, only //with the addition of the brackets with the index value inside set numbers [200] = -200 //you can re-assign members of the array to different values endif endfunction

One limitation of arrays in JASS is that they cannot be returned by functions or passed as parameters to other functions, though array members may be returned (in a function that returns a unit, u [0] may be returned if u is an array of type unit).

vJASS

vJASS is a set of user-made extensions to JASS. It introduces object-oriented programming features to the language, such as structs, encapsulation, and polymorphism. [http://www.wc3campaigns.net/vexorian/jasshelpermanual.html#interfs vJASS Documentation] ] Strictly speaking, vJASS does not add anything to the JASS library but instead mostly uses JASS's own arrays and type casting to integers. The extension relies on a custom-made compiler that compiles vJASS code to strict JASS code. In this manner, no additional mods for either the World Editor program or Warcraft III are required, and maps made using vJASS code are fully compatible with any copy of the game, even those without the compiler.

References

External links

Documentation

* [http://www.wc3campaigns.net/showthread.php?t=74894 An Introduction To JASS] --A beginner's guide to the language, covering its basic features and capabilities.
* [http://jass.sourceforge.net/doc/ JASS Manual] --An advanced guide to the language, intended to serve as a reference for users who are already proficient with it. Includes a comprehensive API browser.
* [http://www.wc3jass.com/viewforum.php?f=22 Wc3jass Tutorials] --A collection of tutorials about the language.
* [http://www.wc3campaigns.net/tutorials.php?f=650 wc3c JASS Tutorials] --Other tutorials about the language.

Communities

* [http://www.hiveworkshop.com/ The Hive Workshop] -- A forum for discussing Warcraft III modding, including Jass.
* [http://wc3campaigns.net/ Wc3Campaigns] --A forum for discussing Warcraft III modding, art and many other Warcraft III related things.
* [http://www.thehelper.net/ TheHelper] --A forum for discussing global Warcraft III mapping, JASS scripting and more.
* [http://www.wc3jass.com/ The Jass Vault] --A forum for discussing JASS development with other programmers.
* [http://www.battle.net/forums/war3/board.aspx?ForumName=war3-maps Warcraft III Map Development] --Blizzard's official Battle.net forum for the World Editor.

Scripts

* [http://www.wc3jass.com The Jass Vault] --Contains a large collection of sample scripts.
** [http://www.wc3jass.com/index.php?scripts=1 JASS scripts]
** [http://www.wc3jass.com/files.php JASS-related files]
** [http://www.ClanMapz.com Map Making Clan]

Tools

* [http://wc3campaigns.net/showthread.php?t=80051 JassCraft] --Editor for JASS scripts.
* [http://jass.sourceforge.net/ JASS Tools] --Includes a syntax checker.