JASS: An Introduction to Structs

[Tom_Kazansky]

i have a question.In my map, i make a spell that uses a 0.04 timer to move a projectle, the problem is when i cast this spell many times at a same time, it causes lag. if i use structs to make this kind of spell, will i get that problem ?

 

[The Undaddy]

I basically got everything except the unitData.create().What does the method create do?Return a random integer or what?Also whats a unitData variable?

 

[SFilip]

Not random, it returns the first unused number (from 1 to 8190).
For example if you have three structs active (with indexes 1, 2 and 3) it will return 4.

 

[NetherHawk]

can there be an example of retrieving data o.o? do i have to create a struct for every trigger and every thing i want to attach some data to? do structs require anything in the header?

 

[phyrex1an]

The line

  local unit u=call CreateUnit(playerId, heroTypeId, x, y, 270) //creates the hero and puts it in the variable to be returned

should be

  local unit u= CreateUnit(playerId, heroTypeId, x, y, 270) //creates the hero and puts it in the variable to be returned

 

[Tinki3]

Thanks for the heads-up phyrex .

Fixed.

 

[Technomancer]

Ok - so for all of you that are asking what exactly a struct is, I'll lay down the law:

First of all you have to understand what happens when you declare a variable. Take this code:

function omgDeclareVariable takes nothing returns nothing
local integer i = 0
endfunction

The middle line can be broken down into four parts:
local
Tells the compiler to rename this variable to a random code and delete it at the end of the function.
integer
Variable type is set to integer. The game cache is accessed, and however many bytes an integer takes up are reserved.
i
This is just a name you give your variable to identify it and make it unique.
= 0
An initializer. Without this, in higher level code, the space would be reserved for the integer, and whatever accessed the int would get whatever was in that space. = 0 clears the space.


Now, think of a struct as making your own kind of integer.

struct potato
boolean redskinned
real weightingrams
real heightininches
real widthininches
endstruct

Now you can create a variable of type "potato", like "i" is an "integer". Really, it's all ones and zeros. Since the compiler doesn't know wtf a potato is already, you have to tell the compiler in advance how much memory to reserve for a potato, otherwise you could overwrite other potatoes, other integers, and half your operating system by running over the amout of memory allocated to you. You do this by declaring it's members (or the parts of the potato that you need to save data for). That way, the compiler knows to save room for one boolean variable (1 byte) and 3 real type variables (like 50 bytes or something, I dunno).

Now later, you have a new type of variable, not to repeat myself, but this is like an integer. So we can declare it like a variable.

local potato Tater = potato.Create()

You don't have to type struct anymore, because the structure for the variable type is already defined for the compiler, so now it can just create a potato (again, just like creating an integer), reserve memory for it, and allow you to mess with it.

How to mess you ask? That's what methods are for. Methods are functions inside of a struct that allow you to access their data. Essentially, treat them just like that: functions inside of a struct. I'm not the WC3 struct master yet, so I don't know of you can directly access the variables, but the method functions you define should do all the manipulating for you (cleaner code), and be very clearly named, because you'll be using them alot.

Oh! I forgot to add. You call method functions by using the "." operator. The "." tell the compiler that THIS is a part of THAT. (THAT.THIS)

Example

struct demo
integer demovalue
method DemoSetup takes nothing returns nothing
set this.demovalue = 3
endmethod
endstruct

function sillyfunction takes nothing returns nothing
local demo D = demo.Create() //create the struct
call D.DemoSetup()
endfunction

So that will create a "demo" variable, and then call it's setup function (aka method) which we created in the struct, which sets demo.demovalue = 3. We can't access demovalue without another method, so we'll have to create that later, but the syntax is all the same all over, to the letter, as making functions.

One more thing anything a method calls inside it's own struct needs to be called with this.whatever, because otherwise you get an error, and that's the plain and simple truth.

 

[The Helper]

5 Star Bump

5 Star Bump!

 

[Light Alkmst]

I've heard and used GameCaches to transfer and keep track of unit data (just like ppl used to), but how do structs do it? Would it become accessible like global data? How would I access the structs in timers where I wouldn't know the structs name, as in, how would I know which struct the unit had attached? This may have been in the tut, but my mind's too warped and tired right now, and I may have missed something...

and another question

what does setUnitUserData() do? Is it only used in vJass?

EDIT: I re-read it really quickly, so my guess is SetUnitUserData() binds the struct to the unit and GetUnitUserData() gets the struct bound to the unit?

 

[Darthfett]

but how do structs do it? Would it become accessible like global data? How would I access the structs in timers where I wouldn't know the structs name, as in, how would I know which struct the unit had attached? This may have been in the tut, but my mind's too warped and tired right now, and I may have missed something...

This is where attachment systems come in...

Look a few up:

TimerUtils, CSData, HSAS, ABC, HAIL, ABCT, PUI, DUI, etc. There's tons of them, and many allow you to attach/ get the attached "integer" from a unit. Structs are actually integers, so you just attach the struct as an integer, and there you go.

This technique (referring to all the data inside a struct as a single integer) is called Encapsulation.

 

[Light Alkmst]

struct ?= attachment system? i thought so...?

and can you check what's attached to a timer?

 

[Darthfett]

struct ?= attachment system? i thought so...?

and can you check what's attached to a timer?

A struct is a 'wrapper' for all the contents. That way, instead of having to attach every single thing inside to a timer, you can just attach the struct itself.

Here's one attachment system for ya:

library CSData

    //****************************************************************************************************
    // CSData 15.2
    // ¯¯¯¯¯¯¯¯¯¯¯
    // CSDatas are like UserData in units and items, they are faster than gamecache unless you have more
    // than 8191 handles in your map. In that case it would be a little slower but only for those
    // handles. And if you have more than 8191 handles your map is too slow already anyways.
    //
    // Notice that for public spells or systems to be distributed you should only use these
    // for private objects (those who the mapper would never have access to) If you are making something
    // for your map you can use them wherever you want.
    //
    // Best to be used in conjunction to CSArrays so you just specify an array id for a handle.
    //
    // DO NOT USE THIS ON THESE HANDLE TYPES: -lightning, -ubersplat, -image, -texttag,
    //                                        -any 'argument' handle (like playerstate, damagetype, etc)
    //
    //****************************************************************************************************

    //====================================================================================================
    globals
        private constant integer MAX_HANDLE_ID_COUNT = 50000
        // values lower than 8191: very fast, but very unsafe.
        // values bigger than 8191: not that fast, the bigger the number is the slower the function gets
        // Most maps don't really need a value bigger than 50000 here, but if you are unsure, leave it
        // as the rather inflated value of 408000
    endglobals

    //=================================================================================================
    // a.k.a H2I, changed name to CS_H2I to prevent conflicts with other systems, it then stayed that
    // instead of changing to a private or public function since many outside spells use it.
    //
    function CS_H2I takes handle h returns integer
        return h
        return 0
    endfunction

    //==================================================================================================
    globals
        private integer array csdata[MAX_HANDLE_ID_COUNT]
        private constant integer MIN_HANDLE_ID=0x100000
    endglobals

    //It is dependent on jasshelper's recent inlining optimization in order to perform correctly.
    function SetCSData takes handle h, integer v returns nothing
        debug if(CS_H2I(h)-MIN_HANDLE_ID>=MAX_HANDLE_ID_COUNT) then
        debug     call BJDebugMsg("SetCSData: Handle id too big, increase the max handle id count or use gamecache instead")
        debug endif
        set csdata[CS_H2I(h)-MIN_HANDLE_ID]=v
    endfunction

    function GetCSData takes handle h returns integer
        debug if(CS_H2I(h)-MIN_HANDLE_ID>=MAX_HANDLE_ID_COUNT) then
        debug     call BJDebugMsg("SetCSData: Handle id too big, increase the max handle id count or use gamecache instead")
        debug endif
        return csdata[CS_H2I(h)-MIN_HANDLE_ID]
    endfunction

endlibrary

And here's an example code:

scope Example

struct Data
    unit U
    timer whichTimer
endstruct

function Callback takes nothing returns nothing
    local Data d = Data(GetCSData(GetExpiredTimer())) //Here we get the data that was attached to the timer.
    call Data.destroy(d)
endfunction

function Start takes nothing returns nothing
    local Data d = Data.create()
    set d.U = GetLastCreatedUnit()
    set d.whichTimer = CreateTimer()
    call SetCSData(d.whichTimer,d) //Here we attach the struct d to the timer
    call TimerStart(d.whichTimer,0.05,true,function Callback)
endfunction

endscope

The attachment system 'links' the two items together.

 

[SanKakU]

i wish you guys who use comments in your jass scroll boxes would make additional comment lines so that i don't have to play scrolly scroll box throughout the entire tutorial...it's like right, left, right, left, right, left while trying to read a sentence it's really hard.

 

[MagnaGuard]

I'm confused, I know a bit of JASS so excuse the obvious questions

>>Whered the statBonus come from? It wasn't declared, and how is it the purpose? " set this.statCredits=this.statCredits+statBonus"

>> Where'd this.RaiseInt() come from? Is it a JASS native :S

>> Whats this.ModifyStatCredits and Pow(this.kills/20) //.25 stats at 10, 1 stat at 20, 2.25 stats at 30, 4 extra stats at 40 kills

>> Can you only attach this to a created unit though triggers?

 

[wraithseeker]

They are all struct members.

For the last question yes.

 

[MagnaGuard]

Can you please explain?

 

[wraithseeker]

>Where'd this.RaiseInt() come from? Is it a JASS native :S

Just calling a function.


> Whats this.ModifyStatCredits and Pow(this.kills/20) //.25 stats at 10, 1 stat at 20, 2.25 stats at 30, 4 extra stats at 40 kills

Some maths.

> Can you only attach this to a created unit though triggers?

Yes..

> Whered the statBonus come from? It wasn't declared, and how is it the purpose? " set this.statCredits=this.statCredits+statBonus"

Remember, statCredits is a member of the struct and statbonus is the real that the function takes.

 

[MagnaGuard]

So what are attachment systems like CSData for if you can attach it to a unit already?

 

[wraithseeker]

I don't know what CSData is but is it a struct attachment system? If it is then use TimerUtils if not use PUI.

 

[SanKakU]

it's been awhile but if i remember right it looks like a system like CSData among other things, makes up entirely new functions to be called. that's why when you try to call the functions in a spell that requires the system you get errors. normal jass doesn't have those functions, but they appear in the systems. i don't really understand any systems to tell you the truth, i've just used them.