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

Creates a new script unit from a supplied battle_unit or battle_army object. An reference name may be passed which is used for debug output (this is mandatory if a battle_army is supplied, as it is used to look up the unit).

Parameters:

1	battle_unit	Unit object to be contained. A battle_army may also be supplied, in which case script_unit:new_from_army is invoked.
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 61

script_unit:new_from_army(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 84

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

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 263

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 271

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 278

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 310

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 343

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 375

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 412

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 447

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 485

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 506

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 513

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 549

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 589

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 598

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 606

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 614

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 622

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 633

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 642

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 678

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 692

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 700

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 708

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 716

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 724

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 756

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 766

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 814

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 821

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 827

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 834

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 841

script_unit:deploy_reinforcement([boolean should deploy])

Instructs the scriptunit to deploy or not. If supplied with false as a single argument, the instruction prevents the unit from deploying until the function is called again with true.

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 858

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 870

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 883

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 891

script_unit:set_enabled([boolean enabled])

Sets the unit to be enabled and visible if true is supplied as an argument, or disabled and invisible if false is supplied.

Parameters:

1

boolean

optional, default value=true enabled

Returns:

1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 913

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 927

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 939

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 947

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 955

script_unit:is_visible_to_enemy()

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.

Returns:

1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 963

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 982

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 990

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 1010

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 1023

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 1040

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 1057

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 1070

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 1077

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 1107

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 1118

script_unit:unary_hitpoints()

Returns this unit's hitpoints as a unary of its initial value. This is an unembellished wrapper for an underlying code function.

Returns:

1. number unary hitpoints

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

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	boolean	optional, default value=false Activate silent mode. max_casualties writes output to the console by default, supply true here to suppress this.

Returns:

1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1156

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 1251

script_unit:set_invincible_for_time_proportion(number time proportion)

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.

Returns:

1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1261

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 1335

script_unit:rout_on_casualties(unary proportion)

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

unary

Proportion of unit at which it routs. Value should be expressed as a unary e.g. 0.5 = 50% casualties.

Returns:

1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1378

script_unit:invincible_if_standing([boolean should release], [boolean invincibility])

Makes the subject unit invincible/fearless if it's not already routing, or reverses the effect

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.
2	boolean	optional, default value=true Set to true to turn the unit invincible, false to reverse the invincibility

Returns:

1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1415

script_unit:prevent_rallying_if_routing([boolean check perpetually])

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.

Returns:

1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1440

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 1470

script_unit:morale_behavior_fearless([boolean should release])

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

Parameters:

1

boolean

optional, default value=false Set to true to release script control of this unit after morale_behavior_fearless 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 1477

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 1491

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 1498

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 1505

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 1519

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 1547

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

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.
4	boolean	optional, default value=true Ignore action when game is paused.

Returns:

1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1558

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 1587

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 1640

script_unit:get_enemy_alliance_num()

Gets the enemy alliance number.

Returns:

1. integer enemy alliance number

defined in ../../Warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 1659

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 1679

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 1744

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 1784

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 1925

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 1966

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 1989

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 2033

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 2053

script_units:contains_sunit(script_unit to test)

Returns true if this script_units collection contains the supplied script_unit, false otherwise.

Parameters:

1

script_unit

to test

Returns:

1. boolean collection contains sunit

defined in ../../Warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2102

script_units:contains_type(string unit type)

Returns true if this script_units collection contains a script_unit of the supplied type, false otherwise.

Parameters:

1

string

unit type

Returns:

1. boolean collection contains type

defined in ../../Warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2117

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 2132

script_units:item(integer index value)

Returns the script_unit in this collection at the supplied index.

Parameters:

1

integer

index value

Returns:

1. script_unit

defined in ../../Warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2140

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 2156

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 2190

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 2198

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 2239

script_units:out()

Debug prints the list of script_unit objects this collection contains to the console.

Returns:

1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2251

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 2265

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 2289

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 2326

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 2340

script_units:centre_point()

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

Returns:

1. vector centre position

defined in ../../Warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2378

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 2386

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 2406

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 2418

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 2434

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 2453

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 2472

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 2491

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

defined in ../../Warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2510

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 2596

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 2604

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 2658

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 2673

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 2682

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 2735

script_units:is_any_firing_missiles()

Is any of the script_unit objects in the collection firing missiles.

Returns:

1. boolean is_any_firing_missiles

defined in ../../Warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2750

script_units:are_all_firing_missiles()

Are all of the script_unit objects in the collection firing missiles.

Returns:

1. boolean is_any_firing_missiles

defined in ../../Warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2765

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 2780

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 2796

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_units_obj>:script_unit:cache_location() first.

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 2826

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 2844

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_units_obj>:script_unit:cache_location() first.

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 2862

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 2880

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 2896

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 2912

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 2928

script_units:unary_hitpoints()

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

Returns:

1. number average hitpoints

defined in ../../Warhammer/working_data/script/_lib/lib_battle_script_unit.lua, line 2944

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 2977

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 3025

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 3054

script_units:deploy_at_random_intervals(
  number min units,
  number max units,
  number min period,
  number max period,
  [boolean debug out],
  [boolean spawn immediately]
)

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.

Returns:

1. nil

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

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 3213

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 3232

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 3279

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 3298

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 3450

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 3472