Army
Army objects represent logical armies taking part in a battle. One or more armies fight together on each side of the battle in an battle_alliance to contest victory.
An army contains one or more logical battle_unit objects, which may be accessed through the battle_units collection object that the army provides.
| Loaded in Battle |
|
Army objects are derived from battle_armies list objects in the battle_hierarchy, which are themselves derived from battle_alliance objects - see the battle_hierarchy page for more information. Army objects must be created in order to create script_unit objects. Using the generated_battle framework negates the need to explicitly create army objects, however.
Once a handle to an army 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 army_player = bm:alliances():item(1):armies():item(1)
local uc_player_01 = army_player:create_unit_controller() -- calling a function on the object once created
-
army:units() -
Creates and returns a
battle_unitsobject listing all units in the army.Returns:
battle_units
-
army:faction_key() -
Returns the key of the army's faction, from the
factionsdatabase table.Returns:
string
-
army:subculture_key() -
Returns the subculture key of the army's faction, from the
cultures_subculturesdatabase table.Returns:
string
-
army:flag_path() -
Returns the folder path of the flag icons used for the army's faction, from the
flags_pathfield of thefactionsdatabase table.Returns:
string
-
army:is_rebel() -
Returns whether the army's faction is a rebel faction.
Returns:
boolean
-
army:create_unit_controller() -
Creates and returns a
battle_unitcontrollerobject associated with this army. Consider using thegenerated_battleorscript_unitframework, or at least the helper functions documented in the sectionUnitcontroller Creationrather than calling this directly.Returns:
battle_unitcontroller
-
army:is_commander_alive() -
Returns whether the army commander is alive or not.
Returns:
boolean
-
army:is_commander_invincible() -
Returns whether the army commander is invicible or not.
Returns:
boolean
-
army:army_handicap() -
Returns the army handicap, which indicates the difficulty level the battle is being played at. A returned value of 1 equates to easy difficulty, 0 to normal difficulty, -1 to hard difficulty and -2 to very hard difficulty.
Returns:
number
-
army:wind_of_magic_remaining_recharge_rate() -
Returns the remaining recharge left for an armies magic pool. This is rate of recharge compared to max possible recharge rate. 0 is slowest speed, 1 is quickest.
Returns:
number
-
army:modify_winds_of_magic_max_depletion(magic to addnumber) -
Adds the supplied amount to the winds of magic reserve for the army.
Parameters:
1
magic to add
Returns:
nil
-
army:get_reinforcement_units([reinforcement collectionnumber]) -
Returns a
battle_unitscollection containing reinforcements waiting to deploy. Supply an optional index if there are multiple units collections waiting to reinforce.Parameters:
1
optional, default value=1
reinforcement collection
Returns:
battle_units
-
army:num_reinforcement_units() -
Return the number of
battle_unitscollections that are reinforcements waiting to deploy for this army.Returns:
number
-
army:suppress_reinforcement_adc() -
Prevents reinforcement aide-de-camp messages being generated for this army.
Returns:
nil
-
army:change_faction(faction keystring) -
Changes the army's faction mid-battle.
Parameters:
1
faction key
Returns:
nil
-
army:enable_army_destruction_morale_effect(enable effectboolean) -
Sets whether the army destruction morale effect can apply to this army or not.
Parameters:
1
enable effect
Returns:
nil
-
army:quit_battle() -
Instructs the army to quit the battle.
Returns:
nil
-
army:highlight_deployment_areas([should highlightboolean]) -
Highlights/flashes the deployment area related to this army.
Parameters:
1
optional, default value=true
should highlight
Returns:
nil
-
army:use_special_ability(special ability key
string,position
[battle_vector],bearing
[number],width
[number]
) -
Instructs the army to use the specified army special ability. An optional position, bearing and width may be specified with the special ability but these are not always required.
Parameters:
1
Special ability key, from the
army_special_abilitiestable.2
optional, default value=nil
Position at which the ability is targeted, if applicable.
3
optional, default value=0
Bearing in radians of special ability, if applicable.
4
optional, default value=0
Width of special ability, if applicable.
Returns:
nil