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 Campaign Loaded in Campaign
Loaded in Battle Loaded in Battle
Loaded in Frontend Loaded in Frontend
Back to top

Creation

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.

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 battle_units object listing all units in the army.

Returns:

  1. battle_units units list

army:faction_key()
Returns the key of the army's faction, from the factions database table.

Returns:

  1. string faction key

army:subculture_key()
Returns the subculture key of the army's faction, from the cultures_subcultures database table.

Returns:

  1. string subculture key

army:flag_path()
Returns the folder path of the flag icons used for the army's faction, from the flags_path field of the factions database table.

Returns:

  1. string faction flags folder path

army:is_rebel()
Returns whether the army's faction is a rebel faction.

Returns:

  1. boolean is rebel

army:alliance()
Returns the alliance object to which the army belongs.

Returns:

  1. battle_alliance parent alliance

army:enable_reinforcement(number spawn zone unique id)

Enables a reinforcement army to deploy from the spawn zone of the specified id, allowing it to start reinforcing. A reinforcing army must be enabled through some mechanism before it can enter the battle. In standard campaign battles, a reinforcing army is enabled through a player-facing timer - this function can be called to enable an army before the timer finishes, for example.

Parameters:

1

number

spawn zone unique id

Returns:

  1. nil

army:create_unit_controller()
Creates and returns a battle_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. battle_unitcontroller unitcontroller

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

Returns:

  1. boolean is commander alive

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

Returns:

  1. boolean is commander invincible

army:is_player_controlled()
Returns whether this army is controlled by a human player.

Returns:

  1. boolean is player controlled

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

army:winds_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

army:winds_of_magic_reserve()
Returns the reserve magic this army can spend. This is the total amount of magic available to this army that hasn't yet entered its current pool. As the current pool is spent on casting spells, magic flows to it from the reserve pool until that pool is empty.

Returns:

  1. number magic

army:winds_of_magic_current()
Returns the current amount of magic this army has available to spend.

Returns:

  1. number magic

army:modify_winds_of_magic_reserve(number magic to add)

Adds the supplied amount to the winds of magic reserve for the army. The reserve is the total amount of magic the army has left to spend, that hasn't yet entered its current pool.

Parameters:

1

number

magic to add

Returns:

  1. nil

army:modify_winds_of_magic_current(number magic to add, [boolean add directly])

Adds the supplied amount to the current winds of magic for the army. The optional flag specifies that it should not be taken from the reserve - if set, the magic is directly added to the current pool with the reserve pool left untouched.

Parameters:

1

number

magic to add

2

boolean

optional, default value=false

add directly

Returns:

  1. nil

army:allow_use_toggleables(boolean allow use toggleables)

Allows/Stops this army to interact with toggleables

Parameters:

1

boolean

allow use toggleables

Returns:

  1. nil

army:get_reinforcement_units([number reinforcement collection])

Returns a battle_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. battle_units reinforcements units

army:is_reinforcement_army()
Returns true if this army is a reinforcement army

Returns:

  1. boolean is a reinforcement army

army:get_reinforcement_target_army()
Returns the target army of the reinforcement if it is one

Returns:

  1. battle_army target reinforcement army, or nil if there is none.

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

Returns:

  1. number number of reinforcement units collections.

army:unique_id()
Return the unique of this army.

Returns:

  1. number unique id of the army.

army:enable_reinforcement_adc()
Allows aide-de-camp messages being generated for this army.

Returns:

  1. nil

army:suppress_reinforcement_adc([number number of messages allowed before disabling them])

Prevents reinforcement aide-de-camp messages being generated for this army.

Parameters:

1

number

optional, default value=nil

number of messages allowed before disabling them

Returns:

  1. nil

army:change_faction(string faction key)

Changes the army's faction mid-battle.

Parameters:

1

string

faction key

Returns:

  1. nil

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

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

Returns:

  1. nil

army:highlight_deployment_areas([boolean should highlight])

Activates or deactivates a highlight on the deployment area related to this army.

Parameters:

1

boolean

optional, default value=true

should highlight

Returns:

  1. nil

army:use_special_ability(string key, battle_vector position, [number bearing], [number width])

Instructs the army to target a special ability at a supplied position.

Parameters:

1

string

Key of the special ability, from the army_special_abilities database table.

2

battle_vector

Position to target the special ability at.

3

number

optional, default value=nil

Bearing of the special ability in degrees. This is optional and is not required for all abilities.

4

number

optional, default value=nil

Width of the special ability in metres. This is optional and is not required for all abilities.

Returns:

  1. nil

army:has_currency(string currency type)

Returns whether this army has access to the specified battle currency.

Parameters:

1

string

Key of the battle currency, from the battle_secondary_currency_types database table.

Returns:

  1. nil

army:currency_amount(string currency type)

Returns the current quantity of the specified battle currency available to this army.

Parameters:

1

string

Key of the battle currency, from the battle_secondary_currency_types database table.

Returns:

  1. nil

army:reset_currency_amount(string currency type)

Resets the quantity of the specified battle currency available to this army to 0.

Parameters:

1

string

Key of the battle currency, from the battle_secondary_currency_types database table.

Returns:

  1. nil
Last updated 7/9/2024 11:45:05 AM