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 Battle |
|
| Loaded in Frontend |
|
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.
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
-
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:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 5377
-
unitcontroller:add_all_units() -
Adds all units in the
battle_armythat this unitcontroller is assocated with, as a group.Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 5454
-
unitcontroller:add_units(...units) -
Adds one or more units to the unitcontroller. Multiple
battle_unitobjects may be specified as individual arguments.Parameters:
1
...One or more
battle_unitobjects.Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 5511
-
unitcontroller:add_group(...units) -
Adds one or more units to the unitcontroller as a group. Multiple
battle_unitobjects may be specified as individual arguments. Grouped units will move together.Parameters:
1
...One or more
battle_unitobjects.Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 5580
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:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 5749
-
unitcontroller:release_control() -
Releases control of all units controlled by this unitcontroller to either the player or the AI.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 5773
-
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_fearlessorunitcontroller:morale_behavior_routto reset the morale to game control.Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 5798
-
unitcontroller:morale_behavior_fearless() -
Sets the units associated with this unitcontroller to be fearless, meaning they can never rout.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 5820
-
unitcontroller:hide_unbreakable_in_ui(hide_in_uiboolean) -
Allows/Disables the UI to show that a unit is fearless/unbreakable.
Parameters:
1
If true the UI will ignore that the unit is fearless/unbreakable.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 5851
-
unitcontroller:morale_behavior_rout() -
Instructs the units associated with this unitcontroller to immediately rout.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 5885
-
unitcontroller:set_invincible([is invincibleboolean]) -
Sets the units associated with this unitcontroller to be invincible or not. Invincible units do not take damage.
Parameters:
1
optional, default value=true
is invincible
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 5915
-
unitcontroller:set_invisible_to_all(set invisibleboolean, [update uiboolean]) -
Makes all units associated with this unitcontroller invisible or not. Supply
trueas an argument to make units invisible, andfalseto make them visible again. Invisible units are still able to take part in the battle, unless also disabled withunitcontroller:change_enabled.
Thescript_unit:set_enabledcommand on thescript_unitinterface sets invisibility and enables/disables the unit in one function call, so consider calling that function instead of this.Parameters:
1
Set invisible.
2
optional, default value=true
Update UI with invisibility change. Supply
falseto 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 tofalseto suppress this behaviour if desired.Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 5941
-
unitcontroller:set_always_visible_to_all(set always visibleboolean) -
Sets the units associated with this unitcontroller to be exempt or not from the terrain visibility test.
Parameters:
1
set always visible
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6017
-
unitcontroller:set_always_visible_no_hidden_to_all(set always visibleboolean) -
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
set always visible
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6041
-
unitcontroller:set_always_visible_no_leave_battle_to_all(set always visibleboolean) -
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
set always visible
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6065
-
unitcontroller:set_always_visible_no_hidden_no_leave_battle_to_all(set always visibleboolean) -
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
set always visible
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6089
-
unitcontroller:change_enabled(enabledboolean) -
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.
Thescript_unit:set_enabledcommand on thescript_unitinterface sets invisibility and enables/disables the unit in one function call, so consider calling that function instead of this.Parameters:
1
enabled
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6132
-
unitcontroller:set_contributes_to_army_strength(contributesboolean) -
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_enabledis called - enabled units will contribute to army strength, whereas disabled units will not. This function may be called after callingunitcontroller:change_enabledto change this behaviour.Parameters:
1
contributes
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6172
-
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:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6211
-
unitcontroller:hide_unit_card() -
Tells the UI to hide the units cards associated with this unitcontroller.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6228
-
unitcontroller:change_fatigue_amount(fatigue levelnumber) -
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
Relative unary fatigue level.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6245
-
unitcontroller:perform_special_ability(ability keystring, [target unitbattle_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_abilitiestable. An optional unit target may be specified.Parameters:
1
ability key
2
optional, default value=nil
target unit
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6362
-
unitcontroller:perform_special_ability_q(ability keystring, [target unitbattle_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_abilitiestable. Queued orders start when the current order completes.
An optional unit target may be specified with the second argument.Parameters:
1
ability key
2
optional, default value=nil
target unit
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6372
-
unitcontroller:perform_special_ability_ground(ability key
string,position
battle_vector,orientation in degrees
[number],width in m
[number]
) -
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_abilitiestable.Parameters:
1
ability key
2
position
3
optional, default value=0
orientation in degrees
4
optional, default value=0
width in m
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6462
-
unitcontroller:reset_ability_cooldown(ability keystring) -
Issues an order to the units associated with this unitcontroller to reset ability cooldown. Special abilities are listed in the
unit_special_abilitiestable.Parameters:
1
ability key
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6541
-
unitcontroller:reset_ability_number_of_uses(ability keystring) -
Issues an order to the units associated with this unitcontroller to reset ability number of uses. Special abilities are listed in the
unit_special_abilitiestable.Parameters:
1
ability key
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6580
-
unitcontroller:change_shot_type(shot typestring) -
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_enumtable - the key from an entry in that table should be supplied to this function.Parameters:
1
shot type
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6619
-
unitcontroller:change_shot_type_q(shot typestring) -
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_enumtable - the key from an entry in that table should be supplied to this function.
Queued orders start when the current order completes.Parameters:
1
shot type
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6628
-
unitcontroller:change_behaviour_active(behaviour keystring,is activeboolean) -
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, andformed_attack.Parameters:
1
behaviour key
2
is active
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6684
-
unitcontroller:melee(enable melee modeboolean) -
Enables or disables melee mode for the units associated with this unitcontroller.
Parameters:
1
enable melee mode
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6705
-
unitcontroller:fire_at_will(enableboolean) -
Enables or disables fire-at-will behaviour for the units associated with this unitcontroller.
Parameters:
1
enable
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6727
-
unitcontroller:halt() -
Instructs the units associated with this unitcontroller to halt.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6751
-
unitcontroller:withdraw() -
Issues a withdraw order to the units associated with this unitcontroller, instructing them to leave the battlefield.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6767
-
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:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6775
-
unitcontroller:step_forward() -
Instructs the units associated with this unitcontroller to take a step forwards.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6803
-
unitcontroller:step_backwards() -
Instructs the units associated with this unitcontroller to take a step backwards.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6820
-
unitcontroller:increment_formation_width() -
Instructs the units associated with this unitcontroller to increase their formation width.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6837
-
unitcontroller:decrement_formation_width() -
Instructs the units associated with this unitcontroller to decrease their formation width.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6854
-
unitcontroller:change_move_speed(move fastboolean) -
Instructs the units associated with this unitcontroller to move fast or slow. Supply
trueas a single argument to instruct the units to move quickly, orfalseto instruct them to move slowly.Parameters:
1
move fast
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6871
-
unitcontroller:change_group_formation(formation namestring) -
Issues an order to the units associated with this unitcontroller to adopt a new formation. Valid formations are set in the
formationstable.Parameters:
1
formation name
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6893
-
unitcontroller:change_group_formation_q(formation namestring) -
Issues a queued order to the units associated with this unitcontroller to adopt a new formation. Valid formations are set in the
formationstable.
Queued orders start when the current order completes.Parameters:
1
formation name
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6902
-
unitcontroller:goto_location(positionbattle_vector, [move fastboolean]) -
Issues an order to the units associated with this unitcontroller to move to a supplied location. No facing or width is specified.
Parameters:
1
position
2
optional, default value=false
move fast
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6951
-
unitcontroller:goto_location_q(positionbattle_vector, [move fastboolean]) -
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
position
2
optional, default value=false
move fast
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6961
-
unitcontroller:goto_location_angle_width(position
battle_vector,facing in degrees
number,width in m
number,move fast
[boolean]
) -
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
position
2
facing in degrees
3
width in m
4
optional, default value=false
move fast
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7004
-
unitcontroller:goto_location_angle_width_q(position
battle_vector,facing in degrees
number,width in m
number,move fast
[boolean]
) -
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
position
2
facing in degrees
3
width in m
4
optional, default value=false
move fast
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7016
-
unitcontroller:teleport_to_location(positionbattle_vector,facing in degreesnumber,width in mnumber) -
Immediately teleports units associated with this unitcontroller to a supplied location/angle/width.
Parameters:
1
position
2
facing in degrees
3
width in m
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7067
-
unitcontroller:occupy_vehicle(targetbattle_vehicle, [move fastboolean]) -
Issues an order to the units associated with this unitcontroller to occupy a vehicle.
Parameters:
1
Target vehicle.
2
optional, default value=false
Move fast to building.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7098
-
unitcontroller:occupy_vehicle_q(targetbattle_vehicle, [move fastboolean]) -
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
Target vehicle.
2
optional, default value=false
Move fast to building.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7108
-
unitcontroller:occupy_zone(targetbattle_vector, [move fastboolean]) -
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
Target position.
2
optional, default value=false
Move fast to position.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7154
-
unitcontroller:occupy_zone_q(targetbattle_vector, [move fastboolean]) -
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
Target position.
2
optional, default value=false
Move fast to position.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7164
-
unitcontroller:rotate(heading changenumber,move fastboolean) -
Issues an order to the units associated with this unitcontroller to rotate about their current heading by the supplied number of degrees.
Parameters:
1
Heading change in degrees.
2
Move quickly.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7208
-
unitcontroller:rotate_q(heading changenumber,move fastboolean) -
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
Heading change in degrees.
2
Move quickly.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7218
-
unitcontroller:attack_unit(target unitbattle_unit, [use primary attackboolean], [move fastboolean]) -
Issues an order to the units associated with this unitcontroller to attack an enemy unit.
Parameters:
1
Target unit to attack. This must be an enemy unit.
2
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
optional, default value=false
Move fast/charge when attacking.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7264
-
unitcontroller:attack_unit_q(target unitbattle_unit, [use primary attackboolean], [move fastboolean]) -
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
Target unit to attack. This must be an enemy unit.
2
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
optional, default value=false
Move fast/charge when attacking.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7275
-
unitcontroller:attack_building(targetbattle_building, [piece indexnumber], [move fastboolean]) -
Issues an order to the units associated with this unitcontroller to attack a specified building.
Parameters:
1
Target building.
2
optional, default value=1
Index for building piece to target. The default value (1) targets the building as a whole.
3
optional, default value=false
Move fast/charge when attacking.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7332
-
unitcontroller:attack_building_q(targetbattle_building, [piece indexnumber], [move fastboolean]) -
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
Target building.
2
optional, default value=1
Index for building piece to target. The default value (1) targets the building as a whole.
3
optional, default value=false
Move fast/charge when attacking.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7343
-
unitcontroller:interact_with_deployable(deployable position
battle_vector,move fast
[boolean],melee attack
[boolean]
) -
Issues an order to the units associated with this unitcontroller to interact with a deployable object on the battlefield.
Parameters:
1
Position of deployable object.
2
optional, default value=false
Move fast to position.
3
optional, default value=false
Attack in melee or not.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7402
-
unitcontroller:interact_with_deployable_q(deployable position
battle_vector,move fast
[boolean],melee attack
[boolean]
) -
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
Position of deployable object.
2
optional, default value=false
Move fast to position.
3
optional, default value=false
Attack in melee or not.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7413
-
unitcontroller:besiege_building(targetbattle_building, [piece indexnumber], [move fastboolean]) -
Issues an order to the units associated with this unitcontroller to besiege a building.
Parameters:
1
Target building.
2
optional, default value=1
Index for building piece to target. The default value (1) targets the building as a whole.
3
optional, default value=false
Move fast/charge when attacking.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7460
-
unitcontroller:besiege_building_q(targetbattle_building, [piece indexnumber], [move fastboolean]) -
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
Target building.
2
optional, default value=1
Index for building piece to target. The default value (1) targets the building as a whole.
3
optional, default value=false
Move fast/charge when attacking.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7471
-
unitcontroller:defend_building(targetbattle_building, [move fastboolean]) -
Issues an order to the units associated with this unitcontroller to defend a building.
Parameters:
1
Target building.
2
optional, default value=false
Move fast/charge when defending.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7530
-
unitcontroller:defend_building_q(targetbattle_building, [move fastboolean]) -
Issues an order to the units associated with this unitcontroller to defend a building. Queued orders start when the current order completes.
Parameters:
1
Target building.
2
optional, default value=false
Move fast/charge when defending.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7540
-
unitcontroller:leave_building() -
Issues an order to the units associated with this unitcontroller to leave the building they're in.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7586
-
unitcontroller:attack_location(positionbattle_vector,move fastboolean) -
Issues an order to the units associated with this unitcontroller to attack a location.
Parameters:
1
position
2
move fast
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7604
-
unitcontroller:attack_location_q(positionbattle_vector,move fastboolean) -
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
position
2
move fast
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7614
-
unitcontroller:attack_line(position abattle_vector,position bbattle_vector,move fastboolean) -
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_vectorpositions.Parameters:
1
position a
2
position b
3
move fast
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7657
-
unitcontroller:attack_line_q(position abattle_vector,position bbattle_vector,move fastboolean) -
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_vectorpositions.
Queued orders start when the current order completes.Parameters:
1
position a
2
position b
3
move fast
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7668
-
unitcontroller:set_matched_combat_chance(chancenumber) -
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
chance
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7722
-
unitcontroller:start_celebrating() -
Instructs the units associated with this unitcontroller to start celebrating.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7745
-
unitcontroller:start_taunting() -
Instructs the units associated with this unitcontroller to start taunting.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7759
-
unitcontroller:trigger_sound_vo() -
Triggers a VO sound for units associated with this unitcontroller.
stringsound event nameReturns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7773
-
unitcontroller:kill() -
Kills all the units associated with this unitcontroller.
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7798
-
unitcontroller:highlight() -
Activates or deactivates a highlights on the units associated with this unitcontroller by showing tracker chevrons under their feet.
[opt=true]booleanhighlightReturns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7814
-
unitcontroller:add_animated_selection_proxy(top left position
battle_vector,top right position
battle_vector,time
battle_vector,remain time
battle_vector,loop
boolean
) -
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 withunitcontroller:remove_animated_selection_proxy.Parameters:
1
Top-left position of the selection proxy.
2
Top-right position of the selection proxy.
3
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
Time to remain in seconds after animation is completed. This should not be supplied if a static proxy is desired.
5
Loop the animated proxy. This should not be supplied if a static proxy is desired.
Returns:
number
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7834
-
unitcontroller:remove_animated_selection_proxy(proxy idnumber) -
Removes a static or animated selection proxy previously added with
unitcontroller:add_animated_selection_proxy, by numeric id.Parameters:
1
proxy id
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7910
-
unitcontroller:change_current_walk_speed(speed scalarnumber) -
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, supplying2as 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
speed scalar
Returns:
nil
defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7928