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 49

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 194

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 202

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 209

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 241

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 286

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 323

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 360

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 398

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 419

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 426

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 462

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 486

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 495

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 503

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 511

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 519

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 530

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 539

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 575

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 589

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 597

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 605

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 613

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 621

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 651

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 662

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 692

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 702

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 749

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 756

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 762

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 769

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 776

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 793

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 805

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 818

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 826

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

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

Parameters:

1	string	attribute key
2	boolean	enable/disable

Returns:

1. nil

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

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 865

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 879

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 891

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 899

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 907

script_unit:is_visible_to_enemy(boolean is visible)

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

Parameters:

1

boolean

is visible

Returns:

1. nil

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

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 935

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 942

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 962

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 975

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 992

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 1009

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 1022

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 1029

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 1059

script_unit:max_casualties(
  number unary proportion,
  [boolean should release],
  [object 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	object	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 by default, supply true here to suppress this.

Returns:

1. nil

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

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 1162

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 1206

script_unit:invincible_if_standing([boolean should release])

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

Parameters:

1

boolean

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

Returns:

1. nil

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

script_unit:set_invincible(boolean set invincible)

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

Parameters:

1

boolean

set invincible

Returns:

1. nil

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

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 1267

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 1297

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 1304

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 1311

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 1318

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 1325

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 1339

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 1367

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

Instantly kills a unary proportion of this unit.

Parameters:

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

Returns:

1. nil

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

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 1405

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 1458

script_unit:get_enemy_alliance_num()

Gets the enemy alliance number.

Returns:

1. number enemy alliance number

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

script_unit:get_enemy_alliance()

Gets the enemy alliance object.

Returns:

1. battle_alliance enemy alliance

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

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 1505

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 1572

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 1612

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 1759

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 1803

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 1826

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 1870

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 1890

script_units:get_sunit_by_name(value reference)

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

Parameters:

1

value

Reference number or string.

Returns:

1. script_unit matching name, or nil

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

script_units:get_sunit_for_unit(battle_unit unit)

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

Parameters:

1

battle_unit

unit

Returns:

1. script_unit matching unit, or nil

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

script_units:get_sunit_by_type(string unit type)

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

Parameters:

1

string

Unit type, from the main_units table.

Returns:

1. script_unit matching unit, or nil

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

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 1981

script_units:contains_type(string unit type)

Returns whether this script_units collection contains a script_unit of the supplied type, from the main_units table.

Parameters:

1

string

unit type

Returns:

1. boolean collection contains type

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

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 2011

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 2019

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 2035

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 2043

script_units:out()

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

Returns:

1. nil

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

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 2095

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 2119

script_units:num_generals()

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

Returns:

1. number number of generals

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

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

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 2210

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 2218

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 2238

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 2257

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 2276

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 2295

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

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

Parameters:

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

Returns:

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

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

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 2410

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 2465

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 2520

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 2536

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 2552

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 2582

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 2600

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 2618

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 2634

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 2650

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 2666

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 2682

script_units:number_of_enemies_killed()

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

Returns:

1. number total enemies killed

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

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 2726

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 2774

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 2803

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 2827

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 2962

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 2981

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 3026

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 3045

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 3199

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 3221