StarCraft II Basic Guide to Abilities (Part 1)

[Daelin]

Part I – Generalities
1. Introduction – purpose and aim of the tutorial
2. Prerequisites – before we can get started
3. Getting to know the Data Editor – brief description of the editor's menus
4. Object Categories – brief explanations of some StarCraft II classes

Part II – Ability Implementations
5. Instant Target Ability – Energy Blast (Single-Effect)
6. Instant Single Target Ability – Energy Burn (Composite-Effect)
7. Buff Single Target Ability – Silence (Simple Behavior)
8. Buff Single Target Ability – Discharge (Repetitive Effect)
9. Buff AoE Ability – Silence Storm (Target Area)
10. Positive Aura Ability – Khaydarin Field (Aura Buff Effect)
11. Negative Aura Ability – Energy Rift (Aura Periodic Effect)

Part III – Conclusions
12. Conclusions

1. Introduction
Everyone knows the modding environment of StarCraft II is highly superior to the capabilities of any other medium Blizzard previously provided. There are very many factors and reasons to sustain this affirmation, but the strongest is probably its flexibility and minimal kernel functionality. Of course, it would be naïve to claim that the system does not bring a set of cons, amongst which its complexity and significant changes from the legacy Editors, both scaring away or inhibiting both newcomers and veteran modders.

So why the switch? I like to believe that evolution requires adaptability, and moving to a superior environment represents a natural step in the improvement of modders’ skills, tools and final results. This guide is intended for both Warcraft 3 modders (who might get a preview taste of what StarCraft II provides for them) and newcomers, who most likely opened the Galaxy Editor at least once, opened the Data Editor, and closed it back. By no means do I attempt to drive anyone away from Warcraft 3. For those who have access to this new environment, however, I think it’s a nice experience and worth giving it a chance. Since you bothered to open this tutorial you must present some minimum interest, right?

Note
This tutorial presents aspects of the Data Editor alone. The abilities developed do not employ any scripting skills – in fact, none of the abilities presented here are Trigger-Enhanced.

Note
The second part of the tutorial features a step-by-step approach to developing example abilities. Most of the abilities need to be constructed in order – that is, some abilities from earlier points will be used to construct more complex ones later. I will do my best to specify all such dependencies.


2. Prerequisites
Before venturing any further, make sure you have StarCraft II installed on your computer, with both the Game and the Galaxy Editor functional (at the date this tutorial was written I have version 1.4.2 installed). Next it would be best to open the editor and familiarize a little with its menus – you do not need to understand much by now, but you should be able to navigate between the menus. Most importantly, open the Data Editor and see what the buttons there do. Don’t worry about “messing up” anything.

I have also attached two maps: one you can use as starting point, the other containing implementations of all the abilities presented in this tutorial. In case you get stuck, you can easily check the references out (there are some aspects which may be specified partially or incompletely – such as linking various actors to our numerous abilities).

That’s pretty much all you need for now. Oh, and arm yourself with lots of patience. Trust me, you're going to need it – the first steps are always the slowest.


3. Getting to know the Data Editor
You've opened it? If you didn't, it's about time you did. Don't worry, it only looks scary, it doesn't bite (or absorb things like a black hole). It splits into 5 subareas as follows:

• 1 (Red). Options – modify the viewing options of the Data Editor. Just play with them to see what each does. I recommend you keep the rightmost five ones permanently active. I also favor Table View (and will be working with it). Displaying objects list as tree sorts the objects on races and parent-objects (we will talk about them shortly), so you may wish to occasionally activate this option too; I prefer to directly search an ability. Lastly, rawcodes are not needed for this tutorial so you might as well keep them deactivated.
• 2 (Blue). Tabs – you will need them to juggle between categories of objects (data). For this tutorial I recommend keeping open only the tabs you see in the screenshot (Units, Abilities, Effects, Behaviors, Validators, and Buttons). You can close tabs by right clicking on them and then selecting the option "Close Tab". Open new tabs with the + button.
• 3 (Green). Objects List – Will list all objects from a category (selected tab). You can filter objects via the Data Source selection list.
• 4 (Orange). Property List – displays the properties of the object selected from the list. List of properties depends on the parent object.
• 5 (Cyan). Dependencies – Galaxy Editor keeps track of dependencies between objects. For example, if a unit possesses an ability you will see that ability listed when you select the unit, and vice-versa (see the unit linked to a parent ability). This allows you to easily keep track of dependencies without scrolling through the property list.

Before moving further make sure you are used to the Data Editor's areas. Play with them a little and personalize the editor to your liking – but please take into account the settings suggested above (Options).


4. Objects Categories (Classes)
StarCraft II objects are organized hierarchically, and placed into what Blizzard refers to as catalogs. Each catalog comprises objects belonging to the same base classes/categories (classes include Unit, Behavior, Validator, etc.). All objects derive from the base classes – these classes are further expanded into subclasses, with supplementary attributes and mechanisms, suitable for a high range of situations. You will most likely derive your new objects from these more specific subclasses, depending on your purpose (most units are indeed based directly off CUnit Class). Here's a more detailed schema of the data system:

Note: Subclasses inherit all properties and mechanisms from the base classes. Because supplemental behavior is inserted, they are said to lose generality (in Object-Oriented Programming terms, think of inheritance for both subclasses and objects – though objects do nothing more than overwrite the values of some fields of the subclass). Notice that classes and subclasses appear in the Data Editor as objects. They do not have their properties set, however, so on their own they have little usage.

You can check the classes yourself by Displaying Objects List as Tree (Ctrl+Shift+O). This will group objects in the Object List based on their parent classes. This holds true for whatever new objects you might choose to further create - they will belong to the subclasses from which they were created.

Warning: The terms 'class' and 'subclass' mentioned here are purely didactic, analogy with object-oriented programming. Blizzard refers to the elements contained into a catalog as 'entries', with 'scopes' indicating the valid fields (and hardcoded, as specified above). Because we do not deal with triggers or scripting, however, this terminology has little use for us, though it is indicated you are aware of it.

Now, remember how I mentioned that compared to Warcraft III, StarCraft II's environment is greatly improved with a tad of added complexity? Well, this is mainly due to the catalog system. For our study, ability behavior is no longer separated from the Editor, with only a distinct number of properties exposed to the user, but instead obtained by combining primitive sub-objects and connecting them via specific mechanisms. We will see thorough this tutorial how a single target Ability can be changed to instantly target an entire Area, become an Aura effect or even become subcomponent of another Ability.

Note
Warcraft III "object rawcodes" are replaced by object ids. IDs are theoretically preserved cross-map - as long as there is no duplicate entry with the same ID in the destination map. This greatly simplifies the process of copying spells into your map and ensuring minimal link-modifications.

For this, however, we first need to understand the basic purpose of the significant classes offered by Blizzard. A very good starting point is to check some of the already existent objects and the connections between them (remember Dependencies). Here is a brief description of the classes we will work with:
a) Units – contains all logical information about units, structures, destructibles etc. Not much to modify here when actually developing abilities. We will mainly connect buttons to abilities and add passive behaviors to units. I will let you play with this section and familiarize with it.
b) Abilities – determine primary interaction mechanisms with the players and their caster's behavior. It should be noted that unlike Warcraft III where abilities featured hard-coded effects (such as damaging units in an area, draining life, boosting armor etc.), in StarCraft II abilities no longer 'do' anything on their own, but generalize a mechanism that can later be expanded. Notable examples of ability classes include:

• Effect (CAbilEffect) – defines basic behavior for most abilities, mainly because it can link effects to that ability (read below for an explanation on effects). Parent class for the classes below.
• Effect – Instant (CAbilEffectInstant) – ability activates instantly. StarCraft II abilities that fall in this category include Guardian Shield & Stimpack. Warcraft III players can remember the common behavior between War Stomp, Taunt, Divine Shield, Mirror Image, Summon Hawk and Defend (all abilities activate without requiring any specific target).
• Effect – Target (CAbilEffectTarget) – ability requires a target (unit or point) or trigger. StarCraft II examples range from Blink, Feedback and Psi Storm, to all Raven abilities, Neural Parasite, Heal and Queen Transfusion.

Notice how abilities have no intrinsic behavior besides their very main mechanics implemented. Classes do not restrict the effect to an Area of Effect behavior, Channeling, Unit Target, Point Target, etc. Such additional behavior (and much more) can be entirely customized.

c) Behavior – remember passive abilities & buffs? Well, they are sort of back, but in the form of behaviors. A behavior can be understood as any form of passive property that can be added and removed from units and that influences the capabilities and stats of the target unit (for a shorter or longer period of time).
Behaviors can be native (passive abilities, properties even unit characteristics – Undead for instance?) or inherited (buffs), temporary or permanent, latent (constant behavior – increase stats, inhibit basic behavior, etc.) or bursting (periodic instant effects – poison, recovery, auras, etc.), positive, negative, or neutral, visible (displayed in the user interface) or hidden etc.
Notice how behavior is such a generic and powerful object, that it could be the subject of discussion of a tutorial of its own. Behaviors generalize not only buffs and ability-related problems, but also issues of unit classifications, custom unit mechanics, possibility of custom attributes etc. Some of the topic will be covered through examples, while other aspects remain an interesting subject for future experiments.

d) Effects – the bread and butter of all abilities, effects perform instant operations on the game environment. This is again a very large and complex class of objects, with quite a lot of interesting mechanics hardcoded yet highly customizable. Native classes and subclasses include:

• Damage (CEffectDamage) – various damage mechanics (including fixed damage, damage based on stats, selective damage, hallucination instant-destruction, non-fatal damage etc.).
• Modify Unit (CEffectModifyUnit) – primarily this effect is used for instantly altering a unit's vitals (life, energy, shields).
• Set (CEffectSet) – very useful mechanism, couples more effects. Whenever set effects are triggered, all the effects connected to the set are all triggered too. This allows implementation of composite effects (ex: remove shields, apply behavior) triggered by a single behavior.
• Search Area (CEffectSearchArea) – AoE abilities, here we come! Search Area automatically scans all possible targets in a specific area and triggers an effect individually for each eligible unit (what if that effect were an AoE effect too?). Target customization can be done via Validators. Say goodbye to all those annoying 'Unit Group – For each Unit in group' trigger-enhanced spells.
• Apply Behavior (CEffectApplyBehavior) – what good are behaviors if you can't apply them to units via abilities? All buff abilities rely on this effect (StarCraft II Stimpack, Cloaking Field, Chrono Boost, EMP, Fungal Growth etc., or Warcraft 3 Thorns Aura, Slow, Immolation, Doom, Heal, Cripple etc.).

e) Validators – from my previous experience as a spell-maker, probably one of the most tedious and heavily used coding parts for me involved manipulating certain abilities' behavior based on their targets' or owner's stats and environmental circumstances. Validators are useful in situations that include filtering unit selection, situational-restrictive behavior, power sources (ex: protoss psi-matrix), special uses for the damage types etc.

Now, a very simple example I could give you regarding validators involves deactivating Evasion (% chance target will dodge/completely negate physical damage) if owner's life drops below 25%. To do this via scripting is quite nasty: you always need to detect when a unit's HP drop below or above the threshold, activate/deactivate the behavior – this may also involve adding a supplementary dummy ability etc. In StarCraft II, this is simply achieved by restricting the behavior, via a validator that checks that a unit's HP percentage is above or equal to 25%. If the validating condition fails, the behavior is turned off by the system – no triggers, no additional code, no mumbo-jumbo tricks.


At this point you probably begin to understand what I meant by the trade-off between flexibility and ease-of-access. Working with abilities that present a natively-implemented behavior/effect releases the modder from having to work with all these strange interconnections (validators inhibiting behavior ability, that is generated by an effect that belongs to an effect set that is-… all pretty confusing, eh?). Fortunately, in StarCraft II, most Blizzard abilities are also implemented using this rather complex system. They can be therefore used as a good reference point to understand how various mechanics work/are implemented like. These new objects and generic interactions also open new possibilities for the various ideas of some modder's never-ending imagination. Instead of learning specific ability behavior, you can now focus on learning a few generic mechanics that can then be combined into pretty much anything…


5. Instant Target Ability – Energy Blast (Single-Effect)

Ability Class: Single Target, Single Effect, Instant

We start our step-by-step tutorial with a rather simplistic spell. I won't deny it is inspired from Warcraft III's Mana Burn, but in order to warm up, we're not going to cause any damage to the target unit (yet).

a) Creating the ability (no effect)

• Go to the Abilities tab (Data Editor)
• Data – Add Ability. Set the initial fields to the following values:
  - Name: Energy Blast – this will help us find the ability in the editor
  - ID: EnergyBlast (or click Suggest button) – unique ability id
  - Ability Type: Effect – Target – ability with target behavior
  - Based On: Default Ability (CAbilEffectTarget) – parent class
  - Race: Protoss – or any of your liking, useful to find ability in editor
• Let's change now some properties (to affect the way the ability interacts on a basic level) – make sure Energy Blast is selected in the objects list
  - Cost – Add a new cost entry (X+ green button). Under Cost Display check Shields. Under Vitals set value for Shields to 15. This has as an effect that our ability will cost the unit 15 shields. In a similar way you could setup a life or energy cost for any ability. It should be noted that if the unit does not have the necessary amount of vitals to cover the cost, the ability cannot be performed! You can also modify the Cooldown of the ability by setting the Time Use field to the desired value (for example 5 seconds). You may also choose to study the effects of the Cost Display field (Warcraft III players surely remember Mana Burn floating text on target).
  - Ability: Target Filters – Add a new entry. Check only Enemy and Neutral (you wouldn't want players to blast their allies or even their own units now, would you?). After you validate the new entry, modify the additional flags as follows (you can play with the fields and notice the effects of the ability on various targets of course):
  i. Exclude Dead, Hidden, Invulnerable, Missile, Self, Stasis and Structure. Any target falling under one of these categories is automatically invalid (ability cannot be performed)!
  ii. Set Can Have Energy, Has Energy and Is Visible as Required. Targets not meeting at least one of the criteria are considered invalid as well!
  - Stats: Range – Represents the maximum distance to the target at which the ability can be performed. Set this to 7 for now.

b) Linking the ability to a unit (via a button)

• Go to Buttons tab. Add a new button with the same name and ID as the ability (in order to avoid confusions). Setup the following properties:
  - Icon: Assets\Textures\btn-ability-protoss-blackhole-color.dds
  - Hotkey: B
  - Tooltip: Reduces target's energy by 50 points (or any other description you fancy)
  
• Go to Units tab and look for Dark Templar (or any other unit of your choice to which you might wish to add this ability). Modify the following fields:
  - Ability: Abilities: Add "Energy Blast" to the list (green "+X" button) – this links the ability to the Dark Templar unit.
  - Ability: Command Card: Add "Energy Blast" button to any of the free positions (stick to Command Card 1). Modify Command Type to Ability Command, and the Ability to our Energy Blast. Notice that the ability will not show up in the list unless you have first linked it to the unit (via the Ability: Abilities field).
• Go to Abilities tab and look for Energy Blast. Modify the Ability: Commands field. Select Execute Command and then choose as default button our Energy Blast button.

Note
Setting Hotkey behavior ingame to "Grid" will override all hotkey settings. Last row, first column's button, for example, always has (Z) as hotkey in the aforementioned mode.

At this point it is already possible to test the ability, though it will do nothing (doesn't even trigger, and can be even blindly attempted on empty ground). In order to make it work, we need to add the effect.

c) Creating and linking the energy reduction effect

• Go to Effects tab. Data – Add Effect. Set the fields to the following values:
  - Name: Energy Blast
  - ID: EnergyBlastEnergyReduction
  - Effect Type: Modify Unit – appropriate for instant stats modification.
  - Based On: Default Effect (CEffectModifyUnit)
• Next we alter the newly created effect to work as we intended.
  - Editor Suffix: (Energy Reduction) – this will help identify the correct effect in the case of more complex abilities (that use more than one effect), but will only show up in the editor.
  - Effect: Vitals: Set Energy Change to -50 (equivalent to a reduction of 50 energy points on target of ability, upon effect activation). Leave all other changes (including all fractions) to 0.
• Lastly go back to Abilities. Select Energy Blast and add our newly created effect to the Effect:Effect list.

Now you can test the ability and notice its effect. There is one more thing that may bug some of you: the absence of a visual effect. Next step I will also give you an example of how you can achieve this, though that problem is outside the scope of this tutorial.

d) Linking a visual effect to the ability

• Go to Actors tab. Search for FeedbackImpact object.
• Modify Event: Events field. Copy-paste Effect.Feedback.Start effect.
• Modify copy's Source Name to Energy Blast (Energy Reduction), and Sub Name to Start.

That's it. For a more correct implementation you could of course copy the entire actor and modify it accordingly. The problem of actors is not of interest for our tutorial, however, so for other types of effects, consult similar abilities.

Summary
This chapter you have learned how to develop basic abilities with an instant effect targeting only one unit at a time. For the basic implementation of the ability we implemented two core objects.

• Energy Blast Ability. It defines properties such as ability basic class (instant target), cost, cooldown, valid targets and maximum range. Also activates the Energy Blast effect.
• Energy Blast Effect. It defines the behavioral effect of the ability, represented by the Energy Reduction of the target.

6. Instant Single Target Ability – Energy Burn (Composite-Effect)

Ability Description: Burns up to 50 points of target unit's energy. The energy combusts dealing an amount of damage equivalent to the energy burnt.
Prerequisite: Energy Blast ability (chapter 5).

It's time we took our ability to a new level and turned it into what was formerly known as Mana Burn (StarCraft II feedback but with a restricted amount of energy consumed). Before continuing, please make sure your Energy Blast works correctly. You may choose of course to make a completely new ability and repeat the steps from chapter 5; I chose to duplicate the previously created objects and change their names and ids before continuing (careful not to copy other items unrelated to the ability such as actors or other unrelated effects).

a) Creating the damage effect

• Go to Effects tab. Data – Add Effect.
  - Name: Energy Burn
  - ID: EnergyBurnDamageTarget
  - Effect Type: Damage – appropriate for damage effects.
  - Based On: Default Effect (CEffectDamage)
• Now let's modify it to perform the bit of damage we seek.
  - Editor Suffix: (Damage Target) – now the purpose of suffixes begins to unravel. Two effects, both with the name "Energy Burn"? (I will assume the Energy Blast effect was adapted to the new ability – good practice to avoid confusions, though the name is not relevant from the functionality's point of view) The Suffix helps us differentiate.
  - Effect: Vital Bonus: Set Energy to 50 (damage equivalent to the unit's current energy, but not more than 50 points).
  - Effect: Response Flags: Acquire, Flee - causes target to response to caster attack (flee if it cannot attack, or strike back if it can).

b) Connecting the new effect to the ability

• We need a new type of effect that can fire both our effects (the damage and the mana drain) one after another. Go to Effects tab, if you're not already there. Data – Add Effect.
  - Name: Energy Burn
  - ID: EnergyBurnSet
  - Effect Type: Set – fires multiple effects.
  - Based On: Default Effect (CEffectSet)
• Now some property changes:
  - Editor Suffix: (Set) – you probably expected this already.
  - Effect: Effects: Add both Energy Burn (Damage Target) and Energy Burn (Energy Reduction) effects. Be careful! The effects must be placed in this order, as they will also trigger in this same order (if the unit's energy is first reduced from 60 to 10 for example, only 10 points of damage will then be dealt to the unit, even though the full 50 points amount should have been inflicted).
• Go back to Abilities, and link Energy Burn's Effect:Effect to the new set effect.

That's all! Now you have a complete Mana Burn-like ability. If you check the Blizzard solution on Feedback, you will find the same approach was implemented (though in their case a percentage of the unit's current energy (100%) is both drained and deals the damage).

Warning
Anyone who's played with the editor probably wondered at some point why some properties appear in the form of arrays, even though it may seem impossible for more than one value to hold at a time (range, costs, etc.). My experiments show that those arrays are there for multilevel abilities. How I can tell?
Let's make an experiment: try to add both the effects of Energy Burn as different entries into the Effect: Effect field (not as part of a set) – some of you maybe already attempted it and certainly failed to achieve that correct behavior! The thing is that only the first effect in list will occur when the ability fires – the spell either damages target or eats away mana. What's more, a (Level 1) appears next to the name of the ability - clearly suggesting the usage of multiple entries in an array.
Multilevel abilities are therefore intrinsically supported in StarCraft II. We might be a bit far-fetched by trying to play with them at this point now, though.

Note
Here are some further details on two additional fields of a Set Effect.
- Effect: Random: Unless you have a very good reason not to do so, keep this field Disabled. When activated, it randomizes the sequence of execution of the effects inside the set, instead of following the preset order. Experiment with Energy Burn and see what happens (sometimes it works correctly, other times you will notice the problem I mentioned - when the incorrect order is inputted).
- Effect: Minimum/Maximum Count: Keep both values to 0 to keep the feature inactive. Otherwise, selects random number inside interval and runs only the first k effects in the list (with k being the number selected). Makes sense to combine with Effect:Random activated. Notice that k always starts from minimum + 1 value (if minimum is set to 1, maximum to 5, and there are 10 effects, the system never fires 1 effect alone, but 2 or more, up to 5).

If you're still confused about their usage, think of an ability that would randomly affect a unit (from a list of both positive and negative effects, ranging from energy boost, healing, shields restoration, to mana burn, mana depletion or shields halving – at this point we do not know how to implement buff spells, so we'll stick to such simple manipulations). It is enough to input all these abilities in a set, which upon every cast randomize the list of effects, and always applies only the first (one) of them on the target. To further complicate the effect of the spell (some effects are more likely to occur than others), just add some primary effects multiple times (an effect can appear more than once in the set list).

Summary
This chapter we have adapted our Energy Blast ability to deal damage to the target unit. This resulted in a composite-effect ability. The following additions and modifications were performed on Energy Blast:

• Energy Burn (Damage Target) Effect. It deals damage to the target with respect to its current mana points (upper
• Energy Burn (Set) Effect. Combines Energy Burn (Damage Target) and Energy Burn (Energy Reduction) into a single effect.
• Energy Burn Ability Effect: Effect field link switched to Energy Burn (Set).

7. Buff Single Target Ability – Silence (Simple Behavior)

Ability Class: Single Target, Single Effect, Buff

Buff abilities are a lot of fun and introduce us to a couple new concepts. They also unravel unlimited possibilities – instant-tweaking with a unit's vitals is not much fun now, is it? Keep in mind that behaviors can manipulate a unit far beyond Warcraft III capabilities. More so, behaviors allow the introduction of custom attributes and properties on units (Undead custom property being a good example).

a) Getting the Silencing behavior (buff)

• Go to Behaviors tab. Data – Add Behavior.
  - Name: Silence
  - ID: Silence
  - Behaviour Type: Buff – used for altering a unit's stats for a period of time (or even permanent – passive behaviors to be later described).
  - Based On: Default Effect (CBehaviourBuff)
• Now let's modify it a little to make it behave the way we want it to and look nice in the user interface too.
  - Behavior: Alignment: Negative (icon always appears red – might have other implications too when other abilities are involved).
  - Behavior: Modification: Select Ability Tab. Scroll for Ability Classes Disabled. Check Effect, Effect-Instant and Effect-Target. Notice that this will disable effect-related abilities (does not affect passive behaviors such as Cloaking Field, Merge abilities such as Archon Merging etc.) Do not disable all abilities (under Behavior). Move/Stop/Attack/Patrol etc. are all considered abilities and will be disabled too!
  - Stats: Duration: Sets the duration of the behavior from the moment it is applied. For now set it to 30.
  - UI: Tooltip: Text that appears upon hovering on behavior in the UI. I set it to This unit cannot use any of its abilities.
  - UI: Icon: Icon that will show up in the interface for the buff. For some weird reason I figured Assets\Textures\btn-ability-zerg-disguise.dds would work.

b) Applying the Behavior

• Go to Effects tab. Data – Add Effect.
  - Name: Silence
  - ID: SilenceApply
  - Effect Type: Apply Behavior – appropriate for applying buff effects.
  - Based On: Default Effect (CEffectApplyBehavior)
• And here are the stats too (very short list).
  - Behavior: Behavior: Silence.
• Next create a target ability similar to Energy Blast (follow steps from 5a if you need more guidance on the subject). Keep in mind that the target of our Silence may not have energy at all (Marine). Decide how to treat such targets by modifying the Target Filters.

Note
It might be a bit tricky to test the behavior directly on an enemy unit. To ensure that it works correctly, temporarily enable the ability to target friendly units – at least until you are certain it works the way you want it too.

Summary
We have developed a new Silence ability that inhibits a unit's ability casting behavior for a period of time. This is a buff ability. The following objects were necessary to obtain this:

• Silence Behavior. It specifies the buff stats, such as effect, duration and user interface information.
• Silence (Apply) Effect. Applies the Silence Behavior to target unit.
• Silence Ability. Defines properties of the core ability (cost, cooldown, target validity, range etc.). Also triggers the activation of the effect.

8. Buff Single Target Ability – Discharge (Repetitive Effect)

Ability Class: Single Target, Composite Effect, Periodic Buff
Requirements: Energy Burn (Chapter 6), Basic Buff (Chapter 7)

While buff abilities such as those in chapter 7 are highly useful, there are situations which require proper understanding of repetitive buff effects. This is a special mechanism developed by Blizzard that allows a buff to launch effects repeatedly as long as a buff is in place. Examples of usage include Poison effects, various auras, Immolation & Siphon Mana (Warcraft III).
a) Setting up the Discharge Effect
Create a copy of the Energy Burn effects (Set, Damage & Energy Reduction effects). If you have not developed any of them yet, follow the steps from chapters 5 and 6. By now you should be able to alter the effect's parameter. Balance the 50 energy points down to 15.

b) Setting up the Behavior

• Go to Behaviors tab. Data – Add Behavior.
  - Name: Discharge
  - ID: Discharge
  - Behaviour Type: Buff – buffs can activate repetitive effects too.
  - Based On: Default Effect (CBehaviourBuff)
• Now to modify the parameters (some previously explained in chapter 7 are not repeated here):
  - Behavior: Alignment: Negative
  - Stats: Duration: 15 - this is the total duration the buff lasts on the target.
  - Stats: Period: 3 - waiting period between firing of the repetitive effect. In our case "every 3 seconds"
  - Effect: Effect – Periodic: Discharge (Set) – this is the repetitive effect the buff executes. In our case it's the energy burn effect we developed previously.

c) Applying the Behavior – follow the steps from 7b. Link the effect to the Discharge behavior.

Note
With the current configuration of the buff, the first effect launches only after the first period (3 seconds). If the effect ought to affect the target immediately after the buff affects the target, also add the set to the Effect: Effect - Initial field.

Note
If you leave the response flags on the buff's damage effect, targeted units will respond every time the effect occurs. This might result in High Templars repeatedly running away in steps, for example. If you wish, you can set the targets to respond to the initial behavior adding effect.

Summary
We have developed a buff ability that performs a repetitive effect on the target. To develop it, we implemented the following:

• Discharge (Set) Effect. This is the actual effect performed on the buffed unit periodically.
• Discharge (Apply) Effect. Applies the Discharge Behavior to target unit.
• Discharge Buff – while active, periodically triggers the Set effect on the target. Can also be tweaked to perform the effect simultaneous with its application.

9. Buff AoE Ability – Silence Storm (Target Area)

Ability Class: Target Area of Effect, Composite Effect, Periodic Buff
Requirements: Discharge (Chapter 8)

Remember how I mentioned StarCraft II mechanics easily allow to modify single target abilities into Area of Effect (AoE) spells? This chapter we will simply turn our previous Discharge ability so that it can be cast on an entire area (not only one target) at a time. Before continuing, please ensure Discharge works properly.

a) Duplicating Discharge – create duplicate elements from all the Discharge objects, to use for our Silence Storm (hint: duplicate the Ability first, and check everything that belongs directly to Discharge, or otherwise said has Discharge in its name). While it is possible to use the same effects, in case you might wish to tune the values differently between the two effects (damage amount, duration of buff, cycle wait time etc.). This is the disadvantage of a highly modular design: changes usually cannot be performed in one place alone.

• Alter the behavior so that it also silences the target unit (Behavior: Modification field – check 7a for more information).

b) Setting up the Area of Effect

• Go to Effects tab. Data – Add Effect.
  - Name: Silence Storm
  - ID: SilenceStormAreaSearch
  - Effect Type: Search Area – effect employed by all Area spells.
  - Based On: Default Effect (CEffectEnumArea)
• Setup for the Area effect.
  - Editor: Editor Suffix: (Area Search)
  - Search: Areas: Add a new entry with 360 Arc (we want to affect an entire circle), Effect for each targeted unit set to Silence Storm (Apply), Maximum Count -1 (for no upper limit), Radius: 3 (this sets up the size of the area), Radius Bonus: 0.
  - Search: Search Filters: Use the same validation fields as those from Energy Blast (5a). Notice how we move the responsibility of selecting the proper targets from the ability to the Search Area effect. Searches are highly customizable, though at this point we use their minimum functionality.
• Now go back to Abilities, and link the Search Area effect. Also add it to the Effect: Cursor Effect property – this will connect the radius of the effect to the ability before it is cast (during the 'selecting area' phase).

c) Setting up the cursor (visual effect only)

• To get the area cursor to actually show up (not only make units in area focus grow a red tint), go to Actors. Data – Add Actor.
  - Name: SilenceStormSplat
  - ID: SilenceStormSplat
  - Actor Type: Splat
  - Based On: CursorSplat
• Now setup the properties as follows:
  - Art Model: PsiStormCustomSplat
  - Event: Events: Add Event (Message Type: Ability, Source Name: Silence Storm, Sub Name: Cursor) – Action: Create, Add Event (Message Type: Actor Orphan) – Action: Destroy.

Tip
You can easy change the behavior of the spell from targeted to non-targeted AoE (non-target AoE spells are automatically performed around the caster – example: Warcraft III War Stomp). Replace the ability's class to EffectInstant and make the Area Search Effect centered on the caster of the ability. If you can't modify the search correctly, read the following chapters (auras) to grasp the technique.

Summary
We combined the Silence and Discharge effects into a special Area of Effect spell. It buffs multiple units in an area that not only alters their behavior, but also periodically triggers a set effect. This ability practically tested all concepts learned up to this point. The following objects were necessary to obtain it:

• Silence Behavior. It specifies the buff stats, such as effect, duration and user interface information.
• Silence (Apply) Effect. Applies the Silence Behavior to target unit.
• Silence Ability. Defines properties of the core ability (cost, cooldown, target validity, range etc.). Also triggers the activation of the effect.

10. Positive Aura Ability – Khaydarin Field (Aura Buff Effect)

Ability Class: Aura, Buff
Requirements: Understanding behaviors (chapter 7), understanding area search (chapter 8)

Most of you who have had to deal with auras in Warcraft III most certainly remember how tricky and difficult to code they were. A real nightmare might I add; this no longer is true in StarCraft II. Nothing about auras is hardcoded anymore. You will see just in a few moments that they can in fact be constructed with the most basic objects – effects, behaviors, validators. Yes you read correctly: because auras are passive, no abilities are involved.

Let me explain a bit more in depth how aura abilities work. Aura casters need a passive behavior that generates the aura around them. What the generation does, in fact, is periodically pick up the appropriate units (valid for the aura), and apply to them a desired behavior for a short period of time. If a unit remains in the proximity of the aura caster, it will be selected by the next refresh period (before its behavior can expire), and the desired behavior refreshed. Otherwise, if the unit is no longer under the influence of the aura, the behavior expires and disappears.

a) Setting up the caster behavior

• Go to Behaviors tab. Data – Add Behavior.
  - Name: Khaydarin Field
  - ID: KhaydarinFieldCaster
  - Behavior Type: Buff
  - Based On: Default Effect (CBehaviourBuff)
• Setup the following properties:
  - Editor: Editor Suffix: (Caster) – it is appropriate to suffix the behavior, because we will have one for the targets of the aura too.
  - Stats: Period: 0.25 – this will refresh the aura four times per second. Refreshing is particularly relevant for new units entering the aura – the smaller the period, the better the responsiveness but the greater the computational complexity (too many auras with a very small period can generate severe lag!). Minimum value: 1/16 of a second (approx. 0.07).
  - Stats: Flags: Hidden (the aura generator shan't show up as a buff on the caster)
  - Behavior: Alignment: Positive (obviously)

b) Setting up the target behavior

• Data – Add Behavior.
  - Name: Khaydarin Field
  - ID: KhaydarinFieldTarget
  - Behaviour Type: Buff
  - Based On: Default Effect (CBehaviourBuff)
  
• Properties fun:
  - Editor: Editor Suffix: (Target)
  - Behavior: Alignment: Positive
  - Stats: Duration: 0.35 – must be greater than the period of the caster with at least 1/16 of a second (time between two frames in StarCraft II). The higher the value of this field, the longer a unit might retain it after it leaves the aura (no guaranteed!).
  - Behavior: Modification: Unit – Vital Max Bonus – Energy: 25. Unit – Vital Regeneration Bonus – Energy: 5.0.
  - Behavior: Validators (Disable): Though we are not using this field here, I figured I might specify it. Here you can tune the targets of the aura in a finer manner (say, affect only units with their life amount above 33% - heavily damaged units cannot then benefit from the aura). Such behaviors are achieved via validators.

Note
We do not validate primary aura targets here – technically speaking, this behavior works on pretty much anything as long as the validators hold true.

c) Setting up the periodic search and behavior application

• Create an Apply Behavior Effect that will apply the Target Buff. Follow the steps from 7b if you don't know how to do it.
• Now let's perform the periodic search. Data – Add Effect.
• Go to Effects tab. Data – Add Effect.
  - Name: Khaydarin Field
  - ID: KhaydarinFieldAreaSearch
  - Effect Type: Search Area
  - Based On: Default Effect (CEffectEnumArea)
• Setup for the Area effect.
  - Editor: Editor Suffix: (Area Search)
  - Search: Areas: Add a new entry with 360 Arc (we want to affect all units around the caster), Effect for each targeted unit set to Khaydarin Field (Apply), Maximum Count -1 (change this value if you want your aura to target a limited number of units), Radius: 4 (this sets up the size of the aura), Radius Bonus: 0.
  - Search: Search Filters: Obviously can affect only player's units (and allies too if you want). Restrict it to units who have energy (there's no point in giving marines energy, apart from rendering them vulnerable to our energy burning spells). Make sure the targeted units are not missiles, dead, structures (unless again, you want it to target structures too) or under construction (let High Templars warp in first before you boost their energy). Decide if you want it to affect self or not (Cloaking Field does not affect the casting Mothership).
  - Impact Location: Caster Unit – we don't have any target point/unit. The unit scan is performed around the caster.
• Go back to Khaydarin Field (Caster) Behavior. Set the Effect: Effect – Periodic field to the Area Search Effect.

d) Buttons for prettiness

• Setup a Button for the ability.
• To give the ability to one of your units, go to Ability: Command Card.
  - Add your button to the unit's command card.
  - Modify Command Type to Passive.
  - Specify the Khaydarin Field (Caster) buff under the Behavior field.
• Now go to Behavior: Behaviors and give the caster behavior to your unit.

Note
It is possible to enable aura stacking. Simply modify the Stats: Maximum Stack Count field (0 is interpreted as no limit). It would be recommended, however, if you modify the maximum stack to also alter the Maximum Stack Count Per Caster to 1. This avoids problems caused by the difference between the duration of the target buff and the refresh period of the aura.

Summary
Auras take advantage of subtle features of behaviors and effects. The right combination gives the right results. The key objects of every aura are:

• Aura Caster Behavior. Hidden buff; periodically launches a search area effect around the caster, to pick up units for the aura.
• Aura Target Behavior. Actual aura effect – at this point can only alter unit behavior as long as it is active. Short duration buff, needs periodic recharging from the aura.
• Aura Search Area & Apply Behavior Effects. Search area scans the area around the caster (at the caster's behavior order), picks up the valid targets, and calls the Apply effect to put the Target Behavior on the units.

11. Negative Aura Ability – Energy Rift (Aura Periodic Effect)

Ability Class: Aura, Periodic Effect
Requirements: Buff Auras (Chapter 10)

Aura abilities all display similar functionality: place all units around a caster under a specific short-duration behavior, and regenerate it periodically. The nature of that behavior allows us to further tune and enhance the aura ability, either by modifying the behavior of the buff itself, or designing it so that it triggers additional abilities.

a) Adapting the Buff Aura – I will let you either start from scratch or copy and adapt the Khaydarin Field aura. Make sure it targets only valid enemy targets (validity is the same as for the well-known Energy Burn). Remove any Behavior Modifications from the Target Buff.
b) Adapting the Energy Burn Effect – Same as above, but featuring Energy Burn Effect this time.

• Change both Energy Reduction and Damage amounts to 10.
• Modify the Set's Effect: Chance to 0.5 - every time the set effect is triggered, it has a 50% chance to fizzle – do nothing. Remember that although this behavior can be set for any effect, if triggered by an ability, fizzling does not give the caster consumed resourced or vitals (ex: energy) back.

c) Setting up Target Buff for periodic effect

• Setting a direct periodic effect on the behavior does not work. That is because the buff refresh is signaled to the system as a completely new buff application, instead of an extension mechanism. While this posed no problems to the passive buff behavior, active effects require adapting of the behavior.
  - Behavior: Buff Flags: Check Extend. This enables the behavior I already mentioned.
  - Effect:Initial & Effecteriodic: Energy Rift (Set)
  - Stats: Duration: 0.3
  - Stats: Duration Bonus (Maximum & Minimum): 0.0 – the extending mechanism allows subsequent applications of the behavior to generate a stacked time bonus. If the behavior would be added three times, for example, and its duration was set to 0.4 seconds, its actual duration would be 0.4x3=1.2 (durations add, resulting in a 'stacking' mechanism). This field limits the maximum duration bonus the buff can receive (we want no bonus in our case, so we set it to 0).
  - Stats: Kill Credit: Caster (give the caster the credit in case it kills any units with this aura).
  - Stats: Period: 2.3 – period of time between two bolts. Shares the behavior of any repetitive buff behavior.

Note
Stacking is still possible with the current configuration of the aura. Test this kind of behavior thoroughly though, to ensure it matches your designed ability.

Summary
Periodic-effect auras function similarly to static buffed ones. Subtle modifications applied to the latter ensure proper functionality of even the most complex periodic effect auras. Involved objects remain similar.

• Aura Caster Behavior. Hidden buff; periodically launches a search area effect around the caster, to pick up units for the aura.
• Aura Search Area & Apply Behavior Effects. Search area scans the area around the caster (at the caster's behavior order), picks up the valid targets, and calls the Apply effect to put the Target Behavior on the units.
• Aura Target Behavior. Actual aura effect, periodically recharged (not reset) by the aura on the caster. Periodically triggers an effect on the affected unit.

12. Conclusions
This tutorial is meant to be part of a series dedicated to developing StarCraft II Abilities. Next time I intend to continue exploring other classes of abilities such as channeling (single target, area, aura-like), toggle (defend, immolation etc.) and passive. If you have any particular suggestions or requests for the next tutorials, feel free to Message me – if I find your idea interesting and useful, I will most certainly make use of it. If you have any questions regarding this tutorial, again, don't hesitate to send me a message. I will do my best to answer your inquiries as promptly and correctly as possible.

Good luck with developing awesome abilities, and most importantly, have fun!

 

[Rui]

Impressive. I just can't rep' you enough. It's amazing how you've been into the Galaxy Editor for so little time and how you've figured out so much already. Are you getting help from other tutorials?
I've had StarCraft II since release and I haven't had the patience to dig into it properly yet. Not because it was overly complex — many of the things in there made sense, especially the existence of things such as effects and actors —, but because of its extreme lack of organization and documentation. My own way of organizing stuff is sloppy, and I can understand what I'm doing even if things are not laid out too well, but this Editor just bores the heck out of me with, on top of the documentation and organization issues, screwing up on a few of the most basic things, like new data sometimes not showing up on drop-down lists and refuses to accept raw codes, not to mention doing simple things takes 10x the time it used to take on the World Editor.

Anyway, I didn't pay much attention to abilities, so I should be trying this out. Thanks again, Daelin, your contributions are quite notorious!

 

[Daelin]

Are you getting help from other tutorials?

I've gotten into StarCraft II modding for a month now; started playing with the Data Editor the previous Friday (one week and a little), to be honest. I didn't use other tutorials, because I didn't really find anything on the particular subject of abilities; tutorials either addressed highly specific problems or very generic fields with little use for me - or at least related to my style of learning.

I think the best point of learning is from Blizzard's abilities. Because they are no longer hardcoded, it's really easy to learn from them. A few mechanics here and there enabled me to unravel a lot of mechanics and figure their usage out. Feedback and Cloaking Field offered pretty much all the basic information I needed.

not to mention doing simple things takes 10x the time it used to take on the World Editor.

Due to the new dependencies system you can actually copy whole batches of objects with a couple of clicks. Renaming them and altering their IDs takes ages though...

 

[Dr Super Good]

Catalogs are populated by "enteries". Each entry has a "scope" which defines the fields an entry can use and is one of many hard coded scopes for each type of catalog. Each entry also has a "parent" which defines what values are inherited (the default values that non-declared fields take). Many scopes have an entry with the same name.

This is the internal terminology used by the SC2 engine and is important to know when using the catalog natives.

As far as I can see, the XML engine defines the scope to base enteries in a hard coded way. You then define the scope of enteries by setting their parent to one of the base enteries or a derivitave of one.

It is important to know that enteries redefined in another XML layer for a catalog (from other mods or in the map) are known as being their own parents (when quieried for their parent they will return their own ID).

 

[moyackx]

Impressive tutorial, your teaching skills are simply awesome. With you I've learned a lot with WC3, and it seems it will happen again with SC2.

Glad to see you again

 

[Daelin]

@Dr Super Good: this tutorial deals with basic aspects only, not taking advantage of scripting capabilities, or modifying the underlying XML code by hand. I do get your point about not misleading people with improper terms (without mentioning they are non-cannon terms). I have made an update with an observation of what you've mentioned, however. You remind me very much of Vexorian

moyack, long time no chat. You grew up to become one of the best Warcraft III scripters I knew. Glad to see you're around, and that you're considering giving StarCraft 2 a shot too.

 

[MGCǂSpectre]

Good job bro, not many people show any interest in doing anything for sc2.

 

[Daelin]

If there were, I wouldn't really have a purpose here now, would I?

 

[xorkatoss]

i don't have sc2 but this tutorial is epicly huge gj O.O

 

[Kabel]

Wow! Great tutorial! As a newcomer to the SC2 editor I gotta say this is one of the best tutorials I have ever read. Not that it just explains how to solve a specific problem, but it presents a more fundamental understanding of the editor.

 

[Adiktuz]

Finally, because of this I've finally been able to create working spells on the SCII editor... I hope you do some other tutorials too... ^_^

btw, what was the path of the icon used on the 2nd skill?

 

[Rui]

I believe it's the Mothership's Vortex ability, so search in protoss abilities. Find the general designation and browse through them if it it ain't named vortex exactly.

 

[Daelin]

Actually, I think it was the Energy Nova icon (used by the Terran Campaign - last level). You can find all these abilities in the attached map (Final), buttons, actors and pretty much everything not mentioned here but implemented.

*searches*

Yep, apparently it is indeed Energy Nova.
Assets\Textures\btn-tips-terran-energynova.dds

 

[Adiktuz]

Thanks!

 

[D3reap3R]

Amazing tutorial; I'll be glad to use it when I get Starcraft II soon - I am highly giddy from anticipation to start with this! Do you have any serious suggestion to start with the editor as a whole ? Especially from the switch from WC3 to SC2.

 

[Daelin]

Don't have any expectations from it until you try it out, D3reap3R. And do not constantly compare Galaxy Editor with the Warcraft III WE. It will only give you this big headache. The modifications are so drastic between the two, and the system of objects (a.k.a Data Editor), which is probably the most important component, is so different, the comparison is pretty much pointless.

There are people who claim World Editor is better, but that's just because they are more used to it. I remember the first time I started playing with the World Editor, and it seemed a nightmare. Galaxy is no different; you just need time and patience, and take things step by step. Studying and playing with what Blizzard already created is a good starting point.

And don't give up; if other people could do it, so can you.

 

[Adiktuz]

yeah, the GE was a nightmare the first time I opened it just like when I first opened the WE...

and this tutorial was really good...

a bit off-top maybe

and for people who says that the GE lacks/has very complicated method for some things that are easy to do in the WE, let's not forget that the GE is still in its early stages so improvements would be sure to come... its the same experience as if you started using the WE from the very first version of Wc3:RoC [it was better than the SC1 editor, but still lacking a lot]...

 

[Glorn2]

I didn't get a chance yet to really go through this; but I bookmarked it. I have been making abilities in the editor; but not always getting to add all of the things I want because...yadda yadda yadda. This is gonna be my quick reference from now on. Thanks!