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 battle_unitcontroller object must be created to which the unit object may then be associated.

Loaded in Campaign Loaded in Campaign
Loaded in Battle Loaded in Battle
Loaded in Frontend Loaded in Frontend
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 lunar_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

battle_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

battle_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

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

Returns:

  1. string unit type

battle_unit:army()
Returns the army object to which the unit currently belongs.

Returns:

  1. battle_army parent army

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

Returns:

  1. number alliance index

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

Returns:

  1. number army index

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

Returns:

  1. string unit class

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

Returns:

  1. boolean is commanding

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

Returns:

  1. boolean is infantry

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

Returns:

  1. boolean is pikemen

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

Returns:

  1. boolean is swordsmen

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

Returns:

  1. boolean is spearmen

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

Returns:

  1. boolean is axemen

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

Returns:

  1. boolean is ranged infantry

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

Returns:

  1. boolean is anti-cavalry infantry

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

Returns:

  1. boolean is cavalry

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

Returns:

  1. boolean is lancers

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

Returns:

  1. boolean is dismounted cavalry

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

Returns:

  1. boolean is chariot

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

Returns:

  1. boolean is camels

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

Returns:

  1. boolean is elephants

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

Returns:

  1. boolean is war beasts

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

Returns:

  1. boolean is artillery

battle_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

battle_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

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

Returns:

  1. boolean is fixed artillery

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

Returns:

  1. boolean is war machine

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

Returns:

  1. boolean can fly

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

Returns:

  1. boolean is flying

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

Returns:

  1. boolean is on a ship

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

Returns:

  1. boolean dismounted from ship
Back to top

Location and Movement

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

Returns:

  1. battle_vector position

battle_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

battle_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

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

Returns:

  1. number orientation

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

Returns:

  1. number orientation

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

Returns:

  1. number width

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

Returns:

  1. battle_vector officer position

battle_unit:is_ai_controlled()
Returns whether the supplied unit is currently under AI control.

Returns:

  1. boolean controlled by AI

battle_unit:is_script_controlled()
Returns whether the supplied unit is currently under script control.

Returns:

  1. boolean controlled by script

battle_unit:is_player_controlled()
Returns whether the supplied unit is currently under script control.

Returns:

  1. boolean controlled by script

battle_unit:unit_in_range(battle_unit target unit)

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

Parameters:

1

battle_unit

target unit

Returns:

  1. boolean is in range

battle_unit:unit_distance(battle_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

battle_unit

target unit

Returns:

  1. number shortest distance

battle_unit:strategic_value()
Returns an arbitrary numeric indicator of this unit's current strength. Better units, or units in a better current condition, will return higher values that less capable units.

Returns:

  1. number strategic value

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

Returns:

  1. boolean is moving

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

Returns:

  1. boolean is moving fast

battle_unit:slow_speed()
Returns the unit's slow/walking movement speed in m/s.

Returns:

  1. number movement speed

battle_unit:fast_speed()
Returns the unit's fast/running movement speed in m/s.

Returns:

  1. number movement speed

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

Returns:

  1. boolean is idle

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

Returns:

  1. boolean is leaving battle

battle_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

battle_unit:is_controllable()
Returns whether the unit is currently controllable.

Returns:

  1. boolean is controllable

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

Returns:

  1. boolean is garrisoned

battle_unit:is_in_group()
Returns whether the unit is currently in a player-created unit group.

Returns:

  1. boolean is in group
Back to top

Visibility

battle_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

battle_unit:is_visible_to_alliance(battle_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

battle_alliance

alliance

Returns:

  1. boolean is visible to alliance
Back to top

Combat

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

Returns:

  1. boolean taking fire

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

Returns:

  1. boolean in melee

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

Returns:

  1. boolean is_firing_missiles

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

Returns:

  1. number number killed
Back to top

Unit Strength

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

Returns:

  1. number initial unit size

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

Returns:

  1. number current unit size

battle_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

battle_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

battle_unit:reduce_hitpoints_unary(number unary hitpoints, [boolean hide bodies])

Reduces hitpoints of 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

percentage of full hit points of unit to reduce

2

boolean

optional, default value=false

hide bodies

Returns:

  1. nil

battle_unit:heal_hitpoints_unary(number unary hitpoints, [boolean allow resurrection])

Heals the unit to the specified unary proportion of full strength i.e. 1.0 = full strength. If the allow-resurrection flag is set then dead entities may be resurrected, otherwise the function heals where it can. The function does not work in all circumstances, healing animals + handlers are not currently supported.

Parameters:

1

number

percentage of full hit points to heal to.

2

boolean

optional, default value=true

Allow resurrection of dead entities.

Returns:

  1. nil

battle_unit:respawn()
Respawns the unit in a supplied position on the battlefield.

Returns:

  1. nil

battle_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
Back to top

Morale and Fatigue

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

Returns:

  1. boolean is wavering

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

Returns:

  1. boolean is routing

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

Returns:

  1. boolean is rampaging

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

Returns:

  1. boolean is shattered

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

Returns:

  1. boolean is duelling

battle_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

battle_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

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

Returns:

  1. boolean rear threatened

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

Returns:

  1. battle_unit threatening unit

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

Returns:

  1. battle_unit threatening unit

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

Returns:

  1. battle_unit threatening unit

battle_unit:current_target()
Returns the battle_unit this unit is targeting. If no unit is being targeted then no value is returned.

Returns:

  1. battle_unit target unit

battle_unit:is_on_top_of_platform()
Returns whether the unit is currently on the top of a platform, such as a wall.

Returns:

  1. boolean is on platform

battle_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
Back to top

Ammunition and Range

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

Returns:

  1. number current ammunition

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

Returns:

  1. number starting ammunition

battle_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

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

Returns:

  1. number missile range
Back to top

Abilities and Behaviours

battle_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

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

Returns:

  1. number number of special abilities

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

Returns:

  1. number rage level

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

Returns:

  1. number aristeia level

battle_unit:can_guerrilla_deploy()
Returns whether this unit is a vanguard unit that can deploy outside of the deployment area before the battle begins.

Returns:

  1. boolean can guerrilla deploy

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

Returns:

  1. boolean can use magic
Back to top

Unit Behaviours

battle_unit:can_use_behaviour(string behaviour)

Returns whether the unit can use a particular behaviour this battle. 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 can be used

battle_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
Back to top

Sounds

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

Returns:

  1. nil

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

Returns:

  1. nil
Back to top

Miscellaneous

battle_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

battle_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

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

Returns:

  1. nil

battle_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

battle_unit:highlight([boolean highlight])

Activates or deactivates a highlight on the unit.

Parameters:

1

boolean

optional, default value=true

highlight

Returns:

  1. nil
Last updated 8/23/2024 4:55:16 PM