- Reaction score
- 456
Learning vJass
Table of Contents
I. Introduction
II. Global blocks
III. Scopes
IV. Private members
V. Public members
VI. Libraries
VII. Text Macros
VIII. Final words
I. Introduction
There is not much to say about this, because this tutorial is quite simple. You don't need to know anything about vJass to understand this tutorial. You need NewGen in order to use these features.
Have a nice time reading my tutorial!
II. Global blocks
vJass allows us to use create global blocks anywhere in our code. Inside global blocks we can write global variables, that work exactly the same way as the ones we can create using the Variable Editor (CTRL+B). The 'udg_' prefix is needed no more.
If some JASS spell uses global variables, it's just pain in the ass to copy the globals from the Variable Editor, and paste them into your map. This way everything works prettier.
We're able to set their values like that. Globals may also be private or public.. and those are explained later on the tutorial.
vJass allows us to use sized arrays to give us more index space. Constant globals can be also used for the size value:
III. Scopes
Scopes are used when you're just writing normal code, like spells.
Scopes allow us to use private and public members inside them. The syntax for scopes is quite simple, as scopes start with scope keyword and end with endscope keyword:
JASS:
scope FirstScope
//Code goes here
endscopeScopes should be able to use numbers in their names, if you're using JassHelper 0.9.9.7 or later. But I am unable to do so.
You are also able to nest scopes inside scopes and libraries:
JASS:
scope FirstScope
scope ChildScope
endscope
endscopeIV. Private Members
Private members can be used inside a scope or a library. We can have as many members with a same name as long as they're private. But you can't have two private members with a same name in a same scope/library:
JASS:
That doesn't give any syntax errors. The names of the private functions will be randomized when the map is saved.
You are unable to call private members out of their library/scope:
JASS:
That gives us a syntax error.
V. Public Members
Public members makes sure that you don't overwrite other codes' members' names, but still you're able to call them from other scopes/libraries.
Public members can be used inside a scope or a library too. Public members will become this after you save the map, <scope/library name>_<member name>. I'll show you an example:
The name of the myFunc would be FirstScope_myFunc after saved.
There is an exception on the public members. If you have a function named InitTrig, it will become InitTrig_<scope/library name>. Here is an example:
The name of the InitTrig would become InitTrig_FirstScope after you save.
VI. Libraries
Libraries are used when a code needs another code, or when you need something on top of the map's script.
Libraries are similar to scopes, libaries have more possibilities, but they cannot be nested. Libraries are moved on top of the map's script when saved. The syntax for a libraries is quite same as scopes syntax, it starts with library keyword and ends with endlibrary keyword:
JASS:
library FirstLibrary
//Code goes here
endlibraryAlso libraries should be able to use numbers in their names.
With libraries you can control the order of the triggers when the map is saved. It is done like this:
JASS:
library FirstLibrary requires SecondLibrary
endlibrary
library SecondLibrary requires ThirdLibrary
endlibrary
library ThirdLibrary
endlibraryThirdLibrary is added on top first, because SecondLibrary requires it. SecondLibrary is added on top next, because FirstLibrary requires it. At last FirstLibrary is added on top. You can use requires, needs, or uses words. They all do the same.
Libraries can require many libraries:
JASS:
library FirstLibrary requires SecondLibrary, ThirdLibrary
endlibrary
library SecondLibrary
endlibrary
library ThirdLibrary
endlibrarySecondLibrary or ThirdLibrary is added on top before FirstLibrary, as it requires them both.
Watch that you don't make a requirement cycle:
JASS:
library FirstLibrary requires SecondLibrary, ThirdLibrary
endlibrary
library SecondLibrary requires FirstLibrary
endlibrary
library ThirdLibrary
endlibraryNow the WE can't know which is added on top first, FirstLibrary (requires SecondLibrary) or SecondLibrary (requires FirstLibrary). That gives a syntax error.
Libraries can also use initializer keyword. It is used like this:
JASS:
The callThisOnInit function is executed on map initialization.
Remember that you're able to nest scopes inside libraries:
JASS:
library FirstLibrary
scope ChildScope
endscope
endlibraryYou aren't able to nest libraries inside libraries, as library nesting is not allowed:
JASS:
library FirstLibrary
library ChildLibrary
endlibrary
endlibraryVII. Text Macros
Text Macros are used for.. well, think of a situation where you need many copies of the same code block, but maybe with different variable types. By using Text Macros, you can just write the code once inside text macro, and then run it as many times with different arguments, and the text macro replaces the parts of the codes you want with the arguments you give to it. Continue reading more, to know how they actually work.
Even though text macro might sound weird, it's one of the easiest features to understand from vJass. But still, it's very complicated to explain, so try to understand me as well as you can.
The syntax for text macros is different from others, as it has three parts.
To begin a text macro, //! textmacro NAME takes ARGUMENT 1, ARGUMENT 2..
To end a text macro, //! endtextmacro.
To "run" a text macro, //! runtextmacro NAME("ARGUMENT 1", "ARGUMENT 2"..).
I show you a simple example, where those three parts appear:
JASS:
//! textmacro SendMessage takes PLAYERID
function MessagePlayer$PLAYERID$ takes string message returns nothing
call DisplayTextToPlayer(Player($PLAYERID$), 0.00, 0.00, message)
endfunction
//! endtextmacro
//! runtextmacro SendMessage("1")As you can see, the text macro takes argument PLAYERID. Where we are running the text macro, the value "1" is for the argument PLAYERID. So, when we save the map, the $PLAYERID$ inside the textmacro gets replaced by that value we set for the PLAYERID. When we have use the arguments in the textmacro, they need dollar signs ($$) on their sides.
The result of that text macro would be:
JASS:
function MessagePlayer1 takes string message returns nothing
call DisplayTextToPlayer(Player(1), 0.00, 0.00, message)
endfunctionSee, the $PLAYERID$'s were replaced by 1.
A text macro can be ran as many times as we want, but as you already might know, the code inside the text macro just gets copied, so do not use same names for the functions and others inside them:
JASS:
//! textmacro SendMessage takes PLAYERID
function MessagePlayer$PLAYERID$ takes string message returns nothing
call DisplayTextToPlayer(Player($PLAYERID$), 0.00, 0.00, message)
endfunction
//! endtextmacro
//! runtextmacro SendMessage("1")
//! runtextmacro SendMessage("2")
//! runtextmacro SendMessage("3")Would be:
JASS:
function MessagePlayer1 takes string message returns nothing
call DisplayTextToPlayer(Player(1), 0.00, 0.00, message)
endfunction
function MessagePlayer2 takes string message returns nothing
call DisplayTextToPlayer(Player(2), 0.00, 0.00, message)
endfunction
function MessagePlayer3 takes string message returns nothing
call DisplayTextToPlayer(Player(3), 0.00, 0.00, message)
endfunctionNotice that text macros do not need arguments, and they can take multiple arguments.
VIII. Final Words
That's all I know about them, and pretty much all you need to ever know about them. I hope that you understood everything, as I tried to be as detailed as I could. For more information, check out the JassHelper manual - by Vexorian.
Thanks for reading my tutorial!
