JASS - vJASS (Light)

[1337D00D]

Whoops, Mod please renaname title to vJass, i messed up.

This is a tutorial on how to use some of the advanced JASS functions provided by vJass.

Stop! If you are not using the JASS NewGen Pack, don't bother reading this tutorial!

This tutorial will cover how to use:
Libraries
Scopes
Text Macros
Structs
<More later>

__________


Globals

You are able to use global blocks almost anywhere now.

globals
	integer val = 0
endglobals

__________



Libraries

Libraries are groups of functions that will be placed before any others in the map script. Useful if you have a function that is called by others.

Syntax:

library NAME [requires LIBRARY] [initializer FUNCTIONNAME]
...
endlibrary

Example:

library mylib
	function libfunc takes nothing returns nothing
	endfunction
endlibrary

libfunc() will be loaded before any other functions.

Library Requirements

Sometimes functions within libraries will need to be placed before other libraries. In this case, you use the "requires" parameter. The library name given here will be placed before this library.

Example:

library liba requires libb
	function libaf takes nothing returns nothing
		call libbf()
	endfunction
endlibrary

library libb
	function libbf takes nothing returns nothing
	endfunction
endlibrary

liba requires libb, so libb will be put before liba.
Note that you cannot have two libraries require each other.

Library Initializers

In cases where you need a function to be run before a certain library is loaded, use the "initializer" parameter. The function specified must take nothing.

Example:

function init_liba takes nothing returns nothing
endfunction

library liba initializer init_liba
	function run takes nothing returns nothing
	endfunction
endlibrary

Library Private

Functions within libraries can be labeled as "private". Functions that are private are only used within their library. Functions outside the library can have the same name as the private one. Useful if there are multiple functions with similar names.

Only functions within the library are able to call to that function.

To make a function private, simply add "private" before the "function" declaration.
Example:

library whee
	private function test takes nothing returns nothing
	endfunction
endlibrary

function test takes nothing returns nothing
endfunction

__________



Scopes

Scopes are similar to libraries, though they don't put the contained code at the top. Useful if you want to have private stuff.

Syntax:

scope NAME
...
endscope

Example:

scope myscope
	function scopetest takes nothing returns nothing
	endfunction
endscope

Scope Private

Same as Library Private

__________




Text Macros

This is something for all you lazy people. Textmacros allow you to make similar copies of other functions.

Syntax:

//! textmacro NAME [takes ANYTHING,ANYTHING,...]
	function...
	...
	endfunction
//! endtextmacro
//! runtextmacro NAME(PARAMETERS)

The text macro will replace $ANYTHINGS$ with whatever value you give it when you run it. It's kind of hard to understand, so look at the example.

Example:

//! textmacro dofunc takes FUNC,INSTANCE
function do$INSTANCE$ takes nothing returns nothing
	call $FUNC$
endfunction
//! endtextmacro
//! runtextmacro dofunc("DoNothing()","1")
//! runtextmacro dofunc("BJDebugMsg(\"HI\")","2")

This text macro will create two functions:

function do1 takes nothing returns nothing
	call DoNothing()
endfunction
function do2 takes nothing returns nothing
	call BJDebugMsg("HI")
endfunction

The parameters this text macro takes are FUNC and INSTANCE. Whatever you put as INSTANCE will be appended to "do". This is required, for if you left this part out it would create two functions with the same name.

Here's another example:

//! textmacro chat takes num
call TriggerRegisterPlayerChatEvent( gg_trg_Untitled_Trigger_001, Player($num$), "asdf", true )
//! endtextmacro
//! runtextmacro chat("0")
//! runtextmacro chat("1")
//! runtextmacro chat("2")
//! runtextmacro chat("3")

Here, you don't have to copy the whole line of code over and over again, just 0,1,2, and 3.

__________



Structs

Structs allow JASS to become more object-oriented. Kind of like Javascript or PHP class.

Example:

struct somestruct
	string message = "Hello!"
endstruct

function showmsg takes nothing returns nothing
	local somestruct s=somestruct.create()
	call BJDebugMsg(s.message)
	call s.destroy()
endfunction

This would display "Hello!".

Syntax:

struct NAME
...
endstruct

Create a struct:

	local STRUCTNAME VARIABLENAME=STRUCTNAME.create(ARGS)

Destroy a struct:

	call VARIABLENAME.destroy()

Note that you need to destroy structs when you're done with them. There's a limit of 8190 undestroyed structs at one time.

In order to get a variable within a struct:

	VARIABLENAME.VARIABLEINSIDEOFSTRUCT

Here's another example:

struct test
	real one=1
	real two=2
	real three=3
	real sum
endstruct

function add takes nothing returns nothing
	local test blah=test.create()
	set blah.sum=blah.one+blah.two+blah.three
	call BJDebugMsg(R2S(blah.sum))
	call blah.destroy()
endfunction

The above function will display "6.000".

Note that you don't need to null struct variables.
Structs also cannot have arrays in them.
Structs also instance themselves, so you can have two of the same structs out at the same time.

Struct Methods

Methods are functions within structs. That's it.

Example:

struct we
	string msg="Hello!"
	method sayit takes nothing returns nothing
		call BJDebugMsg(this.msg)
	endmethod
endstruct

function test takes nothing returns nothing
	local we s=we.create()
	call s.sayit()
	call s.destroy()
endfunction

To call a method:

	call VARIABLENAME.METHOD(ARGS)

Note inside the "sayit" method, I used "this.msg". To get a variable inside the same struct, use "this.".

Don't use GetTriggeringTrigger() or waits inside methods.


You can use structs to almost completely replace local handle variables.

struct spell
	real x
	real y
	unit target
endstruct

function Trig_Spell_Conditions takes nothing returns boolean
    return GetSpellAbilityId() == 'A000'
endfunction

function Trig_Spell_Timeout takes nothing returns nothing
	local timer t = GetExpiredTimer()
	local spell data = spell(GetHandleInt(t,"struct"))
	call SetUnitPosition(data.target,data.x,data.y)
	call data.destroy()
	call PauseTimer(t)
	call FlushHandleLocals(t)
	call DestroyTimer(t)
	set t=null
endfunction


function Trig_Spell_Actions takes nothing returns nothing
	local spell data = spell.create()
	local unit u = GetSpellAbilityUnit()
	local unit ta = GetSpellTargetUnit()
	local timer t = CreateTimer()
	set data.x = GetUnitX(t)
	set data.y = GetUnitY(t)
	set data.target = ta
	call SetHandleInt(t,"struct",data)
	call TimerStart(t,GetRandomReal(0,10),false,function Trig_Spell_Timeout)
	set u=null
	set ta=null
	set t=null
endfunction

//===========================================================================
function InitTrig_Spell takes nothing returns nothing
    set gg_trg_Spell = CreateTrigger(  )
    call TriggerRegisterAnyUnitEventBJ( gg_trg_Spell, EVENT_PLAYER_UNIT_SPELL_FINISH )
    call TriggerAddCondition( gg_trg_Spell, Condition( function Trig_Spell_Conditions ) )
    call TriggerAddAction( gg_trg_Spell, function Trig_Spell_Actions )
endfunction

This spell teleports the target unit back to its original position after a random number of seconds. This spell only uses local handle variables once, and is much faster because structs are faster than using GameCaches.





__________

More to come soon, this is a W.I.P.

 

[substance]

Im thinkin this should go in the JASS section?

Hmm, a very short explaination of vJass, but a explanation nonetheless. Maybe you should show each example in practical use? Either way, I'm happy to see the sight of vJass growing in this community.

 

[Chocobo]

It is more a small README to who doesn't want to read the whole README.

neatt

btw you should increase the size of "Stop!", because it isn't that readable in red.

 

[Sooda]

> [Tutorial WIP]

He is updating it more.

Some full working examples how to move/ use structs would be nice. It' s small but lets hope it will be useful. I' m waiting for this kind of tutorials.

 

[1337D00D]

**Updated with an example of struct usage and a few random other stuff.

 

[1337D00D]

**Update/Bump, includes private in libraries now.

 

[Rheias]

Great job!

Can you give a quick list of the rest of the features in NewGen pack? You don't have to explain them, just the names so I'll know what to look for.

Thanks.

 

[waaaks!]

i was reading the system in the map made by vex, what is that again? is the map in a frost island were you must survive, and i found some functions like libraries, structs, and scope, and i didnt understand any of those, now that you made this, ill understand it first and make my own libraries....i can say this tut must be in the tutorial submission, so that people can also make their own libraries structs and scopes....nice tut, but i cant rep you....

 

[emjlr3]

not too indepth, but it gets the job done, keep it updated

moved

 

[PurgeandFire]

1337D00D doesn't come on anymore. I saw this tutorial a long time ago when he posted it, it made me have a better knowledge of vJASS. Gj 1337.

 

[Sim]

Broken due to the Local Handle vars