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

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

Returns:

  1. battle_units units list

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

Returns:

  1. string faction key

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

Returns:

  1. string subculture key

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

Returns:

  1. boolean is rebel

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

Returns:

  1. battle_alliance parent alliance

battle_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

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

Returns:

  1. boolean is commander alive

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

Returns:

  1. boolean is commander invincible

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

Returns:

  1. boolean is player controlled

battle_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

battle_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

battle_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

battle_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

battle_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

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

Returns:

  1. nil

battle_army:change_faction(string faction key)

Changes the army's faction mid-battle.

Parameters:

1

string

faction key

Returns:

  1. nil

battle_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

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

Returns:

  1. nil

battle_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

battle_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
Last updated 8/23/2024 4:55:16 PM