script_unit:new(army army, object reference)

Creates a new script unit.

Parameters:

1	army	Army the target unit is a member of.
2	object	Reference for the unit. Can be an integer number representing the unit's index within the army ('1' is generally the general, for example) or a string name. If a string name, this must match the script name given to the unit in either the battle xml or in the battle_set_piece_armies_units_junctions table.

Returns:

1. script_unit

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 48

Variables in this section:

These variables are also listed in the global variables list for this class or module.

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 190

script_unit:teleport_to_start_location()

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

Returns:

1. nil

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 198

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 205

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 237

Variables in this section:

These variables are also listed in the global variables list for this class or module.

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 282

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 319

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 354

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 392

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 413

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 420

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 456

script_unit:cache_location()

Caches the units current position, bearing and width.

Returns:

1. nil

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 496

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 505

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 513

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 521

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 529

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 540

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 549

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 585

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 599

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 607

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 615

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 623

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 631

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 663

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 673

script_unit:halt()

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

Returns:

1. nil

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 721

script_unit:celebrate()

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

Returns:

1. nil

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 728

script_unit:taunt()

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

Returns:

1. nil

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 734

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 741

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 748

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 765

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 777

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 790

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 798

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 820

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 834

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 846

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 854

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 862

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 870

script_unit:take_control()

Takes script control of this unit.

Returns:

1. nil

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 889

script_unit:release_control()

Releases script control of the subject unit.

Returns:

1. nil

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 897

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 917

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 930

script_unit:grant_infinite_ammo()

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

Returns:

1. nil

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 947

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 964

script_unit:cache_ammo()

Caches this unit's current ammunition level.

Returns:

1. nil

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 977

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 984

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1014

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1025

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1055

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1063

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1158

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1168

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1242

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1285

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1322

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1347

script_unit:stop_prevent_rallying_if_routing()

Stops any running monitor started by script_unit:prevent_rallying_if_routing.

Returns:

1. nil

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 1377

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1384

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1391

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1398

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1405

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1419

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1447

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1458

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1487

script_unit:stop_kill_proportion_over_time()

Stops a running process started by script_unit:kill_proportion_over_time.

Returns:

1. nil

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 1540

script_unit:get_enemy_alliance_num()

Gets the enemy alliance number.

Returns:

1. integer enemy alliance number

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 1559

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1579

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1644

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1684

All variables provided by script_unit

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1830

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1871

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1894

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1938

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 1958

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2007

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2022

script_units:count()

Returns the number of script_unit objects in this script_units collection.

Returns:

1. number number of units

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 2037

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2045

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2061

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

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.

Returns:

1. script_units

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 2069

script_units:out()

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

Returns:

1. nil

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 2106

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2120

script_units:get_unitcontroller([army, If an army is supplied here])

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

Parameters:

1

army,

optional, default value=nil 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. unitcontroller

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 2144

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2192

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2200

script_units:get_northernmost()

Returns the northern-most script_unit.

Returns:

1. script_unit

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 2220

script_units:get_southernmost()

Returns the southern-most script_unit.

Returns:

1. script_unit

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 2239

script_units:get_westernmost()

Returns the western-most script_unit.

Returns:

1. script_unit

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 2258

script_units:get_easternmost()

Returns the eastern-most script_unit.

Returns:

1. script_unit

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 2277

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2296

script_units:get_centremost()

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

Returns:

1. script_unit

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 2382

script_units:get_outlying()

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

Returns:

1. script_unit

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 2390

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2444

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2459

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2468

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2521

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2536

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2551

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2566

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2582

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2612

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2630

script_units:are_any_running()

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

Returns:

1. boolean any running

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 2648

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2664

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2680

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2696

script_units:unary_hitpoints()

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

Returns:

1. number average hitpoints

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 2712

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2745

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2793

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2822

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2846

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 2981

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 3000

script_units:stop_kill_aura()

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

Returns:

1. nil

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 3047

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 3066

script_units:stop_attack_enemy_scriptunits()

Stops an attack process started with script_units:attack_enemy_scriptunits.

Returns:

1. nil

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 3218

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 ../working_data/script/_lib/lib_battle_script_unit.lua, line 3240