Unitcontroller

Unitcontrollers are the interface through which orders may be issued to units. A unitcontroller is created and then one or more battle_unit objects are attached to it. The unitcontroller can then take control of these units from other controlling entities (such as the player, or the AI) and issue orders for the units to follow. A unitcontroller implicitly takes control of units to which it is assigned if an order is issued, or control may be taken explicitly with unitcontroller:take_control. Should a unitcontroller take control of a player unit then the player will not be able to issue commands to it (the card belonging to the unit will appear greyed-out).

A unitcontroller manages one or more unit groups and a list of individual units. Each group of units that the controller manages moves together, organising themselves into a specific formation. The individual units under control all move autonomously.

Loaded in Campaign Loaded in Campaign
Loaded in Battle Loaded in Battle
Loaded in Frontend Loaded in Frontend
Back to top

Creation

A unitcontroller may be created manually with the army:create_unit_controller method provided by the battle_army interface. However, the script libraries provide a number of shorthand methods for creating unitcontrollers, such as create_unitcontroller and unitcontroller_from_army. Of greater significance is the script_unit interface, which provides easy creation of both a battle_unit and battle_unitcontroller packaged together. When a script unit is created, the unitcontroller it contains may be accessed at <script_unit>.uc.

Furthermore, use of the generated_battle framework negates the need to create (or even use) unitcontrollers.

Back to top

Usage

Once a handle to a unitcontroller 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 uc_player_01 = army_player:create_unit_controller()
uc_player_01:take_control()        -- calling a function on the object once created
Back to top

Adding and Removing Units

unitcontroller:clear_all()
Removes all units from the unitcontroller. Units that were under script control are still left in this state unless explicitly released with unitcontroller:release_control.

Returns:

  1. nil

unitcontroller:add_all_units()
Adds all units in the battle_army that this unitcontroller is assocated with, as a group.

Returns:

  1. nil

unitcontroller:add_units(... units)
Adds one or more units to the unitcontroller. Multiple battle_unit objects may be specified as individual arguments.

Parameters:

1

...

One or more battle_unit objects.

Returns:

  1. nil

unitcontroller:add_group(... units)
Adds one or more units to the unitcontroller as a group. Multiple battle_unit objects may be specified as individual arguments. Grouped units will move together.

Parameters:

1

...

One or more battle_unit objects.

Returns:

  1. nil
Back to top

Taking and Releasing Control

Script control of the units in a unitcontroller is automatically taken when an order is issued to them. Control can be explicitly taken or released using the commands in this section, however.

unitcontroller:take_control()
Explicitly takes control of the assigned units. This removes them from player or AI control.

Returns:

  1. nil

unitcontroller:release_control()
Releases control of all units controlled by this unitcontroller to either the player or the AI.

Returns:

  1. nil
Back to top

Morale and Invincibility

unitcontroller:morale_behavior_default()
Releases the morale value of the units associated with this unitcontroller to be set by the game. Use this function after calling either unitcontroller:morale_behavior_fearless or unitcontroller:morale_behavior_rout to reset the morale to game control.

Returns:

  1. nil

unitcontroller:morale_behavior_fearless()
Sets the units associated with this unitcontroller to be fearless, meaning they can never rout.

Returns:

  1. nil

unitcontroller:hide_unbreakable_in_ui(boolean hide_in_ui)

Allows/Disables the UI to show that a unit is fearless/unbreakable.

Parameters:

1

boolean

If true the UI will ignore that the unit is fearless/unbreakable.

Returns:

  1. nil

unitcontroller:morale_behavior_rout()
Instructs the units associated with this unitcontroller to immediately rout.

Returns:

  1. nil

unitcontroller:teleport_withdraw_unit()
Instructs the units associated with this unit controller to immediately teleport away.

Returns:

  1. nil

unitcontroller:set_invincible([boolean is invincible])

Sets the units associated with this unitcontroller to be invincible or not. Invincible units do not take damage.

Parameters:

1

boolean

optional, default value=true

is invincible

Returns:

  1. nil
Back to top

Visibility and Fatigue

unitcontroller:set_invisible_to_all(boolean set invisible, [boolean update ui])

Makes all units associated with this unitcontroller invisible or not. Supply true as an argument to make units invisible, and false to make them visible again. Invisible units are still able to take part in the battle, unless also disabled with unitcontroller:change_enabled.
The script_unit:set_enabled command on the script_unit interface sets invisibility and enables/disables the unit in one function call, so consider calling that function instead of this.

Parameters:

1

boolean

Set invisible.

2

boolean

optional, default value=true

Update UI with invisibility change. Supply false to not update the UI with this visibility change. This should only be done in very specific circumstances - hiding and showing unit cards can potentially re-order them, so set this flag to false to suppress this behaviour if desired.

Returns:

  1. nil

unitcontroller:set_always_visible_to_all(boolean set always visible)

Sets the units associated with this unitcontroller to be exempt or not from the terrain visibility test.

Parameters:

1

boolean

set always visible

Returns:

  1. nil

unitcontroller:set_always_visible_no_hidden_to_all(boolean set always visible)

Sets the units associated with this unitcontroller to be exempt or not from the terrain visibility test. If set to be visible the unit will still be able to hide in forests and vegetation.

Parameters:

1

boolean

set always visible

Returns:

  1. nil

unitcontroller:set_always_visible_no_leave_battle_to_all(boolean set always visible)

Sets the units associated with this unitcontroller to be exempt or not from the terrain visibility test. If set to be visible the unit will still be able to hide when leaving battle

Parameters:

1

boolean

set always visible

Returns:

  1. nil

unitcontroller:set_always_visible_no_hidden_no_leave_battle_to_all(boolean set always visible)

Sets the units associated with this unitcontroller to be exempt or not from the terrain visibility test. If set to be visible the unit will still be able to hide in forests and vegetation and when leaving battle.

Parameters:

1

boolean

set always visible

Returns:

  1. nil

unitcontroller:change_enabled(boolean enabled)

Enables or disables the units associated with this unitcontroller. Disabled units will not take any part in the battle. However they will still be visible on the UI, unless also set to be invisible with unitcontroller:set_invisible_to_all.
The script_unit:set_enabled command on the script_unit interface sets invisibility and enables/disables the unit in one function call, so consider calling that function instead of this.

Parameters:

1

boolean

enabled

Returns:

  1. nil

unitcontroller:set_contributes_to_army_strength(boolean contributes)

Sets the unit to contribute to the strength of its army for balance-of-power calculations. Note that the underlying setting this function changes is also changed whenever unitcontroller:change_enabled is called - enabled units will contribute to army strength, whereas disabled units will not. This function may be called after calling unitcontroller:change_enabled to change this behaviour.    

Parameters:

1

boolean

contributes

Returns:

  1. nil

unitcontroller:update_card_existance_on_HUD()
Tells the UI to add or remove the units associated with this unitcontroller to or from the HUD based on the current invisibility flag. This is only for use in specific scripted circumstances.

Returns:

  1. nil

unitcontroller:hide_unit_card()
Tells the UI to hide the units cards associated with this unitcontroller.

Returns:

  1. nil

unitcontroller:change_fatigue_amount(number fatigue level)

Changes the fatigue level of the units associated with this unitcontroller to the supplied unary value, relative to their current level. For example, supplying 0.5 as an argument would half their fatigue level (making them fresher). Do not supply 0 to this function as this would cause a divide by zero error in the code - 0.01 or some equivalent will suffice.

Parameters:

1

number

Relative unary fatigue level.

Returns:

  1. nil
Back to top

Abilities and Behaviours

unitcontroller:perform_special_ability(string ability key, [battle_unit target unit])

Issues an order to the units associated with this unitcontroller to perform the supplied special ability. Special abilities are listed in the unit_special_abilities table. An optional unit target may be specified.

Parameters:

1

string

ability key

2

battle_unit

optional, default value=nil

target unit

Returns:

  1. nil

unitcontroller:perform_special_ability_q(string ability key, [battle_unit target unit])

Issues a queued order to the units associated with this unitcontroller to perform the supplied special ability. Special abilities are listed in the unit_special_abilities table. Queued orders start when the current order completes.
An optional unit target may be specified with the second argument.

Parameters:

1

string

ability key

2

battle_unit

optional, default value=nil

target unit

Returns:

  1. nil

unitcontroller:perform_special_ability_ground(
  string ability key,
  battle_vector position,
  [number orientation in degrees],
  [number width in m]
)

Issues an order to the units associated with this unitcontroller to perform the supplied special ability on a specified position (can support orientation and width). Special abilities are listed in the unit_special_abilities table.

Parameters:

1

string

ability key

2

battle_vector

position

3

number

optional, default value=0

orientation in degrees

4

number

optional, default value=0

width in m

Returns:

  1. nil

unitcontroller:reset_ability_cooldown(string ability key)

Issues an order to the units associated with this unitcontroller to reset ability cooldown. Special abilities are listed in the unit_special_abilities table.

Parameters:

1

string

ability key

Returns:

  1. nil

unitcontroller:reset_ability_number_of_uses(string ability key)

Issues an order to the units associated with this unitcontroller to reset ability number of uses. Special abilities are listed in the unit_special_abilities table.

Parameters:

1

string

ability key

Returns:

  1. nil

unitcontroller:change_shot_type(string shot type)

Issues an order to the units associated with this unitcontroller to change shot type to the supplied value. Shot types are listed in the projectile_shot_type_enum table - the key from an entry in that table should be supplied to this function.

Parameters:

1

string

shot type

Returns:

  1. nil

unitcontroller:change_shot_type_q(string shot type)

Issues a queued order to the units associated with this unitcontroller to change shot type to the supplied value. Shot types are listed in the projectile_shot_type_enum table - the key from an entry in that table should be supplied to this function.
Queued orders start when the current order completes.

Parameters:

1

string

shot type

Returns:

  1. nil

unitcontroller:change_behaviour_active(string behaviour key, boolean is active)

Sets the supplied behaviour active or not for the units associated with this unitcontroller. Valid behaviours are 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 key

2

boolean

is active

Returns:

  1. nil

unitcontroller:melee(boolean enable melee mode)

Enables or disables melee mode for the units associated with this unitcontroller.

Parameters:

1

boolean

enable melee mode

Returns:

  1. nil

unitcontroller:fire_at_will(boolean enable)

Enables or disables fire-at-will behaviour for the units associated with this unitcontroller.

Parameters:

1

boolean

enable

Returns:

  1. nil
Back to top

Movement

unitcontroller:halt()
Instructs the units associated with this unitcontroller to halt.

Returns:

  1. nil

unitcontroller:withdraw()
Issues a withdraw order to the units associated with this unitcontroller, instructing them to leave the battlefield.

Returns:

  1. nil

unitcontroller:withdraw_q()
Issues a queued withdraw order to the units associated with this unitcontroller, instructing them to leave the battlefield. Queued orders start when the current order completes.

Returns:

  1. nil

unitcontroller:step_forward()
Instructs the units associated with this unitcontroller to take a step forwards.

Returns:

  1. nil

unitcontroller:step_backwards()
Instructs the units associated with this unitcontroller to take a step backwards.

Returns:

  1. nil

unitcontroller:increment_formation_width()
Instructs the units associated with this unitcontroller to increase their formation width.

Returns:

  1. nil

unitcontroller:decrement_formation_width()
Instructs the units associated with this unitcontroller to decrease their formation width.

Returns:

  1. nil

unitcontroller:change_move_speed(boolean move fast)

Instructs the units associated with this unitcontroller to move fast or slow. Supply true as a single argument to instruct the units to move quickly, or false to instruct them to move slowly.

Parameters:

1

boolean

move fast

Returns:

  1. nil

unitcontroller:change_group_formation(string formation name)

Issues an order to the units associated with this unitcontroller to adopt a new formation. Valid formations are set in the formations table.

Parameters:

1

string

formation name

Returns:

  1. nil

unitcontroller:change_group_formation_q(string formation name)

Issues a queued order to the units associated with this unitcontroller to adopt a new formation. Valid formations are set in the formations table.
Queued orders start when the current order completes.

Parameters:

1

string

formation name

Returns:

  1. nil

unitcontroller:goto_location(battle_vector position, [boolean move fast])

Issues an order to the units associated with this unitcontroller to move to a supplied location. No facing or width is specified.

Parameters:

1

battle_vector

position

2

boolean

optional, default value=false

move fast

Returns:

  1. nil

unitcontroller:goto_location_q(battle_vector position, [boolean move fast])

Issues a queued order to the units associated with this unitcontroller to move to a supplied location. No facing or width is specified. Queued orders start when the current order completes.

Parameters:

1

battle_vector

position

2

boolean

optional, default value=false

move fast

Returns:

  1. nil

unitcontroller:goto_location_angle_width(
  battle_vector position,
  number facing in degrees,
  number width in m,
  [boolean move fast]
)

Issues an order to the units associated with this unitcontroller to move to a supplied location and assume a position there facing a specified angle with a specified width.

Parameters:

1

battle_vector

position

2

number

facing in degrees

3

number

width in m

4

boolean

optional, default value=false

move fast

Returns:

  1. nil

unitcontroller:goto_location_angle_width_q(
  battle_vector position,
  number facing in degrees,
  number width in m,
  [boolean move fast]
)

Issues a queued order to the units associated with this unitcontroller to move to a supplied location and assume a position there facing a specified angle with a specified width. Queued orders start when the current order completes.

Parameters:

1

battle_vector

position

2

number

facing in degrees

3

number

width in m

4

boolean

optional, default value=false

move fast

Returns:

  1. nil

unitcontroller:teleport_to_location(battle_vector position, number facing in degrees, number width in m)

Immediately teleports units associated with this unitcontroller to a supplied location/angle/width.

Parameters:

1

battle_vector

position

2

number

facing in degrees

3

number

width in m

Returns:

  1. nil

unitcontroller:occupy_vehicle(battle_vehicle target, [boolean move fast])

Issues an order to the units associated with this unitcontroller to occupy a vehicle.

Parameters:

1

battle_vehicle

Target vehicle.

2

boolean

optional, default value=false

Move fast to building.

Returns:

  1. nil

unitcontroller:occupy_vehicle_q(battle_vehicle target, [boolean move fast])

Issues a queued order to the units associated with this unitcontroller to occupy a vehicle. Queued orders start when the current order completes.

Parameters:

1

battle_vehicle

Target vehicle.

2

boolean

optional, default value=false

Move fast to building.

Returns:

  1. nil

unitcontroller:occupy_zone(battle_vector target, [boolean move fast])

Issues an order to the units associated with this unitcontroller to occupy a battlefield zone. Battlefield zones tend to be defensive positions associated with a building, most commonly on settlement walls.

Parameters:

1

battle_vector

Target position.

2

boolean

optional, default value=false

Move fast to position.

Returns:

  1. nil

unitcontroller:occupy_zone_q(battle_vector target, [boolean move fast])

Issues a queued order to the units associated with this unitcontroller to occupy a battlefield zone. Battlefield zones tend to be defensive positions associated with a building, most commonly on settlement walls.
Queued orders start when the current order completes.

Parameters:

1

battle_vector

Target position.

2

boolean

optional, default value=false

Move fast to position.

Returns:

  1. nil

unitcontroller:rotate(number heading change, boolean move fast)

Issues an order to the units associated with this unitcontroller to rotate about their current heading by the supplied number of degrees.

Parameters:

1

number

Heading change in degrees.

2

boolean

Move quickly.

Returns:

  1. nil

unitcontroller:rotate_q(number heading change, boolean move fast)

Issues a queued order to the units associated with this unitcontroller to rotate about their current heading by the supplied number of degrees. Queued orders start when the current order completes.

Parameters:

1

number

Heading change in degrees.

2

boolean

Move quickly.

Returns:

  1. nil
Back to top

Attacking

unitcontroller:attack_unit(battle_unit target unit, [boolean use primary attack], [boolean move fast])

Issues an order to the units associated with this unitcontroller to attack an enemy unit.

Parameters:

1

battle_unit

Target unit to attack. This must be an enemy unit.

2

boolean

optional, default value=true

Use primary attack. Some units have more than one method of attacking - this flag allows the command to specify which to use.

3

boolean

optional, default value=false

Move fast/charge when attacking.

Returns:

  1. nil

unitcontroller:attack_unit_q(battle_unit target unit, [boolean use primary attack], [boolean move fast])

Issues a queued order to the units associated with this unitcontroller to attack an enemy unit. Queued orders start when the current order completes.

Parameters:

1

battle_unit

Target unit to attack. This must be an enemy unit.

2

boolean

optional, default value=true

Use primary attack. Some units have more than one method of attacking - this flag allows the command to specify which to use.

3

boolean

optional, default value=false

Move fast/charge when attacking.

Returns:

  1. nil

unitcontroller:attack_building(battle_building target, [number piece index], [boolean move fast])

Issues an order to the units associated with this unitcontroller to attack a specified building.

Parameters:

1

battle_building

Target building.

2

number

optional, default value=1

Index for building piece to target. The default value (1) targets the building as a whole.

3

boolean

optional, default value=false

Move fast/charge when attacking.

Returns:

  1. nil

unitcontroller:attack_building_q(battle_building target, [number piece index], [boolean move fast])

Issues a queued order to the units associated with this unitcontroller to attack a specified building. Queued orders start when the current order completes.

Parameters:

1

battle_building

Target building.

2

number

optional, default value=1

Index for building piece to target. The default value (1) targets the building as a whole.

3

boolean

optional, default value=false

Move fast/charge when attacking.

Returns:

  1. nil

unitcontroller:interact_with_deployable(
  battle_vector deployable position,
  [boolean move fast],
  [boolean melee attack]
)

Issues an order to the units associated with this unitcontroller to interact with a deployable object on the battlefield.

Parameters:

1

battle_vector

Position of deployable object.

2

boolean

optional, default value=false

Move fast to position.

3

boolean

optional, default value=false

Attack in melee or not.

Returns:

  1. nil

unitcontroller:interact_with_deployable_q(
  battle_vector deployable position,
  [boolean move fast],
  [boolean melee attack]
)

Issues an order to the units associated with this unitcontroller to interact with a deployable object on the battlefield. Queued orders start when the current order completes.

Parameters:

1

battle_vector

Position of deployable object.

2

boolean

optional, default value=false

Move fast to position.

3

boolean

optional, default value=false

Attack in melee or not.

Returns:

  1. nil

unitcontroller:besiege_building(battle_building target, [number piece index], [boolean move fast])

Issues an order to the units associated with this unitcontroller to besiege a building.

Parameters:

1

battle_building

Target building.

2

number

optional, default value=1

Index for building piece to target. The default value (1) targets the building as a whole.

3

boolean

optional, default value=false

Move fast/charge when attacking.

Returns:

  1. nil

unitcontroller:besiege_building_q(battle_building target, [number piece index], [boolean move fast])

Issues a queued order to the units associated with this unitcontroller to besiege a building. Queued orders start when the current order completes.

Parameters:

1

battle_building

Target building.

2

number

optional, default value=1

Index for building piece to target. The default value (1) targets the building as a whole.

3

boolean

optional, default value=false

Move fast/charge when attacking.

Returns:

  1. nil

unitcontroller:defend_building(battle_building target, [boolean move fast])

Issues an order to the units associated with this unitcontroller to defend a building.

Parameters:

1

battle_building

Target building.

2

boolean

optional, default value=false

Move fast/charge when defending.

Returns:

  1. nil

unitcontroller:defend_building_q(battle_building target, [boolean move fast])

Issues an order to the units associated with this unitcontroller to defend a building. Queued orders start when the current order completes.

Parameters:

1

battle_building

Target building.

2

boolean

optional, default value=false

Move fast/charge when defending.

Returns:

  1. nil

unitcontroller:leave_building()
Issues an order to the units associated with this unitcontroller to leave the building they're in.

Returns:

  1. nil

unitcontroller:attack_location(battle_vector position, boolean move fast)

Issues an order to the units associated with this unitcontroller to attack a location.

Parameters:

1

battle_vector

position

2

boolean

move fast

Returns:

  1. nil

unitcontroller:attack_location_q(battle_vector position, boolean move fast)

Issues a queued order to the units associated with this unitcontroller to attack a location. Queued orders start when the current order completes.

Parameters:

1

battle_vector

position

2

boolean

move fast

Returns:

  1. nil

unitcontroller:attack_line(battle_vector position a, battle_vector position b, boolean move fast)

Issues an order to the units associated with this unitcontroller to attack a line across the battlefield. The line is drawn between two supplied battle_vector positions.

Parameters:

1

battle_vector

position a

2

battle_vector

position b

3

boolean

move fast

Returns:

  1. nil

unitcontroller:attack_line_q(battle_vector position a, battle_vector position b, boolean move fast)

Issues a queued order to the units associated with this unitcontroller to attack a line across the battlefield. The line is drawn between two supplied battle_vector positions.
Queued orders start when the current order completes.

Parameters:

1

battle_vector

position a

2

battle_vector

position b

3

boolean

move fast

Returns:

  1. nil
Back to top

Miscellaneous

unitcontroller:set_matched_combat_chance(number chance)

Sets the chance of units associated with this unitcontroller performing matched combat when attacking. The chance should be supplied as a percentage, between 0 and 100. Specify a negative number to st the chance back to default.

Parameters:

1

number

chance

Returns:

  1. nil

unitcontroller:start_celebrating()
Instructs the units associated with this unitcontroller to start celebrating.

Returns:

  1. nil

unitcontroller:start_taunting()
Instructs the units associated with this unitcontroller to start taunting.

Returns:

  1. nil

unitcontroller:trigger_sound_vo()
Triggers a VO sound for units associated with this unitcontroller.
string sound event name

Returns:

  1. nil

unitcontroller:kill()
Kills all the units associated with this unitcontroller.

Returns:

  1. nil

unitcontroller:highlight()
Activates or deactivates a highlights on the units associated with this unitcontroller by showing tracker chevrons under their feet.
[opt=true] boolean highlight

Returns:

  1. nil

unitcontroller:add_animated_selection_proxy(
  battle_vector top left position,
  battle_vector top right position,
  battle_vector time,
  battle_vector remain time,
  boolean loop
)

Adds a static or animated selection proxy for the current unitcontroller. This draws out the formation on the terrain as if the player was right-clicking and dragging. If three arguments are supplied then a static proxy is drawn, whereas if five arguments are supplied an animated proxy is drawn.
The function returns a numeric id for the proxy effect, by which it may be later cancelled with unitcontroller:remove_animated_selection_proxy.

Parameters:

1

battle_vector

Top-left position of the selection proxy.

2

battle_vector

Top-right position of the selection proxy.

3

battle_vector

Time to animate if five arguments supplied, or time to remain if three arguments are supplied. Both time values should be supplied in seconds.

4

battle_vector

Time to remain in seconds after animation is completed. This should not be supplied if a static proxy is desired.

5

boolean

Loop the animated proxy. This should not be supplied if a static proxy is desired.

Returns:

  1. number proxy id

unitcontroller:remove_animated_selection_proxy(number proxy id)

Removes a static or animated selection proxy previously added with unitcontroller:add_animated_selection_proxy, by numeric id.

Parameters:

1

number

proxy id

Returns:

  1. nil

unitcontroller:change_current_walk_speed(number speed scalar)

Changes the walk speed for the units associated with this unitcontroller. This is only for use in cutscenes where the movement of units must match a certain speed for cinematic reasons and should not be used during live gameplay. Any speed set here will be reset to default when another order is issued. As such, a movement command and then this command should be issued in order to apply the movement speed modification.
The walk speed is specified as a scalar which is applied to the default walk speed. Therefore, supplying 2 as an argument would make the units walk twice as quickly as before. Beware of setting extreme values, as walk animations will quickly look unnatural if played too quickly or too slowly.

Parameters:

1

number

speed scalar

Returns:

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