Battle Documentation

output

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6867

battle:error(string message)

Shows an assert dialog with the supplied message.

Parameters:

battle:local_alliance()

message

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6906

Battle Objects

battle:alliances()

Creates and returns a alliances object listing all alliances on the battlefield.

Returns:

alliances alliances list

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6922

Returns the index number of the alliance that corresponds to the player on the local machine. This can be used to look up the player's alliance from within the alliances collection that may be retrieved with battle:alliances. In any singleplayer battle this should return 1.

Returns:

number local alliance number

Example:


								 alliances = bm:alliances()

								 player_alliance = alliances:item(bm:local_alliance())

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6935

battle:local_army()

Returns the index number of the army (within the relevant armies collection object) that corresponds to the player on the local machine. This can be used to look up the player's army

Returns:

number local army number

Example:


								 alliances = bm:alliances()

								 player_alliance = alliances:item(bm:local_alliance())

								 player_army = player_alliance:armies():item(bm:local_army())

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6946

battle:winner_alliance_id()

returns the alliance id of the winning alliance

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6957

battle:buildings()

Creates and returns a buildings object listing all buildings on the battlefield.
WARNING: at time of writing this buildings object is broken. This functionality should not be used.

Returns:

buildings buildings list

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6967

battle:assault_equipment()

Creates and returns a assault_equipment object listing all vehicles (such as siege towers and battering rams) on the battlefield.

Returns:

assault_equipment assault equipment list

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6981

battle:debug_drawing()

Creates and returns a debug_drawing object, allowing the script to draw debug lines on the battlefield.

Returns:

debug_drawing debug drawing object

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 6994

battle:camera()

Creates and returns a camera object.

Returns:

camera battle camera

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7007

battle:subtitles()

Creates and returns a subtitles object.

Returns:

subtitles subtitles

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7035

Handlers

battle:register_input_handler(string input handler function)

Registers a function (by string name) as a handler for input events. Input events are triggered when the player makes certain inputs. Valid input events are:

"move forward"

"move forward fast"

"move backward"

"move left"

"move right"

"rotate right"

"rotate left"

"move up"

"move down"

"rotate up"

"rotate down"

"edge rotate right"

"edge rotate left"

"edge move left"

"edge move right"

"edge move forward"

"edge move backward"

When an input event occurs, the registered function is called with the relevant input event string as a single argument. Note that the function being registered must have already been declared when register_input_handler is called.
Once registered, an input handler may be unregistered with battle:unregister_input_handler.

Parameters:

battle:unregister_input_handler()

input handler function

Returns:

nil

Example:


								 function my_input_handler(event_name)

								     if event_name == "move_forward" then

								        -- do something in response to the move_forward event

								    end

								 end

								 bm:register_input_handler("my_input_handler")

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7051

Unregisters the currently-registered input handler function. An input handler may be registered with battle:register_input_handler.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7085

battle:register_unit_selection_handler(string input handler function)

Registers a function (by string name) as a handler for user selection events. These events are triggered when the player selects or deselects units. When such an event occurs, the registered function is called with two arguments - the first being a unit object representing the unit concerned, the second being a boolean flag indicating whether the unit is being selected or deselected. Note that the function being registered must have already been declared when register_unit_selection_handler is called.

Parameters:

battle:unregister_unit_selection_handler()

input handler function

Returns:

nil

Example:


								 function my_unit_selection_handler(unit, is_selected)

								     if is_selected then

								        -- track selected units

								    else

								        -- track unselected units

								    end

								 end

								 bm:register_unit_selection_handler("my_unit_selection_handler")

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7093

Unregisters the currently-registered unit selection handler function. A unit selection handler may be registered with battle:register_unit_selection_handler.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7110

battle:register_command_handler(string command handler function)

Registers a function (by string name) as a handler for command events. Command events are triggered when the player (or script) issues certain commands. When such an event occurs, the registered function is called and passed an event object as a single argument. This object provides several methods which can be used to determine information about the issued command. These methods are listed below:

Method	Description
`event:get_name()`	Returns the `string` name of the issued command. This is provided for every event type.
`event:get_bool1()`	Returns a `boolean` value related to the issued command, if any.
`event:get_string1()`	Returns a `string` value related to the issued command, if any.
`event:get_position()`	Returns a `battle_vector` related to the issued command, if any.
`event:get_unit()`	Returns a `unit` related to the issued command, if any.
`event:get_building()`	Returns a `building` related to the issued command, if any.

Note that each event type only provides methods that are relevant. The list of valid event types, and what methods they provide, are listed here:

Event Type	Event Description	Method Provided	Method Return Type	Method Description
`Group Created`	A group has been created	`event:get_name()`	`string`	Name of event
`Group Destroyed`	A group has been disbanded	`event:get_name()`	`string`	Name of event
`Repair Mode`	A command to repair a ship has been issued	`event:get_name()`	`string`	Name of event
`Move`	A movement command has been issued	`event:get_name()`	`string`	Name of event
`Move`	A movement command has been issued	`event:get_bool1()`	`boolean`	Indicates whether the unit is now moving fast/running
`Move Orientation Width`	A movement command with orientation and width has been issued	`event:get_name()`	`string`	Name of event
`Move Rotation Angle`	A rotation command has been issued	`event:get_name()`	`string`	Name of event
`Change Speed`	The speed of a unit has been toggled	`event:get_name()`	`string`	Name of event
`Change Speed`	The speed of a unit has been toggled	`event:get_bool1()`	`boolean`	Indicates whether the unit is now moving fast/running
`Attack Unit`	A command to attack a unit has been issued	`event:get_name()`	`string`	Name of event
		`event:get_bool1()`	`boolean`	Indicates whether the unit is now moving fast/running
		`event:get_unit()`	`unit`	Returns the target unit
`Change Skirmish`	Skirmish mode has been toggled on a unit	`event:get_name()`	`string`	Name of event
`Change Skirmish`	Skirmish mode has been toggled on a unit	`event:get_bool1()`	`boolean`	Indicates whether skirmish mode is now enabled
`Change Melee`	Melee mode has been toggled on a unit	`event:get_name()`	`string`	Name of event
`Change Melee`	Melee mode has been toggled on a unit	`event:get_bool1()`	`boolean`	Indicates whether melee mode is now enabled
`Change Formation`	A command to change formation has been issued	`event:get_name()`	`string`	Name of event
`Change Formation`	A command to change formation has been issued	`event:get_string1()`	`string`	Returns the name of the formation
`Attack Building`	A command to attack a building has been issued	`event:get_name()`	`string`	Name of event
		`event:get_bool1()`	`boolean`	Indicates whether the unit is now moving fast/running
		`event:get_building()`	`building`	Returns the target building
`Climb/Dock Building`	A command to climb a building has been issued	`event:get_name()`	`string`	Name of event
		`event:get_bool1()`	`boolean`	Indicates whether the unit is now moving fast/running
		`event:get_building()`	`building`	Returns the target building
`Special Ability`	A command to use a special ability has been issued	`event:get_name()`	`string`	Name of event
`Special Ability`	A command to use a special ability has been issued	`event:get_string1()`	`string`	Returns the name of the special ability
`Shot Type`	A command to change shot type has been issued	`event:get_name()`	`string`	Name of event
`Shot Type`	A command to change shot type has been issued	`event:get_string1()`	`string`	Returns the name of the shot type
`Fire At Will`	Fire-at-will mode has been toggled on a unit	`event:get_name()`	`string`	Name of event
`Broadside Attack`	A broadside attack command has been issued	`event:get_name()`	`string`	Name of event
`Broadside Attack`	A broadside attack command has been issued	`event:get_bool1()`	`boolean`	Returns `true` if the broadside is on the left side of the ship, `false` otherwise
`Naval Shot Type`	A command to change the shot type of a ship has been issued	`event:get_name()`	`string`	Name of event
`Naval Shot Type`	A command to change the shot type of a ship has been issued	`event:get_string1()`	`string`	Returns the name of the shot type
`Ram`	A command to ram a ship has been issued	`event:get_name()`	`string`	Name of event
`Withdraw`	A command to withdraw a unit has been issued	`event:get_name()`	`string`	Name of event
`Withdraw`	A command to withdraw a unit has been issued	`event:get_bool1()`	`boolean`	Indicates whether the unit is now moving fast/running
`Halt`	A command to halt a unit has been issued	`event:get_name()`	`string`	Name of event
`Double Click`	The double-click UI gesture has been issued for the selected units	`event:get_name()`	`string`	Name of event
`Entity Hit`	A unit has been hit by a projectile	`event:get_name()`	`string`	Name of event
		`event:get_bool1()`	`boolean`	Indicates whether artillery fired the projectile
		`event:get_unit()`	`unit`	Returns the unit that was hit
`Double Click Unit Card`	A unit card has been double-clicked upon	`event:get_name()`	`string`	Name of event
`Double Click Unit Card`	A unit card has been double-clicked upon	`event:get_unit()`	`unit`	Returns the subject unit
`Unit Left Battlefield`	A unit has left the battlefield	`event:get_name()`	`string`	Name of event
`Unit Left Battlefield`	A unit has left the battlefield	`event:get_unit()`	`unit`	Returns the subject unit
`Battle Results`	The battle has finished and the results have been issued	`event:get_name()`	`string`	Name of event
`Battle Results`	The battle has finished and the results have been issued	`event:get_bool1()`	`boolean`	Indicates whether the local alliance won the battle

Note that the function being registered must have already been declared when register_command_handler is called.

Parameters:

battle:unregister_command_handler()

command handler function

Returns:

nil

Example:


								 function my_command_handler(event)

								     local event_name = event:get_name()

								     if event_name == "Move" then

								        -- handle move orders

								    elseif event_name == "Attack Unit" then

								        -- handle attack unit orders

								    end

								 end

								 bm:register_command_handler("my_command_handler")

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7118

Unregisters the currently-registered command handler function. A command handler may be registered with battle:register_command_handler.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7175

battle:register_battle_phase_handler(string function name)

Registers a function (by string name) as a handler for battle phase changes. Battle phase changes are triggered when the battle moves into various distinct phases, the most important being the deployment and deployment (combat) phases. When a battle phase occurs, the registered function is called and passed the string name of the new battle phase as a single argument. Valid phases are listed below:

Phase Name	Description
`Startup`	This phase change is triggered after the scripts are loaded.
`PrebattleWeather`	Triggered after `Startup` phase.
`PrebattleCinematic`	Triggered after `PrebattleWeather` phase.
`Deployment`	Deployment phase, when both alliances get to position their troops prior to combat.
`Deployed`	Combat phase, in which the battle is fought.
`VictoryCountdown`	A victor for the battle has been determined, and the battle is counting down to completion.
`Complete`	The battle is completed.

Note that the function being registered must have already been declared when register_unit_selection_handler is called. Furthermore, it is recommended that battle_manager:register_phase_change_callback is used in place of this function.

Parameters:

battle:unregister_battle_phase_handler()

Function name to call when phase change event occurs.

Returns:

nil

Example:


								 function my_phase_change_handler(phase_change)

								     local 

								     if phase_change == "deployment" then

								        -- handle deployment phase

								    elseif phase_change == "deployed" then

								        -- handle combat phase

								    end

								 end

								 bm:register_phase_change_handler("my_phase_change_handler")

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7183

Unregisters the currently-registered phase change handler function. A phase change handler may be registered with battle:register_battle_phase_handler.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7210

battle:end_current_battle_phase()

Immediately ends the current battle phase, moving on to the next phase. The main use for this function is to force deployment phase to end - calling this function has no effect in combat phase. More information about battle phases can be found in the Battle Phases section of this documentation.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7218

Time and Timers

battle:timer_exists(string function name)

Returns whether a timer exists for the specified function name. If a timer does exist, the amount of model time remaining before it triggers in ms is also returned as a second return parameter.

Parameters:

function name

Returns:

boolean timer exists
number model time before timer triggers

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7229

battle:register_singleshot_timer(string function name, number interval)

Registers a singleshot timer. A function name must be specified as a string, along with an interval. The battle model then calls the function with the given name after the specified interval. No arguments may be specified for the function. Only one timer instance can be registered for a given function - repeated calls to battle:register_singleshot_timer or battle:register_repeating_timer will overwrite any previous timers.
It is strongly recommended that client scripts do not call this directly but instead use the battle_manager:callback function, which allows arguments to be passed, multiple instances of timers for the same callback, and more flexible cancellation of the callback.

Parameters:

1	`string`	Function name.
2	`number`	Interval in ms.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7240

battle:register_repeating_timer(string function name, number interval)

Registers a repeating timer. A function name must be specified as a string, along with an interval. The battle model then calls the function with the given name each time the specified interval elapses. No arguments may be specified for the function. Only one timer instance can be registered for a given function. Only one timer instance can be registered for a given function - repeated calls to battle:register_singleshot_timer or battle:register_repeating_timer will overwrite any previous timers.
It is strongly recommended that client scripts do not call this directly but instead use the battle_manager:repeat_callback function, which allows arguments to be passed, multiple instances of timers for the same callback, and more flexible cancellation of the callback.

Parameters:

1	`string`	Function name.
2	`number`	Interval in ms.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7251

battle:unregister_timer(string function name)

Unegisters a timer (whether registered with battle:register_singleshot_timer or battle:register_repeating_timer), by it's string function name. In the case of a singleshot function this must be called before the function is triggered.
It is strongly recommended that client scripts use battle_manager:callback, battle_manager:repeat_callback and then battle_manager:remove_process due to ease-of-use.

Parameters:

battle:time_elapsed_ms()

Function name to unregister.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7262

Returns the amount of model time that's elapsed since the start of the battle, in milliseconds.

Returns:

number time elapsed

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7272

battle:model_tick_time_ms()

Returns the model tick time in milliseconds. This is the target interval over which the battle model repeatedly updates - 100ms or 200ms.

Returns:

number tick time

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7281

battle:remaining_conflict_time()

Returns the duration remaining before the battle time limit expires, in seconds. If no time limit is set then -1 is returned.

Returns:

number remaining time

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7290

battle:modify_battle_speed(number battle speed)

Adjusts the game speed. The value supplied should be a unary proportion of normal speed, for example:

Set a speed of 1 to run the battle at normal speed.

Set a speed of 3 to run the battle at triple speed.

Set a speed of 0.5 to run the battle at half speed.

Set a speed of 0 to pause the battle.

Beware that pausing the battle will prevent model time from advancing, which will also affect script.
The battle speed may be restored to the value previously set by the player by calling battle:restore_battle_speed.

Parameters:

battle:restore_battle_speed()

battle speed

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7299

Restores the game speed to the value that was previously set when battle:modify_battle_speed was last called.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7314

battle:battle_terrain_folder_and_catchment()

Returns the current battle terrain folder and catchment area.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7321

battle:change_conflict_time_update_overridden()

Enables or disables the countdown of the conflict timer. 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.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7329

battle:change_victory_countdown_limit(number time limit)

Change the victory countdown limit. This is the grace period that begins counting down once a victor in the battle has been determined but before the battle actually ends, and is usually ten seconds. Battle scripts can use this function to adjust the duration of this countdown in order to display outro advice or cutscene content without having it cut off.
Supply a limit of less than 0 to make the victory countdown period infinite. If the battle enters the victory countdown phase with an infinite period set, and then a limit of 0 is set with a subsequent call to this function, the battle complete phase will trigger immediately.

Parameters:

Time limit in seconds.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7337

Cindy and Composite Scenes

battle:cindy_preload(string scene path)

Preloads a cindy scene. Calling this prior to a cindy scene being played can help prevent a noticeable stall at the start of playback.

Parameters:

Path to the cindy scene manager file, from the working data folder.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7350

battle:cindy_playback(string scene path, [number blend in], [number blend out])

Starts a cindy scene. This plays a cindy cinematic, taking control of the camera. battle:cindy_preload can be called prior to calling this function to preload the scene data.

Parameters:

Path to the cindy scene manager file, from the working data folder.

optional, default value=0

Blend in duration in seconds.

optional, default value=10

Blend out duration in seconds.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7359

battle:cindy_playback_no_camera(string scene path, boolean clear scene, [boolean save to replay])

Starts a cindy scene without a camera track. This can be run in parallel with a scene initiated with battle:cindy_playback. battle:cindy_preload can be called prior to calling this function to preload the scene data.

Parameters:

Path to the cindy scene manager file, from the working data folder.

Clear animated scenes on completion.

optional, default value=true

Saves the cindy scene into the battle replay, so if the replay is loaded the cindy scene plays again.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7370

battle:stop_cindy_playback([boolean clear animated scenes])

Stops a cindy scene that was started with battle:cindy_playback.

Parameters:

optional, default value=false

clear animated scenes

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7381

battle:stop_cindy_playback_no_camera([boolean clear animated scenes])

Stops a cindy scene that was started with battle:cindy_playback_no_camera.

Parameters:

optional, default value=false

clear animated scenes

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7390

battle:start_terrain_composite_scene(string scene key)

Starts a composite scene. The composite scene should be specified by its path from the working data folder.

Parameters:

Composite scene key.

Returns:

nil

Example:


								 bm:start_terrain_composite_scene("composite_scene/seamonster/merwyrm_roar_02.csc")

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7399

battle:stop_terrain_composite_scene(string scene key)

Stops a composite scene. The composite scene should be specified by its path from the working data folder.

Parameters:

Composite scene key.

Returns:

nil

Example:


								 bm:stop_terrain_composite_scene("composite_scene/seamonster/merwyrm_roar_02.csc")

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7409

Advice and Audio

battle:play_adc(string adc key, number x, number y, number z, boolean for player)

Manually triggers an aide-de-camp message at a specified location on the battlefield.

Parameters:

1	`string`	Aide-de-camp key, from the `aide_de_camp_speeches` database table.
2	`number`	X co-ordinate of message, in m.
3	`number`	Y co-ordinate (altitude) of message, in m.
4	`number`	Z co-ordinate of message, in m.
5	`boolean`	Aide-de-camp message is for the player's alliance.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7432

battle:suspend_contextual_advice(boolean should suspend)

Prevents advice from being triggered with effect.advance_contextual_advice_thread, which has the effect of suspending advice not triggered deliberately by battle scripts. This has been made largely redundant by changes in the way scripts trigger advice, but can still be called.

Parameters:

battle:close_advisor()

should suspend

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7445

Dismisses the advisor, if currently shown.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7454

battle:advice_finished()

Returns whether or not any advice is currently playing. A value of true is returned if no advice is playing, false if it is.

Returns:

boolean advice finished

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7462

battle:vo_finished()

Returns whether or not any voiceover sounds are currently playing. A value of true is returned if no voiceover sounds are playing, false otherwise.

Returns:

boolean vo finished

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7471

battle:suppress_unit_voices(boolean should suppress)

Disables or re-enables unit voices in battle. If unit voices are suppressed, ambient voiceover related to units will not be played.

Parameters:

should suppress

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7481

battle:suppress_unit_musicians(boolean should suppress)

Disables or re-enables unit musicians in battle.

Parameters:

should suppress

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7497

battle:set_music_auto_playback(boolean auto playback)

Enables or disables the automatic management of music by the game. Music-auto-playback should be disabled using this function if music is to be scripted.

Parameters:

Automatic music playback enabled.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7506

battle:set_music_loop(boolean should loop)

Sets whether scripted music should loop.

Parameters:

should loop

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7515

battle:play_music(string music name)

Plays a specified piece of music. The music to play is specified by its sound event name.

Parameters:

battle:stop_music()

music name

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7524

battle:play_music_custom_fade(string music name, number fade time)

Plays a specified piece of music with a custom fade-in duration. The music to play is specified by its sound event name.

Parameters:

1	`string`	Music sound event.
2	`number`	Fade time in seconds.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7533

Stops the currently-playing music.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7543

battle:stop_music_custom_fade(number fade time)

Stops the currently-playing music with a custom fade time.

Parameters:

Fade time in seconds.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7551

battle:get_volume(number volume type)

Gets the volume level of a specific volume type. Valid volume types are given in the Volume Types section of this documentation. The volume level will be returned as a number between 0 (inaudible) and 100 (full volume).

Parameters:

battle:is_movie_playing()

volume type

Returns:

number volume level

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7567

battle:set_volume(number volume type, number volume level)

Sets the volume level of a specific volume type. Valid volume types are given in the Volume Types section of this documentation. The volume level should be set as a number between 0 (inaudible) and 100 (full volume).

Parameters:

1	`number`	volume type
2	`number`	volume level

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7577

battle:fade_volume(number volume type, number target level, number fade time)

Gradually fades the volume level of a specified volume type to a specified value over a specified interval. Valid volume types are given in the Volume Types section of this documentation. The volume level should be set as a number between 0 (inaudible) and 100 (full volume).

Parameters:

1	`number`	Volume type.
2	`number`	Target volume level.
3	`number`	Fade time in seconds.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7587

Objectives and Markers

battle:add_ping_icon(number x, number y, number x, [number type], [boolean is waypoint], [number rotation])

Adds a 3d ping marker model at a specified [x/y/z] position. It is sufficient just to supply the position, but a type can be used to change the model displayed - see the table below for a list of ping types.
List of ping types:

Type Number	Type Name
0	MPT_NONE
1	MPT_STANDARD
2	MPT_MOVE
3	MPT_ATTACK
4	MPT_DEFEND
5	MPT_HELP_MOUNTABLE_ARTILLERY
6	MPT_HELP_DISEMBARK
7	MPT_NOTIFICATION
8	MPT_SCRIPT_LOOK_AT
9	MPT_SCRIPT_MOVE_TO
10	MPT_SCRIPT_SELECT
11	MPT_SCRIPT_POINTER
12	MPT_SCRIPT_LOOK_AT_VFX
13	MPT_SCRIPT_MOVE_TO_VFX
14	MPT_SCRIPT_SELECT_VFX

The waypoint flag can be used to link models together. The rotation flag can be used to specify a rotation for the model - the default is to just fade the camera.

Parameters:

1	`number`	X co-ordinate in metres.
2	`number`	Y co-ordinate (altitude) in metres. This parameter specifies the height above the water plane, so if mis-set the marker can appear under the ground.
3	`number`	X co-ordinate in metres.
4	`number`	optional, default value=0 Marker type - see list of valid marker types above.
5	`boolean`	optional, default value=false Is waypoint.
6	`number`	optional, default value=nil Rotation.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7601

battle:remove_ping_icon(number x, number y, number x)

Removes the ping marker that was previously added with battle:add_ping_icon at a specified [x/y/z] position.

Parameters:

1	`number`	X co-ordinate in metres.
2	`number`	Y co-ordinate (altitude) in metres.
3	`number`	X co-ordinate in metres.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7633

battle:show_objective(string objective key, number duration, number fade duration)

Shows an objective message on-screen. This is an old method of showing an objective-style message, which will fade in at the bottom-centre of the screen, remain on-screen for a specified period and then fade out.

Parameters:

1	`string`	Objective key, from the `scripted_objectives` table.
2	`number`	Duration that the objective should remain on-screen in ms.
3	`number`	Duration over which the objective should fade to transparent once its display duration has elapsed.

Returns:

nil

Example - Show an objective key for 5 seconds, then fading out over 2 seconds.:


								 bm:show_objective("my_objective_key", 5000, 2000)

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7644

Fullscreen Movies

battle:play_movie(string movie path, boolean play movie audio)

Plays a fullscreen movie during a battle. The movie should be specified by a file path from the Movies folder in working data (see the videos table for examples of valid paths).

Parameters:

1	`string`	Path to movie file. The file extension may be omitted.
2	`boolean`	Play movie audio - if `false` is supplied then game audio is heard instead.

Returns:

nil

Example:


								 bm:play_movie("startup_movie_01", true)

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7660

Returns whether or not a fullscreen movie is currently playing.

Returns:

boolean is movie playing

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7671

UI and UI Suppression

battle:ui_component(string uicomponent name)

Searches from the root uicomponent for a uicomponent with the specified name, returning the first that matches. It is encouraged that find_uicomponent is used in place of this function.

Parameters:

uicomponent name

Returns:

uicomponent uicomponent, or nil if no component found

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7683

battle:enable_cinematic_ui( boolean enable cinematic ui, [booleanshow cursor], [booleanenable cinematic bars] )

Enables or disables a script lock on the state of the cinematic UI. Additional parameters may be used to enable/disable the mouse cursor and cinematic bars respectively.
Note that it is rare for clients scripts to need to call this directly - consider using the cutscene functionality provided by the script libraries.

Parameters:

Enable or disables the script lock on the cinematic UI. By setting this, the script will lock the state of the cinematic UI (whether the cursor is shown, or the cinematic bars are visible). If this is set the wider UI will not be able to show/unshow the cursor or cinematic bars until the lock is disabled again.

optional, default value=nil

Shows or hides the cursor. If this flag is not supplied then the state of the cursor will remain unchanged.

optional, default value=nil

Enables the cinematic bars. If this flag is not supplied then the state of the cinematic bars will remain unchanged.

Returns:

nil

Example - Enable the cinematic UI, disabling the mouse cursor and showing cinematic borders:

By enabling the cinematic UI with the first argument, the UI will know not to re-enable the mouse cursor or hide the cinematic borders.


								 bm:enable_cinematic_ui(true, false, true)

Example - Disable the cinematic UI, re-enable the mouse and hide the cinematic borders afterwards:


								 bm:enable_cinematic_ui(false, true, false)

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7693

battle:enable_unit_ids(boolean show ids)

Enables or disables the unit IDs - the flags or icons floating above each unit in battle. This provides exactly the same functionality as battle:set_banners_enabled, except the removal/reinstatement of banners in this case will be preserved in replays.
Note that the cutscene functionality provided by the script libraries automatically disables unit ids while the cutscene is playing - use cutscene:set_should_disable_unit_ids to disable this for a given cutscene rather than calling this function directly.

Parameters:

show ids

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7710

battle:enable_cinematic_camera(boolean enable cinematic camera)

Enables or disables the cinematic camera. The cinematic camera is not limited by altitude or proximity to the player's army - it can be positioned anywhere on the battlefield, including below the ground. This can be enabled for cutscenes but should be disabled for live gameplay.
Note that it is rare for clients scripts to need to call this directly - consider using the cutscene functionality provided by the script libraries. A cutscene can be prevented from enabling the cinematic camera with cutscene:set_should_enable_cinematic_camera.

Parameters:

enable cinematic camera

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7720

battle:enable_tooltips(boolean enable tooltips)

Enables or disables tooltips.

Parameters:

enable tooltips

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7730

battle:force_minimised_tooltips(boolean set minimised tooltips)

Forces tooltips into minimised mode.

Parameters:

set minimised tooltips

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7739

battle:disable_groups(boolean disable grouping)

Disables or enables grouping functionality.

Parameters:

disable grouping

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7748

battle:disable_formations(boolean disable formations)

Disables or enables formations functionality.

Parameters:

disable formations

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7757

battle:disable_orders(boolean disable orders)

Disables or enables the giving of any orders at all.

Parameters:

battle:steal_escape_key()

disable orders

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7766

Steals the escape key from the UI. This prevents the UI from intercepting ESC key presses and allows script to detect and process them instead. When the escape key is stolen, a script function called Esc_Key_Pressed will be called when the escape key is pressed by the player.
Note that the escape key will remain stolen from the UI until battle:release_escape_key is called.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7775

battle:release_escape_key()

Releases the stolen escape key from the script, allows the UI to intercepting ESC key presses again. This must be called at some point after battle:steal_escape_key is called.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7784

battle:steal_input_focus()

Steals all keyboard input from the UI, effectively disabling the keyboard in the game. After input focus is stolen by a call to this function, it must be released again with battle:release_input_focus at some point.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7792

battle:release_input_focus()

Releases keyboard input back to the UI after its theft with battle:steal_input_focus.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7800

battle:disable_shortcut(string shortcut name, boolean should disable)

Disables or re-enables a keyboard shortcut by name. A list of keyboard shortcuts is available from the UI team.

Parameters:

1	`string`	shortcut name
2	`boolean`	should disable

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7808

battle:set_banners_enabled(boolean show ids)

Enables or disables the unit IDs - the flags or icons floating above each unit in battle. This provides exactly the same functionality as battle:enable_unit_ids, except the removal/reinstatement of banners in this case will be not preserved in replays.
Note that the cutscene functionality provided by the script libraries automatically disables unit ids while the cutscene is playing - use cutscene:set_should_disable_unit_ids to disable this for a given cutscene rather than calling this function directly.

Parameters:

battle:is_tutorial()

show ids

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7818

Querying

Returns the value of the is_tutorial flag. This can be set in the battle setup to activate certain behaviours.

Returns:

boolean is_tutorial flag

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7831

battle:prepare_for_fade_in()

Returns the value of the prepare_for_fade_in flag. This can be set in the battle setup to show a black screen when the battle starts up.

Returns:

boolean prepare_for_fade_in flag

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7840

battle:is_battle_over()

Returns whether the battle is completely finished.

Returns:

boolean battle is over

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7849

battle:is_siege_battle()

Returns whether or not the battle is a siege battle.

Returns:

boolean is siege battle

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7858

battle:is_ambush_battle()

Returns whether or not the battle is an ambush battle.

Returns:

boolean is ambush battle

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7867

battle:battle_type()

Returns the battle type as a string.

Returns:

string battle type

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7876

battle:get_terrain_height(number x, number y)

Returns the height of the terrain at the specified x/y co-ordinates. This is intended for use to calculate camera and ping marker positions.

Parameters:

1	`number`	X co-ordinate in m.
2	`number`	Y co-ordinate in m.

Returns:

number height in m.

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7885

battle:random_number()

Generate a battle-synchronised random number between 0 and 1.

Returns:

number random number

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7896

Benchmarking and Autotesting

battle:is_benchmarking_mode()

Returns whether this battle has been loaded in benchmarking mode or not. This should only return true if the battle was loaded through the benchmark menu on the frontend.

Returns:

boolean is benchmarking mode

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7908

battle:end_benchmark()

Ends a currently-running benchmark, showing benchmarking statistics and ending the battle.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7917

battle:quit_to_windows_from_script()

Causes the game to completely shut down.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7925

battle:take_screenshot([string filepath])

Takes a screenshot of the battle. This is used by the autotest system.

Parameters:

battle:appdata_screenshots()

optional, default value=nil

Path of the screenshot file. If none is specified the system will generate a default.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7933

Returns a path to the screenshots directory. This is used by the autotest system.

Returns:

string screenshot directory

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7942

Miscellaneous

battle:trigger_projectile_launch( string projectile key, battle_vectorlaunch position, battle_vectortarget position)

Trigger a projectile launch from one position to another. Be careful to shoot downwards if you have artillery projectiles, as they are designed to be lobbed.

Parameters:

1	`string`	Projectile key from the `projectiles` table.
2	`battle_vector`	Launch position.
3	`battle_vector`	Target position.

Returns:

nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 7961

battle:unlock_achievement(string achievement key)

Unlocks a steam achievement by string key. Achievements have to be set up elsewhere to be unlockable with this function.

Parameters: