Data/Abilities

Abilities

Description

Abilities are Data Types with lists of commands. Usually they are linked to a unit through a Button. When a player presses the button the orders defined in the Ability are executed.

Hints

• Abilities manage cargo and magazines, like the Carrier and its Interceptors as well as the Medivac.
• Abilities can not be added on to a unit with scripts. Thus they have to be added in the Data Module directly.
• Abilities can be turned off and on using triggers.
• Build, Buildable, Merge, Mergeable, Warp, Warpable are all abilities related to "Unit Construction" events from actors. They are all "Build" sort of abilities, however, they have different functions over how they manage the placement. The words are also explicit: Build is ability to build it, while Buildable is the ability to be "Built". Of course a unit without the "Buildable" part can still be built, but will burn off the Actor part, and lack the ability to halt/cancel the construction. In that same pace, the Archon is "Mergeable". (and Warpable according to Campaign), etc.

Update 5.0

On any ability, modders can set whether any given ability command will automatically Generate Ability Buttons such that the ability would work as soon as it is applied to a unit. No longer will users have to set these button and icons in the unit command card manually.

Example Usage

Cargo Space

Make a new Ability and set its type to "Transport". A unit with this ability will get cargo space. Set the values of "Stats - Cargo Count Maximum", "Stats - Cargo Size Maximum" and "Stats - Cargo Size Maximum" to your prefered values.

Sub Types (Classes)

The classes have some shared fields, as well as some unique ones. Look at existing abilities for reference.

Ability: Sub Types (Classes)

• Arm Magazine
• Attack
• Attack Modifier
• Augment
• Battery
• Beacon
• Behavior
• Build
• Buildable
• Effect - Instant
• Effect - Target
• Harvest
• Interact
• Inventory
• Learn
• Merge
• Mergeable
• Morph
• Morph Placement
• Move
• Pawn
• Progress
• Queue
• Rally
• Redirect - Instant
• Redirect - Target
• Research
• Revive
• Specialize
• Stop
• Train
• Transport
• Warp Train
• Warpable

Fields

Even though Abilities have several subtypes, most have the following fields.

Common Field

(None): Categories

Category that can be used by a behavior to enable/disable this ability

(None): Data Collection

Collection name of the ability, in order to create alternate copy of it.

(None): Default Button Card Id

In order to allow for abilities to be easily applied to any unit, all buttons now have a property to allow modders to set their default button position and submenu Id on the command card (this is perhaps good for triggers that add abilities on unit that have no settings of the ability on their command card).

(None): Levels

Can directly set the max level of an ability. Combined with the accumulator system, modders will no longer need to implement 1000 sets of abilities for abilities that have 1000 levels.

• Not on all abilities
• The Levels field is also upgradable so that modders will be able to change max ability levels at runtime.
• When the Levels field is set to 0, the default value, the ability level system will fallback to the previous functionality.

(None): State Behavior

This field creates a behavior when an ability is created. It will destroy it when the ability is destroyed, and it will disable/enable it when the ability is disabled/enabled.

(None): Veterancy Level Min

(Unknown)

(None): Veterancy Level Skip

(Unknown)

Ability: Alignment

Selects whether there is any preference given to friendly or enemy units while targeting with this ability (for auto-cast).

• Negative: Enemy units are preferred while targeting
• Neutral: No preference is given to pick either friendly or enemy units when targeting with this ability.
• Positive: Friendly units are preferred while targeting.

Ability: Commands

Auto Queue Id

(Unknown)

Default Button

Button used to identify the right ability command on the Command Board of the unit.

• Since patch 5.0, the command flag allows this button to generate the default button on the unit's command card

Flags

• Allow Minimap: Permits the command to be cast on the minimap. Commands which require a unit cannot be cast on the minimap even if this flag is set.
• Allow Self Cast: If the self cast hotkey is used when issuing this command, it will pick the caster as the target without going into targeting mode.
• Continuous: Indicate if this command should be issued repeatedly while its hotkey is being held down.
• Create Default Button: The ability would work as soon as it is applied to a unit. No longer will users have to set these button and icons in the unit command card manually (this is perhaps good for triggers that add abilities on unit that have no settings of the ability on their command card).
• Hidden: Prevents this command from being shown in the command card, in the editor. You wouldn't be able to associate a command on a unit's command board.
• Hide Path: This command will not be used by the path display UI.
• Ignore User: Ignore any user requests to issue this command. Useful for making passive abilities that auto-cast or not (the auto-cast can be swapped).
• Send To Selection: This command will be issued to all units in the selection who can handle it even if they aren't in the active subgroup. You can also notice that any ability that has this command flag enabled becomes accessible from any units that do not own the ability, in their command cards (see the picture below). Also, an identical selected unit with a buff behavior modifying its subgroup priority will require its abilities to use this flag to have all units execute the ability. This field is best suited when using manually the ability, rather than SET ID that is more suited for Issue Order cases.
• 

• Show In Glossary: This command will be displayed in the unit help glossary ability section.
• Use Default Button: In order to allow for abilities to be easily applied to any unit, property that allow modders to set their default button.

State

State of the button which controls its availability:

• Available: This command will be available unless triggers explicitly restrict it. If not using triggers, this should be a default setting.
• Restricted: This command is explicitly restricted until triggers make it available.
• Supressed: This command will be only avaiable if other commands not currently restricted required it.

Take note that the word "available" has nothing to do with the command being free of any requirement. Requirements can still forbide it and hide it.

Also, in order to use these fields, one must activate their use from triggers; Enable/Disable Tech Tree Restrictions.

Requirement

Value from the Requirements that allows/disallows hide/show the ability command and button.

• When moding, pay attention to this field, even if ignoring it, it only takes a single click on any requirement to imput it., even when scrolling down just to check.

Preempt Level

In case this ability command is issued as a Preempt command toward other commands that are Preempt as well (Preempt means: going as prior command, the contrary of being put in queue), then this number will deceide which ability has the lead as the first used ability.

Ability: Debug Trace

• If enabled logs ability use and execution/errors when testing the map

Ability: Set ID

An arbitrary identifier that can be set on different abilities of the same type to make commands issued by one ability apply to any other abilities on other units in the selection with the same identifier.

Ex: Using an issue order effect on a Zerg to unburrow it can use any unburrow ability that have the Set ID: "BrwU". Since all (most) unburrow abilities carry this Set ID, they will all be activated from this single issue order effect.

• Note that this can cause some undesired outcomes when putting two abilities on the same unit with the same SET ID. Using either one will spend the first ability in the order of abilities, up until the last one, which may cause not to use the right ability at the right moment.
• Does not work for "Unmorph" commands on Morph abilities that would be targetted by an Issue Order effect (even with the proper ability command). This might be a lack of content since this Unmorph system came from patch 5.0. Use Tech_Alias instead.

Ability: Shared Flags

Generic flags for most abilities.

• Disable While Dead: If set, this ability will be disabled while the unit that has it is dead. Disabled by magazine abilities that want their production to live after the death of their carrier unit.
• Disabled: If set, this ability is disabled from on its own. This can be reverted from triggers/buff behaviors.
• Register Charge Event: Allows the CActorUnit of the unit using the ability to be able to use "Ability Cooldown" events. Has a bug: doesn't work if the cost was empty, and then created by an upgrade. It must be innate to the ability.
• Register Cooldown Event: Allows the CActorUnit of the unit using the ability to be able to use "Ability Cooldown" events. Has a bug: doesn't work if the cost was empty, and then created by an upgrade. It must be innate to the ability.
• Hide Target Cursor For Invalid Targets: If set, the target cursor model will be hidden if the target is invalid.
• Ignore Produce Limit: (Unsure) Ignores supplies?
• Skip Preload: (Unknown)
• Snap Target To Unit Radius: If set, the target cursor will target the unit radius circle of a unit instead of the unit center when targeting a unit.
• Target Cursor Visible in Black Mask: As the name states.

Ability: Tech Player

The Player used when requirement checks are run by this ability. By default, this is set to the "Upkeep" player (the player who pays for this unit's food cost).

• Caster: Refers to the Caster player, when using interact ability to cast ability that does not belong to himself.
• Owner: Refers to the primary player that has control of the unit that has this ability.
• Upkeep: Refers to the primary player which this unit and ability provide tech to (ex: Supply Depot provides tech to allow a player to build a Barracks).

Cost: Cost

Cost for using an ability in time, resource or vitals.

• The field category is (None) on some new abilities.
• We can include any Cancel - Cost what so ever other fields that have most of the same fields. Sometimes we find these fields in the Info - Array of the ability, because they are included with their unit fields (ex: build, train, Arm Magazine).
• The Research Ability has a visual bug which causes it not to display extra useful fields for charges such as "Hide Count" for example. Only directly on table view, without opening the array window can you see those missing fields.

Index

Numeric index of the cost. Create only 1 index for most abilities (which is Index 0). More indexes means abilities with levels that use different costs at higher level.

Charge - Count (Max)

Number of charges maximum that the user of the ability can have.

Charge - Count (Start)

Number of charges that the user of the ability start with.

Charge - Count (Use)

Number of charges that the user of the ability uses up per casting the ability

Charge - Enable Charge Time Queuing

Flags for the Charge fields

• Enable Charge Time Queuing: (Unknown)
• Ignore Time Delay: This allows abilities to ignore the TimeDelay set in the unit and instead use the ability’s own settings.
• Restore All Charges On Cooldown: Instead of recharging only 1 charge at the time, every charges gets restored at once upon the completion of the charge's cooldown.

Charge - Hide Count

Hides the numeric value of Charges on the button

Charge - Link

Link of the ability for Charges only. When using a link that matches with other links, any cooldown indicated here will be applied the other abilities as well. This is used by the Terran Merc Compound, that limits the use of summoning Mercs.

Charge - Location

Where the ability link for charges should link at.

Ability vs Unit; After testing some simulations, it seems that the only way an ability can set every ability on cooldown on a single unit is with the "Unit" location. This is however not true when a Modify Unit effect changes the cooldown of one ability (with "ability" cooldown location) with it's link string shared by those abilities; They all have their cooldown modified equally.

• • Add: Adds/Remove cooldown, no matter what. It was not necessary to add a "Substract" field, because this field does it all the same. Does nothing if putting an amount in positive with no active Cooldown.
  • Add if Not In Cooldown: Is default setting. Works like add but requires cooldown inactive. Does nothing if putting an amount if negative, it can only create active cooldown (otherly said, it's like refreshing some cooldown when there's no cooldown to restore). This operator is useful when the modder doesn't want to touch abilities that are currently regenerating.
  • Max: Sets the current cooldown (cooldown active or not) to this amount, but will refuse to modify if the current cooldown is higher than this value (still resets the UI clock of the button to the current timer, for some reasons). Does nothing if put in negative (because you can't set the maximum above completion and because higher current cooldown timer values aren't modified either).
  • Min: Sets the current cooldown (requires cooldown active) to this amount, but will refuse to modify if the current cooldown is lower than this value (which is also why a fully regenerated cooldown is considered 0, so lower than any minimum and won't be modified). Fully restores cooldown if put in negative at any amount (otherly put, it's like asking the minimum cooldown to be more than a fully restored cooldown).
  • Multiply: Multiplies the current cooldown (requires cooldown active) by the "Cooldown time Used" field. Fully restores cooldown if put in negative at any amount (otherly put, it's like asking to multiply the amount that will result of the multiplication above completion).
  • Set: Sets the cooldown to this exact amount, no matter what. Fully restores cooldown if put in negative at any amount (otherly put, it's like asking to set the amount to any set number above completion).

Charge - Time Delay

Works similarly to TimeStart, but it only affects the first charge of the ability, item, or behavior.

• When TimeDelay = 0, the charge system will work as before.
• When TimeDelay > 0, TimeStart will be ignored.
• When the ability begins to stock charges, the first charge’s regen time will use the TimeDelay value, and any following charges will use the TimeUse value.

Charge - Time Start

Charge time that is required for each Charges at the start of the ability's availability.

• Ex: If an ability has 4 charges, with a time start of 10, it will take 40 second for the 4 charges to be ready.
• Having 0 in this field means that all 4 charges would be up for start.

Charge - Time Use

Charge time that is required per charge ability use, per charge.

• Ex: if an ability has 4 charges and it uses 4 charges per cast with a time use of 10, even if the ability was used only once, each charge will still require 10 sec to recharge.

Cooldown - Link

Link of the ability for Cooldown only. When using a link that matches with other links, any cooldown indicated here will be applied the other abilities as well.

Cooldown - Location

Where the ability link for cooldown should link at.

Ability vs Unit; After testing some simulations, it seems that the only way an ability can set every ability on cooldown on a single unit is with the "Unit" location. This is however not true when a Modify Unit effect changes the cooldown of one ability (with "ability" cooldown location) with it's link string shared by those abilities; They all have their cooldown modified equally.

• Ability: On any ability sharing the same ability link that are currently on the same unit.
• Behavior: Related to behaviors only. It is unkown why this is present on abilities.
• Global: For all units of all players sharing the same ability link, a shared cooldown, enemies/allies alike
• Player: For all units of the same player sharing the same ability link.
• Unit: For the same unit, indluding a morph alteratate unit. Ex: A burrowed Zerg that has an ability while unburrowed can affect its same ability while unburrowed (just don't forget to put abilities on both units). This wouldn't work on the "Ability" location, as it is only for the same unit (a morphed unit is a second unit in that way). Also for multiple abilities that wish to alter their cooldown all at once on the same unit when casting one of the abilities.

Cooldown - Operation

The operator that deceides how the cooldown is set.

• Add: Adds/Remove cooldown, no matter what. It was not necessary to add a "Substract" field, because this field does it all the same. Does nothing if putting an amount in positive with no active Cooldown.
• Add if Not In Cooldown: Is default setting. Works like add but requires cooldown inactive. Does nothing if putting an amount if negative, it can only create active cooldown (otherly said, it's like refreshing some cooldown when there's no cooldown to restore). This operator is useful when the modder doesn't want to touch abilities that are currently regenerating.
• Max: Sets the current cooldown (cooldown active or not) to this amount, but will refuse to modify if the current cooldown is higher than this value (still resets the UI clock of the button to the current timer, for some reasons). Does nothing if put in negative (because you can't set the maximum above completion and because higher current cooldown timer values aren't modified either).
• Min: Sets the current cooldown (requires cooldown active) to this amount, but will refuse to modify if the current cooldown is lower than this value (which is also why a fully regenerated cooldown is considered 0, so lower than any minimum and won't be modified). Fully restores cooldown if put in negative at any amount (otherly put, it's like asking the minimum cooldown to be more than a fully restored cooldown).
• Multiply: Multiplies the current cooldown (requires cooldown active) by the "Cooldown time Used" field. Fully restores cooldown if put in negative at any amount (otherly put, it's like asking to multiply the amount that will result of the multiplication above completion).
• Set: Sets the cooldown to this exact amount, no matter what. Fully restores cooldown if put in negative at any amount (otherly put, it's like asking to set the amount to any set number above completion).

Cooldown - Time Start

Waiting time before casting the ability for the first time, always relative to the location of the link.

Cooldown - Time Use

Waiting time after using the ability. This time can pair up with Charge time without trouble, and will act as a secondary time out check.

Cost Display

Allows the ability to pop a small resource text (a small text actor) that indicates how much resource/vital was just spent on use

Technology Resource Cost

Cost, in resource for using the ability.

• Upgrade abilities use this field for the cost.
• Abilities with "Ignore Unit Cost" flags enable do not affect these values.
• It is very possible to put values in negative to gain resource on using the ability! This will also compare to the unit's cost (if train/building a unit/structure) and calculate on its own.
• Good alternative when it is desire to increase the cost of a Zerg unit without changing all the units field. For example, an Hydralisk can be charged more or less when upgrading this field, and this won't affect the difference for morphing into a lurker (in which case the units cost are compared to give the right price).

Vital Fraction

Cost in percentage of a vital (Energy/Life/Shields)

• Does not calculate the flat amount, it will instead show the cost in percentage on the button.

Vital

Cost in flat amount of a vital (Energy/Life/Shields)

Cost: Refund Fraction

Determines the fraction of the specified cost that should return if the ability couldn't cast or didn't get pasted the Refundable Stage such as in Effect - Instant and Effect - Target abilities.

• If -1, returns 100% of the amount of the specified cost used for the ability. This means the amount of charges used, the full cooldown, each resource that was spent.
• The Vital and Vital fraction section seems to be 0 by default, assuming that using it will give an extra % amount (or remove some).

UI: Orders

Order fields allow you to customize the appearance of the waypoint lines that show up when you queue orders (targeting).

UI: Toolip Priority

Determines the order that this ability appears in an "info" toolip tag. If the priority is set to 0, then it will not be shown.