Battle Documentation

soldiers to kill

optional, default value=false

hide bodies

Returns:

nil

unit:reduce_hitpoints_unary(number unary hitpoints, [boolean hide bodies])

Reduces hitpoints of the unit. The optional second argument allows their bodies to be hidden - this is useful if it's desired that the unit 'disappear'.

Parameters:

percentage of full hit points of unit to reduce

optional, default value=false

hide bodies

Returns:

nil

unit:heal_hitpoints_unary(number unary hitpoints, [boolean allow resurrection])

Heals the unit to the specified unary proportion of full strength i.e. 1.0 = full strength. If the allow-resurrection flag is set then dead entities may be resurrected, otherwise the function heals where it can. The function does not work in all circumstances, healing animals + handlers are not currently supported.

Parameters:

percentage of full hit points to heal to.

unit:unary_hitpoints()

optional, default value=true

Allow resurrection of dead entities.

Returns:

nil

unit:respawn()

Respawns the unit in a supplied position on the battlefield.

Returns:

nil

Returns the hitpoint strength of all soldiers in the unit, expressed as a unary fraction of the the initial hitpoint strength of the unit. A returned value of 0.75 would indicate that the unit has lost 25% of the hitpoints it started the battle with.

Returns:

number unary proportion

Morale and Fatigue

unit:is_wavering()

Returns whether the morale of the unit is currently wavering.

Returns:

boolean is wavering

unit:is_routing()

Returns whether the unit is currently routing.

Returns:

boolean is routing

unit:is_invulnerable()

Returns whether the unit is currently invulnerable.

Returns:

boolean is invulnerable

unit:is_rampaging()

Returns whether the unit is currently rampaging.

Returns:

boolean is rampaging

unit:is_shattered()

Returns whether the unit is currently shattered (routing without possibility of return).

Returns:

boolean is shattered

unit:is_crumbling()

Returns whether the unit is currently crumbling (undead's equivalent of routing).

Returns:

boolean is crumbling

unit:is_unstable()

Returns whether the unit is currently daemonically unstable (daemonic equivalent of routing).

Returns:

boolean is unstable

unit:is_left_flank_threatened()

Returns whether the left flank of the unit is currently threatened by the enemy.

Returns:

boolean left flank threatened

unit:is_right_flank_threatened()

Returns whether the right flank of the unit is currently threatened by the enemy.

Returns:

boolean left right threatened

unit:is_rear_flank_threatened()

Returns whether the rear of the unit is currently threatened by the enemy.

Returns:

boolean rear threatened

unit:left_flank_threat()

Returns the battle_unit threatening this unit's left flank. If no such unit is threatening then no value is returned.

Returns:

battle_unit threatening unit

unit:right_flank_threat()

Returns the battle_unit threatening this unit's right flank. If no such unit is threatening then no value is returned.

Returns:

battle_unit threatening unit

unit:rear_threat()

Returns the battle_unit threatening this unit's rear. If no such unit is threatening then no value is returned.

Returns:

battle_unit threatening unit

unit:current_target()

Returns the battle_unit this unit is targeting. If no unit is being targeted then no value is returned.

Returns:

battle_unit target unit

unit:is_on_top_of_platform()

Returns whether the unit is currently on the top of a platform, such as a wall.

Returns:

boolean is on platform

unit:is_controllable()

Returns whether the unit is currently controllable.

Returns:

boolean is controllable

unit:is_deploying()

Returns whether the unit is deploying or waiting to be

Returns:

boolean is deployed.

unit:is_deployed()

Returns whether the unit has been deployed

Returns:

boolean is deployed.

unit:fatigue_state()

Returns the fatigue state of the unit as a string. Possible values are threshold_fresh, threshold_active, threshold_winded, threshold_tired, threshold_very_tired and threshold_exhausted.

Returns:

string fatigue state

Ammunition and Range

unit:ammo_left()

Returns the remaining ammunition count of this unit.

Returns:

number current ammunition

unit:starting_ammo()

Returns the amount of ammunition the unit started the battle with.

Returns:

number starting ammunition

unit:set_current_ammo_unary(number unary ammunition level)

Sets the current ammunition level of the unit to the supplied unary value. Setting a value of 0 would mean the unit would have no ammunition, whereas setting a value of 1 would mean the unit would have the amount of ammunition they started the battle with. It is permitted to set a value greater than 1, but the unit will appear to have full ammunition on the UI until its ammunition level drops back below 100%.

Parameters:

unit:missile_range()

unary ammunition level

Returns:

nil

Returns the missile range of this unit in metres.

Returns:

number missile range

Special Abilities

unit:can_perform_special_ability(string special ability key )

Returns whether the unit can perform the specified special ability. Valid special abilities are defined in the unit_special_abilities database table.

Parameters:

special ability key

Returns:

boolean can perform ability

unit:disable_passive_special_abilities([boolean disable])

Disables or re-enables all passive special abilities of this unit. It only affects abilities owned by the unit. Abilities specify if they are passive in the unit_special_abilities database table. Passive abilities are mostly buffs or infinite effects. This function works independently from unit:disable_special_ability so it will not re-enable abilities affected by it.

Parameters:

optional, default value=true

Disables or re-enables the ability (true for disabling it)

Returns:

nil

unit:disable_non_passive_special_abilities([boolean disable])

Disables or re-enables all non_passive special abilities of this unit. It only affects abilities owned by the unit. Abilities specify if they are passive in the unit_special_abilitiesunit_special_abilities database table. Non-passive abilities are mostly direct damage spells or abilities. This function works independently from unit:disable_special_ability so it will not re-enable abilities affected by it.

Parameters:

optional, default value=true

Disables or re-enables the ability (true for disabling it)

Returns:

nil

unit:disable_special_ability(string ability_key, [boolean disable])

Disables the specified special ability from this unit. It only affects the ability instance currently owned by the unit. This function works independently from unit:disable_passive_special_abilities and unit:disable_non_passive_special_abilities so it will not re-enable abilities affected by it.

Parameters:

ability_key

unit:owned_passive_special_abilities()

optional, default value=true

Disables or re-enables the ability (true for disabling it)

Returns:

nil

Returns a lua table of passive special abilities owned by this unit. Abilities specify if they are passive in the table unit_special_abilities. Passive abilities are mostly buffs or infinite effects - they are abilities activated automatically, not by the player.

Returns:

table owned abilities, Table of strings containing the key of the corresponding special abilities

unit:owned_non_passive_special_abilities()

Returns a lua table of non-passive special abilities owned by this unit. Abilities specify if they are passive in the table unit_special_abilities. Non-passive abilities are abilities activated by the player, mostly direct damage abilities and spells.

Returns:

table owned abilities, Table of strings containing the key of the corresponding special abilities

unit:owned_special_abilities()

Returns all special abilities owned by an unit. Valid special abilities are defined in the special_abilities table.

Returns:

table owned abilities, Table of strings containing the key of the corresponding special abilities

unit:num_special_abilities()

Returns the number of special abilities this unit has.

Returns:

number number of special abilities

unit:can_use_magic()

Returns whether the unit can use any special abilities that cost magic.

Returns:

boolean can use magic

Special Ability Flags

Special Abilities are associated with special ability flags, and are activated and deactivated depending upon what special ability flags are currently active, either globally or on a particular unit. Supported special ability flags on a given unit are found in the special_ability_invalid_usage_flags table and are also listed below. Special ability flags may be activated or deactivated per-unit with unit:set_special_abilities_flags and also globally with battle:set_special_abilities_flags.

army_is_full

other_abilities_none_on_wind_up

other_abilities_at_least_one_on_wind_up

other_abilities_just_activated_after_wind_up

cannot_perform_missile_attack

cannot_find_enemies_in_intercept_range

enemies_in_intercept_range

enemies_in_intercept_range_commander_class

no_enemies_in_intercept_range_commander_class

enemies_in_intercept_range_large

no_enemies_in_intercept_range_large

climbing

climbing_manning_eq_on_platform

not_climbing_manning_eq_on_platform

disembarked_from_a_ship

embarked_on_a_ship

defending_a_zone

dismounted

enraged

engaged_in_melee

engaged_in_melee_anything

flying_currently

flying_unit

ground_unit

grounded

has_casting_ability

hasnt_casting_ability

health_above_10%

health_above_20%

health_above_25%

health_above_50%

health_above_75%

health_below_25%

health_below_50%

health_below_75%

health_above_50%_base

health_below_50%_base

mana_above_50%

mana_below_50%

mana_equal_or_above_value_15

mana_below_value_15

winning_melee_combat

losing_melee_combat

manning_equipment

morale_is_higher_than_broken

morale_is_higher_than_shattered

morale_is_higher_than_wavering

morale_is_broken_or_lower

morale_is_wavering_or_lower

morale_is_higher_than_half_of_base_morale

morale_is_lower_than_half_of_base_morale

fatigue_is_below_active

fatigue_is_below_winded

fatigue_is_below_tired

fatigue_is_below_very_tired

fatigue_is_below_exhausted

moving

not_yet_enraged

officer_dead

on_a_platform

not_on_a_platform

docked

not_docked

out_of_melee

out_of_melee_anything

phase_is_deployment

phase_is_the_end_phase

have_ammo_left

have_max_ammo

have_ammo_below_threshold

hp_replenish_cap_reached

unit_alive

unit_dead

unit_is_commander_class

unit_is_not_commander_class

ground_type_is_not_forest

unit_in_forest

unit_is_not_in_forest

unit_has_murderous_prowess

unit_is_not_pre_murderous_prowess

unit_does_not_have_murderous_prowess

unit_is_in_fort

unit_is_out_fort

unit_is_in_withdraw

unit_is_not_in_withdraw

unit_is_in_melee_breakoff

unit_is_not_in_melee_breakoff

unit_is_attacking_rear_or_flank

unit_is_not_attacking_rear_or_flank

unit_is_fearless

unit_is_not_fearless

has_realm_of_souls_tier_1

has_realm_of_souls_tier_2

has_realm_of_souls_tier_3

hasnt_realm_of_souls_tier_1

hasnt_realm_of_souls_tier_2

hasnt_realm_of_souls_tier_3

unit_is_not_construct

unit_is_not_single_entity

is_not_missile_unit

unit_is_not_shielded

unit_tier1_kills

unit_tier2_kills

unit_tier3_kills

cannot_find_allies_in_intercept_range

allies_in_intercept_range

commander_died_within_range

enemy_unit_died_within_range

no_enemy_unit_died_within_range

contempt_allies_in_intercept_range

no_contempt_allies_in_intercept_range

knight_allies_in_intercept_range

no_knight_allies_in_intercept_range

peasant_allies_in_intercept_range

no_peasant_allies_in_intercept_range

flying_over_platform

flying_over_invalid_location

unit_is_not_charging

unit_is_not_large

unit_is_large

friendly_battle_leader_killed_or_routed

friendly_battle_leader_not_killed_or_routed

no_harmony_yin_in_proximity

no_harmony_yang_in_proximity

unit_broken_within_range

enemy_unit_routing_or_broken_within_range

no_enemy_unit_routing_or_broken_within_range

is_rampaging

is_not_rampaging

living_unit

undead_unit

unit_is_not_a_lizard_unit

unit_is_skaven

unit_is_not_skaven

unit_is_gorger

unit_is_not_gorger

unit_is_hellforged

unit_is_not_hellforged

daemonic_unit

not_daemonic_unit

unit_is_bound_fire_daemon

unit_is_not_bound_fire_daemon

unit_is_moulder_monster

unit_is_nurgling

unit_is_not_nurgling

has_khorne_mark

hasnt_khorne_mark

has_nurgle_mark

hasnt_nurgle_mark

has_slaanesh_mark

hasnt_slaanesh_mark

has_tzeentch_mark

hasnt_tzeentch_mark

unit_is_expendable

unit_is_not_expendable

unit_has_contempt

unit_does_not_have_contempt

unit_in_water

unit_is_not_in_water

Not all flags will be supported by each game.

unit:set_special_abilities_flags(string flag key, boolean enable/disable)

Activates or deactivates a special ability usage flag on the unit. Valid flags are listed at the top of this section.

Parameters:

1	`string`	flag key
2	`boolean`	enable/disable

Returns:

nil

Unit Behaviours

unit:can_use_behaviour(string behaviour)

Returns whether the unit can use a particular behaviour this battle. Valid behaviours are currently as follows: defend, drop_siege_equipment, abandon_artillery_engines, change_formation_spacing, dismantle_artillery_piece, dismount, fire_at_will, skirmish, release_animals, unlimber, board_ship, and formed_attack.

Parameters:

behaviour

Returns:

boolean behaviour can be used

unit:is_behaviour_active(string behaviour)

Returns whether a particular behaviour is currently active. Valid behaviours are currently as follows: defend, drop_siege_equipment, abandon_artillery_engines, change_formation_spacing, dismantle_artillery_piece, dismount, fire_at_will, skirmish, release_animals, unlimber, board_ship, and formed_attack.

Parameters:

behaviour

Returns:

boolean behaviour is active

Unit Attributes

Unit attributes define certain intrinsic properties of a unit in battle. Attributes are generally assigned to a unit type in the game database, but may be enabled or disabled per-unit in script using the unit:set_stat_attribute function. Valid attribute keys are shown in the following list:

Attribute Key	Description
`all_ranks_fire`	All ranks can fire if using a weapon that only allows one rank.
`berserk`	This unit will occasionally go berserk.
`cant_run`	This unit cannot run - generally for limbered artillery.
`campaign_stealth`	This unit is able to move around the campaign map without being seen.
`causes_fear`	This unit frightens all enemy units, reducing their morale when nearby. It is also immune to fear.
`causes_terror`	The unit can cause terror, making enemies rout for a short time but without morale penalties. It is also immune to terror and fear.
`charge_defense`	Defense bonus agains charges by all units.
`charge_defense_vs_large`	Defense bonus agains charges by large units.
`commander_hunter`	This unit is changed in various ways to make them better at killing commanders.
`disciplined`	This unit doesn't suffer morale penalty from general's death.
`encourages`	This unit provides a morale bonus to nearby allies.
`fatigue_res`	Fatigue doesn't have as much of an effect.
`fatigue_immune`	Fatigue doesn't affect this unit.
`fire_while_moving`	This infantry unit can fire while moving.
`formed_attack`	This unit will try to stay in formation when in melee.
`guerrilla_deploy`	Can deploy outside deployment zone (vanguard deployment).
`hide_forest`	Can hide in forest.
`hide_grass`	Can hide in grass.
`hide_scrub_and_forest`	Can hide in scrubland.
`hide_building`	Can hide in buildings.
`ignore_ground_move_mod`	Doesn't get slowed down by terrain.
`strider`	Strider attribute.
`immune_to_psychology`	The unit is immune to psychological attacks (fear and terror).
`impetuous`	The unit gains an extra morale bonus when eager.
`invincible`	The unit cannot be damaged.
`mounted_fire`	The unit can fire while on a mount.
`mounted_fire_move`	The unit can fire while on a moving mount.
`mounted_fire_parthian`	The unit can fire while on a moving mount in a Parthian fashion.
`rampage`	This unit may rampage if put under pressure.
`resist_cold`	This unit doesn't take extra casualties from cold climates in campaign.
`resist_heat`	This unit doesn't take extra casualties from hot climates in campaign.
`run_amok`	This unit may run amok if put under pressure.
`scare_horse`	This unit scares horses.
`scare_immune`	This unit is immune to fear effects.
`snipe`	The unit remains hidden while firing.
`stalk`	This unit can remain hidden while moving.
`unbreakable`	This unit's morale cannot be broken.
`undead`	The unit is undead (does not rout, immune to terror, receives crumble damage when morale is low).
`unspottable`	If this unit is able to hide in its current location, it will not be spotted by enemies until they are very close.
`expendable`	A normal (non-expendable) unit's morale does not suffer from witnessing an expendable unit routing.
`construct`	The unit is a statue.
`gorger`	The unit is a statue.
`hellforged`	The unit is a hellforged.
`wallbreaker`	The unit can attack walls physically.
`devastating_flanker`	The unit can attack walls physically.
`daemonic`	The unit is daemonic.
`bound_fire_daemon`	The unit is a fire bound daemon.
`flying`	The unit is flying.
`always_flying`	The unit is always flying.
`ignore_trees`	The unit ignores trees.
`moulder_monster`	The unit is a moulder monster that can be targeted by Throt's abilities.
`yin`	Cathay unit is affiliated with yin.
`yang`	Cathay unit is affiliated with yang.
spell_mastery	The unit has spell mastery (mastery of elemental winds).
`charge_reflection`	Unit can reflect charges.
`ogre_charge`	The unit has ogre charge.
shoot_disabled	Missile attacks disabled.
melee_disabled	Melee attacks disabled.
mark_khorne	Unit has the mark of Khorne. Used for ability targeting.
mark_nurgle	Unit has the mark of Nurgle. Used for ability targeting.
mark_slaanesh	Unit has the mark of Slaanesh. Used for ability targeting.
mark_tzeentch	Unit has the mark of Tzeentch. Used for ability targeting.
invulnerable_to_effects_ally	Invulnerable to damage from an allied effect.
invulnerable_to_effects_enemy	Invulnerable to damage from allied effects.
contempt	A unit with contempt does not suffer morale penalties from witnissing nearby allies rout, unless they also have contempt.

Not all attributes will be supported by each game.

unit:set_stat_attribute(string attribute key, boolean enable/disable)

Enables or disables a global attribute on the unit. Attribute keys are listed above, in the Unit Attributes section description.

Parameters:

1	`string`	attribute key
2	`boolean`	enable/disable

Returns:

nil

unit:has_attribute(string attribute key)

Returns whether a unit currently has an attribute. Attribute keys are listed above, in the Unit Attributes section description.

Parameters:

unit:trigger_sound_charge()

attribute key

Returns:

boolean has attribute

Sounds

Compels the unit to make a charge sound effect.

Returns:

nil

unit:trigger_sound_taunt()

Compels the unit to make a taunt sound effect.

Returns:

nil

Miscellaneous

unit:play_anim_for_captain(string animation key, boolean loop animation)

Compels the unit leader to play an animation.

Parameters:

1	`string`	animation key
2	`boolean`	loop animation

Returns:

nil

unit:deploy_reinforcement(boolean enable, [number spawn zone index])

Prevents or allows the unit to deploy as a reinforcement from a specific spawn zone if provided. If set to false, and the unit has not yet entered the battlefield, then the unit will not be able to deploy until the function is called again with an argument of true.
Calling this command has no effect if the unit is not part of a reinforcement army.

Parameters:

Enable reinforcement.

unit:select_in_ui()

optional, default value=nil

Index of spawn zone to use, if coming on as a reinforcement.

Returns:

nil

Selects the unit in the user interface.

Returns:

nil

unit:highlight([boolean highlight])

Activates or deactivates a highlight on the unit.

Parameters:

optional, default value=true

highlight

Returns:

nil

unit:mark_as_ally(boolean mark as ally)

Makes a player unit look like it is allied, rather than part of the controlled army. This is useful for specific scripted situations where it's intended to grant allied units to player control.
Call this function with true as a single argument to mark the controlled unit as an ally, and then again supplying false to mark the unit as part of the player's army again.

Parameters: