Battle Manager

The battle_manager is a central interface object through which much functionality is provided to battle scripts. A battle manager is automatically created when the script libraries are loaded in battle by calling load_script_libraries. This battle manager object is called bm, and calls to battle and battle manager functions may be made through it.

When created, the battle_manager script object internally creates a battle code interface object automatically. Functions called on the battle manager that the battle manager does not itself provide are passed through to this battle object. In this way, the battle_manager object automatically provides the full interface of a battle object. The battle manager also provides numerous enhancements and extensions on top of the core battle functionality - see the list of functions on this page.

It is highly preferable for scripts to not create and use a battle interface themselves, but instead to load the script libraries and work exclusively through the battle manager.

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

Creation

A battle manager object is automatically created when the script libraries are loaded in battle, so there should be no need for client scripts to call battle_manager:new themselves. The battle manager object that is automatically created is called bm.

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 battle manager

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 119

Back to top

Usage

Once created (which happens automatically within the declaration of the script libraries), functions on the battle manager object may be called in the form showed below.

Example - Specification:

core:<function_name>(<args>)

Example - Creation and Usage:

-- Object called bm is automatically set up by script libraries -
-- client scripts should not need to call this themselves.
bm = battle_manager:new()
bm:out("test")
Test
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 298

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 317

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 373

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 381

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 400

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 430

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 438

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 446

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 455

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 496

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 battle ui manager

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 590

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 603

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

Returns:

  1. battle_vector origin

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

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 619

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 647

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 665

battle_manager:is_any_unit_selected()
Returns whether any unit cards are selected.

Returns:

  1. boolean any unit selected

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 683

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 712

battle_manager:are_all_units_selected()
Returns whether all unit cards are selected.

Returns:

  1. boolean all units selected

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 743

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

Returns:

  1. number alliance number

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 769

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

Returns:

  1. number alliance number

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 777

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

Returns:

  1. battle_alliance player alliance

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 789

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

Returns:

  1. battle_alliance enemy alliance

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 797

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 805

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

Returns:

  1. battle_army player's army

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 813

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

Returns:

  1. battle_army enemy army

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 821

battle_manager:get_attacking_alliance_num()
Returns the alliance number of the attacking alliance in the battle.

Returns:

  1. number attacking alliance num

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 829

battle_manager:get_defending_alliance_num()
Returns the alliance number of the defending alliance in the battle.

Returns:

  1. number defending alliance num

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 845

battle_manager:get_attacking_alliance()
Returns the attacking alliance object.

Returns:

  1. battle_alliance attacking alliance

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 861

battle_manager:get_defending_alliance()
Returns the defending alliance object.

Returns:

  1. battle_alliance defending alliance

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 877

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 893

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 919

battle_manager:get_closest_capture_location(battle_vector position)

Returns the closest capture location to the supplied position. If no capture location is present on the map then nil is returned.

Parameters:

1

battle_vector

position

Returns:

  1. battle_capture_location closest capture location

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 947

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 974

battle_manager:player_army_is_subculture(string subculture key)

Returns whether the local player army is of the supplied subculture.

Parameters:

1

string

subculture key

Returns:

  1. boolean subculture matches

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1002

battle_manager:player_army_is_faction(string faction key)

Returns whether the local player army is of the supplied faction.

Parameters:

1

string

faction key

Returns:

  1. boolean faction key matches

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1011

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 1036

Back to top

Random Numbers

battle_manager:random_number([number first number], [number max number])

Returns a random number. If no min or max bounding values are supplied then the value returned is a float between 0 and 1. If a single integer number argument is supplied, then the value returned is an integer value from 1 to the max value. If two integer min/max arguments are supplied then the value returned is an integer value between the first and the second.

Parameters:

1

number

optional, default value=nil

First number argument - this is the maximum value for the returned random integer if no second argument is supplied, or the mininum value if a second argument is provided.

2

number

optional, default value=nil

Maximum value for the returned random integer.

Returns:

  1. number random number

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1058

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 1105

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 1134

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 1182

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, from 'Deployment' to 'Deployed' and on to 'VictoryCountdown' and 'Complete'. The battle manager writes debug output whenever a phase change occurs, regardless of whether any callback has been registered for it.
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 1213

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 1238

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 1246

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 1254

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 1262

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 1297

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 1325

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 1365

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 1419

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 1482

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 1535

Back to top

ESC Key Callback Queue

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.

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 1599

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.

Parameters:

1

string

callback name to cancel

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1645

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 1710

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 1724

battle_manager:restart_battle()
Immediately restarts the current battle.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1743

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 1750

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 1803

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 1847

battle_manager:pause()
Pauses the battle.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 1854

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 1861

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 1917

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 1928

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 1939

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 1948

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 1959

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 1970

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 1995

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 2170

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 2182

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

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2210

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 2225

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 2240

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).

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 2264

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 2436

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 2461

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

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2470

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 2477

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 2499

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 2511

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 2519

Back to top

Progress on Advice Actions

battle_manager:progress_on_advice_dismissed(
  string name,
  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

string

Process name, by which this progress listener may be later cancelled if necessary.

2

function

Callback to call.

3

number

optional, default value=0

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

4

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 2574

battle_manager:cancel_progress_on_advice_dismissed(string name)

Cancels a running battle_manager:progress_on_advice_dismissed process.

Parameters:

1

string

Process name, by which this progress listener was started.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 2690

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 2706

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 2713

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 2785

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 2799

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 2852

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 2876

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 2888

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 2901

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 2910

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 2918

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 2926

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 2937

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 2948

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 2959

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 2967

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 3021

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 3078

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 3128

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 3137

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 3146

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 3155

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 3164

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 3172

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 3179

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 3186

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 3201

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

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3263

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 3294

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 3419

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 3450

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

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3458

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 3465

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 3480

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 3509

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 3517

battle_manager:enable_paused_panel([boolean should enable])

Disables or re-enables the display of the paused panel. With the paused panel disabled the game may still be paused, but the panel will not show.

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 3559

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 3567

battle_manager:show_ui([boolean should show])

Shows/hides the army panel, winds of magic panel, portrait panel, top bar, radar frame and army abilities 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 3622

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 3642

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

Shows/hides the winds of magic 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 3679

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 3717

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 3755

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 3793

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

Shows/hides any army abilities on the right-side of the screen.

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 3831

battle_manager:show_spell_browser_button([boolean should show])

Shows/hides the spell browser.

Parameters:

1

boolean

optional, default value=true

Should show.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3869

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 3899

battle_manager:enable_spell_browser_button([boolean should enable])

Enables/disables the spell browser button on the battle interface. A disabled button will still be visible, but greyed-out.

Parameters:

1

boolean

optional, default value=true

should enable

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 3927

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 3954

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 3963

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 3977

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 3991

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 4003

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 4019

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 4033

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 4047

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 4061

Back to top

Showing/Hiding Units for Multiplayer Cutscenes

battle_manager:show_player_alliance_units_for_mp_cutscenes(boolean show)

Shows or hides all units in the player's alliance. This is primarily intended for multiplayer cutscenes but could be used for other purposes.

Parameters:

1

boolean

show

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4134

battle_manager:show_player_army_units_for_mp_cutscenes(boolean show)

Shows or hides all units in the player's army. This is primarily intended for multiplayer cutscenes but could be used for other purposes.

Parameters:

1

boolean

show

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4152

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 4174

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 4183

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 4191

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 4213

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 4220

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 4227

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 4247

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 4256

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 4263

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 4282

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 4291

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 4298

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 4305

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 4383

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 4395

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 4415

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 4430

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:

  • ScriptEventBattleArmiesEngaging, 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.

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 4498

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 4790

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 4802

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 4814

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 4826

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 4838

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 4850

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 4862

battle_manager:stop_engagement_monitor()
Stops the engagement monitor.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 4874

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 4894

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 4967

Back to top

Survival Battle Waves

battle_manager:add_survival_battle_wave(number index, script_units script units, [boolean is final wave])

Adds a script units collection to a survival battle wave by index number. A new survival battle wave process is created if one does not already exist for the supplied number.
When a new survival battle wave is created, the battle manager starts a process which automatically monitors the health of all units in that wave, updating the UI accordingly. The state of the wave is set to "incoming" to start with, to "in_progress" when the units in the wave first enter combat, and then to "defeated" when those units are routed or killed. The progress value of the wave is also continually updated.

Parameters:

1

number

Survival battle wave index. This should be an ascending integer for each new wave e.g. wave 1, wave 2 etc.

2

script_units

Script units collection containing sunits to add to the wave.

3

boolean

optional, default value=false

Is this the final wave.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 5039

Back to top

Spawn Zone Collections

battle_manager:get_spawn_zone_collection_by_name(vararg names)
Returns a table containing all spawn zones on the battlefield where the script id of the contained reinforcement line partially match any of the supplied names. The script_id of each spawn zone/reinforcement line pair is checked - should it contain any of the supplied string arguments then that spawn zone is added to the collection to be returned. Partial matches are possible, so a spawn zone with a reinforcement line called something like sz_section_3_rear will match against the argument section_3.
The returned spawn zone collection is a table containing subtables, each of which contains a spawn zone and a count of how many time that spawn zone has had a reinforcement army assigned to it by script. The spawn zone collection can be passed to battle_manager:get_random_spawn_zone_from_collection to get a semi-random spawn zone from the collection.

Parameters:

1

vararg

Spawn zone names to match, each of which should be a string.

Returns:

  1. table spawn zone collection

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 5200

battle_manager:get_random_spawn_zone_from_collection(table collection)

Returns a random spawn zone from the supplied spawn zone collection, preferentially choosing a spawn zone that hasn't been used as much as the others.

Parameters:

1

table

collection

Returns:

  1. battle_spawn_zone spawn zone

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 5237

battle_manager:assign_army_to_spawn_zone_from_collection(
  battle_army army,
  table collection,
  [string name]
)

Assigns a supplied battle_army to a spawn zone from a collection. The spawn zone will be selected by battle_manager:get_random_spawn_zone_from_collection.

Parameters:

1

battle_army

Army to assign.

2

table

Spawn zone collection.

3

string

optional, default value=nil

Optional army name for output. If supplied, some output is generated featuring this name should the assignment be successful.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 5295

Back to top

Capture Locations

battle_manager:print_capture_locations()
Generates debugging output that lists all capture locations on the battlefield.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 5345

battle_manager:get_victory_locations()
Gets a table containing a battle_capture_location for each capture location that contributes to battle victory. The table is cached internally the first time this function is called.

Returns:

  1. table victory locations

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 5370

Back to top

Toggle Slots

battle_manager:print_toggle_slots()
Prints a list of all toggle slots on the battle map to the console.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 5404

battle_manager:get_toggle_slot_by_script_id(string script id)

Returns the first toggle slot found with the supplied script id. If no matching toggle slot is found then nil is returned.

Parameters:

1

string

script id

Returns:

  1. battle_toggle_slot toggle slot

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 5430

Back to top

Campaign Value Remapping

This subsystem allows values to be remapped for a particular campaign. This can be useful to specify a replacement set of advice keys for a particular campaign, for example, but could be used for other sets of data.

Values are remapped initially by calling battle_manager:remap_value_for_campaign, and then subsequently accessed with battle_manager:get_value_for_campaign.

Example - Remapping advice keys for a prologue campaign:

bm:remap_value_for_campaign("wh3_main_prologue", "deployment_advice_1", "prologue_advice_01")
bm:remap_value_for_campaign("wh3_main_prologue", "deployment_advice_3", "prologue_advice_12")
bm:remap_value_for_campaign("wh3_main_prologue", "deployment_advice_5", "prologue_advice_26")

-- later
local advice_to_use_1 = bm:get_value_for_campaign("wh3_main_prologue", "deployment_advice_1")    -- maps to prologue_advice_01
local advice_to_use_2 = bm:get_value_for_campaign("wh3_main_prologue", "deployment_advice_2")    -- maps to deployment_advice_2 as no remap set
local advice_to_use_3 = bm:get_value_for_campaign("wh3_main_prologue", "deployment_advice_3")    -- maps to prologue_advice_12

battle_manager:remap_value_for_campaign(
  string campaign key,
  value value,
  [value replacement value],
  [boolean allow overwriting]
)

Stores a mapping for the specified campaign, that the supplied value should remap to the supplied replacement value. This can be subsequently looked up with battle_manager:get_value_for_campaign.

Parameters:

1

string

Campaign key.

2

value

Value to remap. This can be any value other than nil or false.

3

value

optional, default value=nil

Replacement value. This can be any value.

4

boolean

optional, default value=false

Allow a previously-mapped value to be overwritten.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 5477

battle_manager:get_value_for_campaign(string campaign key, value value, [boolean return unmapped value])

Retrieves a value remapping for the specified campaign. If the value has been remapped for the particular campaign then the replacement value is returned. If the value has not been remapped then the value itself is returned, un-remapped, or nil is returned if the return-unmapped-value parameter is set to false.

Parameters:

1

string

Campaign key.

2

value

value to remap. This can be any value other than nil or false.

3

boolean

optional, default value=true

Sets whether the function call should return the value as it was supplied if it was not remapped or not. If this is set to false and the value has not been remapped, then nil is returned.

Returns:

  1. value remapped value

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 5508

battle_manager:get_value_for_current_campaign(value value, [boolean return unmapped value])

Retrieves a value remapping for the current campaign. If the value has been remapped for this campaign then the replacement value is returned. If the value has not been remapped then the value itself is returned, un-remapped, or nil is returned if the return-unmapped-value parameter is set to false.

Parameters:

1

value

value to remap. This can be any value other than nil or false.

2

boolean

optional, default value=true

Sets whether the function call should return the value as it was supplied if it was not remapped or not. If this is set to false and the value has not been remapped, then nil is returned.

Returns:

  1. value remapped value

defined in ../../warhammer/working_data/script/_lib/lib_battle_manager.lua, line 5536

Last updated 7/9/2024 11:45:05 AM