Unit

A unit object may be created in script to represent a logical unit of soldiers taking part in the battle. The unit object interface permits querying of the state of the unit - to issue orders to the unit a unitcontroller object must be created to which the unit object may then be associated.

Loaded in Battle loaded in battle
Back to top

Creation

Unit objects are created from the battle_hierarchy. They appear at the bottom of this hierarchy - see the battle_hierarchy page for more information on how unit objects relate to (and are created from) armies and alliances. Alternatively, and preferably, see the section on scriptunits below for a shorthand method of unit object creation.

Back to top

Usage

Once a handle to a sound effect object is obtained, functions may be called on it to query or modify its state in the following form.

Example - Specification:

<object_name>:<function_name>(<args>)

Example - Creation and Usage:

local sfx_01 = battle_sound_effect:new()
sfx_01:load("test_sound_event")        -- calling a function on the object once created
Back to top

Scriptunits and Generated Battles

It is highly recommended for client scripts to work with script_unit objects through the interface provided by the script libraries rather than attempting to manage unit objects individually. By creating a script_unit object, a unit object is automatically created and can be accessed at <script_unit>.unit. See the script_unit documentation for more information.

Alternatively the generated_battle script framework can be used. This automatically creates script_unit objects (with associated unit objects) and negates the need to set up references to anything more granular than an army.

Back to top

Identification

unit:name()
Returns the script name for the unit, if any has been set. A script name for the unit may be set in the battle setup, either in the battle xml or on the appropriate record in the battle_set_piece_armies_units_junctions table if setting up a set-piece/quest battle. It is valid for multiple units in a given army to have the same script name.

Returns:

  1. string script name

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 1848

unit:unique_ui_id()
Returns the unique ui id for the unit, which should match the name of the corresponding unit card.

Returns:

  1. number ui ud

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 1881

unit:type()
Returns the unit type of the unit, from the land_units table.

Returns:

  1. string unit type

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 1898

unit:alliance_index()
Returns the index number of the alliance the unit belongs to, allowing its alliance to be determined or looked up from a alliances object.

Returns:

  1. number alliance index

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 1913

unit:army_index()
Returns the index number of the army the unit belongs to, allowing its army to be determined or looked up from a armies object (which itself can be determined from the value returned by unit:alliance_index).

Returns:

  1. number army index

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 1928

unit:unit_class()
Returns the class of the unit, from the land_units table.

Returns:

  1. string unit class

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 1943

unit:is_commanding_unit()
Returns whether this is the commanding unit of the army.

Returns:

  1. boolean is commanding

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 1959

unit:is_infantry()
Returns whether this is a unit of infantry.

Returns:

  1. boolean is infantry

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 1975

unit:is_pikemen()
Returns whether this is a unit of pikemen.

Returns:

  1. boolean is pikemen

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 1989

unit:is_swordsmen()
Returns whether this is a unit of swordsmen.

Returns:

  1. boolean is swordsmen

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2009

unit:is_spearmen()
Returns whether this is a unit of spearmen.

Returns:

  1. boolean is spearmen

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2029

unit:is_axemen()
Returns whether this is a unit of axemen.

Returns:

  1. boolean is axemen

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2049

unit:is_infantry_ranged()
Returns whether this is a unit of ranged infantry.

Returns:

  1. boolean is ranged infantry

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2069

unit:is_anti_cavalry_infantry()
Returns whether this is a unit of anti-cavalry infantry.

Returns:

  1. boolean is anti-cavalry infantry

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2089

unit:is_cavalry()
Returns whether this is a unit of cavalry.

Returns:

  1. boolean is cavalry

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2110

unit:is_lancers()
Returns whether this is a unit of lancers.

Returns:

  1. boolean is lancers

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2124

unit:is_dismounted_cavalry()
Returns whether this is a dismounted cavalry unit.

Returns:

  1. boolean is dismounted cavalry

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2144

unit:is_chariot()
Returns whether this is a chariot unit.

Returns:

  1. boolean is chariot

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2164

unit:is_camels()
Returns whether this unit fights on camels.

Returns:

  1. boolean is camels

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2184

unit:is_elephants()
Returns whether this is a unit of elephants.

Returns:

  1. boolean is elephants

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2204

unit:is_war_beasts()
Returns whether this is a unit of war beasts.

Returns:

  1. boolean is war beasts

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2224

unit:is_artillery()
Returns whether this is an artillery unit.

Returns:

  1. boolean is artillery

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2244

unit:is_limbered_artillery()
Returns whether the unit is artillery in a limbered state (i.e. it can move but not fire).

Returns:

  1. boolean is limbered artillery

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2258

unit:is_unlimbered_artillery()
Returns whether the unit is artillery in an unlimbered state (it can fire, but not move).

Returns:

  1. boolean is unlimbered artillery

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2270

unit:is_fixed_artillery()
Returns whether the unit is fixed artillery. Fixed artillery can never move.

Returns:

  1. boolean is fixed artillery

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2290

unit:is_war_machine()
Returns whether the unit is a war machine.

Returns:

  1. boolean is war machine

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2310

unit:can_fly()
Returns whether the unit can fly.

Returns:

  1. boolean can fly

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2330

unit:is_currently_flying()
Returns whether the unit can fly and is currently flying.

Returns:

  1. boolean is flying

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2343

unit:has_ships()
Returns whether the unit is currently on a ship.

Returns:

  1. boolean is on a ship

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2356

unit:is_dismounted_ships()
Returns whether the unit has a ship but is not currently on it.

Returns:

  1. boolean dismounted from ship

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2370

Back to top

Location and Movement

unit:position()
Returns the centre position of the main squad of the unit.

Returns:

  1. battle_vector position

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2387

unit:ordered_position()
Returns the position to which the unit has been ordered to move to. Note that if the unit is attacking, as opposed to moving, then this will return the current position of the unit.

Returns:

  1. battle_vector ordered position

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2405

unit:can_reach_position(battle_vector position)

Returns whether the unit can reach the supplied position.

Parameters:

1

battle_vector

position

Returns:

  1. boolean can reach

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2423

unit:bearing()
Returns the current orientation of the main squad of the unit in degrees.

Returns:

  1. number orientation

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2450

unit:ordered_bearing()
Returns the orientation of the position to which the unit has been ordered in degrees.

Returns:

  1. number orientation

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2470

unit:ordered_width()
Returns the width of the position to which the unit has been ordered in metres.

Returns:

  1. number width

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2489

unit:position_of_officer()
Returns the position of the commanding officer of the unit.

Returns:

  1. battle_vector officer position

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2505

unit:unit_in_range(unit target unit)

Returns whether the supplied unit is in missile range of this unit.

Parameters:

1

unit

target unit

Returns:

  1. boolean is in range

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2533

unit:unit_distance(unit target unit)

Returns the shortest distance in metres between this unit and a supplied unit, taking into account their bounding box rather than just working out the centre-to-centre distance.

Parameters:

1

unit

target unit

Returns:

  1. number shortest distance

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2552

unit:is_moving()
Returns whether the unit is moving.

Returns:

  1. boolean is moving

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2572

unit:is_moving_fast()
Returns whether the unit is moving fast (running/charging).

Returns:

  1. boolean is moving fast

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2590

unit:is_idle()
Returns whether the unit is currently idle.

Returns:

  1. boolean is idle

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2608

unit:is_leaving_battle()
Returns whether the unit is currently leaving the battlefield.

Returns:

  1. boolean is leaving battle

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2626

unit:is_valid_target()
Returns whether this unit is currently a valid target for enemies to attack. A unit might be invalid if they are entering or leaving the battlefield, hidden, or dead.

Returns:

  1. boolean is valid target

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2640

unit:is_currently_garrisoned()
Returns whether the unit is currently garrisoned in a building.

Returns:

  1. boolean is garrisoned

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2654

Back to top

Visibility

unit:is_hidden()
Returns whether the unit is currently hidden in tall grass/trees. Note that this is a separate test from the unit being obscured from the enemy behind hills or other terrain features.

Returns:

  1. boolean is hidden

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2670

unit:is_visible_to_alliance(alliance alliance)

Returns whether the unit is visible to a supplied alliance. This returns the last calculated result of the line-of-sight test that determines whether a unit is obscured from its enemy by terrain features.

Parameters:

1

alliance

alliance

Returns:

  1. boolean is visible to alliance

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2688

Back to top

Combat

unit:is_under_missile_attack()
Returns whether the unit is currently taking fire.

Returns:

  1. boolean taking fire

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2717

unit:is_in_melee()
Returns whether the unit is currently in melee combat.

Returns:

  1. boolean in melee

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2735

unit:is_firing_missiles()
Returns whether the unit is currently firing missiles.

Returns:

  1. boolean is_firing_missiles

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2751

unit:number_of_enemies_killed()
Returns the number of enemy combatants this unit has killed in this battle.

Returns:

  1. number number killed

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2769

Back to top

Unit Strength

unit:initial_number_of_men()
Returns the number of soldiers the unit started the battle with.

Returns:

  1. number initial unit size

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2786

unit:number_of_men_alive()
Returns the number of soldiers currently alive in the unit.

Returns:

  1. number current unit size

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2800

unit:unary_of_men_alive()
Returns the number of soldiers currently alive in the unit, expressed as a unary fraction of the the initial size of the unit. A returned value of 0.75 would indicate that 25% of the soldiers in the unit that started the battle have died.

Returns:

  1. number unary proportion

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2814

unit:kill_number_of_men(number soldiers to kill, [boolean hide bodies], [boolean ignore_pause])

Kills a specified number of soldiers in the unit. The optional second argument allows their bodies to be hidden - this is useful if it's desired that the unit 'disappear'.

Parameters:

1

number

soldiers to kill

2

boolean

optional, default value=false

hide bodies

3

boolean

optional, default value=true

ignore_pause

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2827

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

Returns:

  1. number unary proportion

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2860

Back to top

Morale and Fatigue

unit:is_wavering()
Returns whether the morale of the unit is currently wavering.

Returns:

  1. boolean is wavering

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2880

unit:is_routing()
Returns whether the unit is currently routing.

Returns:

  1. boolean is routing

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2894

unit:is_rampaging()
Returns whether the unit is currently rampaging.

Returns:

  1. boolean is rampaging

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2908

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

Returns:

  1. boolean is shattered

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2922

unit:is_dueling()
Returns whether the unit is currently involved in a duel.

Returns:

  1. boolean is duelling

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2936

unit:is_left_flank_threatened()
Returns whether the left flank of the unit is currently threatened by the enemy.

Returns:

  1. boolean left flank threatened

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2950

unit:is_right_flank_threatened()
Returns whether the right flank of the unit is currently threatened by the enemy.

Returns:

  1. boolean left right threatened

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2963

unit:is_rear_flank_threatened()
Returns whether the rear of the unit is currently threatened by the enemy.

Returns:

  1. boolean rear threatened

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2976

unit:left_flank_threat()
Returns the unit threatening this unit's left flank. If no such unit is threatening then no value is returned.

Returns:

  1. unit threatening unit

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 2989

unit:right_flank_threat()
Returns the unit threatening this unit's right flank. If no such unit is threatening then no value is returned.

Returns:

  1. unit threatening unit

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 3009

unit:rear_threat()
Returns the unit threatening this unit's rear. If no such unit is threatening then no value is returned.

Returns:

  1. unit threatening unit

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 3029

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

Returns:

  1. string fatigue state

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 3049

Back to top

Ammunition and Range

unit:ammo_left()
Returns the remaining ammunition count of this unit.

Returns:

  1. number current ammunition

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 3071

unit:starting_ammo()
Returns the amount of ammunition the unit started the battle with.

Returns:

  1. number starting ammunition

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 3085

unit:set_current_ammo_unary(number unary ammunition level)

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

Parameters:

1

number

unary ammunition level

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 3099

unit:missile_range()
Returns the missile range of this unit in metres.

Returns:

  1. number missile range

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 3120

Back to top

Abilities and Behaviours

unit:can_perform_special_ability(string special ability key )

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

Parameters:

1

string

special ability key

Returns:

  1. boolean can perform ability

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 3137

unit:num_special_abilities()
Returns the number of special abilities this unit has.

Returns:

  1. number number of special abilities

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 3158

unit:rage_unary()
Returns the current rage level of this unit as a unary value.

Returns:

  1. number rage level

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 3173

unit:aristeia_unary()
Returns the current aristeia level of this unit as a unary value.

Returns:

  1. number aristeia level

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 3188

unit:can_use_magic()
Returns whether the unit can use any special abilities that cost magic.

Returns:

  1. boolean can use magic

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 3203

unit:is_behaviour_active(string behaviour)

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

Parameters:

1

string

behaviour

Returns:

  1. boolean behaviour is active

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 3232

Back to top

Sounds

unit:trigger_sound_charge()
Compels the unit to make a charge sound effect.

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 3250

unit:trigger_sound_taunt()
Compels the unit to make a taunt sound effect.

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 3262

Back to top

Miscellaneous

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

Compels the unit leader to play an animation.

Parameters:

1

string

animation key

2

boolean

loop animation

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 3277

unit:deploy_reinforcement(boolean can deploy)

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

Parameters:

1

boolean

can deploy

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 3324

unit:select_in_ui()
Selects the unit in the user interface.

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 3341

unit:mark_as_ally(boolean mark as ally)

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

Parameters:

1

boolean

mark as ally

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 3352

Last updated 25/08/2021 12:07:50