Battle Manager

The battle_manager object is a lua wrapper for the battle object provided by the game code. The battle_manager provides access to all functionality provided by battle as well as numerous enhancements and extensions.

Any calls made to a battle_manager which aren't recognised as functions are passed to the underlying battle object. In this way, the battle_manager object automatically provides the full interface of a battle object.

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

Creation

battle_manager:new()
Creates and returns a battle_manager object. Only one battle_manager object may be created in a session - attempting to create a second just returns the first.

Returns:

  1. battle_manager

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 109

Back to top

Console Output

battle_manager:out(string output)
Prints a string to the console for debug purposes. The string is prepended with a timestamp.

Parameters:

1

string

output

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 317

Back to top

Scriptunits

The battle manager automatically constructs a script_unit object for each unit in the battle, and a script_units collection for each army. The script_units collection objects can be accessed with the functions described below.

battle_manager:get_scriptunits_for_army(
  number alliance id,
  number army id,
  [number reinforcement units id]
)

Gets an automatically-generated script_units collection object containing a script_unit for every unit in the specified army. If no scriptunits collection can be found for the supplied alliance/army/optional reinforcement index then false is returned.

Parameters:

1

number

Alliance id. Alliances are specified by 1-based index, currently either 1 or 2.

2

number

Army id, specified by 1-based index, so a value of 1 corresponds to the first army in the specified alliance.

3

number

optional, default value=false

Specifies a reinforcing units to return the scriptunits for. If this argument is omitted, the scriptunits collection corresponding to the main (non-reinforcing) army is returned. Otherwise, the scriptunits collection corresponding to the specified reinforcing units is returned. If no reinforcing army could be found then a script error is thrown.

Returns:

  1. script_units scriptunits collection, or false if no alliance/army found.

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 338

battle_manager:num_alliances()
Returns the number of alliances in the battle. Currently there should always be two alliances.

Returns:

  1. number alliances

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 394

battle_manager:num_armies_in_alliance(number alliance id)

Returns the number of armies in the specified alliance. The alliance is specified by index, which should currently either be 1 or 2.

Parameters:

1

number

alliance id

Returns:

  1. number army

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 402

battle_manager:num_reinforcing_armies_for_army_in_alliance(number alliance id, number army id)

Returns the number of reinforcing armies for an army in the specified alliance and army. The alliance and army are specified by index (indexes are always 1-based).

Parameters:

1

number

alliance id

2

number

army id

Returns:

  1. number num reinforcing armies

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 421

battle_manager:get_scriptunits_for_local_players_army()
Returns the automatically-generated script_units collection object, containing a script_unit for every unit, corresponding to the local player's army.

Returns:

  1. script_units scriptunits collection

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 451

battle_manager:get_scriptunits_for_main_enemy_army_to_local_player()
Returns the automatically-generated script_units collection object, containing a script_unit for every unit, for the local player's primary enemy army.

Returns:

  1. script_units scriptunits collection

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 459

battle_manager:get_scriptunits_for_main_attacker()
Returns the automatically-generated script_units collection object, containing a script_unit for every unit, for the primary attacking army.

Returns:

  1. script_units scriptunits collection

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 467

battle_manager:get_scriptunits_for_main_defender()
Returns the automatically-generated script_units collection object, containing a script_unit for every unit, for the primary defending army.

Returns:

  1. script_units scriptunits collection

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 476

battle_manager:get_scriptunit_for_unit(battle_unit unit)

Returns a previously-created script_unit for the supplied battle_unit. If no matching script_unit can be found then nil is returned.

Parameters:

1

battle_unit

unit

Returns:

  1. script_unit sunit

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 517

Back to top

Miscellaneous Querying

battle_manager:get_battle_ui_manager()
Retrieves a handle to a battle_ui_manager object from the battle manager. One is created if it hasn't been created before.

Returns:

  1. battle_ui_manager

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 611

battle_manager:get_battle_folder()
Returns the path to the battle script folder.

Returns:

  1. string path

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 624

battle_manager:get_origin()
Returns a vector position at the world origin.

Returns:

  1. vector origin

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 632

battle_manager:ui_component()
A wrapper for ui_component. Searches the UI heirarchy and returns a uicomponent object with the supplied name. This overrides the base ui_component function provided by the underlying battle object, which returns a component object (which must be converted to be a UIComponent before use).

Returns:

  1. uicomponent ui component, or false if not found

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 640

battle_manager:get_campaign_key()
Returns the key of the campaign this battle was launched from. If this battle was not launched from a campaign then a blank string is returned.

Returns:

  1. string campaign key

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 668

battle_manager:is_any_cutscene_running()
Returns true if any cutscene object is currently showing a cutscene.

Returns:

  1. boolean is cutscene running

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 686

battle_manager:is_any_unit_selected()
Queries the UI and returns true if any unit cards are selected.

Returns:

  1. boolean any unit selected

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 704

battle_manager:num_units_selected()
Returns the number of unit cards that are selected.

Returns:

  1. number number of units selected

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 733

battle_manager:are_all_units_selected()
Queries the UI and returns true if all unit cards are selected.

Returns:

  1. boolean all units selected

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 764

battle_manager:get_player_alliance_num()
Returns the alliance number of the player's alliance.

Returns:

  1. integer alliance number

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 790

battle_manager:get_non_player_alliance_num()
Returns the alliance number of the non-player alliance.

Returns:

  1. integer alliance number

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 798

battle_manager:get_player_alliance()
Returns the local player's alliance object.

Returns:

  1. alliance player alliance

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 810

battle_manager:get_non_player_alliance()
Returns the alliance object of the local player's enemy.

Returns:

  1. alliance enemy alliance

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 818

battle_manager:player_is_attacker()
Returns true if the local player is the attacker in the battle.

Returns:

  1. boolean player is attacker

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 826

battle_manager:get_player_army()
Returns the local player's army object.

Returns:

  1. army player's army

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 834

battle_manager:get_first_non_player_army()
Returns the first army of the enemy alliance to the local player.

Returns:

  1. army enemy army

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 842

battle_manager:get_general(collection unit collection)
Returns the first commanding battle_unit found in the supplied units collection. Supported collection types are battle_units, battle_army and script_units. If no commanding unit is found then false is returned.

Parameters:

1

collection

Unit collection object.

Returns:

  1. battle_unit commanding unit

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 850

battle_manager:assault_equipment_exists([string key])

Returns true if any assault equipment with the optional supplied key exists on the battlefield. If no key is supplied then the function returns true if any assault equipment exists.

Parameters:

1

string

optional, default value=nil

Assault equipment key, from the battlefield_siege_vehicles table. If no key is supplied then the function returns true if any assault equipment is present.

Returns:

  1. boolean equipment exists

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 878

battle_manager:get_closest_vehicle(battle_vector position)

Returns the closest siege vehicle to the supplied position. If no assault equipment is present on the map then nil is returned.

Parameters:

1

battle_vector

position

Returns:

  1. battle_vehicle closest vehicle

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 906

battle_manager:is_minor_settlement_battle()
Returns true if the battle type is settlement_unfortified, indicating a minor settlement battle.

Returns:

  1. boolean is minor settlement battle

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 934

battle_manager:is_major_settlement_battle()
Returns true if the battle type is settlement_standard, indicating a major settlement battle.

Returns:

  1. boolean is major settlement battle

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 942

Back to top

Scripted Tours

battle_manager:load_scripted_tours()
Loads all scripted tour scripts. Calling this allows battle scripted tours to work.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 963

Back to top

Random Numbers

battle_manager:random_number([number max value])
Returns a random number. If no max value is supplied then the value returned is a float between 0 and 1. If a max value is supplied, then the value returned is an integer value from 1 to the max value. This is safe to use in multiplayer.

Parameters:

1

number

optional, default value=nil

max value

Returns:

  1. random number

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 984

battle_manager:random_sort(table numerically-indexed table)

Randomly sorts a numerically-indexed table. This is safe to use in multiplayer, but will destroy the supplied table. It is faster than battle_manager:random_sort_copy.
Note that records in this table that are not arranged in an ascending numerical index will be lost.
Note also that the supplied table is overwritten with the randomly-sorted table, which is also returned as a return value.

Parameters:

1

table

Numerically-indexed table. This will be overwritten by the returned, randomly-sorted table.

Returns:

  1. table randomly-sorted table

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 998

battle_manager:random_sort_copy(table numerically-indexed table)

Randomly sorts a numerically-indexed table. This is safe to use in multiplayer, and will preserve the original table, but it is marginally slower than battle_manager:random_sort.
Note that records in the source table that are not arranged in an ascending numerical index will not be copied (they will not be deleted, however).

Parameters:

1

table

Numerically-indexed table.

Returns:

  1. table randomly-sorted table

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1027

Back to top

Battle Startup and Phases

As a battle loads and progresses it passes through phases, such as "Deployment", "Deployed" (main battle phase), "VictoryCountdown" and "Complete". The script gets notified as phase changes occur

battle_manager:setup_battle(function deployment end callback)
Packaged function to set up a scripted battle on startup, and register a function to be called when the deployment phase ends (i.e. when battle starts). setup_battle will suppress a variety of unit sounds and steal input focus until the combat phase begins.

Parameters:

1

function

deployment end callback

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1057

battle_manager:register_phase_change_callback(string phase name, function callback)
Registers a function to be called when a specified phase change occurs. Phase change notifications are sent to the script by the game when the battle changes phases, for example from "Deployment" to "Deployed" and on to "VictoryCountdown" and "Complete". The battle manager writes output to the console whenever a phase change occurs, regardless of whether any callback has been registered for it. A script event, ScriptEventBattlePhaseChanged, is also triggered when a phase change occurs, and supplies the name of the new phase as a context string.
This wraps the underlying functionality provided by battle:register_battle_phase_handler. See that function's documentation for a list of phase change events that may be listened for.

Parameters:

1

string

phase name

2

function

callback

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1088

battle_manager:get_current_phase_name()
Returns the name of the current battle phase.

Returns:

  1. string phase name

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1113

battle_manager:is_deployment_phase()
Returns whether the battle is currently in deployment phase.

Returns:

  1. boolean is deployment phase

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1121

battle_manager:is_conflict_phase()
Returns whether the battle is currently in the conflict phase.

Returns:

  1. boolean is conflict phase

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1129

battle_manager:is_victory_countdown_phase()
Returns whether the battle is currently in the victory countdown phase.

Returns:

  1. boolean is victory countdown phase

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1137

battle_manager:winner_alliance_id()
Returns the winning alliance id. Only makes sense after the battle is completed.( I.e. in `Complete` phase)

Returns:

  1. number winning alliance id

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1162

Back to top

Unit Selection Callbacks

battle_manager:register_unit_selection_callback(unit subject unit, function callback)
Registers a function to be called when a specified unit is selected by the player.

Parameters:

1

unit

subject unit

2

function

callback

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1179

battle_manager:unregister_unit_selection_callback(unit subject unit)
Unregisters a function registered with battle_manager:register_unit_selection_callback.

Parameters:

1

unit

subject unit

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1207

Back to top

Command Handler Callbacks

battle_manager:register_command_handler_callback(string command, function callback, [string callback name])
Registers a function to be called when a command event is issued by the game. The function will be called with the command handler context supplied as a single argument, which can be queried for further information depending upon the command.
This wraps the underlying functionality provided by battle:register_command_handler. See the documentation of that function for more information about what command events can be listened for, and what contextual information those events provide.

Parameters:

1

string

Command name to listen for.

2

function

Callback to call when the command is triggered by the game.

3

string

optional, default value=nil

Optional name by which this callback handler can be removed.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1247

battle_manager:unregister_command_handler_callback(string command name, string callback name)
Unregisters a callback function registered with battle_manager:register_command_handler_callback. The callback function is specified by the command name and callback name specified when setting the callback up.

Parameters:

1

string

command name

2

string

callback name

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1301

Back to top

Input Handler Callbacks

battle_manager:register_input_handler_callback(string input, function callback, [string callback name])
Registers a function to be called when an input event is issued by the game. This wraps the underlying functionality provided by battle:register_input_handler. See the documentation of that function for more information about what input events can be listened for.

Parameters:

1

string

Input name to listen for.

2

function

Callback to call when the input is triggered by the game.

3

string

optional, default value=nil

Optional name by which this input handler can be removed.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1364

battle_manager:unregister_input_handler_callback(string command name, string callback name)
Unregisters a callback function registered with battle_manager:register_input_handler_callback. The callback function is specified by the input name and callback name specified when setting the callback up.

Parameters:

1

string

command name

2

string

callback name

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1417

Back to top

ESC Key Callback Queue

The key_steal_manager now does the work involved with stealing keys and handling them being pressed, but these pass-through functions are provided on the battle manager for ease of use.

battle_manager:steal_escape_key_with_callback(
  string callback name,
  function callback,
  [boolean is persistent]
)

Steals the escape key if it wasn't stolen before, and registers a callback to be called if the player presses it. The callback entry must be registered with a unique string name, by which it may be cancelled later if desired.
Multiple escape key callbacks may be registered at one time, although only the most recently-registered callback is notified when the ESC key is pressed. Once an ESC key callback is called it is removed from the list, and the next ESC key press causes the next most recent callback to be notified, and so-on.
This function maps to the underlying key_steal_manager:steal_escape_key_with_callback function which actually does the work now.

Parameters:

1

string

callback name

2

function

callback

3

boolean

optional, default value=false

Key should remain stolen after callback is first called.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1482

battle_manager:release_escape_key_with_callback(string callback name to cancel)
Cancels an escape key callback registered with battle_manager:steal_escape_key_with_callback by name.
This function maps to the underlying key_steal_manager:release_escape_key_with_callback function which actually does the work now.

Parameters:

1

string

callback name to cancel

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1494

Back to top

Victory Callbacks

battle_manager:setup_victory_callback(function callback to call)
Establishes a function to be called when the battle enters VictoryCountdown phase i.e. someone has won. This function also sets the duration of the victory countdown to infinite, meaning the battle will never end until battle_manager:end_battle is called. This allows calling scripts to do things like set up an outro cutscene or play some advice that wouldn't fit into the standard victory countdown duration (10 seconds).

Parameters:

1

function

callback to call

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1514

battle_manager:end_battle()
Causes a battle to immediately end when it enters the VictoryCountdown phase, or to immediately end if it is already in that phase. This function is most commonly used to end a battle that has entered the VictoryCountdown phase after battle_manager:setup_victory_callback has been called.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1528

battle_manager:register_results_callbacks(
  function player victory callback,
  function player defeat callback
)
Old-style battle-ending handlers. These can still be used but won't get called until the battle results screen is shown. Registers player victory and player defeat callbacks to be called at the end of the battle.

Parameters:

1

function

player victory callback

2

function

player defeat callback

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1535

Back to top

Time Manipulation

battle_manager:slow_game_over_time(
  number start game speed,
  number target game speed,
  number duration in ms,
  number steps
)
Changes game speed from one value to another over a total time (note that this will be elongated by the slowing action) over a given number of steps. Note that the script engine only updates once every 1/10th of a second so specifying steps of less than this will have weird results. Speeds are specified as multiples of normal game speed, so a value of 2 would be twice normal speed, 0.5 would be half, and so on.

Parameters:

1

number

start game speed

2

number

target game speed

3

number

duration in ms

4

number

steps

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1588

battle_manager:stop_slow_game_over_time()
Cancels any running processes started by battle_manager:slow_game_over_time.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1632

battle_manager:pause()
Pauses the battle.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1639

battle_manager:modify_battle_speed(number speed, [boolean silent])

Wrapper for the battle:modify_battle_speed function, that prints output and notifies other systems that the model tick speed has changed.

Parameters:

1

number

New battle speed, as a unary proportion of normal speed. Supply a value of 1 to set the battle speed to normal, 0.5 for half speed, 0 for pause etc.

2

boolean

optional, default value=false

Silent flag - do not print output.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1646

Back to top

Timer Callbacks

Timer functionality - the ability for scripts to say that a function should be called after a certain interval (e.g. a second) - is provided by the timer_manager object. The functions in this section provide a pass-through interface to the equivalent functions on the timer manager.

Battle model time is measured in milliseconds throughout.

battle_manager:callback(function callback to call, number interval, [string name])
Calls the supplied function after the supplied interval in seconds using a timer synchronised to the battle model. A string name for the callback may optionally be provided to allow the callback to be cancelled later.
This function call is passed through to timer_manager:callback - this battle_manager alias is provided purely for convenience.

Parameters:

1

function

Callback to call.

2

number

Interval in milliseconds after to which to call the callback.

3

string

optional, default value=nil

Callback name. If supplied, this callback can be cancelled at a later time (before it triggers) with battle_manager:remove_process or battle_manager:remove_callback.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1709

battle_manager:repeat_callback(function callback to call, number time, [string name])

Calls the supplied function repeatedly after the supplied period in seconds using a timer synchronised to the battle model. A string name for the callback may optionally be provided to allow the callback to be cancelled. Cancelling the callback is the only method to stop a repeat callback, once started.
This function call is passed through to timer_manager:callback - this battle_manager alias is provided purely for convenience.

Parameters:

1

function

Callback to call.

2

number

Time in milliseconds after to which to call the callback, repeatedly. The callback will be called each time this interval elapses.

3

string

optional, default value=nil

Callback name. If supplied, this callback can be cancelled at a later time with battle_manager:remove_callback.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1720

battle_manager:remove_callback(string name)

Removes a callback previously added with battle_manager:callback or battle_manager:repeat_callback by name. All callbacks with a name matching that supplied will be cancelled and removed.
This function call is passed through to timer_manager:remove_callback - this battle_manager alias is provided purely for convenience. See also battle_manager:remove_process, which also removes any watches with the specified name.

Parameters:

1

string

Name of callback to remove.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1731

battle_manager:real_callback(function callback, number interval, [string name])

Adds a real callback to be called after the supplied interval has elapsed. Real timers are synchronised to UI updates, not to the game model - see Real Timers for more information.
This function call is passed through to timer_manager:real_callback - this battle_manager alias is provided purely for convenience.

Parameters:

1

function

Callback to call.

2

number

Interval after which to call the callback, in milliseconds.

3

string

optional, default value=nil

Callback name, by which it may be later removed with battle_manager:remove_real_callback. If omitted the callback may not be cancelled.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1740

battle_manager:repeat_real_callback(function callback, number interval, [string name])

Adds a repeating real callback to be called each time the supplied interval elapses. Real timers are synchronised to UI updates, not to the game model - see Real Timers for more information.
This function call is passed through to timer_manager:repeat_real_callback - this battle_manager alias is provided purely for convenience.

Parameters:

1

function

Callback to call.

2

number

Repeating interval after which to call the callback, in milliseconds.

3

string

optional, default value=nil

Callback name, by which it may be later removed with battle_manager:remove_real_callback. If omitted the repeating callback may not be cancelled.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1751

battle_manager:remove_real_callback(string name)

Removes a real callback previously added with battle_manager:real_callback or battle_manager:repeat_real_callback by name. All callbacks with a name matching that supplied will be cancelled and removed.
This function call is passed through to timer_manager:remove_real_callback - this battle_manager alias is provided purely for convenience.

Parameters:

1

string

Name of callback to remove.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1762

Back to top

Watches

A watch is a process that continually polls a supplied condition. When it is true, the watch process waits for a supplied period, and then calls a supplied target function. Watches provide battle scripts with a fire-and-forget method of polling the state of the battle, and of being notified when that state changes in some crucial way.

battle_manager:watch(
  function condition,
  function condition,
  number wait time,
  function target callback,
  [string watch name]
)
Establishes a new watch. A supplied condition function is repeated tested and, when it returns true, a supplied target function is called. A wait period between the condition being met and the target being called must also be specified. A name for the watch may optionally be specified to allow other scripts to cancel it.
The condition must be a function that returns a value - when that value is true (or evaluates to true) then the watch condition is met. The watch then waits the supplied time offset, which is specified in ms as the second parameter, before calling the callback supplied in the third parameter.

Parameters:

1

function

condition

2

function

Condition. Must be a function that returns a value. When the returned value is true, or evaluates to true, then the watch condition is met.

3

number

Time in ms that the watch waits once the condition is met before triggering the target callback

4

function

Target callback

5

string

optional, default value=nil

Name for this watch process. Giving a watch a name allows it to be stopped/cancelled with battle_manager:remove_process.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1787

battle_manager:remove_process(string name)
Stops and removes any watch OR callback with the supplied name. Returns true if any were found, false otherwise.

Parameters:

1

string

name

Returns:

  1. boolean any removed

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1962

battle_manager:remove_process_from_watch_list(string name)
Stops and removes any watch with the supplied name. Returns true if any were found, false otherwise. Best practice is to use remove_process instead of this.

Parameters:

1

string

name

Returns:

  1. boolean any removed

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1974

battle_manager:print_watch_list()
Debug command to dump the watch list to the console.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2002

battle_manager:clear_watches_and_callbacks()
Cancels all running watches and callbacks. It's highly recommend to not call this except for debug purposes (and rarely, even then).

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2017

battle_manager:set_load_balancing(boolean enable load balancing)
By default the watch system performs load balancing, where it tries to stagger its running watches so they don't all process on the same tick. If this is causes problems for any reason it can be disabled with set_load_balancing. Supply a boolean parameter to enable or disable load balancing.

Parameters:

1

boolean

enable load balancing

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2032

Back to top

Advisor Queue

The advisor queueing functionality allows the calling script to queue advisor messages so they don't clumsily collide with each other during playback.

battle_manager:queue_advisor(
  string advice key,
  [number forced duration],
  [boolean debug],
  [function start callback],
  [number start callback wait],
  [playback condition]
)
Enqueues a line of advice for delivery to the player. If there is no other advice playing, or nothing is blocking the advisor system, then the advice gets delivered immediately. Otherwise, the supplied advice will be queued and shown at an appropriate time.
The function must be supplied an advice key from the advice_levels/advice_threads tables as its first parameter, unless the advisor entry is set to be debug (see below).
The third parameter

Parameters:

1

string

Advice key from the advice_levels/advice_threads table.

If the advice entry is set to be debug (see third parameter) the text supplied here will instead be shown directly in the advisor window (debug only)

2

number

optional, default value=0

Forced duration in ms. This is a period that this advice must play for before another item of advice is allowed to start. By default, items of advice will only remain queued while the active advice is actually audibly playing, but by setting a duration the active advice can be held on-screen for longer than the length of its associated soundfile (unless it is closed by the player). This is useful during development to hold advice on-screen when no soundfile yet exists, and also for tutorial scripts which often wish to ensure that an item of advice is shown on-screen for a certain duration.

3

boolean

optional, default value=false

Sets whether the advice line is debug. If set to true, the text supplied as the first parameter is displayed in the advisor window as-is, without using it as a lookup key in the advice_levels table.

4

function

optional, default value=nil

Start callback. If a function is supplied here it is called when the advice is actually played.

5

number

optional, default value=0

Start callback wait period in ms. If a duration is specified it causes a delay between the advice being played and the start callback being called.

6

playback

optional, default value=nil

Playback condition. If specified, it compels the advisor system to check this condition immediately before playing the advisor entry to decide whether to actually proceed. This must be supplied as a function block that returns a result. If this result evaluates to true, the advice is played.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2056

battle_manager:stop_advisor_queue([boolean close advisor], [boolean force immediate stop])
Cancels any running advice, and clears any subsequent advice that may be queued.

Parameters:

1

boolean

optional, default value=false

Closes the advisor if it's open

2

boolean

optional, default value=false

Forces immediate stop. By default the stopping action takes a short amount of time - the game seems happier with this. If set to true, this flag bypasses this behaviour. User beware.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2245

battle_manager:advice_cease()
Stops the advisor queue and prevents any more advice from being queued. The advice system will only subsequently restart if battle_manager:advice_resume is called.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2270

battle_manager:advice_resume()
Allows advice to resume after battle_manager:advice_cease called.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2279

battle_manager:stop_advice_on_battle_end()
Establishes a listener which stops the advice system as soon as the battle results panel appears.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2286

battle_manager:set_close_queue_advice([boolean value])
Sets whether the advisor system should close the advisor panel once an item of advice has finished playing. By default this is set to false, so use this function to turn this behaviour on.

Parameters:

1

boolean

optional, default value=true

value

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2308

battle_manager:has_advice_played_this_battle()
Returns true if any advice has played in this battle session

Returns:

  1. boolean advice has played

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2320

battle_manager:modify_advice([boolean show button], [boolean show highlight])
Modifies the advisor panel to show the progress/close button in the bottom right, and also to highlight this button with an animated ring around it. This setting will persist across subsequent items of advice in a battle session until modified again.

Parameters:

1

boolean

optional, default value=false

Show progress/close button.

2

boolean

optional, default value=false

Show highlight on close button.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2328

Back to top

Progress on Advice Actions

battle_manager:progress_on_advice_dismissed(
  function callback to call,
  [number delay],
  [boolean highlight on finish]
)
Calls a supplied callback when the advisor panel is closed for any reason.

Parameters:

1

function

Callback to call.

2

number

optional, default value=0

Delay in ms after the adisor closes before calling the callback.

3

boolean

optional, default value=false

Highlight the advisor close button upon finishing the currently-playing advice. This is useful for script that knows the advisor is playing, wants to highlight the close button when it finishes and be notified of when the player closes the advisor in any case.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2364

battle_manager:cancel_progress_on_advice_dismissed()
Cancels a running battle_manager:progress_on_advice_dismissed process.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2481

battle_manager:progress_on_advice_dismissed_immediate_highlight()
Causes a battle_manager:progress_on_advice_dismissed process that is listening for the advice to finish so that it can highlight the close button (i.e. the third parameter was set to true) to cancel this listener.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2490

battle_manager:progress_on_advice_finished(
  string name,
  function callback to call,
  [number delay],
  [number playtime]
)

Calls a supplied callback when the advisor has stopped playing an audible sound.

Parameters:

1

string

Name for this progress on advice finished process, by which it may be later cancelled if necessary.

2

function

Callback to call.

3

number

optional, default value=0

Delay in ms after the adisor stops before calling the callback.

4

number

optional, default value=5000

Playing time for the advice item. This sets a time after which battle_manager:progress_on_advice_finished will begin to actively poll whether the advice is still playing, as well as listening for the finish event. This is useful as it ensure this function works even during development when the advisor sound files have not yet been recorded.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2497

battle_manager:cancel_progress_on_advice_finished(string name)

Cancels a running battle_manager:progress_on_advice_finished process.

Parameters:

1

string

Name of the progress on advice finished process to cancel.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2569

battle_manager:progress_on_sound_effect_finished(
  string name,
  battle_sound_effect sound effect,
  function callback,
  [number post-finish delay],
  [number minimum playtime]
)

Calls a supplied function when a supplied sound effect has finished playing. A post-completion delay and a minimum play time - useful during development when sound effects (particularly voiceover) may not yet have been recorded - may also be supplied.

Parameters:

1

string

Name for this progress-on-sound-effect-finished process. The process may be cancelled by the name supplied here by calling battle_manager:cancel_progress_on_sound_effect_finished before the callback is called.

2

battle_sound_effect

Sound effect to monitor.

3

function

Callback to call.

4

number

optional, default value=0

Delay in ms to wait after the sound effect has finished before calling the callback.

5

number

optional, default value=0

Minimum playtime for the sound effect, in ms. If a positive number is supplied here, the process will not begin to monitor until after that period has elapsed.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2583

battle_manager:cancel_progress_on_sound_effect_finished(string name)

Cancels a process started by battle_manager:progress_on_sound_effect_finished with the supplied name.

Parameters:

1

string

name

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2636

Back to top

Objectives

Upon creation, the battle manager automatically creates an objectives manager object which it stores internally. Most of these functions provide a passthrough interface to the most commonly-used functions on the objectives manager. See the documentation on the objectives_manager page for more details.

Note that battle_manager:set_locatable_objective is native to the battle manager and is not related to the objectives manager.

battle_manager:set_objective(string objective key, [number param a], [number param b])

Sets up a scripted objective for the player, which appears in the scripted objectives panel. This objective can then be updated, removed, or marked as completed or failed by the script at a later time.
A key to the scripted_objectives table must be supplied with set_objective, and optionally one or two numeric parameters to show some running count related to the objective. To update these parameter values later, set_objective may be re-called with the same objective key and updated values.
This function passes its arguments through objectives_manager:set_objective on the objectives manager - see the documentation on that function for more information.

Parameters:

1

string

Objective key, from the scripted_objectives table.

2

number

optional, default value=nil] number param a, First numeric objective parameter. If set, the objective will be presented to the player in the form [objective text]: [param a

First numeric objective parameter. If set, the objective will be presented to the player in the form [objective text]: [param a]. Useful for showing a running count of something related to the objective.

3

number

optional, default value=nil] number param b, Second numeric objective parameter. A value for the first must be set if this is used. If set, the objective will be presented to the player in the form [objective text]: [param a] / [param b

Second numeric objective parameter. A value for the first must be set if this is used. If set, the objective will be presented to the player in the form [objective text]: [param a] / [param b]. Useful for showing a running count of something related to the objective.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2660

battle_manager:set_objective_with_leader(
  string objective key,
  [number param a],
  [number param b],
  [function callback]
)

Sets up a scripted objective for the player which appears in the scripted objectives panel, with a topic_leader. This objective can then be updated, removed, or marked as completed or failed by the script at a later time.
A key to the scripted_objectives table must be supplied with set_objective, and optionally one or two numeric parameters to show some running count related to the objective. To update these parameter values later, set_objective may be re-called with the same objective key and updated values.
This function passes its arguments through objectives_manager:set_objective_with_leader on the objectives manager - see the documentation on that function for more information.

Parameters:

1

string

Objective key, from the scripted_objectives table.

2

number

optional, default value=nil] number param a, First numeric objective parameter. If set, the objective will be presented to the player in the form [objective text]: [param a

First numeric objective parameter. If set, the objective will be presented to the player in the form [objective text]: [param a]. Useful for showing a running count of something related to the objective.

3

number

optional, default value=nil] number param b, Second numeric objective parameter. A value for the first must be set if this is used. If set, the objective will be presented to the player in the form [objective text]: [param a] / [param b

Second numeric objective parameter. A value for the first must be set if this is used. If set, the objective will be presented to the player in the form [objective text]: [param a] / [param b]. Useful for showing a running count of something related to the objective.

4

function

optional, default value=nil

Optional callback to call when the objective is shown.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2672

battle_manager:complete_objective(string objective key)

Marks a scripted objective as completed for the player to see. Note that it will remain on the scripted objectives panel until removed with battle_manager:remove_objective. This function passes its arguments through objectives_manager:complete_objective on the objectives manager - see the documentation on that function for more information.
Note also that is possible to mark an objective as complete before it has been registered with battle_manager:set_objective - in this case, it is marked as complete as soon as battle_manager:set_objective is called.

Parameters:

1

string

Objective key, from the scripted_objectives table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2685

battle_manager:fail_objective(string objective key)

Marks a scripted objective as failed for the player to see. Note that it will remain on the scripted objectives panel until removed with battle_manager:remove_objective. This function passes its arguments through objectives_manager:fail_objective on the objectives manager - see the documentation on that function for more information.

Parameters:

1

string

Objective key, from the scripted_objectives table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2694

battle_manager:remove_objective(string objective key)

Removes a scripted objective from the scripted objectives panel. This function passes its arguments through objectives_manager:remove_objective on the objectives manager - see the documentation on that function for more information.

Parameters:

1

string

Objective key, from the scripted_objectives table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2702

battle_manager:activate_objective_chain(
  string chain name,
  string objective key,
  [number number param a],
  [number number param b]
)

Starts a new objective chain. This function passes its arguments through objectives_manager:activate_objective_chain on the objectives manager - see the documentation on that function for more information.

Parameters:

1

string

Objective chain name.

2

string

Key of initial objective, from the scripted_objectives table.

3

number

optional, default value=nil

First numeric parameter - see the documentation for battle_manager:set_objective for more details.

4

number

optional, default value=nil

Second numeric parameter - see the documentation for battle_manager:set_objective for more details.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2710

battle_manager:activate_objective_chain_with_leader(
  string chain name,
  string objective key,
  [number number param a],
  [number number param b]
)

Starts a new objective chain, with a topic_leader. This function passes its arguments through objectives_manager:activate_objective_chain_with_leader on the objectives manager - see the documentation on that function for more information.

Parameters:

1

string

Objective chain name.

2

string

Key of initial objective, from the scripted_objectives table.

3

number

optional, default value=nil

First numeric parameter - see the documentation for battle_manager:set_objective for more details.

4

number

optional, default value=nil

Second numeric parameter - see the documentation for battle_manager:set_objective for more details.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2721

battle_manager:update_objective_chain(
  string chain name,
  string objective key,
  [number number param a],
  [number number param b]
)

Updates an existing objective chain. This function passes its arguments through objectives_manager:update_objective_chain on the objectives manager - see the documentation on that function for more information.

Parameters:

1

string

Objective chain name.

2

string

Key of initial objective, from the scripted_objectives table.

3

number

optional, default value=nil

First numeric parameter - see the documentation for battle_manager:set_objective for more details

4

number

optional, default value=nil

Second numeric parameter - see the documentation for battle_manager:set_objective for more details

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2732

battle_manager:end_objective_chain(string chain name)

Ends an existing objective chain. This function passes its arguments through objectives_manager:end_objective_chain on the objectives manager - see the documentation on that function for more information.

Parameters:

1

string

Objective chain name.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2743

battle_manager:reset_objective_chain(string chain name)

Resets an objective chain so that it may be called again. This function passes its arguments through objectives_manager:reset_objective_chain on the objectives manager - see the documentation on that function for more information.

Parameters:

1

string

Objective chain name.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2751

battle_manager:set_locatable_objective(
  string objective key,
  battle_vector camera position,
  battle_vector camera target,
  number zoom duration,
  [boolean show topic leader]
)

Sets up a locatable objective in battle. This will appear in the scripted objectives list alongside a zoom-to button which, when clicked, will zoom the camera to a location on the battlefield. The key of the objective text, as well as the camera position/target and zoom duration must all be supplied.

Parameters:

1

string

Objective key, from the scripted_objectives table.

2

battle_vector

Final camera position.

3

battle_vector

Final camera target.

4

number

Duration of camera movement in seconds.

5

boolean

optional, default value=false

Shows a topic_leader before displaying the objective.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2805

battle_manager:set_locatable_objective_callback(
  string objective key,
  function camera position generator,
  number zoom duration,
  [boolean show topic leader]
)

Sets up a locatable objective in battle. This will appear in the scripted objectives list alongside a zoom-to button which, when clicked, will zoom the camera to a location on the battlefield. Whereas battle_manager:set_locatable_objective requires static camera position/targets to be supplied, this function takes a function argument which, when called, should return a battle_vector camera position and a battle_vector camera target. This allows the camera position to be generated at runtime, to follow a unit for example.

Parameters:

1

string

Objective key, from the scripted_objectives table.

2

function

Camera position generator function. When called, this should return two battle_vector values that specify the camera position and target to move to.

3

number

Duration of camera movement in seconds.

4

boolean

optional, default value=false

Shows a topic_leader before displaying the objective.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2862

Back to top

Infotext

These functions provide a passthrough interface to the most commonly-used functions on the infotext manager, which the battle manager creates automatically.

battle_manager:add_infotext(object first param, ... additional infotext strings)
Adds one or more lines of infotext to the infotext panel. This function passes through to infotext_manager:add_infotext - see the documentation on the infotext_manager page for more details.

Parameters:

1

object

Can be a string key from the advice_info_texts table, or a number specifying an initial delay in ms after the panel animates onscreen and the first infotext item is shown.

2

...

Additional infotext strings to be shown. add_infotext fades each of them on to the infotext panel in a visually-pleasing sequence.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2913

battle_manager:add_infotext_with_leader(object first param, ... additional infotext strings)
Adds one or more lines of infotext to the infotext panel, with a topic_leader. This function passes through to infotext_manager:add_infotext_with_leader - see the documentation on the infotext_manager page for more details.

Parameters:

1

object

Can be a string key from the advice_info_texts table, or a number specifying an initial delay in ms after the panel animates onscreen and the first infotext item is shown.

2

...

Additional infotext strings to be shown. add_infotext fades each of them on to the infotext panel in a visually-pleasing sequence.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2922

battle_manager:add_infotext_simultaneously(object first param, ... additional infotext strings)
Adds one or more lines of infotext simultaneously to the infotext panel. This function passes through to infotext_manager:add_infotext_simultaneously - see the documentation on the infotext_manager page for more details.

Parameters:

1

object

Can be a string key from the advice_info_texts table, or a number specifying an initial delay in ms after the panel animates onscreen and the first infotext item is shown.

2

...

Additional infotext strings to be shown. add_infotext_simultaneously fades each of them on to the infotext panel in a visually-pleasing sequence.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2931

battle_manager:add_infotext_simultaneously_with_leader(
  object first param,
  ... additional infotext strings
)
Adds one or more lines of infotext simultaneously to the infotext panel, with a topic_leader. This function passes through to infotext_manager:add_infotext_simultaneously_with_leader - see the documentation on the infotext_manager page for more details.

Parameters:

1

object

Can be a string key from the advice_info_texts table, or a number specifying an initial delay in ms after the panel animates onscreen and the first infotext item is shown.

2

...

Additional infotext strings to be shown. add_infotext_simultaneously fades each of them on to the infotext panel in a visually-pleasing sequence.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2940

battle_manager:remove_infotext(string infotext key)
Pass-through function for infotext_manager:remove_infotext. Removes a line of infotext from the infotext panel.

Parameters:

1

string

infotext key

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2949

battle_manager:clear_infotext()
Pass-through function for infotext_manager:clear_infotext. Clears the infotext panel.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2957

battle_manager:set_infotext_auto_clear_timer(
  number seconds,
  [boolean should_dismiss_advice_on_infotext_auto_hide_time_elapsed]
)

Pass-through function for infotext_manager:set_auto_clear_timer. Clears all infotexts after the specified time. Mouse over the infotext panel will freeze the timer. A value <= 0 will cancel any current timer

Parameters:

1

number

seconds

2

boolean

optional, default value=false

should_dismiss_advice_on_infotext_auto_hide_time_elapsed

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2963

battle_manager:hide_infotext()
Pass-through function for infotext_manager:hide_infotext. Hides and clears the infotext panel with an animation.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2972

battle_manager:attach_to_advisor([boolean should attach])

Pass-through function for infotext_manager:attach_to_advisor. This attaches or detaches the infotext panel from the advisor. By default they are attached, but by detaching them infotext may be triggered independently of advice.

Parameters:

1

boolean

optional, default value=true

should attach

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2979

Back to top

Subtitles

battle_manager:show_subtitle(string subtitle key, [boolean full key supplied], [boolean force subtitle on])
Shows a cutscene subtitle on-screen.

Parameters:

1

string

subtitle key

2

boolean

optional, default value=false

Full localised key supplied. If false, or if no value supplied, the script assumes that the key is from the scripted_subtitles table and pads the supplied key out accordingly.

If the key has been supplied in the full localisation format (i.e. [table]_[field_of_text]_[key_from_table]), set this to true.

3

boolean

optional, default value=false

Forces the subtitle to display, overriding the user's preferences.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2998

battle_manager:hide_subtitles()
Hides any currently-shown subtitle.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3061

Back to top

Help Message Queue

Help messages are used primarily in quest battles. They are text messages faded onto the HUD above the army panel, that persist for a time and then fade off. The battle manager queues them so they don't overwrite one another.

battle_manager:queue_help_message(
  string key,
  [number duration],
  [number fade time],
  [boolean high priority],
  [boolean play after battle victory],
  [function callback]
)
Enqueues a help message for showing on-screen.

Parameters:

1

string

Help message key, from the scripted_objectives table.

2

number

optional, default value=5000

Duration that the message will persist on-screen for in ms. If this is specified then a fade time must also be set.

3

number

optional, default value=2000

Time that the message will take to fade on/fade off in ms. If this is specified then a duration must also be set.

4

boolean

optional, default value=false

Set this to true to set this message to high priority. High priority messages are bumped to the top of the queue.

5

boolean

optional, default value=false

By default, help messages won't play after the battle has been won. Set this to true to allow this message to play after this point.

6

function

optional, default value=nil

Callback to call when the message actually starts to show on-screen.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3092

battle_manager:hide_help_message([boolean clear help message queue])

Hides any help message currently being shown. The help message queue may optionally also be cleared.

Parameters:

1

boolean

optional, default value=false

clear help message queue

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3208

Back to top

Aide-de-Camp

battle_manager:suspend_adc(boolean should suspend)

Suspends or un-suspends the aide-de-camp. This function wraps the battle:suspend_adc but provides lock levels - if multiple calls to suspend the adc are made, followed by multiple calls to unsuspend it, the adc won't actually get unsuspended until each suspend call is undone with an unsuspend call. This means that every call to suspend the adc must be matched with an equivalent call to unsuspend it.

Parameters:

1

boolean

should suspend

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3239

Back to top

Camera

battle_manager:cache_camera()
Caches the current position/target of the camera for later retrieval.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3276

battle_manager:get_cached_camera_pos()
Gets the cached position of the camera. This must be called after the position has been cached with battle_manager:cache_camera (else it will return false).

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3285

battle_manager:get_cached_camera_targ()
Gets the cached target of the camera. This must be called after the position has been cached with battle_manager:cache_camera (else it will return false).

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3292

battle_manager:scroll_camera_with_cutscene(
  battle_vector position,
  battle_vector target,
  number duration,
  [function end callback],
  [number fov],
  [boolean skippable],
  [function skip callback]
)

Automatically creates and starts a cutscene in which the camera is moved to the supplied co-ordinates.

Parameters:

1

battle_vector

Camera position.

2

battle_vector

Camera target.

3

number

Duration of camera movement in seconds.

4

function

optional, default value=nil

Function to call when cutscene ends (either naturally or by being skipped).

5

number

optional, default value=0

Field of view at target position in degrees. Supply 0 or nil to use the game default.

6

boolean

optional, default value=true

Sets whether cutscene is skippable or not.

7

function

optional, default value=nil

Function to call when cutscene is skipped.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3299

Back to top

Camera Movement Tracker

The camera movement tracker is used by some tutorial scripts to track how the player is moving the camera.

battle_manager:start_camera_movement_tracker()
Starts the camera movement tracker. Only tutorial scripts which need to query camera tracker information need to do this.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3377

battle_manager:stop_camera_movement_tracker()
Stops the camera movement tracker.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3389

battle_manager:get_camera_altitude_change()
Gets the difference in camera altitude between now and when the tracker was started. The returned value is absolute (always positive).

Returns:

  1. number difference in m

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3409

battle_manager:get_camera_distance_travelled()
Gets the total distance the camera has travelled between now and when the tracker was started. This distance is not exact, but gives the calling script an indication of how much the player is moving the camera.

Returns:

  1. number distance in m

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3424

Back to top

Showing/Hiding UI

Functions in this section may be used to show/hide elements on the battle ui. In some cases, the hidden elements will be restored if the cinematic ui is disabled/re-enabled, such as going into and then coming out of a cutscene. To circumvent this problem cutscene objects will call battle_manager:restore_ui_hiding to re-establish all hiding behaviour that would otherwise be reset, unless told not to with cutscene:set_should_restore_ui_hiding_on_end.

battle_manager:is_cinematic_ui_enabled()
Returns whether the cinematic UI is currently enabled. The cinematic UI is enabled from script with battle:enable_cinematic_ui, and is commonly activated/deactivated by cutscenes.

Returns:

  1. boolean is cinematic ui enabled

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3473

battle_manager:clear_selection()
Deselects any currently-selected units.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3481

battle_manager:restore_ui_hiding()
Restores certain ui hiding behaviours established by calls to ui-hiding functions in this section, where those ui-hiding behaviours would be reset by disabling/re-enabling the cinematic ui. This is called by cutscene objects.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3488

battle_manager:steal_input_focus(boolean steal focus, boolean dont restore)

Steals or releases all input from the UI, disabling or re-enabing user input in the game. This calls/overrides the battle functions battle:steal_input_focus and battle:release_input_focus. The state set with this function will be re-established when battle_manager:restore_ui_hiding is called.

Parameters:

1

boolean

Steal focus. Set to false to release focus.

2

boolean

Don't add this action to the list of actions to restore if battle_manager:restore_ui_hiding is called.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3503

battle_manager:is_input_focus_stolen()
Returns whether input focus has currently been stolen by battle_manager:steal_input_focus.

Returns:

  1. boolean input focus is stolen

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3532

battle_manager:enable_ui_hiding([boolean should enable])

Enables/disables UI hiding. With UI hiding disabled the player will not be able to hide the UI by pressing K or alt-K. This function does not prevent the script from being able to hide or show the UI.
Any state set by a call to this function is restored if battle_manager:restore_ui_hiding is called.

Parameters:

1

boolean

optional, default value=true

should enable

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3540

battle_manager:is_ui_hiding_enabled()
Returns false if UI hiding has been disabled with battle_manager:enable_ui_hiding, otherwise true.

Returns:

  1. boolean is ui hiding enabled.

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3563

battle_manager:show_start_battle_button([boolean should show], [boolean is multiplayer])

Shows/hides the start battle button. Any state set by a call to this function is restored if battle_manager:restore_ui_hiding is called.

Parameters:

1

boolean

optional, default value=true

Should show.

2

boolean

optional, default value=false

Set this to true if this is a multiplayer battle.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3571

battle_manager:show_ui([boolean should show])

Shows/hides the army panel, portrait panel, top bar and radar frame from script.

Parameters:

1

boolean

optional, default value=true

should show

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3611

battle_manager:show_army_panel([boolean should show], [boolean immediate])

Shows/hides the army panel.

Parameters:

1

boolean

optional, default value=true

Should show.

2

boolean

optional, default value=false

Hide immediately. If the first parameter is false and this is true, the panel will not animate offscreen but will instead immediately disappear.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3629

battle_manager:show_portrait_panel([boolean should show], [boolean immediate])

Shows/hides the unit portrait panel.

Parameters:

1

boolean

optional, default value=true

Should show.

2

boolean

optional, default value=false

Hide immediately. If the first parameter is false and this is true, the panel will not animate offscreen but will instead immediately disappear.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3666

battle_manager:show_top_bar([boolean should show], [boolean immediate])

Shows/hides the top bar on the battle interface.

Parameters:

1

boolean

optional, default value=true

Should show.

2

boolean

optional, default value=false

Hide immediately. If the first parameter is false and this is true, the panel will not animate offscreen but will instead immediately disappear.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3704

battle_manager:show_radar_frame([boolean should show], [boolean immediate])

Shows/hides the radar.

Parameters:

1

boolean

optional, default value=true

Should show.

2

boolean

optional, default value=false

Hide immediately. If the first parameter is false and this is true, the panel will not animate offscreen but will instead immediately disappear.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3742

battle_manager:show_ui_options_panel([boolean should show])

Shows/hides the ui options rollout panel.

Parameters:

1

boolean

optional, default value=true

should show

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3793

battle_manager:enable_camera_movement([boolean enable movement])

Allows script to prevents player movement of the camera without stealing input - other game interactions are still permitted. Supply false as an argument to disable camera movement.

Parameters:

1

boolean

optional, default value=true

enable movement

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3821

battle_manager:disable_orders([boolean disable])

Disables or enables the giving of any orders at all. This function wraps the battle:disable_orders function of the same name on the battle interface, adding console output.

Parameters:

1

boolean

optional, default value=true

disable

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3835

battle_manager:disable_pausing([boolean disable])

Disables or enables pausing.

Parameters:

1

boolean

optional, default value=true

disable

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3849

battle_manager:disable_time_speed_controls([boolean disable])

Disables or enables the time speed controls.

Parameters:

1

boolean

optional, default value=true

disable

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3863

battle_manager:disable_tactical_map([boolean disable])

Disables or enables the tactical map.

Parameters:

1

boolean

optional, default value=true

disable

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3878

battle_manager:disable_help_page_button([boolean disable])

Disables or enables the help page button.

Parameters:

1

boolean

optional, default value=true

disable

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3892

battle_manager:disable_cycle_battle_speed([boolean disable])

Disables or enables the battle speed cycling keyboard shortcuts.

Parameters:

1

boolean

optional, default value=true

disable

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3906

battle_manager:disable_unit_camera([boolean disable])

Disables or enables the unit camera.

Parameters:

1

boolean

optional, default value=true

disable

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3920

battle_manager:disable_unit_details_panel([boolean disable])

Prevents the unit details panel from being displayed, or allows it to be displayed again after it was previously prevented.

Parameters:

1

boolean

optional, default value=true

disable

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3934

Back to top

Building Lists

battle_manager:get_fort_tower_buildings()
Returns a table containing a battle_building object for each fort tower building on the map. The table will not be copied, so modifying the returned table will also modify the battle manager's internal version.

Returns:

  1. table fort tower buildings

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3975

battle_manager:get_fort_gate_buildings()
Returns a table containing a battle_building object for each fort gate building on the map. The table will not be copied, so modifying the returned table will also modify the battle manager's internal version.

Returns:

  1. table fort gate buildings

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3984

battle_manager:get_fort_wall_buildings()
Returns a table containing a battle_building object for each fort wall building on the map. The table will not be copied, so modifying the returned table will also modify the battle manager's internal version.

Returns:

  1. table fort wall buildings

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3992

battle_manager:print_fort_tower_buildings()
Prints a debug list of all fort tower buildings on the map.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4014

battle_manager:print_fort_gate_buildings()
Prints a debug list of all fort gate buildings on the map.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4021

battle_manager:print_fort_wall_buildings()
Prints a debug list of all fort wall buildings on the map.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4028

Back to top

Conflict Time Update

The functions in this section relate to conflict time updating, which is the battle timer that ticks down to the end of the battle. Certain client scripts such as cutscenes may want to enable/disable/cache/restore conflict time settings.

battle_manager:change_conflict_time_update_overridden(boolean disable update)

Enables or disables the countdown of the conflict timer. This function wraps the underlying battle interface function battle:change_conflict_time_update_overridden. Call with an argument of true to disable the countdown of the conflict timer, or false to enable it again. With conflict time update overridden, time can pass but the victory timer will not count down.

Parameters:

1

boolean

disable update

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4048

battle_manager:cache_conflict_time_update_overridden()
Caches whether conflict time is currently overridden. The cached value can be later restored with battle_manager:restore_conflict_time_update_overridden.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4057

battle_manager:restore_conflict_time_update_overridden()
Restores any conflict override setting previously cached with battle_manager:cache_conflict_time_update_overridden.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4064

Back to top

Engagement Monitor

The Engagement monitor is a set of processes that continually query the battle state and either store information for other scripts to look up or trigger events for other scripts to listen to. The engagement monitor doesn't start automatically, but must be started by scripts that need the processing and information that it requires, mostly advice/tutorial scripts.

The Engagement monitor tracks the following information:

  • the distance between the two alliances on the battlefield, which other scripts can query instead of continually working it out themselves which is potentially expensive.

  • the number/proportion of the player's alliance that is engaged in melee/under fire.

  • the average altitude of both the player and enemy alliance.

The Engagement monitor also triggers the following events:

  • tScriptEventBattleArmiesEngaging, when the two sides close to within 100m or once more than 40% of the player's army is under fire.

  • ScriptEventPlayerGeneralWounded, if the player's general is wounded (they must be invincible).

  • ScriptEventPlayerGeneralDies, if the player's general dies (not invincible).

  • ScriptEventEnemyGeneralWounded, if the enemy general is wounded (they must be invincible).

  • ScriptEventEnemyGeneralDies, if the enemy general dies (not invincible).

  • ScriptEventPlayerGeneralRouts, if the player's general routs.

  • ScriptEventEnemyGeneralRouts, if the enemy general routs.

  • ScriptEventPlayerUnitRouts, if one of the player's units routs.

  • ScriptEventPlayerUnitRallies, if one of the player's units rallies.

  • ScriptEventEnemyUnitRouts, if one of the enemy units routs.

It also triggers ScriptEventPlayerApproachingVictoryPoint as an approximation of the player approaching a victory point. The implementation for this can charitably be described as a best guess - it happens two minutes after the player docks to the walls or the gate.

battle_manager:start_engagement_monitor()
Starts the engagement monitor. This must be called before the "Deployed" phase change occurs (i.e. before the end of deployment).

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4104

battle_manager:get_distance_between_forces()
Returns the cached distance between the two alliances. battle_manager:start_engagement_monitor must have been called before the battle started for this to work.

Returns:

  1. number distance

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4427

battle_manager:get_num_units_engaged()
Returns the number of units in the player's alliance engaged in melee. battle_manager:start_engagement_monitor must have been called before the battle started for this to work.

Returns:

  1. number engaged

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4439

battle_manager:get_proportion_engaged()
Returns the proportion of units in the player's alliance engaged in melee. This proportion will be a unary value (0 - 1). battle_manager:start_engagement_monitor must have been called before the battle started for this to work.

Returns:

  1. number proportion engaged

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4451

battle_manager:get_num_units_under_fire()
Returns the number of units in the player's alliance under missile fire. battle_manager:start_engagement_monitor must have been called before the battle started for this to work.

Returns:

  1. number under fire

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4463

battle_manager:get_proportion_under_fire()
Returns the proportion of units in the player's alliance engaged in melee. This proportion will be a unary value (0 - 1). battle_manager:start_engagement_monitor must have been called before the battle started for this to work.

Returns:

  1. number proportion engaged

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4475

battle_manager:get_player_army_altitude()
Returns the average altitude of the player's army in m.

Returns:

  1. number average altitude

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4487

battle_manager:get_enemy_army_altitude()
Returns the average altitude of the enemy army in m.

Returns:

  1. number average altitude

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4499

battle_manager:stop_engagement_monitor()
Stops the engagement monitor.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4511

Back to top

Composite Scenes

battle_manager:start_terrain_composite_scene(string key, [string group name], [number delay])
Starts a composite scene with the supplied key. If an optional group name is set then this composite scene will not play if another from the same group is active, but will instead be enqueued. When a composite scene in a group stops and a second in the same group is enqueued, then that second scene will begin to play automatically.

Parameters:

1

string

Composite scene key.

2

string

optional, default value=false

Composite group name.

3

number

optional, default value=false

Delay in milliseconds to wait before starting if this composite scene becomes enqueued behind another (allowing a minimum time separation between composite scenes of the same group to be specified). This has no effect if no group name is specified.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4531

battle_manager:stop_terrain_composite_scene(string key)
Stops a composite scene with the supplied key. If this composite scene was specified as belonging to a group when it was started, and other composite scenes in that group are enquened, then the next one will begin to play automatically (after an optional delay).

Parameters:

1

string

Composite scene key.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4604

Back to top

Building Grid

On startup, the battle manager

battle_manager:print_buildings_grid()
Dump console spool output related to the buildings grid.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4797

battle_manager:get_buildings_from_grid(
  battle_vector position,
  number range,
  [function filter],
  [boolean test 3D]
)

Returns a table of buildings that exist within a given range of a given position from the cached building grid. This lookup is much more computationally efficient than measuring the distance of every building on the battlefield to the given position manually.
An optional filter function may be provided. If supplied, this function is called for each eligible building, with the building passed in as a single argument. The function should return a value that evaluates to true for the building to be added to the returned list. If no filter function is provided then all buildings within range of the position are added to the returned list.
Distances between the supplied position and each tested building may be measured in two or three dimensions. By default, distances are measured in two dimensions.

Parameters:

1

battle_vector

Position to test against.

2

number

Range from the position to test buildings against. Buildings within this range of the position are added to the returned list, assuming they either pass the supplied filter function or no filter function is supplied.

3

function

optional, default value=nil

Optional filter function. If supplied, each in-range building is supplied to this function, which must return a value that evaluates to true for that building to be added to the returned list. If no filter function is supplied then all buildings within range of the position are added.

4

boolean

optional, default value=false

Test distances between each candidate building and the supplied position in three dimensions rather than two dimensions.

Returns:

  1. table table of battle_building objects within range

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4838

battle_manager:get_buildings_close_to_building_from_grid(
  battle_building subject building,
  number range,
  [function filter],
  [boolean test 3D]
)

Returns a table of buildings that exist within a given range of a supplied building from the cached building grid. The supplied building itself is not returned as part of this list.
An optional filter function may be provided. If supplied, this function is called for each eligible building, with the building passed in as a single argument. The function should return a value that evaluates to true for the building to be added to the returned list. If no filter function is provided then all buildings within range of the position are added to the returned list.
Distances between the supplied building and each tested building may be measured in two or three dimensions. By default, distances are measured in two dimensions.

Parameters:

1

battle_building

Subject building to test against.

2

number

Range from the subject building to test other buildings against. Buildings within this range of the subject are added to the returned list, assuming they either pass the supplied filter function or no filter function is supplied.

3

function

optional, default value=nil

Optional filter function. If supplied, each in-range building is supplied to this function, which must return a value that evaluates to true for that building to be added to the returned list. If no filter function is supplied then all buildings within range of the subject are added.

4

boolean

optional, default value=false

Test distances between each candidate building and the subject in three dimensions rather than two dimensions.

Returns:

  1. table table of battle_building objects within range

defined in ../../Warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4924

Last updated 8/23/2024 4:55:16 PM