How to develop spells with effects over time

Introduction.

Ok, the purpose of this tutorial is to give a general idea about how to make spells with effects over time, with a focus in the usage of some of the new features of vJASS and as addition I will treat with some aspect related to spell stackability and optimization according to the situations. In order to follow it you MUST have some experience in JASS and hopefully vJASS.



Basic Concepts.

What are scopes and libraries?? well, this is not something easy to explain but you can understand it by seeing the examples of the JassHelper manual. Libraries - Scopes

What's a struct?? A struct is a way to "pack" several variables and functions, so they can be called as one object. This is the concept that we're going to work here more deeply.

With the new improvements made by Vexorian, structs can be set in several ways, but right now I'll start with something very easy, showing little by little more features that a struct can do.

Because an example is the best way to see how this technique works, I'll do it with a spell which deals damage over time to a unit. You can extrapolate this to other situations.



Starting the Spell Development.

Ok, we know how to start. Let's create a custom ability (in this case base it on slow), set the fields that you consider more appropriate, create a custom buff for that spell and assign it to that ability in the buff field. After this, create a new trigger, in GUI set the event to "Unit - Generic Unit Event" and then select "A unit Starts the effect of an Ability", in Conditions select an "Ability Comparison" select "ability being cast equal to <your custom ability name>". Then Select in the Edit menu "Convert to custom script" and the funny thing will start.

Ok, we get this:
function Trig_Rabid_Bite_Conditions takes nothing returns boolean
    if ( not ( GetSpellAbilityId() == 'A000' ) ) then
        return false
    endif
    return true
endfunction

function Trig_Rabid_Bite_Actions takes nothing returns nothing
endfunction

//===========================================================================
function InitTrig_Rabid_Bite takes nothing returns nothing
    set gg_trg_Rabid_Bite = CreateTrigger(  )
    call TriggerRegisterAnyUnitEventBJ( gg_trg_Rabid_Bite, EVENT_PLAYER_UNIT_SPELL_EFFECT )
    call TriggerAddCondition( gg_trg_Rabid_Bite, Condition( function Trig_Rabid_Bite_Conditions ) )
    call TriggerAddAction( gg_trg_Rabid_Bite, function Trig_Rabid_Bite_Actions )
endfunction


And we'll convert into this:
scope RabidBite

globals
    private constant integer SpellID = 'A000' //Spell Rawcode.
endglobals

private function Conditions takes nothing returns boolean
    return GetSpellAbilityId() == SpellID
endfunction

private function Actions takes nothing returns nothing
endfunction

//===========================================================================
function InitTrig_Rabid_Bite takes nothing returns nothing
    set gg_trg_Rabid_Bite = CreateTrigger(  )
    call TriggerRegisterAnyUnitEventBJ( gg_trg_Rabid_Bite, EVENT_PLAYER_UNIT_SPELL_EFFECT )
    call TriggerAddCondition( gg_trg_Rabid_Bite, Condition( function Conditions ) )
    call TriggerAddAction( gg_trg_Rabid_Bite, function Actions )
endfunction

endscope

As we can see, we've added the scope, we have shorten the functions names and we've started to apply good programming practice by setting the constant variables which will allow to a spell user customize the code (mandatory if you want to comply with the JESP standard).

With this we have part of the spell skeleton, now we need to define what information must be managed by the spell. In this specific case the ability needs to damage an enemy, so we'll need to store the unit who cast the spell and the target, therefore this preliminary info will be part of our spell struct.

private struct Data
    unit caster
    unit target
endstruct

Things to notice: Why private? because we don't want that other functions but the ones of the trigger can access to that struct, if you need that other functions can call that struct, then you should make it with a more appropriate name and remove the private keyword. You've noticed that I've used the name data, in this case there's no problem because this struct only has sence in this scope, so we can set them with short or very stardard names and JassHelper will do the ugly job of differentiation for us

Now the spell skeleton has grown and it could look in this way:

scope RabidBite

globals
    private constant integer SpellID = 'A000' //Spell Rawcode.
endglobals

private struct Data
    unit caster
    unit target
endstruct

private function Conditions takes nothing returns boolean
    return GetSpellAbilityId() == SpellID
endfunction

private function Actions takes nothing returns nothing
    local Data D = Data.create()
    set D.caster = GetTriggerUnit()
    set D.target = GetSpellTargetUnit()
   
endfunction

//===========================================================================
function InitTrig_Rabid_Bite takes nothing returns nothing
    set gg_trg_Rabid_Bite = CreateTrigger(  )
    call TriggerRegisterAnyUnitEventBJ( gg_trg_Rabid_Bite, EVENT_PLAYER_UNIT_SPELL_EFFECT )
    call TriggerAddCondition( gg_trg_Rabid_Bite, Condition( function Conditions ) )
    call TriggerAddAction( gg_trg_Rabid_Bite, function Actions )
endfunction

endscope

Let's check the Actions function. We are calling a kind of function called Data.create() those special functions will be called from now on methods, because they're functions which only have sense inside the struct, and only can be called or used by making reference to the struct of which they belong. Now we're setting the variable components of this struct after it's created. Until now it's ok, but we can do the things better, in fact we can make this in only one line by defining a custom create method. So let's do it:

private struct Data
    unit caster
    unit target

    #static# method create takes unit c, unit t returns Data
        local Data D = Data.allocate() // this method is private, therefore it ONLY has sense and only can be used inside the struct.
        set D.caster = c
        set D.target = t
        return D
    endmethod
endstruct

With this new struct, we can reduce the number of lines in the Action function to simply one line. There are other advantages of doing this, one important is to make it easy the debug process because you know in which methods you set the variables, where you destroy them, etc.

Static keyword??? what the hell is that??

Probably you noticed the static keyword, this word is used when we need to make a method or a component global (or independent) of the structs created. If we assign the static keyword to a component of the struct, it will behave exactly as a global variable, the difference will be in the way it can be called. In the case of methods, a static method does not depends of the struct variable, it's like a normal function.

Code (jass) Select Expand

globals
    private group G
endglobals

function F takes unit u returns nothing
    call GroupAddunit(G, u)
endfunction

function Bla takes nothing returns nothing
    set G = CreateGroup()
    call F(GetTriggerUnit())
endfunction[c]

Code (jass) Select Expand

struct Test
    static group G

    static method F takes unit u returns nothing
        call GroupAddunit(Test.G, u)
    endmethod
endstruct

function Bla takes nothing returns nothing
    set Test.G = CreateGroup()
    call Test.F(GetTriggerUnit())
endfunction

Both codes are equivalent. So the first question to ask is: what is more convenient? My answer is: it depends. If you need that your functions could get access to any private method or component of the struct, then the static  methods and component are the way to go. I personally use this notation so I can separate the variables which can be modified by the user with the ones that shouldn't be touched. This notation is so powerful that if we want we can make totally this spell inside one struct, converting all the functions into static methods and all the globals into static components.

scope RabidBite

globals
    private constant integer SpellID = 'A000' //Spell Rawcode.
endglobals

private struct Data
    unit caster
    unit target

    static method create takes unit c, unit t returns Data // This method now will carry the responsibility of setting the variable components of the struct
        local Data D = Data.allocate()
        set D.caster = c
        set D.target = t
        return D
    endmethod
endstruct

private function Conditions takes nothing returns boolean
    return GetSpellAbilityId() == SpellID
endfunction

private function Actions takes nothing returns nothing
    local Data D = Data.create(GetTriggerUnit(), GetSpellTargetUnit()) // we do all our creating process in only one line
   
endfunction

//===========================================================================
function InitTrig_Rabid_Bite takes nothing returns nothing
    set gg_trg_Rabid_Bite = CreateTrigger(  )
    call TriggerRegisterAnyUnitEventBJ( gg_trg_Rabid_Bite, EVENT_PLAYER_UNIT_SPELL_EFFECT )
    call TriggerAddCondition( gg_trg_Rabid_Bite, Condition( function Conditions ) )
    call TriggerAddAction( gg_trg_Rabid_Bite, function Actions )
endfunction

endscope

With this the only pending thing to do is to do something with this stuff and add the timed effect. But before everything, let's remember what is the problem now: we need to create a periodic timer which will execute a function periodically, and this function must be able to get the information properly if the spell is casted by several units (AKA ensure the MUI of this spell). In order to achieve this, there are 2 ways that we'll discuss in detail.



Approach N° 1: Using timers and storage system to pass the struct data.

This procedure implies the usage of a timer recycler like TimerUtils and a storage system, or simply a storage system with timer recycler included. For this example I'll do this spell dependent of TimerUtils now that this system allows us recycle and attach data to timers. Note: This procedure can be adapted perfectly to other storage systems like ABC, HAIL, HSAS, Cool Coll.

Ok, let's start adding functionality to this baby. First let's add to the Actions function some stuff:

scope RabidBite

globals
    private constant integer SpellID = 'A000' //Spell Rawcode.
    private constant real    dt      = 0.1 //timer period
endglobals

private struct Data
    unit caster
    unit target

    static method create takes unit c, unit t returns Data
        local Data D = Data.allocate()
        set D.caster = c
        set D.target = t
        return D
    endmethod
endstruct

private function Loop takes nothing returns nothing
    //Our periodic stuff
endfunction

private function Conditions takes nothing returns boolean
    return GetSpellAbilityId() == SpellID
endfunction

private function Actions takes nothing returns nothing
    local Data D = Data.create(GetTriggerUnit(), GetSpellTargetUnit())
    local timer t = NewTimer() //Creates a new timer...
    call SetTimerData(t, integer(D)) //Attach the data to the timer
    call TimerStart(t, dt, true, function Loop) // Start the created timer so it can periodically run the Loop function
    set t = null // Set the local timer variable to null, we don't need ti more in this function
endfunction

//===========================================================================
function InitTrig_Rabid_Bite takes nothing returns nothing
    set gg_trg_Rabid_Bite = CreateTrigger(  )
    call TriggerRegisterAnyUnitEventBJ( gg_trg_Rabid_Bite, EVENT_PLAYER_UNIT_SPELL_EFFECT )
    call TriggerAddCondition( gg_trg_Rabid_Bite, Condition( function Conditions ) )
    call TriggerAddAction( gg_trg_Rabid_Bite, function Actions )
endfunction

endscope

Now let's put some work to the Loop function. We need that the effect in the target unit keeps on it until the buff vanishes or get removed by external sources (dispelling spells for instance), so the Looping function basically will do a check if the buff is on the unit, if so, it will deal the damage to that unit. To do that, them we need to add more variables to this spell, like the buff rawcode and the damage per second. Check the highlighted text in the next code:

scope RabidBite

globals
    private constant integer SpellID = 'A000' //Spell Rawcode.
    private constant integer BuffID = 'B000' //Buff Rawcode
    private constant real    dt      = 0.1 //timer period
endglobals

private constant function Damage takes integer level returns real
    return 15. + 7. * (level - 1) //Damage proportional to the spell level so it complies with the JESP standard
endfunction

private struct Data
    unit caster
    unit target

    static method create takes unit c, unit t returns Data
        local Data D = Data.allocate()
        set D.caster = c
        set D.target = t
        return D
    endmethod
endstruct

private function Loop takes nothing returns nothing
    local timer t = GetExpiredTimer() // Gets the timer...
    local Data D = Data(GetTimerData(t)) // Gets the struct attached to the timer...
    local real Dam = Damage(GetUnitAbilityLevel(D.caster, SpellID)) // Gets the damage according to the level of the spell...
    if GetUnitAbilityLevel(D.target, BuffID) > 0 then // Checks if the buff is on the target unit...
        //If so, it will deal damage to the unit...
        call UnitDamageTarget(D.caster, D.target, Dam * dt, false, false, ATTACK_TYPE_CHAOS, DAMAGE_TYPE_UNIVERSAL, WEAPON_TYPE_WHOKNOWS)
    else // There's no buff on the unit, so....
        call D.destroy() // Recycle the struct for a later use...
        call ReleaseTimer(t) // Release the timer, pausing it, and making it avaliable for a later use with other struct...
    endif
    set t = null
endfunction

private function Conditions takes nothing returns boolean
    return GetSpellAbilityId() == SpellID
endfunction

private function Actions takes nothing returns nothing
    local Data D = Data.create(GetTriggerUnit(), GetSpellTargetUnit())
    local timer t = NewTimer()
    call SetTimerData(t, integer(D))
    call TimerStart(t, dt, true, function Loop)
    set t = null
endfunction

//===========================================================================
function InitTrig_Rabid_Bite takes nothing returns nothing
    set gg_trg_Rabid_Bite = CreateTrigger(  )
    call TriggerRegisterAnyUnitEventBJ( gg_trg_Rabid_Bite, EVENT_PLAYER_UNIT_SPELL_EFFECT )
    call TriggerAddCondition( gg_trg_Rabid_Bite, Condition( function Conditions ) )
    call TriggerAddAction( gg_trg_Rabid_Bite, function Actions )
endfunction

endscope

As you can see, I'm doing like a template, I'm putting the configuration stuff in the first lines, including the constant functions, then the struct and then the looping function and finally the trigger functions. Other thing to notice is that the Damage is actually Damage per second, and therefore all the damage must be multiplied by the period of the timer in order to get an accurate value.

With this changes, we have now this spell working. But (there's always a but... ) what would happen if this spell uses a projectile (not instant, like one based on Acid bomb or Storm bolt)?? well, it simply won't start because it's non instant and the EVENT_PLAYER_UNIT_SPELL_EFFECT starts before the buff is set on the target unit, so the only if that will activate will be the one that destroys the recently created struct (buahhh!!! snif!!!). So in order to fix that, and ensure that those kinds of spells work with this situation we need to make some adjustments to our struct. Please check the highlighted code to see the new stuff.

scope RabidBite

globals
    private constant integer SpellID = 'A000' //Spell Rawcode.
    private constant integer BuffID = 'B000' //Buff Rawcode
    private constant real    dt      = 0.1 //timer period
endglobals

private constant function Damage takes integer level returns real
    return 15. + 7. * (level - 1)
endfunction

private struct Data
    unit caster
    unit target
    boolean hasbuff = false //used to check if the buff is on the target unit...

    static method create takes unit c, unit t returns Data
        local Data D = Data.allocate()
        set D.caster = c
        set D.target = t
        return D
    endmethod
   
    method onDestroy takes nothing returns nothing
        set .hasbuff = false // this custom method will set the hasbuff variable to false, so it can start properly when the spell is casted again...
    endmethod
endstruct

private function Loop takes nothing returns nothing
    local timer t = GetExpiredTimer()
    local Data D = Data(GetTimerData(t))
    local real Dam = Damage(GetUnitAbilityLevel(D.caster, SpellID))
    // This conditional detects if the buff is on the target unit...
    if not D.hasbuff and GetUnitAbilityLevel(D.target, BuffID) > 0 then
        set D.hasbuff = true
    endif
    // If the buff is on the target unit, then do the effect
    if D.hasbuff and GetUnitAbilityLevel(D.target, BuffID) > 0 then
        call UnitDamageTarget(D.caster, D.target, Dam * dt, false, false, ATTACK_TYPE_CHAOS, DAMAGE_TYPE_UNIVERSAL, WEAPON_TYPE_WHOKNOWS)
    endif
    // If the buff is not present anymore, then stop the spell
    if D.hasbuff and GetUnitAbilityLevel(D.target, BuffID) < 1 then
        call D.destroy()
        call ReleaseTimer(t)
    endif
    set t = null
endfunction

private function Conditions takes nothing returns boolean
    return GetSpellAbilityId() == SpellID
endfunction

private function Actions takes nothing returns nothing
    local Data D = Data.create(GetTriggerUnit(), GetSpellTargetUnit())
    local timer t = NewTimer()
    call SetTimerData(t, integer(D))
    call TimerStart(t, dt, true, function Loop)
    set t = null
endfunction

//===========================================================================
function InitTrig_Rabid_Bite takes nothing returns nothing
    set gg_trg_Rabid_Bite = CreateTrigger(  )
    call TriggerRegisterAnyUnitEventBJ( gg_trg_Rabid_Bite, EVENT_PLAYER_UNIT_SPELL_EFFECT )
    call TriggerAddCondition( gg_trg_Rabid_Bite, Condition( function Conditions ) )
    call TriggerAddAction( gg_trg_Rabid_Bite, function Actions )
endfunction

endscope

Wow!!! now this is becoming more complex . Things to notice:

   
• In the struct you see that the hasbuff component is set to false, that's used when we need to set a value to the new struct created. This set is done when we call the allocate() private method and therefore is advisable to use it only with non handle variable types (booleans, reals, integers, strings). With handles, I suggest to set and manage them with create and destroy methods in order to control their respective creation and destruction.
• Other thing is that we added to our struct a custom onDestroy method, this method will be executed when we call D.destroy() (This function can't have any arguments and it will generate syntax error if you set arguments to it).
• The Loop function now does 3 verifications: Checks if the buff is present on the target unit, Checks if the hasbuff flag and the buff are present so it can do the effect and lastly it checks if the buff is gone, stopping the spell effect. With this this template can manage instant and not instant buff spells.

Stackable and not stackable effects.

Yay!!! our spell is working wonderfully.... hmmmm... actually not, there's one "problem" more to solve. What would happen if this spell is casted and 1 second later other unit cast this spell in the same unit?? well, the unit will be damaged by 2 and the worst thing is the buff duration has been extended, in other words: a stacked spell.

Sometimes the stackability is desirable and sometimes it doesn't but in the desirable situation we should balance this effect at least by detecting when the first cast should end, so one solution is to give to the spell the ability to detect if the duration has been reached, independently of the buff presence in the target unit. Here's the modification of this spell so it stacks but takes into account the duration of the spell but not necessarily the buff duration. (Note: There are other ways to balance a stackable spell, according of the effect type, this example is one way that works with the example)

scope RabidBite

globals
    private constant integer SpellID = 'A000' //Spell Rawcode.
    private constant integer BuffID = 'B000' //Buff Rawcode
    private constant real    dt      = 0.1 //timer period
endglobals

private constant function Damage takes integer level returns real
    return 10. + 7. * (level - 1)
endfunction

private constant function Duration takes integer level returns real
    return 20. + 4. * (level - 1) // Returns the duration of this spell...
endfunction

private struct Data
    unit caster
    unit target
    boolean hasbuff = false
    real counter // Yay!! a new component of this struct...

    static method create takes unit c, unit t returns Data
        local Data D = Data.allocate()
        set D.caster = c
        set D.target = t
        set D.counter = 0. // The counter component is set to 0 so it can count the time it should be active...
        return D
    endmethod
   
    method onDestroy takes nothing returns nothing
        set .hasbuff = false
    endmethod
endstruct

private function Loop takes nothing returns nothing
    local timer t = GetExpiredTimer()
    local Data D = Data(GetTimerData(t))
    local real Dam = Damage(GetUnitAbilityLevel(D.caster, SpellID))
    local real Dur = Duration(GetUnitAbilityLevel(D.caster, SpellID)) //Gets the duration of the spell so it works properly and it can't be abusable
    if not D.hasbuff and GetUnitAbilityLevel(D.target, BuffID) > 0 then
        set D.hasbuff = true
    endif
    if D.hasbuff and GetUnitAbilityLevel(D.target, BuffID) > 0 then
        call UnitDamageTarget(D.caster, D.target, Dam * dt, false, false, ATTACK_TYPE_CHAOS, DAMAGE_TYPE_UNIVERSAL, WEAPON_TYPE_WHOKNOWS)
        set D.counter = D.counter  + dt //Stores in the struct the elapsed time...
    endif
    if D.hasbuff and (D.counter > Dur or GetUnitAbilityLevel(D.target, BuffID) < 1) then // now any of those parameters will stop the spell
        call D.destroy()
        call ReleaseTimer(t)
    endif
    set t = null
endfunction

private function Conditions takes nothing returns boolean
    return GetSpellAbilityId() == SpellID
endfunction

private function Actions takes nothing returns nothing
    local Data D = Data.create(GetTriggerUnit(), GetSpellTargetUnit())
    local timer t = NewTimer()
    call SetTimerData(t, integer(D))
    call TimerStart(t, dt, true, function Loop)
    set t = null
endfunction

//===========================================================================
function InitTrig_Rabid_Bite takes nothing returns nothing
    set gg_trg_Rabid_Bite = CreateTrigger(  )
    call TriggerRegisterAnyUnitEventBJ( gg_trg_Rabid_Bite, EVENT_PLAYER_UNIT_SPELL_EFFECT )
    call TriggerAddCondition( gg_trg_Rabid_Bite, Condition( function Conditions ) )
    call TriggerAddAction( gg_trg_Rabid_Bite, function Actions )
endfunction

endscope

Now let's analyze the possibility of making this spell not stackable. In order to do this, the spell should deal the same damage over time and it should be able to detect if the target unit has the buff, and if it's the case, then update the respective struct with the new caster in order to ensure in case of the death of the unit, the bounty and/or credits for death get assigned properly to the last caster.

Here I'm going to use the usage of some static elements in order to allow the reader to check how they can be used. Let's see how the code should look:

scope RabidBite

globals
    private constant integer SpellID = 'A000' //Spell Rawcode.
    private constant integer BuffID = 'B000' //Buff Rawcode
    private constant real    dt      = 0.1 //timer period
endglobals

private constant function Damage takes integer level returns real
    return 10. + 7. * (level - 1)
endfunction

// the duration function is not needed anymore now that this spell is not stackable...

private struct Data
    static group IsBitten //This group is used to store all the unit affected by the spell...
    static integer index = 0 //This integer is used to keep a track of the size of the struct array.

    unit caster
    unit target
    boolean hasbuff = false
    // The counter is not needed anymore because we don't want to do stackable this spell
   
    private static method onInit takes nothing returns nothing
        set Data.IsBitten = CreateGroup() //Used to set the variable at map init
    endmethod

    static method create takes unit c, unit t returns Data
        local Data D = Data.allocate()
        set D.caster = c
        set D.target = t
        call GroupAddUnit(Data.IsBitten, t) //Adds the unit to the affected units...
        if integer(D) > Data.index then //updates the array size
            set Data.index = integer(D)
        endif
        return D
    endmethod
   
    method onDestroy takes nothing returns nothing
        call GroupRemoveUnit(Data.IsBitten, .target) // Remove from the group the target unit, it's not affected anymore by the buff.
        set .hasbuff = false
        if integer(#this#) == Data.index then // Adjust the index size, so it doesn't search in inactive structs
            set Data.index = Data.index - 1
        endif
    endmethod
   
    static method SetCaster takes unit caster, unit target returns nothing
        // this method will search in all the active structs which of them has the  target unit, so it can update the caster properly...
        local integer i = 0
        local Data D
        loop
            exitwhen i > Data.index
            set D = Data(i)
            if D.target == target and D.hasbuff then
                set D.caster = caster
                return
            endif
            set i = i + 1
        endloop
    endmethod
endstruct

private function Loop takes nothing returns nothing
    local timer t = GetExpiredTimer()
    local Data D = Data(GetTimerData(t))
    local real Dam = Damage(GetUnitAbilityLevel(D.caster, SpellID))
    if not D.hasbuff and GetUnitAbilityLevel(D.target, BuffID) > 0 then
        set D.hasbuff = true
    endif
    if D.hasbuff and GetUnitAbilityLevel(D.target, BuffID) > 0 then
        call UnitDamageTarget(D.caster, D.target, Dam * dt, false, false, ATTACK_TYPE_CHAOS, DAMAGE_TYPE_UNIVERSAL, WEAPON_TYPE_WHOKNOWS)
    endif
    if D.hasbuff and GetUnitAbilityLevel(D.target, BuffID) < 1 then
        call D.destroy()
        call ReleaseTimer(t)
    endif
    set t = null
endfunction

private function Conditions takes nothing returns boolean
    return GetSpellAbilityId() == SpellID
endfunction

private function Actions takes nothing returns nothing
    local Data D
    local timer t
    if not IsUnitInGroup(GetSpellTargetUnit(), Data.IsBitten) then
        //if the target unit doesn't have the effect, then it will start a new effect...
        set D = Data.create(GetTriggerUnit(), GetSpellTargetUnit())
        set t = NewTimer()
        call SetTimerData(t, integer(D))
        call TimerStart(t, dt, true, function Loop)
    else
        // Otherwise, it will update the current effect with the new caster...
        call Data.SetCaster(GetTriggerUnit(), GetSpellTargetUnit())
    endif
    set t = null
endfunction

//===========================================================================
function InitTrig_Rabid_Bite takes nothing returns nothing
    set gg_trg_Rabid_Bite = CreateTrigger(  )
    call TriggerRegisterAnyUnitEventBJ( gg_trg_Rabid_Bite, EVENT_PLAYER_UNIT_SPELL_EFFECT )
    call TriggerAddCondition( gg_trg_Rabid_Bite, Condition( function Conditions ) )
    call TriggerAddAction( gg_trg_Rabid_Bite, function Actions )
endfunction

endscope

Things to notice:

   
• The Duration function and the counter parameter in the struct have been removed now that this spell is not stackable anymore.
• We've added 2 static components: group IsBitten and integer index, as we said before, they behave as global variables, dependent of the Data struct. The purpose of the group variable is to store all the units affected by the spell and the integer stores the struct array size.
  
• We have a new method: onInit. Every method created with this name is executed at map initialization. In this case we added it in order to set up the IsBitten group variable.
  
• We added a custom method: SetCaster. This one will search through all the active structs and if it finds the respective target unit, then it will update the caster which deals the passive damage.
  
• The Actions function has been changed so the spell can determine if it has to create or updated an existing struct.

this keyword??? integer as a function?? what's happening??

The keyword this is used ONLY in non static methods to make reference to the struct that it's applying it. This cannot be used in static methods because it has no sense in them, so don't try it!!

Notation: set this.caster = u set .caster = u

Both notations are perfectly equivalents.

the integer(Struct) function is used to return the index of the struct. It's possible to get this value directly but it's advisable to use this notation in order to ensure compatibility with later versions of JassHelper.

local integer i = integer(Struct) = local integer i = Struct

Very well, now our spell is stable and can work in the way we needed. Now let's see the second approach.



Approach N° 2: using one single timer for all the units casting the spell.

I personally love this approach, because it allows you to reduce (for not saying avoid) the usage of storage systems. This approach is based in the following precept: If the time is the same for all the units, then one timer should be able to review and control all the units affected by one spell and not one timer per spell casted as we did before.

So the first step has been defined: We can't start a new timer every time we cast the spell, instead, we need to start one timer at map init and putting it to run a code periodically so it can check units affected.

Let's do the modifications based on the non stackable version of Rabid Bite:

scope RabidBite

globals
    private constant integer SpellID = 'A000' //Spell Rawcode.
    private constant integer BuffID = 'B000' //Buff Rawcode
    private constant real    dt      = 0.1 //timer period
endglobals

private constant function Damage takes integer level returns real
    return 10. + 7. * (level - 1)
endfunction

private struct Data
    static group IsBitten
    static integer index = 0

    unit caster
    unit target
    boolean hasbuff = false
   
    private static method onInit takes nothing returns nothing
        set Data.IsBitten = CreateGroup()
    endmethod

    static method create takes unit c, unit t returns Data
        local Data D = Data.allocate()
        set D.caster = c
        set D.target = t
        call GroupAddUnit(Data.IsBitten, t)
        if integer(D) > Data.index then
            set Data.index = integer(D)
        endif
        return D
    endmethod
   
    method onDestroy takes nothing returns nothing
        call GroupRemoveUnit(Data.IsBitten, .target)
        set .hasbuff = false
        if integer(this) == Data.index then
            set Data.index = Data.index - 1
        endif
    endmethod
   
    static method SetCaster takes unit caster, unit target returns nothing
        local integer i = 0
        local Data D
        loop
            exitwhen i > Data.index
            set D = Data(i)
            if D.target == target and D.hasbuff then
                set D.caster = caster
                return
            endif
            set i = i + 1
        endloop
    endmethod
endstruct

private function Loop takes nothing returns nothing
    local integer i = 0 //Used to make the loop through all the struct array
    local Data D
    local real Dam
    loop // Looping through the struct array...
        exitwhen i > Data.index
        set D = Data(i)
        if not D.hasbuff and GetUnitAbilityLevel(D.target, BuffID) > 0 then
            set D.hasbuff = true
        endif
        if D.hasbuff and GetUnitAbilityLevel(D.target, BuffID) > 0 then
            set Dam = Damage(GetUnitAbilityLevel(D.caster, SpellID))
            call UnitDamageTarget(D.caster, D.target, Dam * dt, false, false, ATTACK_TYPE_CHAOS, DAMAGE_TYPE_UNIVERSAL, WEAPON_TYPE_WHOKNOWS)
        endif
        if D.hasbuff and GetUnitAbilityLevel(D.target, BuffID) < 1 then
            call D.destroy()
        endif
        set i = i + 1
    endloop
endfunction

private function Conditions takes nothing returns boolean
    return GetSpellAbilityId() == SpellID
endfunction

private function Actions takes nothing returns nothing
    // The Actions function just determines if it has to create or update an active struct...
    if not IsUnitInGroup(GetSpellTargetUnit(), Data.IsBitten) then
        call Data.create(GetTriggerUnit(), GetSpellTargetUnit())
    else
        call Data.SetCaster(GetTriggerUnit(), GetSpellTargetUnit())
    endif
endfunction

//===========================================================================
function InitTrig_Rabid_Bite takes nothing returns nothing
    set gg_trg_Rabid_Bite = CreateTrigger(  )
    call TriggerRegisterAnyUnitEventBJ( gg_trg_Rabid_Bite, EVENT_PLAYER_UNIT_SPELL_EFFECT )
    call TriggerAddCondition( gg_trg_Rabid_Bite, Condition( function Conditions ) )
    call TriggerAddAction( gg_trg_Rabid_Bite, function Actions )
    call TimerStart(CreateTimer(), dt, true, function Loop) //Start the timer at map init...
endfunction

endscope

As you can see, too few changes were required to get this improvement. In this case we removed the usage of CSSafety and HandleVars, which is in my opinion a big improvement. Other thing to notice is that the timer never stops, if there's no units, the loop won't run so this function practically won't put any stress in the game.


Stackacle spell using the second approach

Now... if we want to make it stackable, we just have to remove the SetCaster method, add the duration function, do the modifications in the conditionals in the Loop function and modify the Actions function to get the desired effect. Check the highlighted text and appreciate how the code changed:

scope RabidBite

globals
    private constant integer SpellID = 'A000' //Spell Rawcode.
    private constant integer BuffID = 'B000' //Buff Rawcode
    private constant real    dt      = 0.1 //timer period
endglobals

private constant function Damage takes integer level returns real
    return 10. + 7. * (level - 1)
endfunction

private constant function Duration takes integer level returns real
    return 20. + 4. * (level - 1) // Returns the duration of this spell...
endfunction

private struct Data
    static group IsBitten
    static integer index = 0

    unit caster
    unit target
    boolean hasbuff = false
    real counter
   
    private static method onInit takes nothing returns nothing
        set Data.IsBitten = CreateGroup()
    endmethod

    static method create takes unit c, unit t returns Data
        local Data D = Data.allocate()
        set D.caster = c
        set D.target = t
        set D.counter = 0. // The counter component is set to 0 so it can count the time it should be active...
        call GroupAddUnit(Data.IsBitten, t)
        if integer(D) > Data.index then
            set Data.index = integer(D)
        endif
        return D
    endmethod
   
    method onDestroy takes nothing returns nothing
        call GroupRemoveUnit(Data.IsBitten, .target)
        set .hasbuff = false
        if integer(this) == Data.index then
            set Data.index = Data.index - 1
        endif
    endmethod

    //The method SetCaster has been removed....
endstruct

private function Loop takes nothing returns nothing
    local integer i = 0
    local Data D
    local real Dam
    local real Dur
    loop
        exitwhen i > Data.index
        set D = Data(i)
        if not D.hasbuff and GetUnitAbilityLevel(D.target, BuffID) > 0 then
            set D.hasbuff = true
        endif
        if D.hasbuff and GetUnitAbilityLevel(D.target, BuffID) > 0 then
            set Dam = Damage(GetUnitAbilityLevel(D.caster, SpellID))
            call UnitDamageTarget(D.caster, D.target, Dam * dt, false, false, ATTACK_TYPE_CHAOS, DAMAGE_TYPE_UNIVERSAL, WEAPON_TYPE_WHOKNOWS)
            set D.counter = D.counter  + dt //Stores in the struct the elapsed time...
        endif
        set Dur = Duration(GetUnitAbilityLevel(D.caster, SpellID))
        if D.hasbuff and (D.counter > Dur or GetUnitAbilityLevel(D.target, BuffID) < 1) then
            call D.destroy()
        endif
        set i = i + 1
    endloop
endfunction

private function Conditions takes nothing returns boolean
    return GetSpellAbilityId() == SpellID
endfunction

private function Actions takes nothing returns nothing
    call Data.create(GetTriggerUnit(), GetSpellTargetUnit()) // Just one line of code!!!
endfunction

//===========================================================================
function InitTrig_Rabid_Bite takes nothing returns nothing
    set gg_trg_Rabid_Bite = CreateTrigger(  )
    call TriggerRegisterAnyUnitEventBJ( gg_trg_Rabid_Bite, EVENT_PLAYER_UNIT_SPELL_EFFECT )
    call TriggerAddCondition( gg_trg_Rabid_Bite, Condition( function Conditions ) )
    call TriggerAddAction( gg_trg_Rabid_Bite, function Actions )
    call TimerStart(CreateTimer(), dt, true, function Loop)
endfunction

endscope



When is better one approach than other??

Unconsciously, this example has evolved from the approach 1 to the approach 2, but it's important to point out that it doesn't mean that one approach is worst than the other, actually it depends in how is used and with which frequency.

For example, if we have an AoS sytle map, which is generally hero based, the first approach is more convenient because you don't know if the hero with the custom spells will be summoned and therefore the chances that this spell can be casted are less. In the other hand, with spells that can be casted by several hundreds of units (like in custom melee games of footies) the second approach is more convenient, because instead of having several timers controlling a spell (one timer per unit, and imagine a footies game with full house and the footmen casting those custom spells), this will be a considerable memory eater. With one timer checking all the units, we can optimize it pretty fine.




Final Words.

Well, what we did in this tutorial was creating a spell, modify it according to the required circumstances and at the end we ended doing something very interesting: a template, a very nice template. That's something good, because it allows us develop several kind of spells with small modifications of one pattern. The template is basically in this way:

Scope My spell
// Customization section
globals
    //Constant variables...
endglobals

< Constant functions... >

// End customization section

private struct Data
     // Struct components
endstruct

< Spell functions required for the looping function>

< Looping function >

< Triggers functions >

endscope

Well, I think this is all. I hope this tutorial helps you to improve your the spell development. Any questions, typos, mistakes or suggestions about how to make this tutorial better can be post here. Happy spell making

==========================================================================

Addition: Looping throught units.

As a part of development of spells controlled with a single timer, we need to iterate through an array of data. this can be done in several way, ones are less efficients than others. If we have units as a part of the data struct, we can use them to develop a very safe way of iteration using the ForGroup command. An example can help us right now.

// ================================================================= \\
// Custom Immolation modifier spell, so it targets destructables too \\
// Request by Abriko, by moyack. 2008.                               \\
// ================================================================= \\
// Requires Table to work...                                         \\
// ================================================================= \\
scope Immolation2 initializer init

// Configuration Part...
globals
    private constant integer SpellID = 'AEi2' //Spell based on Immolation
    private constant integer BuffID = 'BEim' //Immolation buff, please base it on the immolation buff.
    private constant real dt = 1.
endglobals

private constant function DamageRate takes integer level returns real
    return 10. + 5. * (level - 1)
endfunction

private constant function AOE takes integer level returns real
    return 160.
endfunction
// End configuration Part...

private struct data
    static HandleTable T
    static group G
    static rect R
    static unit U

    unit c
    boolean flag = false
   
    static method Start takes unit c returns nothing
        local data D = data.allocate()
        set D.c = c
        call GroupAddUnit(data.G, c)
        set data.T[c] = integer(D)
    endmethod
   
    method onDestroy takes nothing returns nothing
        call GroupRemoveUnit(data.G, .c)
        call data.T.flush(.c)
    endmethod
endstruct

private function GetLivingDestructables takes nothing returns boolean
    return GetDestructableLife(GetFilterDestructable()) > 0.405
endfunction

private function BurnDestructables takes nothing returns nothing
    local destructable d = GetEnumDestructable()
    call DestroyEffect(AddSpecialEffect(GetAbilityEffectById(BuffID, EFFECT_TYPE_SPECIAL, 0), GetWidgetX(d), GetWidgetY(d)))
    call UnitDamageTarget(data.U, d, DamageRate(GetUnitAbilityLevel(data.U, SpellID)) * dt, false, false, ATTACK_TYPE_CHAOS, DAMAGE_TYPE_UNIVERSAL, WEAPON_TYPE_WHOKNOWS)
    set d = null
endfunction

private function CheckStatus takes nothing returns nothing
    local unit u = GetEnumUnit()
    local data D = data( data.T[u] )
    if not D.flag and GetUnitAbilityLevel(u, BuffID) > 0 then
        set D.flag = true
    endif
    if D.flag and GetUnitAbilityLevel(u, BuffID) > 0 then
        call SetRect(data.R, GetUnitX(u) - AOE(GetUnitAbilityLevel(u, SpellID)), GetUnitY(u) - AOE(GetUnitAbilityLevel(u, SpellID)), GetUnitX(u) + AOE(GetUnitAbilityLevel(u, SpellID)), GetUnitY(u) + AOE(GetUnitAbilityLevel(u, SpellID)))
        set data.U = u
        call EnumDestructablesInRect(data.R, Condition(function GetLivingDestructables), function BurnDestructables)
    endif
    if D.flag and GetUnitAbilityLevel(u, BuffID) < 1 then
        call D.destroy()
    endif
    set u = null
endfunction

private function Loop takes nothing returns nothing
    call ForGroup(data.G, function CheckStatus)
endfunction

private function Conditions takes nothing returns boolean
    return GetSpellAbilityId() == SpellID
endfunction

private function Actions takes nothing returns nothing
    if not IsUnitInGroup(GetTriggerUnit(), data.G) then
        call data.Start(GetTriggerUnit())
    endif
endfunction

//===========================================================================
private function init takes nothing returns nothing
    local trigger t = CreateTrigger(  )
    call TriggerRegisterAnyUnitEventBJ( t, EVENT_PLAYER_UNIT_SPELL_EFFECT )
    call TriggerAddCondition( t, Condition( function Conditions ) )
    call TriggerAddAction( t, function Actions )
    set t = null
    set data.T = HandleTable.create()
    set data.G = CreateGroup()
    set data.R = Rect(0,0,1,1)
    call TimerStart(CreateTimer(), dt, true, function Loop)
endfunction

endscope

What I'm doing in this spell:

   
• I use a group to store all the units that cast the spell. Those units will be my reference or index key.
• I use a HandleTable to store the struct data ID related to the unit.
• To iterate though all the active struct data, I call the ForGroup command and in the enumerating function I retrieve the data struct related to the unit with the command data.

The advantages of this iterating process:

   
• You can have total control of the structs.
• Therefore, you'll have control over all the struct in a safe way.
• Data search is practically O(1) thanks to the usage of table (gamecache search property)

Disadvantage:

   
• Only can be used with handles which support grouper handles (units > groups, player > force)

This procedure is very useful in spells because almost in all the cases (for not saying all the cases) there's a unit involved in the spell process, and that unit can serve us as a index for the spell itself.

This tutorial looks pretty cool
Is it going to be updated to make use of the new Jass tags? ;P

Quote from: Magtheridon96 on December 29, 2011, 10:24:35 PM
This tutorial looks pretty cool
Is it going to be updated to make use of the new Jass tags? ;P

Definitely, and not only that, I'll update to the new coding standards to make it up to date.

Tutorial converted, now I have to update to the current coding style

And to do that, you have to make the struct extend an array, use a library, use struct/module initializers (they look cooler )