Data/Abilities/Queueable/Train

# Train

### Hint

* Use this when you want to disable/enable the building/training of a specific unit. You may also want to disable Queue.
* This is very similar to the Learn, Specialize and Research abilities, but is used for unit creation

## Fields Description

### None - Agent Unit Validator

When set, the ability will always need an agent unit to cast and will check against the validators set in this field when training units.

With this field, “Item Shop” abilities now can be easily created in SC2.

* For item shops, users will usually want the buyer unit of the shop to have an inventory to be able to purchase items.
* Previously, SC2 didn't have this support, so even if the buyer unit didn’t have an inventory, the item would always be created.
* With the AgentUnitValidator field, users can add validators like “Unit has a valid inventory” and “Inventory is not full”. Therefore, if the agent unit doesn’t have an inventory, the ability would simply throw an error message and wouldn’t be cast.

### None - Ignore Unit Cost Requirements

When set, the train ability will ignore unit costs as long as tech requirements are met.

* This can be used to implement special game mechanics like “Your first hero is free”.
* This field does not require the flag: **Ignore Unit Cost** enabled, as using that flag will override the requirement.

### Ability - Death Type When Cancelled

Configures the death type as a message to the actor to use the right type of death when the train is cancelled.

* Does not work with eggs for Zerg. As far as the Larva transforms into an egg, it seems to send this field oblivion, searching for a Larva that doesn't exist anymore.

### Ability - Death Type When Finished

Configures the death type as a message to the actor to use the right type of death when the train is complete.

* Does not work with eggs for Zerg. As far as the Larva transforms into an egg, it seems to send this field oblivion, searching for a Larva that doesn't exist anymore.

### Ability - Info - Cost Display

When a unit is trained, this will cause a floating text tag with the cost to appear above the training structure/unit.

### Ability - Info - Technology Resource Cost

Additional cost to train a unit. If the flag "Ignore unit cost" is true, then this field can be used to set an alternate price for training a unit

### Ability - Proxy Unit

Temporary unit that should precede any production made by this ability.

* Used by Swarm Queen to produce an egg, that becomes the trained units. Think of it as instead sacrificing the main unit to become an egg, you produce the egg aside.
* Is static, you can't really control or use a delay before the proxy unit spawns.
* The real caster can barely be traced by validators or triggers. They don't even consider the caster to cast an ability (not even train) when the caster uses it. There are only 2 methods to trace it, known:

1. On the egg actor, you can send a signal to a reference. The Swarm Queen Egg sends a Signal "Egg" to target ::global.SwarmQueen, which is a reference. On the Swarm Queen, there is an event use called "ActorCreation" that "Reference Set" that Queen actor (the real caster). When the Egg is created, it communicates to its only relative that belongs to the same effect tree (of casting the train ability).
2. Triggers almost can't trace it, except for one event called: "Unit is Issued Order". This is the only event that can trace it.

* Uses the Kill on Complete, Kill On Cancel flags, instead of the main unit using the train ability. Omitting to use those may result into keeping the proxy unit.
* Proxy unit's supply cost adds up when created. It won't be displayed on the training button, however.
* Once selected as "proxy unit", that X unit may never be able produce another proxy unit externally with this train ability. For example, if Barracks produces a proxy marine that generates a Reaper, even if you create a marine aside (from another source), and use its train reaper button, the marine will not produce another proxy unit, he is the proxy unit.
* The Proxy unit cannot be affected by the trained unit info effect. Any effect intended will not happen until the final unit is trained.

There are rules in order to make this work:

* The proxy unit must possess the same train ability, and have the button set on its command board. It is recommended to use a Queueable ability, although not it is necessary.
* The cost is only applied on the Proxy unit. For example, if your train costs 75 energy, your main unit won't be able to use it, but once it has enough energy, its energy won't spend. This is actually a bug and as this is has been reported to Blizzard as an inconvenience, it is a rule that we can't escape from. The Proxy Unit has to spend, so make sure he has the vitals/cost to afford the unit.
* If there's not enough supplies to cover the final production, but yet enough for the proxy unit, only the proxy unit may spawn and it won't queue the final unit. You want to disable the "Wait For Supplies" flag.
* If the previous rule isn't respected, the proxy unit will simply remain as such and replace any production.
* If the proxy unit moves or act while producing the final unit, the production is cancelled.
* There is a bug discovered using the Queen. Set all the same Zerg Units as a cocoon produces, and it seems that the Queen auto-uses the ability on its own without any script control or anything.

### Ability - Proxy Offset

Location around the unit owning the train ability where the proxy unit should immediately spawn.

### Ability - Info

Combines field of Ability Commands and Cost fields in abilities.

These fields are exclusive to the train ability.

#### Alert

Alerts from the Alerts data type that are played if certain abilities are unable to be learned because the requirements have not been met

#### Effect

Casts an effect when a unit / item is done training. The following can cause targeting of the training structure of unit being trained. For Shops, there does not appear to be a way to target the buying unit.
Use Target or Target Outer to affect the unit being trained (ex. An Apply behavior at Target will apply the behavior to the unit / item)
Use Caster, Caster Outer Source or Outer to affect the unit doing the training (ex. an apply behavior at source will apply it to the training unit / shop / structure)
Use Unit Origin for (Unknown - didn't appear to apply to any units)

#### Unit

Which Unit is created when training is finished

* Inserting many units in this field is not related to a level system. It will produce every units listed there (as much as the placement allows it) per train.

#### Location

Should the unit be spawned at Source, or should it be spawned at rally point.

#### Rotation

If an offset is used (like for the proxy unit for example), dertmines which of the produced unit or caster will orient the offset.

* For example, if using a (0,1) which represents 1 range behind the caster, if the rotation is set at:
	+ Target: The unit will spawn always on north, at 1 range, because (x,y+1) means vertical and above
	+ Source: The unit will spawn behind the source, according to its rotation point.
* A good way to guess why, would be to try it on a Swarm Queen. Notice that queens have an animation that has them cast their rear end. To keep the animation adequate, this field is useful as "source".

### Cost - Refund Fraction

Cost that is refunded. See cost on abilities for more detailed information.

### Stats - Flags

**Best Unit:** Uses one unit at the time for this ability.

**Bypass Food Restriction:** Ignore the unit's supply cost and produce it anyway.

* This field requires **Wait for Supplies** flag disabled in order to work (unknown if it's a intented or not).
* Does not allow to exceed the supply limit.

**Charge Caster Player:** Normally, neutral shop abilities require buyer and seller players to share the spending of resources with each other via the “Ally Spending” flag. If this is not the case, the buyer would get the error message, “Can't Spend On that Player”.

* By default, neutral players share costs with all players. But if a user wanted to create an allied shop, a shop where allied players are able to purchase items or units, he probably wouldn’t want these players to share spending. Otherwise, players would be able to spend their allies’ money.
* This flag, ChargeCasterPlayer, is designed to solve this issue. When on, the cost of the sold item or unit will be charged on the player who issued the Purchase order, even if the buyer and seller aren’t share spending.
* If there are other players who share spending with the buyer player, and the buyer player doesn’t have enough resources to pay the cost, the ability will still charge the cost on these other players.

**Copy Life Percentage:** Determines whether the trained unit would inherit the life percentage of the trainer unit.

**Disable Collision:** (Unsure) Newly produced unit ignore collision when the placement occurs on production

**Ignore Unit Build Time:** If unchecked, a unit’s build time will be added to the ability's build time.

**Ignore Unit Cost:** Ignore the cost field (minerals and vespene) on the unit data. This does not affect the resource cost from within the ability.

**Ignore Unit Stock Charge:** Units and item can have a charge data, so that when selling items and units, unit and item data can set their default Stock information (such as starting cooldown in shops, max stocks in shops, etc.) This flags ignores this.

**Kill On Cancel:** Kill the ability user on cancel (ex: Eggs)

**Kill On Complete:** Kill the ability user on complete (ex: Eggs)

**Select:** If using a proxy unit or simply a morph unit, that unit, if selected, will select its newest productions.

**Transient:** This ability can be used while moving

**Turn Auto Cast Off When Owner Leaves:** If the unit is set to auto-cast, this sets it to off if the player is not active in the map anymore.

**Use Unit Order Queue:** Prevent the unit using this ability from performing any other action.

**Wait For Supplies:** Allows or disallows the unit to be placed in queue in the event of lacking the supply to produce it.

## Related

* Learn
* Queue
* Research
* Specialize