Battle Manager

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

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

Loaded in Battle loaded in battle
Back to top

Creation

battle_manager:new()
Creates a battle_manager object. The single parameter should be an battle code object, which can be created with empire_battle:new(). Only one battle_manager object may be created in a session - attempting to create a second just returns the first.

Returns:

  1. battle_manager

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 124

Back to top

Debug Output

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

Parameters:

1

string

output

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 258

Back to top

Miscellaneous Querying

battle_manager:get_tm()
Directly access the timer_manager object the battle manager creates and stores internally. It shouldn't be necessary to do this too often, as the battle manager exposes its most useful functions.

Returns:

  1. timer_manager

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 276

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

Returns:

  1. battle_ui_manager

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 284

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

Returns:

  1. string path

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 297

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

Returns:

  1. vector origin

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 305

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 ../working_data/script/_lib/lib_battle_manager.lua, line 313

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 ../working_data/script/_lib/lib_battle_manager.lua, line 351

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

Returns:

  1. boolean any unit selected

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 369

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

Returns:

  1. boolean all units selected

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 398

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

Returns:

  1. integer alliance number

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 424

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

Returns:

  1. integer alliance number

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 432

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

Returns:

  1. alliance player alliance

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 444

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

Returns:

  1. alliance enemy alliance

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 452

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 ../working_data/script/_lib/lib_battle_manager.lua, line 460

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

Returns:

  1. army player's army

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 468

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

Returns:

  1. army enemy army

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

Back to top

Random Numbers

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

Parameters:

1

number

optional, default value=nil

max value

Returns:

  1. random number

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 498

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 ../working_data/script/_lib/lib_battle_manager.lua, line 512

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 ../working_data/script/_lib/lib_battle_manager.lua, line 541

Back to top

Battle Startup and Phases

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 ../working_data/script/_lib/lib_battle_manager.lua, line 576

battle_manager:register_phase_change_callback(string phase change 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 change name

2

function

callback

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 607

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 ../working_data/script/_lib/lib_battle_manager.lua, line 662

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 ../working_data/script/_lib/lib_battle_manager.lua, line 690

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 ../working_data/script/_lib/lib_battle_manager.lua, line 730

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 ../working_data/script/_lib/lib_battle_manager.lua, line 784

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 ../working_data/script/_lib/lib_battle_manager.lua, line 847

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 ../working_data/script/_lib/lib_battle_manager.lua, line 900

Back to top

ESC Key Callback Queue

battle_manager:steal_escape_key_with_callback(string callback name, function callback)
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

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 964

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 ../working_data/script/_lib/lib_battle_manager.lua, line 1008

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 ../working_data/script/_lib/lib_battle_manager.lua, line 1069

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 ../working_data/script/_lib/lib_battle_manager.lua, line 1083

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 ../working_data/script/_lib/lib_battle_manager.lua, line 1090

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 ../working_data/script/_lib/lib_battle_manager.lua, line 1143

battle_manager:pause()
Pauses the battle.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 1187

Back to top

Timer Manager

These wrapper functions expose functionality provided by the timer_manager. It is highly recommended to use battle_manager:callback or battle_manager:repeat_callback in place of register_singleshot_timer and register_repeating_timer, the latter are mainly provided for legacy support.

battle_manager:callback(function callback to call, number delay in ms, [string callback name])
Exposes the callback function from the timer_manager object. Instructs the timer manager to call a supplied function after a supplied delay. A string name for the callback may also be supplied with which the callback may be later cancelled using battle_manager:remove_process.

Parameters:

1

function

callback to call

2

number

delay in ms

3

string

optional, default value=nil

callback name

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 1241

battle_manager:repeat_callback(function callback to call, number delay in ms, [string callback name])
Exposes the repeat_callback function from the timer_manager object. Instructs the timer manager to call a supplied function after a supplied delay, and then repeatedly after the same delay. A string name for the callback may also be supplied with which the callback may be later cancelled using battle_manager:remove_process.

Parameters:

1

function

callback to call

2

number

delay in ms

3

string

optional, default value=nil

callback name

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 1251

battle_manager:register_singleshot_timer(string function name, number time in ms)
Exposes the register_singleshot_timer function from the timer_manager object.

Parameters:

1

string

function name

2

number

time in ms

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 1261

battle_manager:register_repeating_timer(string function name, number time in ms)
Exposes the register_repeating_timer function from the timer_manager object.

Parameters:

1

string

function name

2

number

time in ms

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 1270

battle_manager:unregister_timer(string function name)
Exposes the unregister_timer function from the timer_manager object.

Parameters:

1

string

function name

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 1279

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 ../working_data/script/_lib/lib_battle_manager.lua, line 1300

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 ../working_data/script/_lib/lib_battle_manager.lua, line 1475

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 ../working_data/script/_lib/lib_battle_manager.lua, line 1487

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

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 1515

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 ../working_data/script/_lib/lib_battle_manager.lua, line 1530

battle_manager:set_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.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 1545

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 ../working_data/script/_lib/lib_battle_manager.lua, line 1569

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 ../working_data/script/_lib/lib_battle_manager.lua, line 1733

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 ../working_data/script/_lib/lib_battle_manager.lua, line 1758

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

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 1767

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 ../working_data/script/_lib/lib_battle_manager.lua, line 1774

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 ../working_data/script/_lib/lib_battle_manager.lua, line 1796

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 ../working_data/script/_lib/lib_battle_manager.lua, line 1808

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 ../working_data/script/_lib/lib_battle_manager.lua, line 1816

Back to top

Progress on Advice Actions

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

Parameters:

1

function

Callback to call.

2

number

optional, default value=0

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

3

boolean

optional, default value=false

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

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 1871

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

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 1988

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 ../working_data/script/_lib/lib_battle_manager.lua, line 1997

battle_manager:progress_on_advice_finished(function callback to call, [number delay], [number playtime])
Calls a supplied callback when the advisor has stopped playing an audible sound.

Parameters:

1

function

Callback to call.

2

number

optional, default value=0

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

3

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 ../working_data/script/_lib/lib_battle_manager.lua, line 2004

battle_manager:cancel_progress_on_advice_finished()
Cancels a running battle_manager:progress_on_advice_finished process.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 2070

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])
Pass-through function for objectives_manager:set_objective on the objectives manager. 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.

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 ../working_data/script/_lib/lib_battle_manager.lua, line 2094

battle_manager:complete_objective(string objective key)
Pass-through function for objectives_manager:complete_objective on the objectives manager. 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.
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 ../working_data/script/_lib/lib_battle_manager.lua, line 2105

battle_manager:fail_objective(string objective key)
Pass-through function for objectives_manager:fail_objective on the objectives manager. 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.

Parameters:

1

string

Objective key, from the scripted_objectives table.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 2114

battle_manager:remove_objective(string objective key)
Pass-through function for objectives_manager:remove_objective on the objectives manager. Removes a scripted objective from the scripted objectives panel.

Parameters:

1

string

Objective key, from the scripted_objectives table.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 2122

battle_manager:activate_objective_chain(
  string chain name,
  string objective key,
  [number number param a],
  [number number param b]
)
Pass-through function for objectives_manager:activate_objective_chain. Starts a new objective chain - see the documentation on the objectives_manager page for more details.

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 ../working_data/script/_lib/lib_battle_manager.lua, line 2130

battle_manager:update_objective_chain(
  string chain name,
  string objective key,
  [number number param a],
  [number number param b]
)
Pass-through function for objectives_manager:update_objective_chain. Updates an existing objective chain - see the documentation on the objectives_manager page for more details.

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 ../working_data/script/_lib/lib_battle_manager.lua, line 2141

battle_manager:end_objective_chain(string chain name)
Pass-through function for objectives_manager:end_objective_chain. Ends an existing objective chain - see the documentation on the objectives_manager page for more details.

Parameters:

1

string

Objective chain name.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 2152

battle_manager:reset_objective_chain(string chain name)
Pass-through function for objectives_manager:reset_objective_chain. Resets an objective chain so that it may be called again - see the documentation on the objectives_manager page for more details.

Parameters:

1

string

Objective chain name.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 2160

battle_manager:set_locatable_objective(
  string objective key,
  vector camera position,
  vector camera target,
  number zoom duration
)
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. The button visibility, on-click listener, and camera movements are all handled in script (which means the camera movement doesn't work when paused..)

Parameters:

1

string

Objective key, from the scripted_objectives table.

2

vector

Final camera position.

3

vector

Final camera target.

4

number

Duration of camera movement in seconds.

Returns:

  1. nil

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

battle_manager:set_locatable_objective_callback(
  string objective key,
  function camera position generator,
  number zoom duration
)

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.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 2247

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)
Pass-through function for infotext_manager:add_infotext. Adds one or more lines of infotext to the infotext panel - 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 ../working_data/script/_lib/lib_battle_manager.lua, line 2288

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 ../working_data/script/_lib/lib_battle_manager.lua, line 2297

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

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 2305

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 ../working_data/script/_lib/lib_battle_manager.lua, line 2323

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

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 2386

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 ../working_data/script/_lib/lib_battle_manager.lua, line 2417

Back to top

Camera

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 ../working_data/script/_lib/lib_battle_manager.lua, line 2549

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

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 2563

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 ../working_data/script/_lib/lib_battle_manager.lua, line 2572

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 ../working_data/script/_lib/lib_battle_manager.lua, line 2579

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 ../working_data/script/_lib/lib_battle_manager.lua, line 2600

battle_manager:stop_camera_movement_tracker()
Stops the camera movement tracker.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 2612

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 ../working_data/script/_lib/lib_battle_manager.lua, line 2629

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 ../working_data/script/_lib/lib_battle_manager.lua, line 2644

Back to top

Showing/Hiding UI

battle_manager:show_ui([boolean should show])
Shows/hides the battle UI from script.

Parameters:

1

boolean

optional, default value=true

should show

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 2692

battle_manager:show_army([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 ../working_data/script/_lib/lib_battle_manager.lua, line 2711

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 ../working_data/script/_lib/lib_battle_manager.lua, line 2735

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 ../working_data/script/_lib/lib_battle_manager.lua, line 2759

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 ../working_data/script/_lib/lib_battle_manager.lua, line 2783

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 ../working_data/script/_lib/lib_battle_manager.lua, line 2807

battle_manager:show_start_battle_button([boolean should show], [boolean is multiplayer])
Shows/hides the start battle button.

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 ../working_data/script/_lib/lib_battle_manager.lua, line 2831

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 ../working_data/script/_lib/lib_battle_manager.lua, line 2860

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 ../working_data/script/_lib/lib_battle_manager.lua, line 2886

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.

Parameters:

1

boolean

optional, default value=true

should enable

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 2911

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

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 2926

Back to top

Engagement Monitor

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

The Engagement monitor tracks the following information:

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

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

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

The Engagement monitor also triggers the following events:

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

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

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

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

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

  • ScriptEventPlayerGeneralRouts, if the player's general routs.

  • ScriptEventEnemyGeneralRouts, if the enemy general routs.

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

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

  • ScriptEventEnemyUnitRouts, if one of the enemy units routs.

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

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

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 2962

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 ../working_data/script/_lib/lib_battle_manager.lua, line 3318

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 ../working_data/script/_lib/lib_battle_manager.lua, line 3330

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 ../working_data/script/_lib/lib_battle_manager.lua, line 3342

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 ../working_data/script/_lib/lib_battle_manager.lua, line 3354

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 ../working_data/script/_lib/lib_battle_manager.lua, line 3366

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

Returns:

  1. number average altitude

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 3378

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

Returns:

  1. number average altitude

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 3390

battle_manager:stop_engagement_monitor()
Stops the engagement monitor.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 3402

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 ../working_data/script/_lib/lib_battle_manager.lua, line 3422

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 ../working_data/script/_lib/lib_battle_manager.lua, line 3495

Last updated 07/02/21 06:39:14