WC3 JASS.com
"The Jass Vault" plus vJASS and Zinc

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:

And we'll convert into this:

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.


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:


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:


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.



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:


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:


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.


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)


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:


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.

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:


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:




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:


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.


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

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

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