Generated Battle

The generated battle system is designed to allow scripters to create battles of moderate complexity relatively cheaply. The central premise of the generated battle system is that events are directed without needing to refer to the individual units, which would be the case with full battle scripts. Instead, orders are given and conditions are detected at army level (or across the battle as a whole). This limits the complexity of what can be done but allows for a much simpler interface. The generated battle system is used to script most/all quest battles.

A generated_battle object is created first with generated_battle:new, and from that multiple generated_army objects are created using calls to generated_battle:get_army, one for each conceptual army on the battlefield. A conceptual army may be an entire army in the conventional sense, or it may be a collection of units within an army grouped together by a common script_name.

Commands are given through the use of messages, built on the script_messager system. Once created, the generated_battle object and generated_army objects can be instructed to listen for certain messages, and act in some manner when they are received. Additionally, the generated_battle and generated_army objects can be instructed to trigger messages when certain conditions are met e.g. when under attack. Using these tools, scripted scenarios of surprising complexity may be constructed relatively easily.

The message listeners a generated_battle object provides can be viewed here: Message Listeners, and the messages it can generate can be viewed here: Message Generation. The message listeners a generated_army object provides can be viewed here: Message Listeners, and the messages it can generate can be viewed here: Message Generation.

Example:

A simple generate battle script that sets up two opposing armies. The army in the second alliance is set to defend a position at the start of the battle and then rout when it takes 50% casualties
load_script_libraries();
bm = battle_manager:new(empire_battle:new());

-- declare generated battle object
gb = generated_battle:new(
    false,                        -- screen starts black
    true,                        -- prevent deployment for player
    true,                        -- prevent deployment for ai
    nil,                        -- intro cutscene function
    false                        -- debug mode
);

-- declare generated army objects
ga_player_01 = gb:get_army(gb:get_player_alliance_num());
ga_ai_01 = gb:get_army(gb:get_non_player_alliance_num());

-- ai defends position [-100, 400] when the battle starts
ga_ai_01:defend_on_message("battle_started", -100, 400, 100);

-- rout the enemy army over 10s when they take 50% casualties
ga_ai_01:message_on_casualties("rout_ai_army", 0.5);
ga_ai_01:rout_over_time_on_message("rout_ai_army", 10000);

Loaded in Battle loaded in battle
Back to top

Self-Generated Messages

The generated battle object and other related objects send the following messages during battle automatically:

  • "deployment_started" when the deployment phase begins.

  • "battle_started" when the playable combat phase begins.

  • "battle_ending" when the VictoryCountdown phase begins (someone has won).

  • "cutscene_ended" when any cutscene ends.

  • "generated_custscene_ended" when a generated cutscene ends.

  • "outro_camera_finished" when the outro camera movement on a generated cutscene intro has finished.

Back to top

Creation

generated_battle:new(
  [boolean screen starts black],
  [boolean prevent player deployment],
  [boolean prevent ai deployment],
  [function intro cutscene],
  [boolean debug mode]
)
Creates a generated_battle. There should be only one of these per-battle script.

Parameters:

1

boolean

optional, default value=false

The screen starts black. This should match the prepare_for_fade_in flag in the battle setup, which always seems to be true for quest battles. Furthermore, this flag is only considered if no intro cutscene callback is specified.

2

boolean

optional, default value=false

Prevents player control during deployment.

3

boolean

optional, default value=false

Prevents deployment for the ai.

4

function

optional, default value=nil

Intro cutscene callback. This is called when deployment phase ends, unless generated_battle:set_cutscene_during_deployment is set.

5

boolean

optional, default value=false

Turns on debug mode, for more output.

Returns:

  1. generated_battle

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 95

Back to top

Configuration

generated_battle:set_cutscene_during_deployment([boolean play in deployment])
Sets the supplied intro cutscene callback specified in generated_battle:new to play at the start of deployment, rather than at the end.

Parameters:

1

boolean

optional, default value=true

play in deployment

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 397

Back to top

Querying

generated_battle:has_battle_started()
Returns true if the combat phase of the battle has started, false otherwise.

Returns:

  1. boolean battle has started

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 420

generated_battle:get_player_alliance_num()
Returns the index of the alliance the player is a part of.

Returns:

  1. number index

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 428

generated_battle:get_non_player_alliance_num()
Returns the index of the enemy alliance to the player.

Returns:

  1. number index

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 436

Back to top

Creating Generated Armies

generated_battle:get_army is called to create generated_army objects.

generated_battle:get_army(number alliance index, string script name)

Returns a generated_army corresponding to the supplied arguments. Use in one of two modes:
 - Supply an alliance number, an army number, and (optionally) a script name. This is the original way armies were specified in quest battle scripts. Returns a generated_army corresponding to the supplied alliance/army numbers, containing all units where the name matches the supplied script name (or all of them if one was not supplied). WARNING: at time of writing the ordering of armies in an alliance beyond the first cannot be guaranteed if loading from campaign, so specifying an army index in this case may not be a good idea.
 - Supply an alliance number and a script name. This supports the randomised ordering of armies in an alliance that we see from campaign.

Parameters:

1

number

alliance index

2

string

script name

Returns:

  1. boolean battle has started is specified then it will be assumed that the script name is a blank string. No more than one army in the specified alliance can contain units with the supplied script name.
  2. generated_army

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 455

Back to top

Script Message Listeners

generated_battle:add_listener(string message name, function callback to call, [boolean persistent])
Allows the generated_battle object to listen for a message and trigger an arbitrary callback. The call gets passed to the underlying script_messager - see script_messager:add_listener.

Parameters:

1

string

message name

2

function

callback to call

3

boolean

optional, default value=false

persistent

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 615

generated_battle:remove_listener(string message name)
Removes any listener listening for a particular message. This call gets passed through to script_messager:remove_listener.

Parameters:

1

string

message name

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 625

Back to top

Message Listeners

generated_battle:advice_on_message(string message, string advice key, [number wait offset in ms])
Takes a string message, a string advice key, and an optional time offset in ms. Instruct the generated_battle to play a piece of advice on receipt of a message, with the optional time offset so that it doesn't happen robotically at the same moment as the message.

Parameters:

1

string

message

2

string

advice key

3

number

optional, default value=0

wait offset in ms

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 644

generated_battle:play_sound_on_message(
  string message,
  battle_sound_effect sound,
  [vector position],
  [number wait offset],
  [string end message],
  [number minimum duration]
)
Instruct the generated_battle to play a sound on receipt of a message.

Parameters:

1

string

Play the sound on receipt of this message.

2

battle_sound_effect

Sound file to play.

3

vector

optional, default value=nil

Position at which to play the sound. Supply nil to play the sound at the camera.

4

number

optional, default value=0

Delay between receipt of the message and the supplied sound starting to play, in ms.

5

string

optional, default value=nil

Message to send when the sound has finished playing.

6

number

optional, default value=500

Minimum duration of the sound in ms. This is only used if an end message is supplied, and is handy during development for when the sound has not been recorded.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 682

generated_battle:stop_sound_on_message(string message, battle_sound_effect sound, [number wait offset])
Instructs the generated_battle to stop a sound on receipt of a message.

Parameters:

1

string

Stop the sound on receipt of this message.

2

battle_sound_effect

Sound file to stop.

3

number

optional, default value=0

Delay between receipt of the message and the supplied sound being stopped, in ms.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 756

generated_battle:start_terrain_composite_scene_on_message(
  string message,
  string scene key,
  [number wait offset],
  [string group name],
  [number delay if queued]
)
Instructs the generated_battle to start a terrain composite scene on receipt of a message. Terrain composite scenes are general-purpose scene containers, capable of playing animations, sounds, vfx and more.

Parameters:

1

string

Play the composite scene on receipt of this message.

2

string

Composite scene key.

3

number

optional, default value=0

Delay between receipt of the message and the scene being started, in ms.

4

string

optional, default value=false

Composite scene group name. If supplied, this prevents this composite scene being played at the same time as any other in the same group. See documentation for the underlying battle_manager:start_terrain_composite_scene function for more information.

5

number

optional, default value=false

Delay before playing in ms if queued. This only applies if a group name is set. See battle_manager:start_terrain_composite_scene for more information.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 794

generated_battle:stop_terrain_composite_scene_on_message(
  string message,
  string scene key,
  [number wait offset]
)
Instructs the generated_battle to stop a terrain composite scene on receipt of a message.

Parameters:

1

string

Stop the composite scene on receipt of this message.

2

string

Composite scene key.

3

number

optional, default value=0

Delay between receipt of the message and the scene being stopped, in ms.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 853

generated_battle:set_objective_on_message(
  string message,
  string objective key,
  [number wait offset],
  [number objective param a],
  [number objective param b]
)
Instructs the generated_battle to add a scripted obective to the objectives panel, or update an existing scripted objective, on receipt of a message. The scripted objective is automatically completed or failed when the battle ends, based on the winner of the battle.

Parameters:

1

string

Add/update the objective on receipt of this message.

2

string

Objective key to add or update.

3

number

optional, default value=0

Delay between receipt of the message and the objective being added/updated, in ms.

4

number

optional, default value=nil

First numeric objective parameter, if required. See documentation for objectives_manager:set_objective.

5

number

optional, default value=nil

Second numeric objective parameter, if required. See documentation for objectives_manager:set_objective.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 896

generated_battle:complete_objective_on_message(string message, string objective key, [number wait offset])
Instructs the generated_battle to mark a specified objective as complete, on receipt of a message. Note that objectives issued to the player are automatically completed if they win the battle.

Parameters:

1

string

Complete the objective on receipt of this message.

2

string

Objective key to complete.

3

number

optional, default value=0

Delay between receipt of the message and the objective being completed, in ms.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 941

generated_battle:fail_objective_on_message(string message, string objective key, [number wait offset])
Instructs the generated_battle to mark a specified objective as failed, on receipt of a message. Note that objectives issued to the player are automatically failed if they lose the battle.

Parameters:

1

string

Fail the objective on receipt of this message.

2

string

Objective key to fail.

3

number

optional, default value=0

Delay between receipt of the message and the objective being failed, in ms.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 981

generated_battle:remove_objective_on_message(string message, string objective key, [number wait offset])
Instructs the generated_battle to remove a specified objective from the UI on receipt of a message.

Parameters:

1

string

Remove the objective on receipt of this message.

2

string

Objective key to remove.

3

number

optional, default value=0

Delay between receipt of the message and the objective being removed, in ms.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 1021

generated_battle:set_locatable_objective_on_message(
  string message,
  string objective key,
  [number wait offset],
  vector camera position,
  vector camera target,
  number camera move time
)
Instructs the generated_battle to set a locatable objective on receipt of a message. See battle_manager:set_locatable_objective for more details.

Parameters:

1

string

Add/update the locatable objective on receipt of this message.

2

string

Objective key to add or update.

3

number

optional, default value=0

Delay between receipt of the message and the objective being added/updated, in ms.

4

vector

Camera position to zoom camera to when objective button is clicked.

5

vector

Camera target to zoom camera to when objective button is clicked.

6

number

Time the camera takes to pan to the objective when the objective button is clicked, in seconds.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 1061

generated_battle:set_locatable_objective_callback_on_message(
  string message,
  string objective key,
  [number wait offset],
  function camera position generator,
  number camera move time
)

Instructs the generated_battle to set a locatable objective using a callback on receipt of a message. The callback function should return two battle_vector objects that specify the camera position and target to zoom to - see battle_manager:set_locatable_objective_callback for more details.

Parameters:

1

string

Add/update the locatable objective on receipt of this message.

2

string

Objective key to add or update.

3

number

optional, default value=0

Delay between receipt of the message and the objective being added/updated, in ms.

4

function

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

5

number

Time the camera takes to pan to the objective when the objective button is clicked, in seconds.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 1122

generated_battle:add_ping_icon_on_message(
  string message,
  battle_vector marker position,
  number marker type,
  [number wait offset],
  [number duration]
)

Instructs the generated_battle to add a battlefield ping icon on receipt of a message. This is a marker that appears in 3D space and can be used to point out the location of objectives to the player.

Parameters:

1

string

Add the ping icon on receipt of this message.

2

battle_vector

Marker position.

3

number

Marker type. See the documentation for battle:add_ping_icon for a list of valid values.

4

number

optional, default value=0

Delay between receipt of the message and the marker being added, in ms.

5

number

optional, default value=nil

Duration that the marker should stay visible for, in ms. If not set then the marker stays on-screen until it is removed with generated_battle:remove_ping_icon_on_message.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 1174

generated_battle:remove_ping_icon_on_message(string message, vector marker position, [number wait offset])
Instructs the generated_battle to remove a battlefield ping icon on receipt of a message. The marker is specified by its position.

Parameters:

1

string

Remove the ping icon on receipt of this message.

2

vector

Marker position.

3

number

optional, default value=0

Delay between receipt of the message and the marker being removed, in ms.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 1235

generated_battle:fade_in_on_message(string message, number duration)
Takes a string message, and a fade duration in seconds. Fades the scene from black to picture over the supplied duration when the supplied message is received.

Parameters:

1

string

message

2

number

duration

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 1320

generated_battle:set_custom_loading_screen_on_message(string message, number duration)
Takes a string message and a string custom loading screen key. Sets that loading screen key to be used as the loading screen on receipt of the string message. This is used to set a custom outro loading screen.

Parameters:

1

string

message

2

number

duration

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 1345

generated_battle:start_terrain_effect_on_message(string message, string effect name, [number wait offset])
Instructs the generated_battle to start a terrain effect on receipt of a message.

Parameters:

1

string

Start the terrain effect on receipt of this message.

2

string

Effect name to start.

3

number

optional, default value=0

Delay between receipt of the message and the effect being started, in ms.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 1370

generated_battle:stop_terrain_effect_on_message(string message, string effect name, [number wait offset])
Instructs the generated_battle to stop a terrain effect on receipt of a message.

Parameters:

1

string

Stop the terrain effect on receipt of this message.

2

string

Effect name to stop.

3

number

optional, default value=0

Delay between receipt of the message and the effect being stopped, in ms.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 1410

generated_battle:queue_help_on_message(
  string message,
  string objective key,
  [number display time],
  [number display time],
  [number wait offset],
  [boolean high priority],
  [string message on trigger]
)
Enqueues a help message for display on-screen on receipt of a message. The message appears above the army panel with a black background. See Help Message Queue for more information. Note that if the battle is ending, this message will not display.

Parameters:

1

string

Enqueue the help message for display on receipt of this message.

2

string

Message key, from the scripted_objectives table.

3

number

optional, default value=10000

Time for which the help message should be displayed on-screen, in ms.

4

number

optional, default value=2000

Time for which the help message should be displayed on-screen, in ms.

5

number

optional, default value=0

Delay between receipt of the message and the help message being enqueued, in ms.

6

boolean

optional, default value=false

High priority advice gets added to the front of the help queue rather than the back.

7

string

optional, default value=nil

Specifies a message to be sent when this help message is actually triggered for display.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 1450

generated_battle:set_victory_countdown_on_message(string message, number countdown time)
Sets the victory countdown time for the battle to the specified value when the specified message is received. The victory countdown time is the grace period after the battle is deemed to have a victor, and before the battle formally ends, in which celebratory/commiseratory advice often plays. Set this to a negative number for the battle to never end after entering victory countdown phase, or 0 for it to end immediately.
Note that it's possible to set a negative victory countdown period, then enter the phase, then set a victory countdown period of zero to end the battle immediately.

Parameters:

1

string

Set victory countdown on receipt of this message.

2

number

Victory countdown time in ms.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 1522

generated_battle:block_message_on_message(string message, string message to block, [boolean should block])
Blocks or unblocks a message from being triggered, on receipt of a message. Scripts listening for a blocked message will not be notified when that message is triggered. See script_messager:block_message for more information.

Parameters:

1

string

Perform the blocking or unblocking on receipt of this message.

2

string

Message to block or unblock.

3

boolean

optional, default value=true

Should block the message. Set this to false to unblock a previously-blocked message.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 1554

Back to top

Message Generation

generated_battle:message_on_all_messages_received(string message, ... messages)
Takes a subject message, and then one or more other messages. When all of these other messages are received, the subject message is sent.

Parameters:

1

string

Subject message to send.

2

...

One or more string messages to receive.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 1652

generated_battle:message_on_any_message_received(string message, ... messages)
Takes a subject message, and then one or more other messages. When any of these other messages are received, the subject message is sent.

Parameters:

1

string

Subject message to send.

2

...

One or more string messages to receive.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 1701

generated_battle:message_on_time_offset(
  string message,
  number wait time,
  [string start message],
  [string cancel message]
)

Takes a string message and a wait time in ms. Waits for the specified interval and then triggers the message. If an optional start message is supplied as a third parameter then the timer will start when this message is received, otherwise it starts when the battle is started.
A cancellation message may be supplied as a fourth parameter - this will cancel the timer if the message is received (whether the timer has been started or not).

Parameters:

1

string

Message to send.

2

number

Wait time in ms before sending the message.

3

string

optional, default value="battle_started"

Start message which begins the wait time countdown.

4

string

optional, default value=false

Cancellation message.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 1740

Generated Army

A generated army object represents a conceptual army in a generated battle. This can mean an entire army in the conventional sense, or a collection of units within a conventional army, grouped together by the same script_name. A generated_army object can be created by calling generated_battle:get_army.

Each generated army object can be instructed to respond to trigger script messages when certain in-battle conditions are met (e.g. when a certain proportion of casualties has been taken, or the enemy is within a certain distance), or to respond to script messages triggered by other parts of the script by attacking/defending/moving and more. Using these tools, the actions that determine the course of events in a generated/quest battle can be laid out.

Back to top

Querying

generated_army:get_script_name()
Gets the script_name of the generated army.

Returns:

  1. string script_name

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2028

generated_army:get_unitcontroller()
Gets a unitcontroller with control over all units in the generated army. This can be useful for the intro cutscene which needs this to restrict player control.

Returns:

  1. unitcontroller

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2036

generated_army:get_handicap()
Returns the battle difficulty. See the documentation for army:army_handicap for possible return values.

Returns:

  1. number army handicap

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2044

generated_army:get_first_scriptunit()
Returns the first scriptunit of the generated army.

Returns:

  1. script_unit

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2052

generated_army:get_most_westerly_scriptunit()
Returns the script_unit within the generated army positioned furthest to the west.

Returns:

  1. script_unit

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2060

generated_army:get_most_easterly_scriptunit()
Returns the script_unit within the generated army positioned furthest to the east.

Returns:

  1. script_unit

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2082

generated_army:get_most_northerly_scriptunit()
Returns the script_unit within the generated army positioned furthest to the north.

Returns:

  1. script_unit

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2104

generated_army:get_most_southerly_scriptunit()
Returns the script_unit within the generated army positioned furthest to the south.

Returns:

  1. script_unit

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2126

generated_army:get_casualty_rate()
Returns the amount of casualties this generated army has taken as a unary value e.g. 0.2 = 20% casualties.

Returns:

  1. number casualties

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2148

generated_army:get_rout_proportion()
Returns the unary proportion (0 - 1) of the units in this generated army that are routing e.g. 0.2 = 20% routing

Returns:

  1. number rout proportion

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2156

generated_army:get_shattered_proportion()
Returns the unary proportion (0 - 1) of the units in this generated army that are shattered e.g. 0.2 = 20% routing

Returns:

  1. number shattered proportion

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2173

generated_army:are_unit_types_in_army()
Returns true if any of the supplied unit types are present in the army, false otherwise.

Returns:

  1. boolean army contains types

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2190

Back to top

Direct Commands

These commands directly call some function or give some instruction to the generated army without listening for a script message. They are mostly for use within intro cutscenes, or they may be used internally by the functions that listen for messages.

generated_army:set_visible_to_all([boolean visible])
Sets the visibility on a generated_army, so that they are visible in an intro cutscene.

Parameters:

1

boolean

optional, default value=true

visible

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2228

generated_army:set_enabled([boolean enabled])
Sets whether a generated_army is enabled - when disabled, they will be invisible and effectively not exist. See script_unit:set_enabled.

Parameters:

1

boolean

optional, default value=true

enabled

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2240

generated_army:halt()
Halts the generated_army.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2248

generated_army:celebrate()
Orders the generated_army to celebrate.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2255

generated_army:taunt()
Orders the generated_army to taunt.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2262

generated_army:play_sound_charge()
Orders the generated_army to trigger the charge sound.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2269

generated_army:play_sound_taunt()
Orders the generated_army to trigger the taunt sound.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2277

generated_army:add_ping_icon([number icon type], [number unit index], [number duration])
Adds a ping icon to a unit within the generated army. See script_unit:add_ping_icon.

Parameters:

1

number

optional, default value=8

Icon type. This is a numeric index defined in code.

2

number

optional, default value=1

Index of unit within the army to add the ping icon to.

3

number

optional, default value=nil

Duration to show the ping icon, in ms. Leave blank to show the icon indefinitely.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2285

generated_army:remove_ping_icon([number unit index])
Removes a ping icon from a unit within the generated army.

Parameters:

1

number

optional, default value=1

Index of unit within the army to remove the ping icon from.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2307

generated_army:teleport_to_start_location_offset([number x offset], [number z offset])
Teleports the generated army to a position offset from its start location. Supply no offset to teleport it directly to its start location.

Parameters:

1

number

optional, default value=0

x offset

2

number

optional, default value=0

z offset

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2327

generated_army:goto_start_location([boolean move fast])
Instructs all the units in a generated army to move to the position/angle/width at which they started the battle.

Parameters:

1

boolean

optional, default value=false

move fast

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2357

generated_army:goto_location_offset(number x offset, number x offset, [boolean move fast])
Instructs all units in a generated army to go to a location offset from their current position. Supply a numeric x/z offset and a boolean argument specifying whether they should run.

Parameters:

1

number

x offset in m

2

number

z offset in m

3

boolean

optional, default value=false

move fast

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2365

generated_army:move_to_position(vector position)
Instructs all units in a generated army to move to a position under control of a script_ai_planner. See script_ai_planner:move_to_position.

Parameters:

1

vector

position

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2377

generated_army:advance()
Instructs all units in a generated army to advance upon the enemy.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2396

generated_army:attack()
Instructs all units in a generated army to attack the enemy.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2414

generated_army:attack_force(script_units enemy force)
Instructs all units in a generated army to attack a specific enemy force.

Parameters:

1

script_units

enemy force

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2431

generated_army:defend(number x co-ordinate, number y co-ordinate, number radius)
Instructs all units in a generated army to defend a position.

Parameters:

1

number

x co-ordinate in m

2

number

y co-ordinate in m

3

number

radius

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2451

generated_army:release()
Instructs the generated army to release control of all its units to the player/general ai.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2468

Back to top

Message Listeners

These functions listen for messages and issue commands to the generated army on their receipt. They are intended to be the primary method of causing armies to follow orders on the battlefield during open gameplay - use these instead of issuing direct orders where possible.

generated_army:teleport_to_start_location_offset_on_message(
  string message,
  number x offset,
  number y offset y offset in m
)
Teleports the units in the army to their start position with the supplied offset when the supplied message is received.

Parameters:

1

string

message

2

number

x offset in m

3

number

y offset y offset in m

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2501

generated_army:goto_start_location_on_message(string message, [boolean move fast])
Instructs the units in the army to move to the locations they started the battle at when the supplied message is received.

Parameters:

1

string

message

2

boolean

optional, default value=false

move fast

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2523

generated_army:goto_location_offset_on_message(
  string message,
  number x offset,
  number z offset,
  boolean move fast
)
Instructs the units in the army to move relative to their current locations when the supplied message is received.

Parameters:

1

string

message

2

number

x offset in m

3

number

z offset in m

4

boolean

move fast

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2544

generated_army:set_enabled_on_message(string message, boolean enabled)
Sets the enabled status of a generated army on receipt of a message.

Parameters:

1

string

message

2

boolean

enabled

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2567

generated_army:set_formation_on_message(string message, string formation, boolean release)
Sets the formation of the units in the generated army to the supplied formation on receipt of a message. For valid formation strings, see documentation for script_units:change_formation.

Parameters:

1

string

Message.

2

string

Formation name.

3

boolean

set to true to release script control after issuing the command. Set this if the command is happening to the player's army.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2585

generated_army:move_to_position_on_message(string message, vector position)
Instructs all units in a generated army to move to a position under control of a script_ai_planner on receipt of a message. See generated_army:move_to_position.

Parameters:

1

string

message

2

vector

position

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2617

generated_army:advance_on_message(string message, [number wait offset])
Orders the units in the generated army to advance on the enemy upon receipt of a supplied message.

Parameters:

1

string

Message.

2

number

optional, default value=0

Time to wait in ms after receipt of the message before issuing the advance order.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2643

generated_army:attack_on_message(string message, [number wait offset])
Orders the units in the generated army to attack the enemy upon receipt of a supplied message.

Parameters:

1

string

Message.

2

number

optional, default value=0

Time to wait after receipt of the message before issuing the attack order.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2681

generated_army:attack_force_on_message(string message, generated_army target, [number wait offset])
Orders the units in the generated army to attack a specified enemy force upon receipt of a supplied message.

Parameters:

1

string

Message.

2

generated_army

Target force.

3

number

optional, default value=0

Time to wait after receipt of the message before issuing the attack order.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2719

generated_army:defend_on_message(
  string message,
  number x co-ordinate,
  number x co-ordinate,
  number radius,
  [number wait offset]
)
Orders the units in the generated army to defend a specified position upon receipt of a supplied message.

Parameters:

1

string

Message.

2

number

x co-ordinate in m.

3

number

y co-ordinate in m.

4

number

Defence radius.

5

number

optional, default value=0

Time to wait after receipt of the message before issuing the defend order.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2763

generated_army:release_on_message(string message, [number wait offset])
Releases script control of the units in the generated army to the player/general AI upon receipt of a supplied message.

Parameters:

1

string

Message.

2

number

optional, default value=0

Time to wait after receipt of the message before the units are released.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2814

generated_army:reinforce_on_message(string message, [number wait offset])
Prevents the units in the generated army from entering the battlefield as reinforcements until the specified message is received, at which point they are deployed.

Parameters:

1

string

Message.

2

number

optional, default value=0

Time to wait after receipt of the message before issuing the reinforce order.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2847

generated_army:rout_over_time_on_message(string message, number period in ms)
Routs the units in the generated army over the specified time period upon receipt of a supplied message. See script_units:rout_over_time.

Parameters:

1

string

Message.

2

number

Period over which the units in the generated army should rout, in ms.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2883

generated_army:withdraw_on_message(string message)
Withdraw the units in the generated army upon receipt of a supplied message.

Parameters:

1

string

Message.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2913

generated_army:set_melee_mode_on_message(string message, [boolean activate], [boolean release])
Activates or deactivates melee mode on units within the generated army on receipt of a supplied message. An additional flag specifies whether script control of the units should be released afterwards - set this to true if the player is controlling this army.

Parameters:

1

string

Message.

2

boolean

optional, default value=true

Should activate melee mode.

3

boolean

optional, default value=false

Release script control afterwards.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2932

generated_army:use_army_special_ability_on_message(
  string message,
  string special ability key,
  [battle_vector position],
  [number orientation],
  [number width],
  [number delay]
)

Instructs the logical battle_army associated with the first unit in this generated_army to use the supplied special ability, upon receipt of the supplied message. An optional position, orientation and width may be specified for the army special ability. A delay may also be specified, in which case an interval in ms will be waited between the message being received and the ability being used.

Parameters:

1

string

Message.

2

string

Special ability key, from the army_special_abilities table.

3

battle_vector

optional, default value=nil

Position to trigger special ability with, if applicable.

4

number

optional, default value=nil

Orientation to trigger special ability with, if applicable. This is specified in radians.

5

number

optional, default value=nil

Width in m to trigger special ability with, if applicable.

6

number

optional, default value=0

Delay in ms to wait after receiving the message before triggering the ability.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 2957

generated_army:change_behaviour_active_on_message(
  string message,
  string behaviour,
  [boolean activate],
  [boolean release]
)
Activates or deactivates a supplied behaviour on units within the generated army on receipt of a supplied message. An additional flag specifies whether script control of the units should be released afterwards - set this to true if the player is controlling this army.

Parameters:

1

string

Message.

2

string

Behaviour to activate or deactivate. See documentation on script_unit:change_behaviour_active for a list of valid values.

3

boolean

optional, default value=true

Should activate behaviour.

4

boolean

optional, default value=false

Release script control afterwards.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3042

generated_army:set_invincible_on_message(string message, [boolean enable effect])

Sets the units in the generated army to be invincible and fearless upon receipt of a supplied message. If the enable flag is set to false then the effect is undone, removing invincibility and setting morale behaviour to default.

Parameters:

1

string

message

2

boolean

optional, default value=true

enable effect

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3069

generated_army:refresh_on_message(string message)
Refreshes the ammunition and fatigue of units in the generated army upon receipt of a supplied message.

Parameters:

1

string

message

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3099

generated_army:deploy_at_random_intervals_on_message(
  string message,
  number min units,
  number max units,
  string min period,
  string max period,
  [string cancel message],
  [boolean spawn immediately]
)
Prevents the units in the generated army from deploying as reinforcements when called, and instructs them to enter the battlefield in random chunks upon receipt of a supplied message. Supply min/max values for the number of units to be deployed at one time, and a min/max period between deployment chunks. Each chunk will be of a random size between the supplied min/max, and will deploy onto the battlefield at a random interval between the supplied min/max period after the previous chunk. This process will repeat until all units in the generated army are deployed, or until the cancel message is received. See script_units:deploy_at_random_intervals for more information.
A cancel message may also be supplied, which will stop the reinforcement process either before or after the trigger message is received.

Parameters:

1

string

Trigger message.

2

number

Minimum number of units to deploy in chunk.

3

number

Maximum number of units to deploy in chunk.

4

string

Minimum duration between chunks.

5

string

Maximum duration between chunks.

6

string

optional, default value=nil

Cancel message. If specified, this stops the deployment once received.

7

boolean

optional, default value=false

Spawns the first wave immediately.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3118

generated_army:grant_infinite_ammo_on_message(string message)
Continually refills the ammunition of all units in the generated army upon receipt of the supplied message.

Parameters:

1

string

message

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3168

generated_army:add_ping_icon_on_message(
  string message,
  [number icon type],
  [number unit index],
  [number duration]
)
Adds a ping marker to a specified unit within the generated army upon receipt of a supplied message.

Parameters:

1

string

Trigger message

2

number

optional, default value=8

Icon type. This is a numeric index defined in code.

3

number

optional, default value=1

The unit to apply the ping marker to is specified by their index value within the generated army, so 1 would be the first unit (usually the general).

4

number

optional, default value=nil

Duration to display the ping icon for, in ms

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3189

generated_army:remove_ping_icon_on_message(string message, [number unit index])
Removes a ping marker from a specified unit within the generated army upon receipt of a supplied message.

Parameters:

1

string

Trigger message

2

number

optional, default value=1

The unit to remove the ping marker from is specified by their index value within the generated army, so 1 would be the first unit (usually the general).

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3236

generated_army:add_winds_of_magic_on_message(string message, number modification value)
Adds an amount to the winds of magic reserve for the generated army upon receipt of a supplied message.

Parameters:

1

string

Trigger message.

2

number

Winds of Magic modification value.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3269

generated_army:set_always_visible_on_message(
  string message,
  [boolean always visible],
  [boolean release control]
)
On receipt of the supplied message, sets the army's visibility status to the supplied true or false value. True = the army will not be hidden by terrain LOS, false = the army can be (i.e. normal behaviour). Note that the target units will still be able to hide in forests or long grass. Also note that they may perform a fade in from the point this function is called, so may not be fully visible until several seconds later.
If the release_control flag is set to true, control of the sunits is released after the operation is performed. Do this if the army belongs to the player, otherwise they won't be able to control them.

Parameters:

1

string

message

2

boolean

optional, default value=false

always visible

3

boolean

optional, default value=false

release control

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3295

generated_army:force_victory_on_message(string message, [number duration])
Forces the enemies of the generated army to rout over time upon receipt of the supplied message. After the enemies have all routed, this generated army will win the battle.

Parameters:

1

string

Trigger message.

2

number

optional, default value=10000

Duration over which to rout the enemy in ms.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3336

generated_army:remove_on_message(string message)
Immediately kills and removes the units in the generated army upon receipt of the supplied message.

Parameters:

1

string

Trigger message.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3382

Back to top

Message Generation

These functions listen for conditions and generate messages when they are met.

generated_army:message_on_casualties(string message, number unary threshold)
Fires the supplied message when the casualty rate of this generated army equals or exceeds the supplied threshold.

Parameters:

1

string

Message to trigger.

2

number

Unary threshold (between 0 and 1).

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3423

generated_army:message_on_proximity_to_enemy(string message, number threshold distance)
Triggers the supplied message when this generated army finds itself with the supplied distance of its enemy.

Parameters:

1

string

Message to trigger.

2

number

Threshold distance in m.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3460

generated_army:message_on_proximity_to_ally(string message, number threshold distance)
Triggers the supplied message when this generated army finds itself with the supplied distance of any allied generated armies.

Parameters:

1

string

Message to trigger.

2

number

Threshold distance in m.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3500

generated_army:message_on_proximity_to_position(string message, vector position, number threshold distance)
Triggers the supplied message when this generated army finds itself with the supplied distance of the supplied position.

Parameters:

1

string

Message to trigger.

2

vector

Test position.

3

number

Threshold distance in m.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3545

generated_army:message_on_rout_proportion(string message, number threshold)
Triggers the supplied message when the proportion of units routing or dead in this generated army exceeds the supplied unary threshold.

Parameters:

1

string

Message to trigger.

2

number

Unary threshold (0 - 1).

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3589

generated_army:message_on_shattered_proportion(string message, number threshold)
Triggers the supplied message when the proportion of units that are shattered in this generated army exceeds the supplied unary threshold.

Parameters:

1

string

Message to trigger.

2

number

Unary threshold (0 - 1).

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3626

generated_army:message_on_deployed(string message)
Triggers the supplied message when the units in the generated army are all fully deployed.

Parameters:

1

string

Message to trigger.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3663

generated_army:message_on_any_deployed(string message)
Triggers the supplied message when any of the units in the generated army have deployed.

Parameters:

1

string

Message to trigger.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3692

generated_army:message_on_seen_by_enemy(string message)
Triggers the supplied message when any of the units in the generated army have become visible to the enemy.

Parameters:

1

string

Message to trigger.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3721

generated_army:message_on_commander_death(string message)
Triggers the supplied message when the commander of the army corresponding to this generated army has died. Note that the commander of the army may not be in this generated army.

Parameters:

1

string

Message to trigger.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3759

generated_army:message_on_commander_dead_or_routing(string message)
Triggers the supplied message when the commanding unit within this generated army is either dead or routing. If no commanding unit exists in the generated army, this function will throw a script error.

Parameters:

1

string

Message to trigger.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3788

generated_army:message_on_commander_dead_or_shattered(string message)
Triggers the supplied message when the commanding unit within this generated army is either dead or shattered. If no commanding unit is present, this function will throw a script error.

Parameters:

1

string

Message to trigger.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3834

generated_army:message_on_under_attack(string message)
Triggers the supplied message when any of the units in this generated army come under attack.

Parameters:

1

string

Message to trigger.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3880

generated_army:message_on_alliance_not_active_on_battlefield(string message)
Triggers the supplied message if none of the units in the alliance to which this generated army belongs are a) deployed and b) not routing, shattered or dead

Parameters:

1

string

Message to trigger.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3912

generated_army:message_on_victory(string message)
Triggers the supplied message if this generated army wins the battle.

Parameters:

1

string

Message to trigger.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3974

generated_army:message_on_defeat(string message)
Triggers the supplied message if this generated army loses the battle.

Parameters:

1

string

Message to trigger.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_generated_battle.lua, line 3993

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