Tutorial Basic Jass Tutorial

[Andrewgosu]

Basic JASS Tutorial​

So, you want to learn the JASS magic? Just stick around and read this tutorial then. Hopefully, it will give a reboost to your already damaged braincells. I was just kidding. Maybe.

Anyway, I tried to make this as informatory yet still, fun, as I could. Proceed.

Before we get started, you must understand the basics. That's why I have listed a somewhat boring, but very important list of definitions, which you have to know in order to learn JASS. Do not skip reading that (Well, for your own sake, of course).

After you have read it, proceed to step 1.


Definition: function

• In computer science, a subroutine (function, procedure, or subprogram) is a sequence of code which performs a specific task, as part of a larger program, and is grouped as one or more statement blocks.

Example:

function AddSpecialEffectLocBJ takes location where, string modelName returns effect
    set bj_lastCreatedEffect = AddSpecialEffectLoc(modelName, where)
    return bj_lastCreatedEffect
endfunction

"AddSpecialEffectLocBJ" - the name of the function.
"(takes) location where, string modelName" - the parameter list.
"(returns) effect" - the value it returns.

A function can take nothing and return a value.
A function can take a parameter and return nothing.
A function can take multiple parameters and return a value (Not multiple values!).
A function can take multiple parameters and return nothing.

"call AddSpecialEffectLocBJ(where, modelName)" - how to call a function. A function call.

Function is immediately ended, when it meets a "return". ("Skip Remaining Actions" in GUI)
​

​

Definition: native

• Belonging to one by birth; "my native land"; "one's native language".
• Characteristic of or relating to people inhabiting a region from the beginning; "native Americans"; "the aboriginal peoples of Australia".
• A person who was born in a particular place; an indigenous person.
• As found in nature in the elemental form; "native copper".

Example:

    native AddSpecialEffectLoc          takes string modelName, location where returns effect

Definition: constant

• Changeless: persistent in occurrence and unvarying in nature; "maintained
  a constant temperature"; "principles of unvarying validity".
• A quantity that does not vary.
• In mathematics and the mathematical sciences, a constant is a fixed, but possibly unspecified, value. This is in contrast to a variable, which is not fixed.

Example:

    constant integer   bj_MAX_PLAYERS                   =  12

Definition: variable

• In computer science and mathematics, a variable is a symbol denoting a quantity or symbolic representation. In mathematics, a variable often represents an unknown quantity; in computer science, it represents a place where a quantity can be stored. Variables are often contrasted with constants, which are known and unchanging.

Definition: local

• Local means "in effect only in a particular context"; the relevant kind of context is a particular function execution, a particular buffer, or a particular major mode. It is the opposite of 'global'.

Example:

function AddRandomInt takes integer i returns integer
    local integer x = GetRandomInt(10, 20)
    return i + x
endfunction

Whereas "x" is being a local variable of type integer.

Syntax for declaring local variables: local /variable type/ /variable name/ = expression (optional)
​

Definition: global

• Values (or Parameters) that apply to the whole system.
• A variable designation that means the entire script can read that variable. Opposite of a local variable.

Example:

function SetRandomReal takes real r returns nothing
    set udg_tmpReal = GetRandomReal(10., 20.)
endfunction

Whereas "udg_tmpReal" is a global variable of type real, which is given a new value.

Note: Global variables have an "udg_" prefix!
​

Step 1 - Preparing to learn JASS

Now, I assume(*) you have read the definitions list. Lets proceed.

Firstly, we need a professional JASS editing program, although, one can do JASS in notepad, too. But since, I assume(*) you're a total beginner in JASS, we need to have function search option and syntax highlighting.

The best(**) tool for that is JassCraft. Download it.

http://www.wc3campaigns.net/showthread.php?t=80105

Credits where due.

If you have searched for other tutorials, threads or posts about learning JASS and seen a "convert GUI into JASS and examine" suggestion, then I, I do not recommend that. It's wrong. You want to learn pure, fluid JASS, right? Forget converting GUI to JASS, then.


Open JassCraft.

The function search is a nice feature, which helps to learn faster. I highly suggest to learn the most common functions by heart.

The syntax check is a very useful tool, which helps to prevent us from copy pasting faulty code into World Editor.

And finally, the indent option. Learn to indent your code the correct way, for the sake of readability.


Proceed to step 2.

(*) Never assume anything.
(**) In my honest opinion.

Step 2 - Basic JASS

Well, no - I am not going to teach how to convert a GUI trigger and display a message to players. Lets start with something practical without being too hasty. Lets make a basic creep reviving function.

Start by clicking Ctrl+U or selecting Templates->New function. A template function without a name and parameter list should appear. Give the function a name.

TIP #1: Use descriptive names! Doesn't matter whether you're naming variables, function or something else.

Use capital letter to separate words. Avoid using numbers, slashes etc.​

I named my function "UnitReviveCreep", Unit - takes an unit, ReviveCreep - revives the taken unit. Simple, uh? Descriptive naming isn't that hard. Remember it!

After naming the function, we have to think what is the purpose of the function. My function will take an unit, x and y coordinates where to "revive" it. Lets do it! (Damn, it sounds so cliché)

function UnitReviveCreep takes unit whichUnit, real x, real y returns boolean

... takes unit whichUnit - unit is the type of the variable the function takes, "whichUnit" is the name of it. One can name "whichUnit" whatever he wants, but I try to be as descriptive as I can be.

As you can see, parameters are separated with commas.​

Now, you ask, why does it return a boolean. Well, because the unit is not a hero, we have to check, whether the unit is dead or alive in order to "revive" it. I mean recreating the same unit with revive.

Lets make an if/then condition to make sure the unit is not a hero and it's dead.

function UnitReviveCreep takes unit whichUnit, real x, real y returns boolean
    if (IsUnitType(whichUnit, UNIT_TYPE_HERO) == true) or (IsUnitType(whichUnit, UNIT_TYPE_DEAD) != true) then
        return false
        // The unit is a hero OR it is alive. Lets end the function.
    endif
endfunction

Note #1: JASS uses double signs to do comparisons.

a == b is 'a is equal to b'
a != b is 'a is not equal to b'
a > b is 'a greater than b'
a < b is 'a is less than b'
a <= b is 'a is less than or equal to b'
a >=b is 'a is greater than or equal to b'

Note #2: When doing a "IsUnitType" check, you always have to compare it with a boolean. Otherwise, it will bug.

Note #3: JASS is case-sensitive. "or" does not equal to "Or", "and" does not equal to "And".

Tip #2: To view all the unit types, type "UNIT_TYPE" into the function finder.​

Now, having made the check, we need to create the same type of unit for the same player at given coordinates.

function UnitReviveCreep takes unit whichUnit, real x, real y returns boolean
    if (IsUnitType(whichUnit, UNIT_TYPE_HERO) == true) or (IsUnitType(whichUnit, UNIT_TYPE_DEAD) != true) then
        return false
        // The unit is a hero OR it is alive. Lets end the function.
    endif
    call CreateUnit(GetOwningPlayer(whichUnit), GetUnitTypeId(whichUnit), x, y, GetUnitFacing(whichUnit))

The function names are quite self-explanatory. "GetOwningPlayer" gets the owner of the unit, "GetUnitType" gets the units type, e.g, a footman. No need to explain "GetUnitFacing".

But something is a miss. The function returns a boolean, but, if the function passes the conditions, it will return nothing.

function UnitReviveCreep takes unit whichUnit, real x, real y returns boolean
    if (IsUnitType(whichUnit, UNIT_TYPE_HERO) == true) or (IsUnitType(whichUnit, UNIT_TYPE_DEAD) != true) then
        return false
        // The unit is a hero OR it is alive. Lets end the function.
    endif
    call CreateUnit(GetOwningPlayer(whichUnit), GetUnitTypeId(whichUnit), x, y, GetUnitFacing(whichUnit))
    return true
    // The unit was not a hero nor was it alive. The function was a success.
endfunction

Now it's complete. Your very own "custom script" ready to be inserted into your maps header.

How to call it? Just like any other function. Allow me to do some pseudo-code.

"call UnitReviveCreep(GetTriggerUnit(), xCoord, yCoord)". Just like that.


Proceed to step 3.


Step 3 - examples

A picture is worth more than a thousand words. Well, lets replace "picture" with "example". Aren't I clever, am I?

Example: if/then, if/then/else, elseif

function IfThen_Example takes boolean flag returns integer
    // if (condition(s)) then.
    if (flag == true) then
        return 1337
    endif
    // all if's end with an "endif".
    return 0
endfunction

function IfThenElse_Example takes integer i returns integer
    if (i == 1) then
        return 1337
    // else, no "then" after it.
    else
        return 0
    endif
    return 0    
endfunction

function Elseif_Example takes integer i returns integer
    if (i == 1) then
        return 1337
    // elseif has a "then" after the condition.
    elseif (i == 2) then
        return 666
    elseif (i == 3)
        return 7
    endif
    return 0    
endfunction

Example: Loop

function Loop_Example takes nothing returns nothing
    local integer index = 0
    
    // "loop" to mark the beginning of the loop.
    loop
        // exitwhen (condition(s)) to exit a loop.
        exitwhen (index > 50)
        ...
        set index = index + 1
    endloop
    // "endloop" to mark the end of the loop.    
endfunction

function Loop_Example takes unit whichUnit returns nothing
    loop
        // A exitwhen condition, which deals with an unit's health.
        exitwhen (GetUnitState(whichUnit, UNIT_STATE_LIFE) > 100)
        call TriggerSleepAction(.25)
        // A wait, to ensure the loop doesn't meet the execution limit. REQUIRED.
    endloop
endfunction

That's enough for today, folks.

Thank you for reading this tutorial. Feedback is appreciated.

 

[~GaLs~]

>That's enough for today, folks.

Is it more to come..?
Arh..i can understand the taking perimeter but still cant understand the return value...can make it more understandable..?

Sry for my idioties

 

[Rheias]

Returning returns something... Think about triggering unit. When refering to triggering unit you are refering to unit, right? Well, so are all returning values. When you have a function that returns an integer, when refering to that function you will get an integer that you can manipulate etc...

 

[Doom-Angel]

Great tutorial +Rep

 

[elmstfreddie]

I'm kind of disapointed by this. I don't know what to say, it just wasn't very informative...
At the beginning you said you'd try to make this fun... Well, it wasn't, but I don't see how any tutorial could be fun :nuts:
The definitions were stupid. Those mean absolutely nothing to anyone. Try to describe a function, not some stupid dictionary definition.

Oh, and you use (*) and (**) but there is nothing at the bottom or anywhere which tells me what these *s are referring to :nuts:

 

[WarLuvr3393]

Great tutorial. But I think Ghan has written one recently too...hmmm.

 

[Sim]

There are too many JASS tutorials around now, unfortunately.

 

[Ghan]

> There are too many JASS tutorials around now, unfortunately.

Yeah, seems we just had an explosion of them.

 

[Andrewgosu]

Yes, but most if not all, convert GUI to JASS. I don't recommend doing that.

The definitions were stupid. Those mean absolutely nothing to anyone. Try to describe a function, not some stupid dictionary definition.

Oh, and you use (*) and (**) but there is nothing at the bottom or anywhere which tells me what these *s are referring to :nuts:

Don't speak for everybody.

Can you describe what a function is? Thought so.

There isn't one and only, correct definition. There are plenty. That's why you can see examples below.

(*) Never assume anything.
(**) In my honest opinion.

There are too many JASS tutorials around now, unfortunately.

Unfortunately?

 

[Sim]

> Unfortunately?

I mean for this one

> Yes, but most if not all, convert GUI to JASS. I don't recommend doing that.

This is why I approved Ghan_04's tutorial.

 

[elmstfreddie]

Yes, but most if not all, convert GUI to JASS. I don't recommend doing that.

I forgot to mention that that actually really helped me when I first learnt JASS. It explains lots of things, like how GUI uses BJs and useless function calls and really bad overall scripting. It's like an introduction to efficiency, which is why you switched to JASS in the first place.

 

[Andrewgosu]

I see nothing efficient in GUI->JASS conversion... It helps to learn the most common functions by heart, but it's far from efficient.

Besides, the conversion makes the function's names loony, doesn't teach descriptive naming.

 

[elmstfreddie]

I see nothing efficient in GUI->JASS conversion... It helps to learn the most common functions by heart, but it's far from efficient.

I said it helps you learn efficiency by correcting the total uber noobiness of the conversation (ie those stupid functions for every if/then/else, the crazy condition if (not( then etc)

 

[Andrewgosu]

I said it helps you learn efficiency by correcting the total uber noobiness of the conversation

That's turtle-work. Why not do it right in the first place?

 

[~GaLs~]

=.=

Originally Posted by elmstfreddie View Post
I said it helps you learn efficiency by correcting the total uber noobiness of the conversation

I alwayz use this to learn....

>>That's turtle-work. Why not do it right in the first place?
Bcoz i just dun know how to write jass....editing the coverted is the best option for GUI to Jass people

 

[Andrewgosu]

Bcoz i just dun know how to write jass....editing the coverted is the best option for GUI to Jass people

That's why there are professional JASS editing programs, like JassCraft.


Anyway, why are we arguing, again?

There's my taste and recommendation and there's others. Suit what's best for yourself.

This is a tutorial.

 

[~GaLs~]

arh...when are we argueing @@?
But this is nice...though i still cant understand how to use return ><''

 

[Andrewgosu]

The parameter list is basically the input value.

function Pandamonium takes unit whichUnit returns ...

The return value is the output.

...returns real

function Pandamonium takes unit whichUnit returns real
     return GetUnitState(whichUnit, UNIT_STATE_MAX_LIFE)
endfunction

This function takes a unit and returns it's max life.


Think of it like that:

The ATM machine is the function, metaphorically.

Your bankcard is the value used in the parameter list. The takes ... part. Input.

And the ATM machine returns cash after a successful transfer, right? However, it needs your bankcard to do that.

function ATMmachine takes bankcard yourCard returns cash
     return GetYourCash(yourCard, GetPinCode(yourCard))
endfunction

 

[~GaLs~]

o.o
I think i make some sense from here....
The returned value is what u be wanted from the function and the taking value is the procedure of the function?

 

[Andrewgosu]

Well, almost right.

To put it even into a simpler form: the parameters are the "ingredients" needed for the function to return a value.

But sometimes, there are no ingredients needed, but a value is still returned.

constant function SPELL_ID takes nothing returns integer
     return 'A000'
endfunction

However, time to time, a function needs one or more "ingredients", but doesn't return a value at all!

function DoSomeRandomStuff takes unit whichUnit, real x, real y, real addOn returns nothing
     call SetUnitPosition(whichUnit, x + addOn, y + addOn)
endfunction

A function may not have single "ingredient" nor a return value.

function Pandamonium takes nothing returns nothing
    call KillUnit(bj_lastCreatedUnit)
endfunction

Lastly, a function which takes a single parameter - "ingredients" -, or more, and returns a value.

function GetUnitMaxLife takes unit whichUnit returns real
     return GetUnitState(whichUnit, UNIT_STATE_MAX_LIFE)
endfunction