Ability Lua Tutorial 1: Ability Form

Okay, since this is my very first tutorial, there may be some mistakes. Just go along with me and ask some question, and we'll be fine. After a lot of considerations (mostly in sleeping, but still), I decided to take this one as the first tutorial.

---

I'm pretty sure that you guys are already an expert in designing unique abilities and explain them to us, but how do you explain your abilities to Dota 2 engine?
You can tell the machine about your abilities by using a certain registration form. With this, there'll be more clarity for the machine about the description of your abilities, what they can do and what they cannot do.

Now the form, here you go.

Random Guy: Dafuq is that?

Relax, I'll explain them one by one. Just copy it to your editor, and save it as:
"<heroname>_<abilityname>.txt"
Where to? Anywhere, for now.

Hey, don't just read it. Copy and save it, get your hands dirty.

Now, here's the guide to fill the form. The form above has been filled with an ability by Vera Olivia, named Tutorial Ability. On the back-end, the name turned into "vera_tutorial_ability".

General Explanation

• You can call the contents of the form as key-value pairs; key name on the left, its value on the right.
• Enclose both key name and value name with double-quote marks.
• White-spaces are ignored between key and values.

Ability Techincal Aspect

"BaseClass"
Don't touch this

"ScriptFile"
Filepath to the ability's script file. More on technical later.

"AbilityTextureName"
Filepath to the ability's icon. More on technical later.

"FightRecapLevel"
Larger the number, higher it will be seen in fight recap. As a reference, all basic abilities in Dota 2 is "1", while (active) ultimates have "2". One exception is Monkey King's Mischief (has "2"), and don't ask me why.

"MaxLevel"
This is the maximum level allowed for the ability. Value "0" is possible (for empty ability, usually). This key-value is optional; the default max-level is 4.
An ability can have any number of levels, but it is STRONGLY RECOMMENDED BY SYSTEM that any ability has 0, 1, 3, 4, or 7 levels.

Ability General

"AbilityType"
Self-explanatory


"AbilityBehavior"
This key describes the ability's behavior (duh). Is it unit or point target? Does it has AOE? Can it be cast while stunned? Tag it there.
A pipe ("|") designates an "or", which means the ability has both behavior. So,
"DOTA_ABILITY_BEHAVIOR_POINT | DOTA_ABILITY_BEHAVIOR_NORMAL_WHEN_STOLEN | DOTA_ABILITY_BEHAVIOR_ROOT_DISABLES"
means that the ability is a point-target, use normal cast when stolen, and can't be cast if rooted.
I won't explain them one by one (that's a long list), so just ask later if required.


"AbilityUnitTargetTeam"
Determines which team should be the target of this ability. No need further explanations for the values, I think.


"AbilityUnitTargetType"
Determines the type of target is allowed for this ability. Most abilities uses HERO, BASIC, and BUILDINGS (or combination of them), but be creative.


"AbilityUnitTargetFlags"
Determines any specific conditions of the target is allowed for this ability. This and above 2 keys determines an error/success when selecting target unit during casting.


These three values will be shown in the HUD
"AbilityUnitDamageType"
Self-explanatory.


"SpellDispellableType"
Self-explanatory.


"SpellImmunityType"
Determines whether the spell pierces spell immunity.


Random Guy: What if my ability can sometimes be AOE and sometimes not based on buffs? What if my ability can target only allies when night, and only enemies at day? What if--

Hold up! You need to learn to walk before you sprint, okay. If you already know how to walk, please explore yourself. I'm helping those who still can't. Don't worry, we'll eventually go for those things, as they are completely possible.

Ability Casting, Resource and Damage

I think these are pretty explanatory (you can read about Cast Buffer on dota2 gamepedia). One note, however, If you think a certain key does not fit, you can always OMIT them. Like, when it is a passive ability, there's no need for cast point, and you can just delete both the key and value. Or when your ability does not require mana, then just erase it. Erase BOTH key and value(s), okay?

Here's the tips:

• "500" is integer value, while "14.0" is float.
• If a key has different values for each level, write values like this: "10 20 30 40".
• Be consistent! If your ability has 3 levels, then you have to write either 1 or 3 values for all keys.
• Be consistent! Don't write like "20 30 40.0 50". Please.

Ability Special

There's a thing that this is called key-value pairs. This form holds all important values for the ability, like damage multiplier, blink range, projectile speed, or perhaps numbers that are important to your ability, but goes unnoticed by the player. When you tweak and balance it, you generally edit these numbers, as opposed to go to the script file. Make sure you store important values here, but only when necessary, as long list tends to get ugly.

To fill it, go with the pattern.

• The number above is a counter. Theoretically you may have 99 key-values, but please don't.
• The "var_type" key has either "FIELD_INTEGER" or "FIELD_FLOAT" as its value. This determines the type of value the main key would be.
• You can name the main key anything you want. Generally you want a descriptive but short names.
• You must write number without a dot if it is an integer as described above.
• You can write values for each level in similar fashion as above key-value pairs, but always with the same type!

Here's some examples.

• Spirit Breaker's Charge of Darkness
• Storm Spirit's Ball Lightning

Okay, that's all for now. I hope this wall of text helps you understand how ability works on the back-end.
Make sure you converted your beautifully designed abilities into the ability form before we go on, okay?
Questions, comments, and Critics are always welcomed.

Next on, I'll explain how to integrate these into Dota 2 engine, and play it. Stay tuned!