Editing Mod API Reference:CustomSpecialUnit

'''CustomSpecialUnit''':  Subclass of [[Mod API Reference:SpecialUnit|SpecialUnit]]
* '''AttackPower''' ''integer'': The number of armies this unit adds to attacks that it's a part of.
* '''AttackPowerPercentage''' ''number'': Attacks that include this unit have their power multiplied by this number.  For example, 1.5 would mean that if a player attacked with this unit and 20 armies, it would get a total attack power of 30 (50% more).  A value of 1 (the default) has no effect.
* '''CanBeAirliftedToSelf''' ''boolean'': If true, players can use the Airlift Card to move this unit around, as long as it doesn't change ownership.
* '''CanBeAirliftedToTeammate''' ''boolean'': If true, players can use the Airlift Card to move this unit to a teammate.
* '''CanBeGiftedWithGiftCard''' ''boolean'': If true, players can gift this unit to another player if it's on the territory they play a Gift Card on.
* '''CanBeTransferredToTeammate''' ''boolean'': If true, players can transfer this unit to a teammate using an attack/transfer order.
* '''CombatOrder''' ''integer'':  Determines which special units take damage before others if multiple special units are on the same territory.  The lower the number, the sooner your special unit takes damage.  If you supply a negative number, your special unit will take damage before armies involved in the combat (added in v5.24.1).  A commander has a CombatOrder of 10000, so if you want your special unit to protect the commander you should use a number less than 10000.  You should try to use a number that no other mod is using so that damage order is consistent.  For this reason, avoid round numbers like 0, 1, or 1000, etc.
* '''DamageAbsorbedWhenAttacked''' ''integer'': When this unit takes damage, it will reduce the amount of damage remaining to other units on this territory by this value.   This value has no effect if the unit has a ''Health''.
* '''DamageToKill''' ''integer'': The number of damage points it takes to kill this unit.  This value has no effect if the unit has a ''Health'', as the health will be used instead.
* '''DefensePower''' ''integer'': The number of armies this unit adds to defence when it's on a territory that's attacked.
* '''DefensePowerPercentage''' ''number'': When the unit is on a territory that's attacked, the total defence power is multiplied by this number.  See AttackPowerPercentage.
* '''Health''' ''[[Mod API Reference:Nullable|Nullable]]<integer>'': When not nil, this defines the health of the unit.  The unit will automatically reduce its health when it's part of combat where it receives damage, and automatically die if the health goes below 1.
* '''ImageFilename''' ''string'': The name of a png file in the SpecialUnitImages/ folder of the mod.  This image must be a png and must be no bigger than 60x100 pixels.  Mods may have up to 5 SpecialUnitImages.
* '''IncludeABeforeName''' ''boolean'': If true, Warzone will automatically put the word "A" before the name of this unit.  For example, if Name is "Tank", and IncludeABeforeName, Warzone will use "a Tank" or "A Tank" as necessary in places where it makes sense to include the "a", and leave off the "a" in places where it makes sense to leave it off.
* '''IsVisibleToAllPlayers''' ''boolean'': If true, the territory this unit is on will always be visible to all players in the game, even if that spot would normally be fogged.
* '''ModData''' ''string'': Has no effect.  This is just a place for mods to place data if they want to store something along with the unit.
* '''ModID''' ''[[Mod API Reference:Nullable|Nullable]]<[[Mod API Reference:ModID|ModID]]>'': The ID of the mod that created this unit.
* '''Name''' ''string'': The name of the unit, which is shown to players.
* '''TextOverHeadOpt''' ''string'': A string that will show above the unit's head on the map.  If the unit has a ''Health'' and this field is left at nil, the unit's health is automatically put over its head.

It is strongly advised that you limit the number of special units that a player can have to something reasonable, such as 3, otherwise it can easily become tedious to the player.

== Creating ==

Since CustomSpecialUnit is read-only, creating one requires the use of the CustomSpecialUnitBuilder class, like this:


  local builder = WL.CustomSpecialUnitBuilder.Create(order.PlayerID);
  builder.Name = 'Tank';
  builder.IncludeABeforeName = true;
  builder.ImageFilename = 'Tank.png';
  builder.AttackPower = 10;
  builder.DefensePower = 10;
  builder.DamageToKill = 10;
  builder.DamageAbsorbedWhenAttacked = 10;
  builder.CombatOrder = 3415;
  builder.CanBeGiftedWithGiftCard = true;
  builder.CanBeTransferredToTeammate = true;
  builder.CanBeAirliftedToSelf = true;
  builder.CanBeAirliftedToTeammate = true;
  builder.IsVisibleToAllPlayers = false;
  local unit = builder.Build();
  
  
  
You can also clone and existing CustomSpecialUnit like this:

  local builder = WL.CustomSpecialUnitBuilder.CreateCopy(unit);
  builder.Name = 'ChangedName';
  local newUnit = builder.Build();
  

'''CustomSpecialUnitBuilder''': 
* '''AttackPower''' ''integer'': 
* '''AttackPowerPercentage''' ''number'': 
* '''CanBeAirliftedToSelf''' ''boolean'': 
* '''CanBeAirliftedToTeammate''' ''boolean'': 
* '''CanBeGiftedWithGiftCard''' ''boolean'': 
* '''CanBeTransferredToTeammate''' ''boolean'': 
* '''CombatOrder''' ''integer'': 
* '''DamageAbsorbedWhenAttacked''' ''integer'': 
* '''DamageToKill''' ''integer'': 
* '''DefensePower''' ''integer'': 
* '''DefensePowerPercentage''' ''number'': 
* '''Health''' ''[[Mod API Reference:Nullable|Nullable]]<integer>'': Added in v5.22.2
* '''ImageFilename''' ''string'': 
* '''IncludeABeforeName''' ''boolean'': 
* '''IsVisibleToAllPlayers''' ''boolean'': 
* '''ModData''' ''string'': 
* '''Name''' ''string'': 
* '''OwnerID''' ''[[Mod API Reference:PlayerID|PlayerID]]'': 
* '''TextOverHeadOpt''' ''string'': 

== Functions ==

* '''WL.CustomSpecialUnitBuilder.Create'''('''ownerPlayerID''' ''[[Mod API Reference:PlayerID|PlayerID]]'') (static) returns [[Mod API Reference:CustomSpecialUnitBuilder|CustomSpecialUnitBuilder]]:
* '''WL.CustomSpecialUnitBuilder.CreateCopy'''('''clone''' ''[[Mod API Reference:CustomSpecialUnit|CustomSpecialUnit]]'') (static) returns [[Mod API Reference:CustomSpecialUnitBuilder|CustomSpecialUnitBuilder]]:
* '''Build'''() returns [[Mod API Reference:CustomSpecialUnit|CustomSpecialUnit]]:

[[Category:Mod API Reference]]