script_unit:new_by_reference(battle_army army, value reference)

Creates a new script unit. The unit object to encapsulate is looked up by the supplied army and reference name.

Parameters:

1	battle_army	Army the target unit is a member of.
2	value	Reference for the unit. This can either be a string name, or an integer number representing the unit's index within the army ('1' is generally the general, for example). If a string name is supplied this must match the script name given to the unit in the battle setup - this is generally set in either the battle xml or in the relevant entry in the battle_set_piece_armies_units_junctions database table.

Returns:

1. script_unit

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 63

script_unit:new(battle_unit unit, [string name])

Creates a new script unit from a supplied battle_unit. An optional reference name may be passed which is used for debug output.

Parameters:

1	battle_unit	Unit object to be contained.
2	string	optional, default value=nil Reference name for the unit.

Returns:

1. script_unit

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 130

Variables in this section:

These variables may be accessed via <interface>.<variable_name>:

Functions in this section:

script_unit:army()

Returns the army object to which the unit contained by this scriptunit currently belongs.

Returns:

1. battle_army army

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 231

script_unit:alliance()

Returns the alliance object to which the unit contained by this scriptunit belongs.

Returns:

1. battle_alliance alliance

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 239

Variables in this section:

These variables may be accessed via <interface>.<variable_name>:

Functions in this section:

script_unit:goto_start_location([boolean should run])

Instructs the scriptunit to move to its start location.

Parameters:

1

boolean

optional, default value=false should run

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 265

script_unit:teleport_to_start_location()

Teleports the scriptunit to the position/bearing/width it started the battle at.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 273

script_unit:teleport_to_start_location_offset(
  number x offset,
  number z offset,
  [number bearing override],
  [boolean release control]
)

Teleports the scriptunit to an offset from the position/bearing/width it started the battle at. This offset will be calculated from the scriptunit's start bearing, so an offset of [0, -10] will teleport it 10m behind its starting position. The function also optionally takes an override bearing to alter the position calculation, as well as a flag to release the unit to script control afterwards.

Parameters:

1	number	x offset in m
2	number	z offset in m
3	number	optional, default value=nil Bearing override in degrees. Supply a value here to override the bearing used to make the offset calculation.
4	boolean	optional, default value=false Release control after teleporting. Set this to true if you want the player (or AI, if it's not player-controlled) to be able to control this unit immediately after teleporting.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 280

script_unit:goto_start_location_offset(
  number x offset,
  number z offset,
  [boolean should run],
  [number bearing override],
  [boolean release control]
)

Instructs the scriptunit to move to an offset from the position/bearing/width it started the battle at. This offset will be calculated from the scriptunit's start bearing, so an offset of [0, -10] will send it 10m behind its starting position. The function also optionally takes a flag to instruct the unit to run, an override bearing to alter the position calculation, as well as a flag to release the unit to script control afterwards.

Parameters:

1	number	x offset in m
2	number	z offset in m
3	boolean	optional, default value=false Set to true to instruct the unit to move quickly to its destination.
4	number	optional, default value=nil Bearing override in degrees. Supply a value here to override the bearing used to make the offset calculation.
5	boolean	optional, default value=false Release control after the movement order is issued. Set this to true if you want the player (or AI, if it's not player-controlled) to be able to control this unit immediately after moving.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 312

script_unit:respawn_in_start_location([boolean only if dead])

Respawns the unit at the location it started the battle. This resets its health, fatigue, casualties and other stats.

Parameters:

1

boolean

optional, default value=false Respawn the unit only if it is dead, or if it has routed off the battlefield.

Returns:

1. boolean unit was respawned

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 345

script_unit:position_offset(number x offset, number y offset, number z offset, [number bearing override])

Returns the position of the scriptunit, offset from its current position. This offset will be calculated from the scriptunit's current bearing, so an offset of [0, 0, -10] will report a position 10m behind its current position. An override bearing to alter the position calculation may optionally be supplied.

Parameters:

1	number	x offset in m
2	number	y offset (height) in m
3	number	z offset in m
4	number	optional, default value=nil Bearing override in degrees. Supply a value here to override the bearing used to make the offset calculation.

Returns:

1. battle_vector offset position

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 377

script_unit:goto_location_offset(
  number x offset,
  number z offset,
  [boolean should run],
  [number bearing override],
  [boolean release control]
)

Instructs the scriptunit to move to an offset from its current position. This offset will be calculated from the scriptunit's current bearing, so an offset of [0, -10] will send it 10m behind its current position. The function also optionally takes a flag to instruct the unit to run, an override bearing to alter the position calculation, as well as a flag to release the unit to script control afterwards.

Parameters:

1	number	x offset in m
2	number	z offset in m
3	boolean	optional, default value=false Set to true to instruct the unit to move quickly to its destination.
4	number	optional, default value=nil Bearing override in degrees. Supply a value here to override the bearing used to make the offset calculation.
5	boolean	optional, default value=false Release control after the movement order is issued. Set this to true if you want the player (or AI, if it's not player-controlled) to be able to control this unit immediately after moving.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 414

script_unit:teleport_to_location_offset(
  number x offset,
  number z offset,
  [number bearing override],
  [boolean release control]
)

Instructs the scriptunit to teleport to an offset from its current position. This offset will be calculated from the scriptunit's current bearing, so an offset of [0, -10] will teleport it 10m behind its current position. The function also optionally takes an override bearing to alter the position calculation, as well as a flag to release the unit to script control afterwards.

Parameters:

1	number	x offset in m
2	number	z offset in m
3	number	optional, default value=nil Bearing override in degrees. Supply a value here to override the bearing used to make the offset calculation.
4	boolean	optional, default value=false Release control after the teleport order is issued. Set this to true if you want the player (or AI, if it's not player-controlled) to be able to control this unit immediately after teleporting.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 449

script_unit:goto_location_offset_when_deployed(
  number x offset,
  number z offset,
  [boolean should run],
  [number bearing override],
  [boolean release control]
)

Instructs the scriptunit to goto an offset from its location when it deploys. This offset will be calculated from the scriptunit's bearing at the time it finds itself on the battlefield, so an offset of [0, -5] will move it 50m forward. The function also optionally takes a flag instructing it to run, an override bearing to alter the position calculation, as well as a flag to release the unit to script control afterwards.

Parameters:

1	number	x offset in m
2	number	z offset in m
3	boolean	optional, default value=false Set to true to instruct the unit to move quickly to its destination.
4	number	optional, default value=nil Bearing override in degrees. Supply a value here to override the bearing used to make the offset calculation.
5	boolean	optional, default value=false Release control after the movement order is issued. Set this to true if you want the player (or AI, if it's not player-controlled) to be able to control this unit immediately after moving.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 487

script_unit:stop_goto_location_offset_when_deployed()

Stops a running script_unit:goto_location_offset_when_deployed listener on the current unit. Call this after calling script_unit:goto_location_offset_when_deployed to stop the listener for any reason.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 508

script_unit:turn_to_face(vector position)

Instructs the scriptunit to turn to face a position vector.

Parameters:

1

vector

position

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 515

script_unit:teleport_to_location(vector position, number bearing, number width)

Instructs the scriptunit to teleport to a location.

Parameters:

1	vector	Position to teleport to.
2	number	Bearing to face at the target position in degrees.
3	number	Width in m of formation at target position.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 551

script_unit:cache_location()

Caches the units current position, bearing and width.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 591

script_unit:get_cached_position()

Returns the vector position of the unit last time it was cached with script_unit:cache_location.

Returns:

1. vector position (or nil, if never cached).

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 600

script_unit:get_cached_bearing()

Returns the bearing of the unit in degrees last time it was cached with script_unit:cache_location.

Returns:

1. number bearing (or nil, if never cached).

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 608

script_unit:get_cached_width()

Returns the width of the unit in m last time it was cached with script_unit:cache_location.

Returns:

1. number width (or nil, if never cached).

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 616

script_unit:goto_cached_location([boolean should run])

Instructs the scriptunit to move to the location the unit occupied the last time it was cached with script_unit:cache_location.

Parameters:

1

boolean

optional, default value=false Instructs the unit to move fast.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 624

script_unit:teleport_to_cached_location()

Teleports the scriptunit to the location the unit occupied the last time it was cached with script_unit:cache_location.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 635

script_unit:has_moved([vector position override], [number threshold distance])

Returns true if the scriptunit has moved from the last cached position, or an optional supplied position. The movement threshold can also be overriden (by default it's 1m).

Parameters:

1	vector	optional, default value=nil position override
2	number	optional, default value=1 threshold distance

Returns:

1. boolean has moved

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 644

script_unit:cache_destination()

Caches the current destination position of the scriptunit. Note that the if the subject unit is attacking rather than moving to a position it will have no valid destination. The function also caches whether the unit is running.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 681

script_unit:cache_destination_and_halt()

Caches the current destination position of the scriptunit with script_unit:cache_destination, and then orders the unit to halt.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 695

script_unit:get_cached_destination_position()

Returns the vector destination last cached by script_unit:cache_destination.

Returns:

1. vector destination position (or nil if destination never cached).

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 703

script_unit:get_cached_destination_bearing()

Returns the ordered bearing in degrees that was last cached by script_unit:cache_destination.

Returns:

1. number bearing in degrees (or nil if destination never cached).

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 711

script_unit:get_cached_destination_width()

Returns the ordered width in m that was last cached by script_unit:cache_destination.

Returns:

1. number width in m (or nil if destination never cached).

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 719

script_unit:goto_cached_destination([boolean should release])

Instructs the unit to move to the location last cached by script_unit:cache_destination. If the unit was moving quickly when its destination was last cached, than it will resume moving quickly when this function is called.

Parameters:

1

boolean

optional, default value=false Set to true to release script control of the unit after calling this function. Set this if it's desirable for the player (or AI, if it's not a player-controlled unit) to be able to control this unit after the order has been issued.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 727

script_unit:is_under_attack()

Returns true if the unit is under missile attack, in melee, or has casualties since the last time is_under_attack was called. Designed to be called repeatedly.

Returns:

1. boolean is under attack

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 759

script_unit:is_in_melee()

Returns true if the unit is in melee. This is an unembellished wrapper for an underlying code function.

Returns:

1. boolean is in melee

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 769

script_unit:halt()

Instructs the scriptunit to halt. This is an unembellished wrapper for an underlying code function.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 817

script_unit:celebrate()

Instructs the scriptunit to celebrate. This is an unembellished wrapper for an underlying code function.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 824

script_unit:taunt()

Instructs the scriptunit to taunt. This is an unembellished wrapper for an underlying code function.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 830

script_unit:play_sound_charge()

Instructs the scriptunit to play a charge sound. This is an unembellished wrapper for an underlying code function.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 837

script_unit:play_sound_taunt()

Instructs the scriptunit to play a taunt sound. This is an unembellished wrapper for an underlying code function.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 844

script_unit:deploy_reinforcement([boolean should deploy])

Instructs the scriptunit to deploy as a reinforcement if it can.

Parameters:

1

boolean

optional, default value=true should deploy

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 861

script_unit:change_behaviour_active(string behaviour name, boolean activate)

Sets a supplied behaviour active on the unit or not. This is an unembellished wrapper for an underlying code function. This is the main mechanism for turning on/turning off certain unit behaviours such as fire at will, skirmish etc. Current list of behaviours includes, but may not be limited to the following:
"defend", "dismount", "fire_at_will", "skirmish", "change_formation_spacing", "drop_siege_equipment", "release_animals", "disembark_from_ship", "board_ship"

Parameters:

1	string	behaviour name
2	boolean	activate

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 873

script_unit:withdraw(boolean should run)

Instructs the specified unit to withdraw. This is an unembellished wrapper for an underlying code function.

Parameters:

1

boolean

should run

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 886

script_unit:set_melee_mode([boolean activate], [boolean release control])

Activates or deactivates melee mode.

Parameters:

1	boolean	optional, default value=true Should activate melee mode.
2	boolean	optional, default value=false Release script control after setting melee mode. Set this to true if the unit is under player control.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 894

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

Enables or disables a unit attribute for the unit. Valid attribute keys are listed in the Unit Attributes section of this documentation.

Parameters:

1	string	attribute key
2	boolean	enable/disable

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 907

script_unit:set_enabled(
  [boolean enabled],
  [boolean force unit card update],
  [boolean unit contributes to army strength]
)

Sets the unit to be enabled and visible if true is supplied as an argument, or disabled and invisible if false is supplied. The second argument forces the UI to refresh the unit card's visibility, but this only needs to be set to true in certain specific circumstances.
The third argument, if set to true or false, will also set that unit to contribute to the army strength or not depending upon the value supplied. If no value is supplied here then enabled units will contribute to army strength whereas disabled units will not.

Parameters:

1	boolean	optional, default value=true enabled
2	boolean	optional, default value=false force unit card update
3	boolean	optional, default value=nil unit contributes to army strength

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 937

script_unit:set_always_visible([boolean always visible])

Sets the unit to be always visible, according to the rules of the terrain visibility system.

Parameters:

1

boolean

optional, default value=true always visible

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 965

script_unit:set_always_visible_no_hidden([boolean always visible])

Sets the unit to be always visible, doesn't affect hidden by forest / abilities

Parameters:

1

boolean

optional, default value=true always visible

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 976

script_unit:set_always_visible_no_leave_battle([boolean always visible])

Sets the unit to be always visible, doesn't affect leaving battle

Parameters:

1

boolean

optional, default value=true always visible

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 987

script_unit:set_always_visible_no_hidden_no_leave_battle([boolean always visible])

Sets the unit to be always visible, doesn't affect hidden by forest / abilities doesn't affect leaving battle

Parameters:

1

boolean

optional, default value=true always visible

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 998

script_unit:mark_as_ally(boolean mark as ally)

Makes player unit look like ally (for script where gradually give units in tutorials). This is an unembellished wrapper for an underlying code function.

Parameters:

1

boolean

mark as ally

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1010

script_unit:is_hidden()

Returns true if the unit is hidden in grass/forests etc. This is an unembellished wrapper for an underlying code function. Returned result is not related to the terrain visibility system, which came later than this code function, so a unit may not be hidden (according to this result returned by this function) but may still not be visible to its enemy - check also script_unit:is_visible_to_enemy.

Returns:

1. boolean is hidden

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1018

script_unit:set_invisible_to_all(boolean is hidden)

Makes the unit invisible. This is an unembellished wrapper for an underlying code function.

Parameters:

1

boolean

is hidden

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1026

script_unit:is_visible_to_enemy(boolean is visible)

Returns true if this unit is visible to its enemy, by the rules of the visibility system. Note that the unit may be visible according to the visibility system, but may still be hidden in forests or tall grass - check script_unit:is_hidden.

Parameters:

1

boolean

is visible

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1034

script_unit:take_control()

Takes script control of this unit.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1054

script_unit:release_control()

Releases script control of the subject unit.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1061

script_unit:modify_ammo(number proportion)

Modifies this unit's ammo to a specified unary proportion of its starting value.

Parameters:

1

number

Desired proportion of starting ammo. Supply 1 to set the ammo back to its starting value, 0.5 to half etc. Values of greater than one are semi-supported - the command will work, but any ammo bars on the UI will show as full until the unit's ammo value drops below its starting value.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1081

script_unit:refill_ammo(number proportion)

Modifies this unit's ammo to a specified unary proportion of its starting value, but only if it has less than the specified amount.

Parameters:

1

number

Desired proportion of starting ammo. Supply 1 to set the ammo back to its starting value, 0.5 to half etc. Values of greater than one are semi-supported - the command will work, but any ammo bars on the UI will show as full until the unit's ammo value drops below its starting value.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1094

script_unit:grant_infinite_ammo()

Grants this unit infinite ammo by refilling ammo every 5 seconds.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1111

script_unit:refresh([boolean should release])

Sets this unit to 1/10th its current fatigue level, and tops its ammo back to full.

Parameters:

1

boolean

optional, default value=false Release script control of the unit after refreshing. Set this to true if the unit is under player control.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1128

script_unit:cache_ammo()

Caches this unit's current ammunition level.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1141

script_unit:restore_cached_ammo()

Restores this unit's ammunition level to the value previously cached with script_unit:cache_ammo.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1148

script_unit:cache_health()

Caches the proportion of the scriptunit still alive, so that it can be queried later with script_unit:has_taken_casualties.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1178

script_unit:has_taken_casualties([number tolerance])

Compares the scriptunits current casualties with that when it was previously cached with script_unit:cache_health, and returns true if they're different.

Parameters:

1

number

optional, default value=0 Tolerance value. The casualties values is expressed internally as a unary value (between 0 and 1), so this should be expressed in a similar manner. Therefore a tolerance of 0.1 would allow for 10% casualties (of the original number of soldiers in the unit) more than when previously cached before returning true.

Returns:

1. boolean has taken casualties

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1189

script_unit:unary_hitpoints([shattered considered dead])

Returns this unit's hitpoints as a unary of its initial value. If the shattered-considered-dead flag is set and the unit is shattered (or it's routing and has left the field), then 0 is returned.

Parameters:

1

shattered

optional, default value=false considered dead

Returns:

1. number unary hitpoints

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1219

script_unit:max_casualties(
  number unary proportion,
  [boolean should release],
  [script_units exception sunit(s)],
   boolean silent mode
)

Sets the maximum number of casualties that this unit can take. If the unit's hitpoints drop below the specified unary value, the unit is made invincible so that it can no longer take casualties (note that it may still rout). Exception scriptunits can be set, so that proximity to those script_unit or script_units disables this invincibility (allow certain units to be perceived to charge in and 'save the day').

Parameters:

1	number	Unary proportion. A value of 0.5 would allow the unit to take 50% casualties before becoming invincible (note that in extreme scenarios the unit may still die, if one-shotted by something for example). Call max_casualties with a proportion value of 0 to disables any previous max_casualties monitor on this unit.
2	boolean	optional, default value=false Set to true to release script control of this unit after max_casualties makes a change. Set this primarily if the unit is under player control.
3	script_units	optional, default value=nil Exception script_unit or script_units collection. If this unit comes within 30m of any unit specified here, the max_casualties monitor will temporarily cease and they will become vulnerable to casualties. The monitor will resume and this unit will (potentially) regain invincibility when this unit moves more than 40m away from any unit specified as an exception.
4		Activate silent mode. max_casualties writes output by default, supply true here to suppress this.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1232

script_unit:set_invincible(boolean set invincible)

Makes the subject unit invincible. This wraps an underlying code function, and also cancels any running process started for this unit with script_unit:max_casualties or script_unit:set_invincible_for_time_proportion.

Parameters:

1

boolean

set invincible

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1327

script_unit:set_invincible_for_time_proportion(number time proportion, [boolean should release])

Makes the subject unit invincible a proportion of the time. The intended effect is to slow the rate at which the unit receives casualties. Invincibility is toggled on and off over a five second interval, with the unit being invincible the specified proportion of time. The proportion is set as a unary number, so supplying a value of 0.8 would make the unit invincible for four seconds out of every five.
Set a value of 0 to turn off any previous invincibility set with this function.

Parameters:

1	number	Unary (0-1) time proportion over which this unit should be invincible.
2	boolean	optional, default value=false Instructs the function to release script control of the unit after setting it to be invincible or otherwise. Set this to true if the scriptunit is player-controlled.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1337

script_unit:fearless_until_casualties(unary proportion, [boolean should release])

Prevents this unit from routing until it takes a certain proportion of casualties. If a proportion of 0 is supplied then any previous monitor set up with fearless_until_casualties is cancelled and the unit is allowed to rout.

Parameters:

1	unary	Proportion of unit at which it may rout. Value should be expressed as a unary e.g. 0.5 = 50% casualties.
2	boolean	optional, default value=false Set to true to release script control of this unit after fearless_until_casualties makes a change. Set this primarily if the unit is under player control.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1421

script_unit:rout_on_casualties(number unary proportion, [boolean set invincible])

Forces this unit to rout when it reaches a certain proportion of casualties. If a proportion of 0 is supplied then any previous monitor set up with rout_on_casualties is cancelled.

Parameters:

1	number	Proportion of unit hitpoints remaining at which it routs. Value should be expressed as a unary e.g. 0.6 = unit will rout when its health gets below 60%.
2	boolean	optional, default value=false Makes the unit invincible when it routs, so that it's guaranteed to survive.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1464

script_unit:invincible_if_standing([boolean should release])

Makes the subject unit invincible/fearless if it's not already routing.

Parameters:

1

boolean

optional, default value=false Set to true to release script control of this unit after invincible_if_standing makes a change. Set this primarily if the unit is under player control.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1518

script_unit:prevent_rallying_if_routing(
  [boolean check perpetually],
  [boolean shattered only],
  [boolean permit rampaging]
)

Prevents the subject unit from rallying if it's already routing. Supply true as a single argument to start a monitor that will continually poll whether this unit is routing, and prevent it

Parameters:

1	boolean	optional, default value=false Check perpetually. If false or no value is supplied here, the function will only check the unit's routing state once, at the time the function is called. If the unit is not routing at this time, it may later rout and subsequently rally. If true is supplied instead, the function sets up a monitor that will continually poll the unit's routing status and, when found to be routing, prevents it from rallying at that time.
2	boolean	optional, default value=false Only count shattered units
3	boolean	optional, default value=false Don't automatically count rampaging units, check if they are actually routing too.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1533

script_unit:stop_prevent_rallying_if_routing()

Stops any running monitor started by script_unit:prevent_rallying_if_routing.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1565

script_unit:morale_behavior_fearless()

Sets this unit to be fearless/unroutable. This is an unembellished wrapper for an underlying code function.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1572

script_unit:morale_behavior_rout()

Causes this unit to instantly rout. This is an unembellished wrapper for an underlying code function.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1579

script_unit:morale_behavior_default()

Causes this unit to be subject to normal morale. This is an unembellished wrapper for an underlying code function.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1586

script_unit:morale_behavior_fearless_if_standing([boolean should release])

Makes the subject unit fearless if it's not already routing.

Parameters:

1

boolean

optional, default value=false Set to true to release script control of this unit after morale_behavior_fearless_if_standing makes a change. Set this primarily if the unit is under player control.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1593

script_unit:morale_behavior_default_if_standing([boolean should release])

Makes the subject unit fearless if it's not already routing.

Parameters:

1

boolean

optional, default value=false Set to true to release script control of this unit after morale_behavior_default_if_standing makes a change. Set this primarily if the unit is under player control.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1607

script_unit:hide_unbreakable_in_ui(boolean hide unbreakable state)

Calls unitcontroller:hide_unbreakable_in_ui to prevent or allow the UI to show that this unit is unbreakable. This is useful for scripted content which is altering whether a unit can rout or not but doesn't want this to be reflected on the user interface.

Parameters:

1

boolean

hide unbreakable state

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1621

script_unit:kill([boolean should disappear])

Instantly kills this unit.

Parameters:

1

boolean

optional, default value=false Set to true to make the unit instantly disappear, instead of appearing to drop dead on the spot.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1643

script_unit:kill_proportion(number proportion, [number preserve proportion], [boolean hide bodies])

Instantly kills a unary proportion of this unit.

Parameters:

1	number	Proportion to kill, expressed as a unary value (e.g. 0.5 = 50% of the unit's starting number of soldiers die).
2	number	optional, default value=0 Prevents kill_proportion from reducing the strength of the unit below a specified unary proportion.
3	boolean	optional, default value=false Hides the bodies.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1654

script_unit:kill_proportion_over_time(number proportion, number duration, [boolean stop on rout])

Kills a unary proportion of this unit over a specified time period in ms.

Parameters:

1	number	Proportion to kill, expressed as a unary value (e.g. 0.5 = 50% of the unit's starting number of soldiers die).
2	number	Duration in ms over which to kill soldiers.
3	boolean	optional, default value=false Stops the function from killing any more soldiers if the unit routs during the process.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1682

script_unit:stop_kill_proportion_over_time()

Stops a running process started by script_unit:kill_proportion_over_time.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1735

script_unit:get_enemy_alliance_num()

Gets the enemy alliance number.

Returns:

1. number enemy alliance number

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1754

script_unit:get_enemy_alliance()

Gets the enemy alliance object.

Returns:

1. battle_alliance enemy alliance

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1762

script_unit:highlight_unit_card(boolean should highlight, [number pulse strength], [boolean force highlight])

Pulses a highlight effect on the unit card associated with this scriptunit.

Parameters:

1	boolean	Set to true to turn the highlight effect on, false to turn it off.
2	number	optional, default value=5 Sets the strength of the pulse effect. A higher supplied value leads to a more pronounced pulse effect. The default value is 5.
3	boolean	optional, default value=false Overrides the disabling of help page highlighting with battle_ui_manager:set_help_page_link_highlighting_permitted. Set this to true if the script explicitly wants to highlight the UI cards when help page link highlighting is disabled (useful in tutorials).

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1782

script_unit:add_ping_icon(
  [number icon_type Type of icon to add. This is a numeric index.],
  [number duration]
)

Adds a ping icon above the unit, optionally for a duration.

Parameters:

1	number	optional, default value=8 icon_type Type of icon to add. This is a numeric index.
2	number	optional, default value=nil Duration in ms.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1847

script_unit:remove_ping_icon()

Removes a ping icon from above the unit added with script_unit:add_ping_icon.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1887

script_unit:start_attack_closest_enemy([number interval], [boolean debug])

Instructs this scriptunit to attack the closest enemy unit under full script control. This process will continually re-acquire the closest enemy target every interval and instruct the unit to attack. The process repeats until the unit is shattered, dead, or until script_unit:stop_attack_closest_enemy is called.

Parameters:

1	number	optional, default value=10000 Repeating interval in milliseconds after which the scriptunit re-acquires the closest enemy target.
2	boolean	optional, default value=false Shows debug output about what this unit is attacking.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1937

script_unit:stop_attack_closest_enemy([string reason])

Stops any running attack closest enemy process that was started with script_unit:start_attack_closest_enemy. An optional string reason may be supplied which is printed as debug output.

Parameters:

1

string

optional, default value=nil reason

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1967

Variables in this section:

These variables may be accessed via <interface>.<variable_name>:

script_units:new(string name, ... scriptunits)

Creates a new script units collection.

Parameters:

1	string	Name for this script_units collection. Will be used for debug output.
2	...	One or more script_unit objects to add to the collection. Note that a scriptunit can be a member of multiple script_units collections at the same time.

Returns:

1. script_units

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2096

script_units:set_debug([boolean debug mode])

Sets the scriptunits collection into debug mode, for more output.

Parameters:

1

boolean

optional, default value=true debug mode

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2137

script_units:add_sunits(... additional script units)

Adds one or more supplied script_unit objects to this scriptunits collection.

Parameters:

1

...

additional script units

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2160

script_units:merge(script_units other script units)

Copies all script_unit objects associated with a supplied script_units collection into this script units collection.

Parameters:

1

script_units

other script units

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2204

script_units:remove_sunit(script_unit scriptunit to remove)

Removes a supplied script_unit object from this scriptunits collection.

Parameters:

1

script_unit

scriptunit to remove

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2216

script_units:remove_sunits(... script_unit list)

Removes one or more supplied script_unit objects from this scriptunits collection.

Parameters:

1

...

scriptunits to remove

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2236

script_units:get_sunit_by_name(value reference)

Returns a script_unit from this script_units collection that matches the supplied reference number or string. nil is returned if no matching script_unit is found.

Parameters:

1

value

Reference number or string.

Returns:

1. script_unit matching name, or nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2285

script_units:get_sunit_for_unit(battle_unit unit)

Returns a script_unit from this script_units collection that contains the supplied battle_unit. nil is returned if no matching script_unit is found.

Parameters:

1

battle_unit

unit

Returns:

1. script_unit matching unit, or nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2299

script_units:get_sunit_by_type(string unit type)

Returns the first script_unit in this script_units collection that contains a battle_unit of the supplied type. nil is returned if no matching script_unit is found.

Parameters:

1

string

Unit type, from the main_units table.

Returns:

1. script_unit matching unit, or nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2313

script_units:count()

Returns the number of script_unit objects in this script_units collection.

Returns:

1. number number of units

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2327

script_units:item(number index value)

Returns the script_unit in this collection at the supplied index.

Parameters:

1

number

index value

Returns:

1. script_unit

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2335

script_units:contains(object object)

Returns whether the script units collection contains the supplied object. Supported object types are script_unit, battle_unit and battle_unitcontroller.

Parameters:

1

object

Object to test - supported types are script_unit, battle_unit and battle_unitcontroller.

Returns:

1. script_unit

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2351

script_units:get_sunit_table()

Returns the internal table containing all the script_unit objects in this script_units collection. Be aware that modifications to this table will also modify this script_units object.

Returns:

1. table of script_unit objects

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2385

script_units:get_unit_table()

Returns a table containing all battle_unit objects contained within this script_units collection. The table that's returned is built each time this function is called, so be wary of calling this function too often.

Returns:

1. table of battle_unit objects

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2393

script_units:filter(string name, function test, [boolean assert if empty], [number max size])

Returns another scriptunits collection containing all script_unit objects from the subject collection that pass the supplied test. The test should be supplied as a function that takes a scriptunit parameter and returns a boolean value. Should a call to the function with a specific scriptunit return true, that scriptunit will be added to the returned collection.

Parameters:

1	string	Name for the returned scriptunits collection
2	function	Function that takes a scriptunit parameter and returns a boolean value.
3	boolean	optional, default value=false If set to true, filter triggers a script assert if the returned collection is empty.
4	number	optional, default value=nil Maximum number of units to add to the returned scriptunit collection.

Returns:

1. script_units filtered scriptunits collection

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2407

script_units:sort(function filter function)

Sorts the internal list of script_unit objects based on the supplied filter function. The filter function should take two script_unit arguments and return true if the first should be sorted before the second, and false otherwise. table:sort is used to perform the operation.

Parameters:

1

function

filter function

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2448

script_units:out()

Prints the list of script_unit objects this collection contains to the debug console spool.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2460

script_units:duplicate(string name)

Returns a duplicate script_units collection with the supplied name.

Parameters:

1

string

name

Returns:

1. script_units duplicate collection

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2475

script_units:get_unitcontroller([battle_army army])

Returns a unitcontroller with control over all the units this script_units collection contains.

Parameters:

1

battle_army

optional, default value=nil If an army is supplied here, the function will only add units that belong to that army and ignore any that don't. If no army is supplied, the function assumes that all units in the scriptunits collection are in the same army, and will assert if any aren't.

Returns:

1. battle_unitcontroller unitcontroller

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2499

script_units:num_generals()

Returns the number of commanding general units the scriptunits collection contains.

Returns:

1. number number of generals

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2536

script_units:get_general_sunit([number general index])

Returns a commanding general scriptunit from the scriptunits collection. By default the first general scriptunit is returned. An index value may be given to specify a particular general to return.

Parameters:

1

number

optional, default value=1 general index

Returns:

1. script_unit number of generals

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2550

script_units:centre_point()

Returns a vector corresponding to the mean centre position of all the script_unit objects in the collection.

Returns:

1. battle_vector centre position

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2588

script_units:radius()

Returns the distance from the furthest unit from the centre, to the centre, which is an indication of how spread out the units in this collection are.

Returns:

1. number radius

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2596

script_units:width()

Returns the current cumulative width of all units in the collection in metres.

Returns:

1. number combined width

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2616

script_units:average_bearing()

Returns the average ordered bearing of all units in the collection, in degrees.

Returns:

1. number average bearing

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2628

script_units:get_northernmost()

Returns the northern-most script_unit.

Returns:

1. script_unit

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2644

script_units:get_southernmost()

Returns the southern-most script_unit.

Returns:

1. script_unit

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2663

script_units:get_westernmost()

Returns the western-most script_unit.

Returns:

1. script_unit

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2682

script_units:get_easternmost()

Returns the eastern-most script_unit.

Returns:

1. script_unit

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2701

script_units:get_closest(object position collection, [2d only])

Returns the closest script_unit in this collection to the supplied collection of units/positions, as well as the distance in m.

Parameters:

1	object	Position object or collection. Supported object types are vector, unit, script_unit, units, script_units, army, armies, alliance or table.
2	2d	optional, default value=false consider 2D distance only (disregarding altitude)

Returns:

1. script_unit closest scriptunit
2. distance distance of closest scriptunit in m
3. object closest foreign object from the supplied object - either a battle_vector, a battle_unit or a script_unit, depending upon the container type.

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2720

script_units:get_furthest(object position collection, [2d only])

Returns the furthest script_unit in this collection from the supplied collection of units/positions, as well as the distance in m.

Parameters:

1	object	Position object or collection. Supported object types are battle_vector, battle_unit, script_unit, battle_units, script_units, battle_army, battle_armies, battle_alliance or table.
2	2d	optional, default value=false consider 2D distance only (disregarding altitude)

Returns:

1. script_unit furthest scriptunit
2. distance distance of furthest scriptunit in m

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2816

script_units:get_centremost()

Returns the script_unit in the collection that is closest to the calculated centre.

Returns:

1. script_unit

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2902

script_units:get_outlying()

Returns the furthest script_unit in this collection from the mean centre.

Returns:

1. script_unit

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2910

script_units:are_any_routing_or_dead([boolean shattered only], [boolean permit rampaging])

Returns true if any unit in this scriptunits collection is routing or dead, or false otherwise.

Parameters:

1	boolean	optional, default value=false Only count shattered units.
2	boolean	optional, default value=false Don't automatically count rampaging units, check if they are actually routing too.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2963

script_units:are_all_routing_or_dead([boolean shattered only], [boolean permit rampaging])

Returns true if all units in this scriptunits collection are routing or dead, or false otherwise.

Parameters:

1	boolean	optional, default value=false Only count shattered units.
2	boolean	optional, default value=false Don't automatically count rampaging units, check if they are actually routing too.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2978

script_units:rout_over_time(number period in ms)

Prevents routing units within the collection from rallying, and routs all non-routing units over the specified period in ms so that all units are eventually routing.

Parameters:

1

number

Time in ms over which the units are routed. Must be positive.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2987

script_units:teleport_withdraw_over_time(number period in ms)

Teleports units over the specified period in ms so all units eventually withdraw

Parameters:

1

number

Time in ms over wich the units are teleported away. Must be positive.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3029

script_units:have_any_deployed()

Have any of the script_unit objects in the collection deployed onto the battlefield.

Returns:

1. boolean any deployed

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3078

script_units:have_all_deployed()

Have all of the script_unit objects in the collection deployed onto the battlefield.

Returns:

1. boolean all deployed

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3094

script_units:num_deployed()

Returns the number of script_unit objects in the collection that are currently deployed onto the battlefield.

Returns:

1. number number deployed

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3110

script_units:are_any_active_on_battlefield()

Returns true if any script_unit in this collection is deployed on the battlefield and not routing or dead.

Returns:

1. boolean any active

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3126

script_units:have_any_moved([vector position], [distance threshold distance])

Returns true if script_unit:has_moved returns true for any unit in this collection. Call script_unit:cache_location() first to set a position from which each unit's distance is tested.

Parameters:

1	vector	optional, default value=nil Position to test against. May be of limited usefulness when testing multiple units like this.
2	distance	optional, default value=0 Threshold distance in m.

Returns:

1. boolean have any moved

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3156

script_units:num_moved([vector position], [distance threshold distance])

Returns the number of units in this collection that have moved when tested with script_unit:has_moved. Call script_unit:cache_location() first to set a position from which each unit's distance is tested.

Parameters:

1	vector	optional, default value=nil Position to test against. May be of limited usefulness when testing multiple units like this.
2	distance	optional, default value=0 Threshold distance in m.

Returns:

1. number Number that have moved

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3174

script_units:have_all_moved([vector position], [distance threshold distance])

Returns true if script_unit:has_moved returns true for all units in this collection. Call script_unit:cache_location() first to set a position from which each unit's distance is tested.

Parameters:

1	vector	optional, default value=nil Position to test against. May be of limited usefulness when testing multiple units like this.
2	distance	optional, default value=0 Threshold distance in m.

Returns:

1. boolean have all moved

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3192

script_units:are_any_running()

Returns true if any script_unit in this collection is moving fast.

Returns:

1. boolean any running

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3210

script_units:are_all_running()

Returns true if all script_unit objects in this collection are moving fast.

Returns:

1. boolean any running

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3226

script_units:is_under_attack()

Returns true if any script_unit in this collection is under attack (uses script_unit:is_under_attack)

Returns:

1. boolean any under attack

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3242

script_units:is_in_melee()

Returns true if any script_unit in this collection is in melee combat (uses script_unit:is_in_melee).

Returns:

1. boolean any in melee

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3258

script_units:unary_hitpoints([boolean shattered considered dead])

Returns the average unary hitpoints of all script_unit objects in this collection.

Parameters:

1

boolean

optional, default value=false Shattered units (or units that have routed and left the field) are considered dead, with 0 hitpoints.

Returns:

1. number average hitpoints

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3274

script_units:number_of_enemies_killed()

Returns the total number of enemies killed by all units in this collection.

Returns:

1. number total enemies killed

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3294

script_units:disordered_teleport(
  battle_vector target position,
  number radius in m,
  [boolean release control]
)

Performs a disordered teleport of all units contained within this collection to within a radius around a position, both supplied. A disordered teleport preserves the current orientation and width of each unit, but teleports them within the radius of the position if they're not already inside.
The function is intended to assist in transitions between different sections of gameplay within a heavily scripted battle. We may wish for the player to start the latter section with their troops in unformed order, akin to where they were at the end of the previous section, but to ensure that none of the player's forces are too far away from a known position (i.e. where we'd like them to start the latter section of gameplay).
Script control of the teleported units is automatically released after this function is called.

Parameters:

1	battle_vector	target position
2	number	radius in m
3	boolean	optional, default value=false release control

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3322

script_units:respawn_in_start_location([boolean only if dead], [boolean debug output])

Respawns the units in the collection at the locations they started the battle. This resets their health, fatigue, casualties and other stats.

Parameters:

1	boolean	optional, default value=false Respawn each unit only if it is dead, or if it has routed off the battlefield.
2	boolean	optional, default value=false Produce debug output about which units have been respawned.

Returns:

1. number number respawned

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3371

script_units:change_formation(string group formation name)

Sets all script_unit objects in the collection into a group formation.
A list of formations can be found in raw data. Valid entries at time of writing are:

• flanking


• generic_directfire_defence


• generic_directfire_attack


• generic


• generic_ranged_protected


• generic_melee_heavy


• generic_melee_super_heavy


• assault_gates_formation


• assault_reserves_formation


• Multiple Selection Drag Out Land


• Multiple Selection Deployable Drag Out Land


• single_line


• Multiple Selection Naval


• Ambush Defence Block


• test_melee_forward_simple


• test_missile_forward_simple


• river_ai_attack


• river_ai_attack_narrow


• river_ai_stop_and_shoot


• river_ai_defend


• stop_and_shoot_artillery


• stop_and_shoot_ranged_direct

Parameters:

1

string

group formation name

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3432

script_units:is_hidden([boolean all units])

Returns true if any script_unit in this collection is hidden in long grass or trees. If true is supplied as a single argument, then all units in the collection must be hidden for the function to return true.

Parameters:

1

boolean

optional, default value=false all units

Returns:

1. boolean is hidden

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3480

script_units:is_visible_to_enemy()

Returns true if any script_unit in this collection is visible to the enemy, by the rules of the terrain visibility system. Note that a unit can be considered visible by this system but still be hidden in forests.

Returns:

1. boolean is visible

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3509

script_units:deploy_at_random_intervals(
  number min units,
  number max units,
  number min period,
  number max period,
  [boolean debug out],
  [boolean spawn immediately],
  [boolean allow respawning],
  [function new wave callback]
)

Deploys the units in this collection onto the battlefield in randomly-sized, randomly-timed batches. Units must have been scripted to not deploy automatically before this is called. Arguments can be used to influence the size and timing of the batches of units.

Parameters:

1	number	Minimum size of random unit batch. Must be postive.
2	number	Maximum size of random unit batch. Must be positive, and not less than the supplied min units value.
3	number	Minimum time period between the arrival of batches in ms. Must be positive.
4	number	Maximum time period between the arrival of batches in ms. Must be positive, and not less than the supplied minimum period.
5	boolean	optional, default value=false Supply true to turn on debug output.
6	boolean	optional, default value=false Spawns the first wave immediately.
7	boolean	optional, default value=false Allows units to be respawned and deployed again.
8	function	optional, default value=nil Callback to call when a new wave in deployed. A table containing a list of script_unit objects representing the units being deployed will be passed to the callback when it is called.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3534

script_units:cancel_deploy_at_random_intervals()

Cancels/stops a running process started with script_units:deploy_at_random_intervals.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3674

script_units:start_kill_aura(script_units target sunits, number range, [number casualties proportion])

Activates a kill aura around these units that cause a specified enemy/other script_units to take casualties when they come within a specified range. Only one kill aura process may be active on a scriptunit at a time.

Parameters:

1	script_units	Target script_units collection.
2	number	Range in m at which the enemy script_units begin to take casualties.
3	number	optional, default value=0.02 Proportion of casualties taken per second. This should be specified as a unary proportion of the unit's initial strength, so the default value of 0.02 represents 2% of the initial strength per second.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3693

script_units:stop_kill_aura()

Stops the kill aura started on this collection with script_units:start_kill_aura.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3740

script_units:attack_enemy_scriptunits(script_units enemy script_units, [boolean should run])

Instructs this scriptunits collection to attack another, acting entirely under script control. This is best used for a close-quarters scripted engagement where no AI randomness or maneouvring is desired.

Parameters:

1	script_units	enemy script_units
2	boolean	optional, default value=false should run

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3759

script_units:stop_attack_enemy_scriptunits()

Stops an attack process started with script_units:attack_enemy_scriptunits.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3911

script_units:highlight_unit_cards(
  boolean should highlight,
  [number pulse strength],
  [boolean force highlight]
)

Pulses a highlight effect on all the unit cards associated with this scriptunits collection, using script_unit:highlight_unit_card.

Parameters:

1	boolean	Set to true to turn the highlight effect on, false to turn it off.
2	number	optional, default value=5 Sets the strength of the pulse effect. A higher supplied value leads to a more pronounced pulse effect. The default value is 5.
3	boolean	optional, default value=false Overrides the disabling of help page highlighting with battle_ui_manager:set_help_page_link_highlighting_permitted. Set this to true if the script explicitly wants to highlight the UI cards when help page link highlighting is disabled (useful in tutorials).

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3933

script_units:serialise_state()

Returns a string which represents the serialised state of this script_units collection. This does not embody the full model state of the units but only selected information. It is mainly intended for use by script_units:save_state_to_svr which will save the returned string into the scripted value registry. This string can then be loaded by campaign_manager:load_army_state_from_svr, allowing campaign scripts to spoof the results from a scripted battle that occurs mid-campaign flow.

Returns:

1. string serialised state

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3961

script_units:save_state_to_svr(string name)

Saves a string which represents the serialised state of this script_units collection to the scripted value registry. script_units:serialise_state is used to generate the state string, and core:svr_save_string is used to save the string. This is for use by scripts that wish to pass the state of an army, usually at the end of a battle, from battle script to campaign script, usually so that the latter can spoof the battle results in script. The function campaign_manager:load_army_state_from_svr can be used on the campaign-side to load the values saved by this string.

Parameters:

1

string

Name for this svr entry, to be passed to core:svr_save_string.

Returns:

1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3983

script_units:load_state_from_svr(string name, [boolean allow partial])

Checks for a scriptedvalueregistry string with the supplied name, and attempts to apply the health values it contains to the units in this script_units collection. These svr strings would be set by either campaign_manager:save_army_state_to_svr in campaign or script_units:save_state_to_svr in battle.
This is primarily intended to spoof casualties on a battle army that is coming from campaign, but where the army in battle is not logically related to that campaign army (for example, when loading from a campaign into a scripted xml battle).
The function returns whether the application was successful. A successful application is one that modifies all units in the script_units collection (a "modification" from 100% health to 100% health would count), unless the allow_partial flag is set, in which case even a partial application would be considered successful. If the application is not successful then no changes are applied. Output is generated in all cases.

Parameters:

1	string	Name of string saved in the scriptedvalueregistry.
2	boolean	optional, default value=false Allow a partial application of the state string. If this is set to true

Returns:

1. boolean state was applied successfully

defined in ../../warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 3998