Mod API Reference:CustomSpecialUnit

CustomSpecialUnit: Subclass of 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 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 Nullable<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 Nullable<integer>: Added in v5.22.2
• ImageFilename string:
• IncludeABeforeName boolean:
• IsVisibleToAllPlayers boolean:
• ModData string:
• Name string:
• OwnerID PlayerID:
• TextOverHeadOpt string:

Functions

• WL.CustomSpecialUnitBuilder.Create(ownerPlayerID PlayerID) (static) returns CustomSpecialUnitBuilder:
• WL.CustomSpecialUnitBuilder.CreateCopy(clone CustomSpecialUnit) (static) returns CustomSpecialUnitBuilder:
• Build() returns CustomSpecialUnit: