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 alliance to contest victory.

An army contains one or more logical unit objects, which may be accessed through the units collection object that the army provides.

Loaded in Battle loaded in battle
Back to top

Creation

Army objects are derived from armies list objects in the battle_hierarchy, which are themselves derived from 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.

Back to top

Usage

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

Methods

army:units()
Creates and returns a units object listing all units in the army.

Returns:

  1. units units list

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

army:create_unit_controller()
Creates and returns a unitcontroller object associated with this army. Consider using the generated_battle or script_unit framework, or at least the helper functions documented in the section Unitcontroller Creation rather than calling this directly.

Returns:

  1. unitcontroller unitcontroller

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

army:is_commander_alive()
Returns whether the army commander is alive or not.

Returns:

  1. boolean is commander alive

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

army:is_commander_invincible()
Returns whether the army commander is invincible or not.

Returns:

  1. boolean is commander invincible

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

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:

  1. number handicap value

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

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:

  1. number recharge rate

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

army:modify_winds_of_magic_max_depletion(number magic to add)

Adds the supplied amount to the winds of magic reserve for the army.

Parameters:

1

number

magic to add

Returns:

  1. nil

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

army:get_reinforcement_units([number reinforcement collection])

Returns a units collection containing reinforcements waiting to deploy. Supply an optional index if there are multiple units collections waiting to reinforce.

Parameters:

1

number

optional, default value=1

reinforcement collection

Returns:

  1. units reinforcements units

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

army:num_reinforcement_units()
Return the number of units collections that are reinforcements waiting to deploy for this army.

Returns:

  1. number number of reinforcement units collections

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

army:suppress_reinforcement_adc()
Prevents reinforcement aide-de-camp messages being generated for this army.

Returns:

  1. nil

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

army:change_faction(string faction key)

Changes the army's faction mid-battle.

Parameters:

1

string

faction key

Returns:

  1. nil

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

army:enable_army_destruction_morale_effect(boolean enable effect)

Sets whether the army destruction morale effect can apply to this army or not.

Parameters:

1

boolean

enable effect

Returns:

  1. nil

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

army:quit_battle()
Instructs the army to quit the battle.

Returns:

  1. nil

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

army:highlight_deployment_areas([boolean should highlight])

Highlights/flashes the deployment area related to this army.

Parameters:

1

boolean

optional, default value=true

should highlight

Returns:

  1. nil

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

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