Data/Abilities/Morph

* Expect a placement differential if the unit A has a different size of footprints than unit B.
* Morph abilities can wear out behaviors aquired from Behavior abilities if the morphed unit doesn't own the behavior ability as well.
* Many times, when starting a new mod with a combinaison of many dependencies, you might get errors on the editor, stating that there are too many abilities of a single type on X unit. That may occur when a unit a regular attack ability for example, can morph into another unit with a different brand of attack ability. Morph abilities are in that way a gate to those types of error.
* Morph abilities carry on turret actors between unmorph and morphed units. For example, an inniate siege turret on a regular siege tank is carried toward the sieged siege tank upon morphing. What is specific to that example, is that turret actors of the siege tank destroy the turret upon morph events/actions. It could also be destroyed upon the "TurretDisable Event" which fires when a unit morphs to another.

Use this page to view Morph Placement ability's editor fields (both abilities have the exact same copy of fields).

## Example Usage

* Change a Hydralisk into Lurker, Zergling from burrowed to un-burrowed, or lift off a Command Center.

### Update 5.0

New CAbilMorph command index: **Unmorph**.

* For a togglable morph ability, after the unit has already morphed, the ability can still be issued an Unmorph command, which will cause the unit to start the morphing process defined in the InforArrayUnmorph field.
* For most cases, the InforArrayUnmorph field should be set so that its final unit type is its normal state unit type. This way, the unit will be morphed back to normal with the Unmorph command.
* Even if a unit is directly created as the Morphed unit type, morph abilities will still consider the unit as having gone through the morphing process. They will apply the relevant behaviors and allow it to use the Unmorph command.
* Has a huge bothersome bug with toggling morphs in which training/creating Morphed version unit before, who does not have abilities/weapon matching the Unmorphed will cause the Unmorphed version to be able to use them. This seem to be an equivalent bug to the Morph effect in which you can't just morph a unit to something else and hope that the innate weapon will apply properly. There is however a method to have it work: add a dummy morph ability that morphs the morphed unit to the unmorph version; It may not be used, simply left there.

## Fields Description

### (None): Behavior Off

Will apply the BehaviorOff buff when the unit is in its Normal state.

* Only work if the morph ability is marked as “Toggle”.

### (None): Behavior On

When set, the ability will apply BehaviorOn buff to the unit when the unit is in its Morphed state.

* Only work if the morph ability is marked as “Toggle”.

### (None): Cost Unmorph

Cost field (like default cost fields) for the Unmorph phase

### (None): Info Unmorph

When the flag Toggle is on, morph Abilities can be used to toggle back and forth between two different unit type chains.

* Two recommandations until Blizzard improves this functionality:
	1. Do not use for units using an auto-cast coponent, such as underground turrets and such. This results in an heavy conflict of the ability trying to burrow and unborrow at the same time. Of course validator can be set, but this gets way more complicated if a delay for burrowing is anticipated, and etc.
	2. Starting off with the Morphed unit can cause a bug in which if the Morphed unit doesn't own weapons, abilities equal to the unmorphed unit, unmorphing back will prevent the Unmorphed unit to use those assets.

### (None): Range

Unit will search its autocast radius, try to find a target within range that matches the validator, and then move to that target. The unit will start to morph after it reaches the target unit. The Range field indicates the highest range a caster can start to morph from.

### (None): Target Sorts

Unit will search its autocast radius, try to find a target within range that matches the validator, and then move to that target. The unit will start to morph after it reaches the target unit.

### (None): Validators Unmorph

Validators for the unmorph. Works well in pair with the automatic unmorph flag.

### Ability: Abilities Disabled

* Specific Abilities that are disabled when morphing

### Ability: Abilities Enabled

* Specific Abilities that are enabled when morphing

### Ability: Ability Classes Disabled

* Class of Abilities that cannot be queued during the morph.

### Ability: Ability Classes Enabled

* Class of Abilities that have been previously disabled that can be queued during the morph. The final unit will execute the ability queued.

### Ability: Acquire Priority

* The priority used for an auto cast abilities to determine the ability order used to search for targets

### Ability: Alignment

* Determines what the ability is known as for AI use

### Ability: Auto Cast Acquire Level

* (Unknown) Offensive is the default even for defensive abilities
* Offensive
* Defensive
* None
* Passive

### Ability: Auto Cast Filters

* The filters for determining what unit attributes can be targeted by the auto cast

### Ability: Auto Cast Maximum

* The maximum number of potential targets within range that allows the auto cast to execute

### Ability: Auto Cast Minimum

* The minimum number of potential targets within range for the auto cast to be able to execute

### Ability: Auto Cast Range

* Maximum range at which the auto cast looks for valid targets

### Ability: Auto Cast Validators

* Validators that must return true for the ability to be auto cast

### Ability: Cancel Unit

* Unit that will be created if the morph is canceled. Default (blank) creates the original unit on cancel.

### **Ability: Commands**

#### Command Index

* Cancel
* Execute
* Unmorph

On Issue Order effects, the Execute is command 0, Cancel is 1 and Unmorph is 2.

For the rest, see the ability command section in abilities.

### Ability: Debug Trace

* If enabled the ability returns a message in the UI at the top of the test map if an error occurs when executing.

### **Ability: Info**

Contains the entries for the primary (default morph). This section is affected by most flags, especially auto-cast.

#### Index

Indicates which units the morph will navigate through until reaching the last index. Zerg Roaches units uses this when morphing into an egg first, then into the Ravager.

* Deleting the unit in between, especially on Blizzard's work creates an invisible bug that breaks the whole ability, unless reset. Do not attempt.

#### Sections - Durations + Build Time array

Gives the total time of the morph, according the single section with the greatest sum of time.

* **Delay:** is how long after the morph begins before the abilities, the actor, the collision, the direction the unit is facing, the mover and the stats start to become that of the final unit
* **Duration:** the time over which the abilities, the actor, the collision, the direction the unit is facing, the mover and the stats transition between the initial and final unit.

Here's the summary of each section. Take note that each of the stats transformation in each is transitioned proportinally to the time given in their duration entry.

* The name of the follow up or final unit always displays when processing and cannot be delayed.
* There is an hidden section called: **Use Build Time Array**, that can only been seen in table view. For the **Unmorph** section, it was integrated. This field contains a Delay and Duration enabling check box, which seems to allow the ability to scale with the unit's build time field.

1. **Abilities:** The moment at which point abilities last (**duration**) vs abilities of the new units are obtained (**delay**). Take note that "Cancel" command doesn't play by the Duration rule, but instead, must be put on the "Morphed" unit (so yes, add the same morph ability on the morphed unit). As it seems, the **delay** used in this section also prevents innate behaviors from the Morphed unit.
2. **Actor:** The moment at which point the actors executing a morph.start event last (**duration**). Abil Morph event with blank sub name but with Morph to/morph from event may still appropriate the duration's progressing time for their animation.
3. **Collision:** (Untested) The moment at which point the collision lasts (**duration**) vs the new unit's collision is checked (**delay**).
4. **Facing:** The allowed time at which point the unit may turn to be in position (**duration**). If there is 0 time given, the unit will simply instantly rotate to the morph position (unless the flag: **Ignore Facing** is on). The necessary facing also corresponds to the unit's model animation facing, which is still a smart system.
5. **Mover:** The scaled time at which point the unit adopts the height of the unit (**duration**). For example, Terran structures lifting off evaluate both unit's height, and do the gradual height change according to the duration. If canceling the ability, the height will slowly reset. If using the ability over again while the height was being cancelled (slowly returning), the height will halt from dropping, until the Mover duration arrives over again exactly at that point of height, and will continue taking its new height from that point. This doesn't work for height below 0 and will result in an instant height morph (or delayed). This seems to be a lack of content that would take in consideration negative height.
6. **Stats:** Unit Flags (such as cloaked/burrow), life points, life armor etc that will be obtained according to the **delay**. One way to use it for example would be to put a delay of 1 second, to indicate that in one second, the unit will be cloaked/burrowed). It is unclear which field is kept with the **duration**.

#### Sections - Effects

The Effects applied to the unit when the morph is cancelled, starts and finishes for the abilities.

* Used commonly to apply the **Zerg General - Post Morph (Healing Effect)** when the stats have finished changing
* By default, any effect target at "Target" location considers the caster as the target, it is not necessary to set the location to caster.

#### Collision Range

* If the caster is unable to morph because of blockers, this indicates how much range it can move aside to execute its morphing ability (ex: Viking Fighter Mode).

#### Rally Reset Phase

* **Delay:** (Unknown)
* **Duration:** (Unknown)

#### Random Delay Maximum

* Random delay will be added just before the morph starts. This sets the smallest amount of delay that can be randomized.
* Ability Classes (Dis/En)abled will take effect at this point.

#### Random Delay Minimum

* Random delay will be added just before the morph starts. This sets the largest amount of delay that can be randomized.
* Ability Classes (Dis/En)abled will take effect at this point.

#### Score

* (Unknown)

#### Unit

* Unit that is morphed into. If multiple units are specified, the morphs will occur in succession (like Zerg cocoons which then become the final unit).

### Ability: Progress Button

Custom progress Button that appears if the **Show Progress** flag is enabled (also shows its text) when using the Morph ability. If this field is empty, the default unit icon of the actor containing the newer unit will be used (goes blank if that unit has no relative actor). Also, the default unit icon does not provide any text.

* Modifying unit icon from the actor events does not modify this button image, unfortunatly.

* It has already been proposed to Blizzard to add a functionnality that covers the "Unmorph" stage, as it does not exist yet. For what it does now, using this field overrides all "Morph" "Unmorph" stages icons.

### Ability: Set ID

* String that groups different abilities of the same type
* This is used to link different abilities together
* Used for getting different units with the same ability to also use the ability
* The Issue Order effect and triggers that order the use of the one ability will also use the other
* Abilities sharing the same string will also be used by selected units when using any one of the abilities

### Ability: Tech Alias

* String used as an alias to group data objects together as equivalent for use by Requirements

### Ability: Tech Player

* **Owner:** Player currently in control of the unit (eg. neural parasite) is used for requirements of the ability
* **Upkeep:** Player paying the supply of the unit is used for requirements of the ability

### Ability: Validator

* Validators for the morph. Works well in pair with the automatic flag.

### Cost: Refund Fraction

#### Charge

* If the ability is cancelled this determines what fraction of the \*\*Cost - Cost - Charge - Count (Use)\*\* is refunded

#### Cooldown

* If the ability is cancelled this field determines what fraction of the cooldown is deducted from the cooldown

#### Resource

* How much is refunded in resources if the ability is cancelled

#### Vital Fraction

* How much is refunded in percentage of vitals if the ability is cancelled

#### Vitals

* How much is refunded in vitals if the ability is cancelled

### Stats: Flags

* **Auto Cast:** Allows the ability to be auto cast. Seems only to work for the Morph side, not the Unmorph.
* **Auto Cast (Idle Only):** (Unknown)
* **Auto Cast (On):** Makes the auto cast default to on
* **Automatic:** Begins the morph automatically as soon as the requirements are met and all validators return true
* **Automatic Unmorph:** Autmaticly uses Unmorph, the same way "Automatic" does. Seems to be unable to work without Automatic on. This is an unfortunate bug that has been reported to Blizzard.
* **Best Unit:** Used for group casting. If enabled, only the "best unit" (closest unit) will cast the ability.
* **Birth:** (Unknown) plays the birth animation on morph completion?
* **Disable Abilities:** Disables all abilities during the morph.
* **Disable Collision:** disables the units collision while morphing
* **Fast Build:** Allows the "FastBuild" cheat code to affect the morph completion time. As this cheat is probably only used in testing, this flag is mainly for testing purposes.
* **Ignore Collision:** Ignores the collision of the unit doing the morphing for the duration of the morph
* **Ignore Facing:** Ignores the default facing set under the Units data tab. If this is unticked turnable units will rotate back to their default facing during the morph.
* **Ignore Food:** Ignores the supply value of the unit under the Units data type
* **Ignore Placement:** Placement requirements do not affect the morph. If both unts have conlifcting pathing footprints and are unable to move (ex: Spire to Greater Spire), leaving this disabled will cause the unit to be unable to Morph, since it wont be able to find a placement. This must be disabled if using a Morph Placement ability.
* **Ignore Unit Cost:** Ignores the costs of the unit under the Units data type
* **Interruptible:** Morph cannot be stopped by other abilities or use of weapon.
* **Move Blocking Units:** Orders blocking units to move out of the way
* **Produce:** (Unknown)
* **Provide Source Unit Tech:** When on, CAbilMorph will pass the source unit’s unit type to the unit it morphed to. The final unit will automatically inherit the source unit's unit link as its Tech Alias. This property is inherited throughout the entire morphing chain.
	+ Ex: Town Hall -> Keep -> Castle. A Castle would count as both a Keep and a Town Hall. Even a directly created Castle would count as both a Keep and a Town Hall even though it was not actually morphed from either. Why don't we simply add Town Hall and Keep to the Castle's alias (by adding them into the Tech Alias field of the Castle)? We use this more indirect route because ProvideSourceUnitTech only takes effect when the unit is in its Completed state. Only then would it count as the source unit in tech count. If we were to use the TechAlias field, the alias would exist in any state, even when the unit is morphing (InProgress state). In this case, when you morph a Keep to Castle, you would be in an awkward interstitial state: because you have a Completed Keep and an InProgress Castle at the same time, the tech count system would think you have an InProgress Keep, which is not the case.
* **Rally:** (Unknown)
* **Rally Reset:** (Unknown)
* **Require Acquired Target:** “Move to and then Morph” support
* **Require Acquired Target Unmorph:** “Move to and then Morph” support
* **Show PlaceHolder:** Used for the Morph Placement, enables or not the display of the placeholder from the unit's actor when the unit is issued the command to morph at location.
* **Show Progress:** The progress bar for the morph will be visible.
* **Suppress Movement:** Stops the unit from moving while morphing
* **Toggle:** Instead of having 2 morph abilities (like the viking), this enables the newer unit to use the same ability to morph back.
* **Transient:** Casting ability does not interrupt the order queue
	+ If enabled disrupts the progress of the ability making the morph instant
* **Turn Off Auto Cast When Owner Leaves:** When the owning player leaves the game the autocast is turned off
* **Wait Until Stopped:** Does not wait for the unit to fully deaccelerate.

### UI: Activity

* The string shown above the progress bar when morphing
* Do not forget to change the Text Key first if altering this

### UI: Actor

* String sent to the Actors data type when the ability is used for the Ability Key term for actor events

### UI: Alert

* The alert from the Alerts data type that is played when the morph finishes

### UI: Error Alert

* The alert from the Alerts data type that is played if there is an error and the morph cannot occur

### UI: Finish Global Alert

* The alert from the Alerts data type that is played to all players when the morph finishes

### UI: Start Global Alert

* The alert from the Alerts data type that is played to all players when the morph starts

## Related

* Merge
* Mergeable
* Morph Placement