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();

-- 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 Campaign Loaded in Campaign
Loaded in Battle Loaded in Battle
Loaded in Frontend Loaded in Frontend
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 generated battle

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 99

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 409

generated_battle:stop_end_battle([boolean stop battle end])

Stops battle_manager:end_battle() from being called at the end of the battle. Use this if you want to stop the battle from leaving the VictoryCoundown phase.

Parameters:

1

boolean

optional, default value=true

stop battle end

Returns:

  1. nil

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

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 443

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

Returns:

  1. number index

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 451

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

Returns:

  1. number index

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 459

Back to top

Fetching Generated Armies

When the generated battle object is created with generated_battle:new it automatically creates all generated_army objects internally. The generated_battle:get_player_army and generated_battle:get_army functions can be called by client scripts to get handles to to fetch generated_army objects.

generated_battle:get_player_army([string script name])

Returns the player-controlled generated_army with the supplied script name.

Parameters:

1

string

optional, default value=""

script name

Returns:

  1. generated_army generated army

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 478

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

optional, default value=""

script name

Returns:

  1. generated_army generated army

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 487

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 646

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

Parameters:

1

string

message name

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 656

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 675

generated_battle:play_sound_on_message(
  string message,
  battle_sound_effect sound,
  [battle_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

battle_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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 713

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 786

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 824

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 883

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 926

generated_battle:set_objective_with_leader_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 with a topic_leader, or to 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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 969

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 1011

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 1051

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 1091

generated_battle:set_locatable_objective_on_message(
  string message,
  string objective key,
  [number wait offset],
  battle_vector camera position,
  battle_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

battle_vector

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

5

battle_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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 1131

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 1190

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. These have to be looked up from code. 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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 1242

generated_battle:remove_ping_icon_on_message(
  string message,
  battle_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

battle_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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 1303

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 1388

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 1413

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 1438

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 1476

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 1514

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 1586

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 1618

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 1718

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 1764

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. If a value of true is supplied then the countdown starts as soon as this function is called.

4

string

optional, default value=false

Cancellation message.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 1803

Back to top

Messages on Capture Location Events

generated_battle:message_on_capture_location_capture_commenced(
  string message,
  [string start message],
  [string script id filter],
  [string type filter],
  [number holding alliance filter],
  [number contesting alliance filter]
)

Generates the supplied script message when the capture of a battle_capture_location begins. A number of filters may optionally be specified, for the holding alliance, the contesting alliance, and the script id and the type of the capture location. When a script event indicating the capture of a capture location has begun the supplied filters are checked and, should they all match, the supplied message is generated. Filters that are omitted are not checked.
The script id and type filters perform a string compare, so a supplied script id filter "section_1" would pass for capture locations with ids "section_1", "section_1a", "end_section_1" but would not match "section_2", for example. Similarly a supplied type filter of "minor_key_building" would match "minor_key_building_defence" but not "major_key_building". Capture location types may be looked up in the capture_location_types database table.
A start message may optionally be specified. If this is left blank then the listener will start when deployment ends. If the boolean value true is supplied as a start message the listener will start immediately, but this is highly situational.

Parameters:

1

string

Message to send.

2

string

optional, default value="battle_started"

Start message which begins the listening process. If a value of true is supplied then the process starts as soon as this function is called.

3

string

optional, default value=nil

Capture location script id filter. If supplied, a string match of this filter is performed against the capture location script id as described above.

4

string

optional, default value=nil

Capture location type filter. If supplied, a string match of this filter is performed against the capture location type as described above.

5

number

optional, default value=nil

Holding alliance filter. This may be an alliance index (1 or 2), a generated_army (the alliance of the army is used), or nil may be supplied to bypass this filter.

6

number

optional, default value=nil

Contesting alliance filter. This may be an alliance index (1 or 2), a generated_army (the alliance of the army is used), or nil may be supplied to bypass this filter.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2015

generated_battle:message_on_capture_location_capture_completed(
  string message,
  [string start message],
  [string script id filter],
  [string type filter],
  [number holding alliance filter],
  [number contesting alliance filter]
)

Generates the supplied script message when the capture of a battle_capture_location completes. A number of filters may optionally be specified, for the (previous) holding alliance, the contesting alliance, and the script id and the type of the capture location. When a script event indicating the capture of a capture location has completed the supplied filters are checked and, should they all match, the supplied message is generated. Filters that are omitted are not checked.
The script id and type filters perform a string compare, so a supplied script id filter "section_1" would pass for capture locations with ids "section_1", "section_1a", "end_section_1" but would not match "section_2", for example. Similarly a supplied type filter of "minor_key_building" would match "minor_key_building_defence" but not "major_key_building". Capture location types may be looked up in the capture_location_types database table.
A start message may optionally be specified. If this is left blank then the listener will start when deployment ends. If the boolean value true is supplied as a start message the listener will start immediately, but this is highly situational.

Parameters:

1

string

Message to send.

2

string

optional, default value="battle_started"

Start message which begins the listening process. If a value of true is supplied then the process starts as soon as this function is called.

3

string

optional, default value=nil

Capture location script id filter. If supplied, a string match of this filter is performed against the capture location script id as described above.

4

string

optional, default value=nil

Capture location type filter. If supplied, a string match of this filter is performed against the capture location type as described above.

5

number

optional, default value=nil

Holding alliance filter. This may be an alliance index (1 or 2), a generated_army (the alliance of the army is used), or nil may be supplied to bypass this filter.

6

number

optional, default value=nil

Contesting alliance filter. This may be an alliance index (1 or 2), a generated_army (the alliance of the army is used), or nil may be supplied to bypass this filter.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2030

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2264

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. battle_unitcontroller unitcontroller

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2272

generated_army:get_alliance()
Returns the battle_alliance object that contains the units in this generated army.

Returns:

  1. battle_alliance alliance

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2280

generated_army:get_army()
Returns the battle_army object that contains the units in this generated army. If the units are reinforcing then they may instead belong to a dummy army before they enter the battlefield - use generated_army:get_reinforcement_source_army instead to access that army object.

Returns:

  1. battle_army army

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2288

generated_army:get_reinforcement_source_army()
Returns the temporary battle_army object that contains reinforcing units in this generated army, before they enter the battlefield. As they enter the battlefield they will be transferred to the proper army object which may be accessed with generated_army:get_army.
If the units in this generated army are not reinforcing then there will be no source army and this function will return false.

Returns:

  1. battle_army source army

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2296

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2306

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

Returns:

  1. script_unit scriptunit

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2314

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

Returns:

  1. script_unit scriptunit

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2322

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

Returns:

  1. script_unit scriptunit

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2344

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

Returns:

  1. script_unit scriptunit

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2366

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

Returns:

  1. script_unit scriptunit

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2388

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2410

generated_army:get_rout_proportion([boolean permit rampaging])

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

Parameters:

1

boolean

optional, default value=false

Permit rampaging, so that rampaging units are considered to be still controllable/not-routing. By default, rampaging units are considered to be routing.

Returns:

  1. number rout proportion

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2418

generated_army:get_shattered_proportion([boolean permit rampaging])

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

Parameters:

1

boolean

optional, default value=false

Permit rampaging, so that rampaging units are considered to be still controllable/not-routing. By default, rampaging units are considered to be routing.

Returns:

  1. number shattered proportion

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2436

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2454

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2492

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2504

generated_army:halt()
Halts the generated_army.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2512

generated_army:celebrate()
Orders the generated_army to celebrate.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2519

generated_army:taunt()
Orders the generated_army to taunt.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2526

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

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2533

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

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2541

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

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2571

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2591

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2621

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

generated_army:move_to_position(battle_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

battle_vector

position

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2659

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

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2678

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

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2696

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2713

generated_army:rush()
Instructs all units in a generated army to rush the enemy, ie move fast, attack without forming up

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2733

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2750

generated_army:rush_position(number x co-ordinate, number y co-ordinate, number radius)

Instructs all units in a generated army to rush 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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2767

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

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2784

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2811

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2833

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2854

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2877

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2895

generated_army:move_to_position_on_message(string message, battle_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

battle_vector

position

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2927

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2953

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 2991

generated_army:rush_on_message(string message, [number wait offset])

Orders the units in the generated army to rush 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 rush order.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3029

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3067

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3111

generated_army:rush_position_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 first move to, then 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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3162

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3213

generated_army:reinforce_on_message(
  string message,
  [number wait offset],
  [number wave index],
  [boolean is final wave]
)

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.

3

number

optional, default value=nil

Set an integer value to notify the game that this is a new wave in a survival battle.

4

boolean

optional, default value=false

Set this to true to notify the game that this is the final wave in a survival battle. This value is disregarded if no wave index is specified.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3246

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3294

generated_army:teleport_withdraw_over_time_on_message(string message, number period in ms)

Teleports away the units in the generated army over the specified time period upon receipt of a supplied message. See script_units:teleport_withdraw_over_time.

Parameters:

1

string

Message.

2

number

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

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3323

generated_army:prevent_rallying_if_routing_on_message(string message)

Prevents the units in the generated army from rallying if they ever rout upon receipt of a supplied message. See script_unit:prevent_rallying_if_routing.

Parameters:

1

string

Message.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3352

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3371

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3390

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3415

generated_army:kill_proportion_over_time_on_message(
  number proportion,
  number duration,
  [boolean stop on rout],
  string message
)

Kills a unary proportion of this unit over a specified time period in ms.

Parameters:

1

number

Proportion to kill, expressed as a unary value (e.g. 0.5 = 50% of the unit's starting number of soldiers die).

2

number

Duration in ms over which to kill soldiers.

3

boolean

optional, default value=false

Stops the function from killing any more soldiers if the unit routs during the process.

4

string

Message.

Returns:

  1. nil

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

generated_army:stop_kill_proportion_over_time_on_message(string message)

Stops a running process started by generated_army:kill_proportion_over_time_on_message.

Parameters:

1

string

Message.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3522

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3541

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3568

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3598

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],
  [boolean allow respawning],
  [number wave index],
  [boolean is final wave],
  [boolean ongoing output]
)

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.

8

boolean

optional, default value=false

Allow units to respawn that have previously been deployed.

9

number

optional, default value=nil

Set an integer value to notify the game that this is a new wave in a survival battle.

10

boolean

optional, default value=false

Set this to true to notify the game that this is the final wave in a survival battle. This value is disregarded if no wave index is specified.

11

boolean

optional, default value=false

Generate ongoing debug output as units are deployed.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3617

generated_army:assign_to_spawn_zone_from_collection_on_message(
  string message,
  table spawn zone collection,
  [boolean suppress warning]
)

Assigns this army to a random spawn zone from the supplied collection on receipt of the supplied message. This will make units that deploy onto the battlefield from this army come on from the position of the spawn zone that is chosen. The spawn zone collection is a bespoke table data type - see the functions listed in the Spawn Zone Collections section of this documentation for more information.
It is valid to call this function while the army is partially deployed. In this case, units that subsequently deploy will enter the battlefield from the position of the new spawn zone. This functiom may be used in conjuction with other functions such as generated_army:message_on_number_deployed, which broadcasts script messages when a certain number of units have deployed from the army. This function switches spawn zones in response to these messages, so that the enemy force appears from multiple directions. To facilitate this behaviour, this function persists in listening for its message after the message is first received, which is uncommon behaviour amongst generated battle message listeners.
Note that this function breaks the generated battle system paradigm that generated army objects can represent a subset of a logical army. Units are assigned to spawn zones on a per-logical-army basis, so if this generated army shares a logical army with another generated army, then changing the spawn zone on this generated army will also change the spawn zone for the other. To increase visibility of this issue the function will throw a script error if called on a generated army that does not control all units for its associated logical army, unless the suppress warning flag is enabled.

Parameters:

1

string

message

2

table

spawn zone collection

3

boolean

optional, default value=false

suppress warning

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3709

generated_army:add_to_survival_battle_wave_on_message(
  string message,
  number wave index,
  [boolean final wave]
)

Adds the scriptunits in this generated army to a survival battle wave on receipt of the supplied message. This will call battle_manager:add_survival_battle_wave and start a process which monitors these units and updates the UI as if they were a survival battle wave. Calling this has no effect on the actual behaviour of the units.
The survival battle wave is specified by numeric index. Additional waves can be introduced by ascending index.

Parameters:

1

string

message

2

number

wave index

3

boolean

optional, default value=false

final wave

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3747

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3781

generated_army:play_general_vo_on_message(
  string message,
  battle_sound_effect sound,
  [number wait interval],
  [string end message],
  [number minimum duration]
)

Plays a battle_sound_effect associated with the army general on receipt of the supplied message. The sound will appear to come from the general unit in 3D (unless overridden in sound data), and the unit's standard VO will be suppressed while the sound is playing.

Parameters:

1

string

Play the sound on receipt of this message.

2

battle_sound_effect

Sound file to play.

3

number

optional, default value=0

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

4

string

optional, default value=nil

Message to send when the sound has finished playing.

5

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 yet been recorded.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3801

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3875

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3922

generated_army:add_winds_of_magic_reserve_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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3955

generated_army:add_winds_of_magic_on_message(string message, number modification value)

Adds an amount to the current winds of magic level 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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 3981

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 4007

generated_army:enable_map_barrier_on_message(string message, string script id, [boolean enable])

Instructs this generated army to enable or disable a battle_map_barrier when the specified message is received. The map barrier is specified by toggle slot script id. If no toggle slot with the supplied script id is found on the map, or the toggle slot found is not linked to a map barrier, then a script error is produced.

Parameters:

1

string

Change state of map barrier on receipt of this message.

2

string

Script id specifiying the togggle slot the map barrier is linked to.

3

boolean

optional, default value=true

Enable the map barrier. Specify false here to disable the barrier instead.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 4047

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 4091

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 4137

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 4178

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 4215

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 4255

generated_army:message_on_proximity_to_position(
  string message,
  battle_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

battle_vector

Test position.

3

number

Threshold distance in m.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 4300

generated_army:message_on_rout_proportion(string message, number threshold, [boolean permit rampaging])

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

3

boolean

optional, default value=false

Permit rampaging, so that rampaging units are considered to be still controllable/not-routing. By default, rampaging units are considered to be routing.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 4344

generated_army:message_on_shattered_proportion(
  string message,
  number threshold,
  [boolean permit rampaging]
)

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

3

boolean

optional, default value=false

Permit rampaging, so that rampaging units are considered to be still controllable/not-routing. By default, rampaging units are considered to be routing.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 4382

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 4420

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 4449

generated_army:message_on_number_deployed(string message, boolean read repeatedly, vararg numbers)

Triggers the supplied message, potentially repeatedly, when a certain number of units in the generated army have been deployed. The function takes one or more number arguments and will count through those numbers in order each time a unit from the army deploys onto the battlefield. The supplied message will be triggered each time a supplied number in the sequence is counted down to 0.
For example, if the generated army contains 10 units, and the message example_message is specified along with numerical arguments 2, 1, 3, the function will trigger that message after the second unit has been deployed (the first supplied number 2 is counted down), the third unit has been deployed (the second supplied number 1 is counted down, after the first) and the sixth unit has been deployed (the third number 3, after the first and second).
If the repeat_pattern flag is set then the supplied list of numbers is read repeatedly until all units in the generated army are accounted for. Setting this flag and supplying numerical arguments 1, 2 would be the same as not setting this flag and supplying arguments 1, 2, 1, 2, 1, 2, 1, 2 etc.
If the last unit being deployed does not complete the sequence (e.g 2, 2, 2 for an army that only contains five units) then no final message will be issued.

Parameters:

1

string

Message to trigger.

2

boolean

Read back to the start of the supplied list of numbers if there are still units in the generated army that are unassigned.

3

vararg

Sequence of numbers on which to trigger the message, when counting number of units deployed.

Returns:

  1. nil

Example - Send message reinforcements_arriving after the 3rd, 5th and 8th unit in the army are deployed:

ga_enemy_01:message_on_number_deployed("reinforcements_arriving", 3, 2, 3);

defined in ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 4478

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 4559

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 4597

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 4628

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 4667

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 4706

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 4738

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 4798

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 ../../warhammer/working_data/script/_lib/lib_generated_battle.lua, line 4817

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