Narrative Trigger Templates

The narrative_triggers table contains a list of narrative trigger templates that campaign scripts can use to create narrative triggers. See the page on narrative for an overview of the narrative event framework. See also the narrative_trigger documentation for detailed information about the narrative_trigger object interface.

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

Functionality

narrative_triggers.generic(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  string
event name,
  [function
condition],
  [boolean
Immediate]
)

Creates and starts a narrative trigger that attempts to trigger when a specified event is received. An optional condition function may also be supplied, which must be passed for the narrative trigger to fire its target events. If supplied, the condition function will be called when the specified event is received, and will be passed the event context and the narrative trigger object as separate arguments. It must return a value that evaluates to true for the condition to pass. If no condition function is supplied then the condition always passes.
If the immediate flag is set, or if it is a multiplayer game, then the narrative trigger will immediately trigger the target messages when the event is received and condition passes. If the flag is not set and it's a singleplayer game the narrative will instead create an intervention which will fire the target messages when it gets to trigger.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

string

Event name to listen for.

7

function

optional, default value=nil

Condition function to call when the event is received. The event context and narrative trigger objects are provided to the function as arguments. If no condition function is supplied then the condition always passes.

8

boolean

optional, default value=true

Trigger the target message(s) immediately when the event is received and the optional condition is met.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 77

narrative_triggers.message(
  
string unique name,
  string
faction key,
  string
trigger message,
  string
target message,
  [string
cancel message]
)

Triggers a message when a different message is received for the specified faction. Instead of using this, it is encouraged to make the narrative entity triggering the incoming message to instead just trigger the target message as well/instead, making this intermediate narrative trigger redundant. However, there are circumstances which can make the creation of an intermediate trigger desirable.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

Message on which this narrative trigger should trigger. If multiple trigger messages are required then a table containing string message names can be supplied here instead.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel. If multiple messages are required then a table containing string message names can be supplied here instead.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 139

narrative_triggers.turn_start(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  [function
condition],
  [string
faction starting turn],
  [boolean
Immediate]
)

Creates and starts a narrative trigger that attempts to trigger on start of turn for the specified faction. An optional condition function may also be supplied, which must be passed for the narrative trigger to fire its target events. If supplied, the condition function will be called when the faction starts its turn and will be passed the context of the FactionTurnStart event and the narrative trigger object as separate arguments. It must return a value that evaluates to true for the condition to pass. If no condition function is supplied then the condition always passes.
If the immediate flag is set, or if it is a multiplayer game, then the narrative trigger will immediately trigger the target messages when the turn start event is received. If the flag is not set and it's a singleplayer game the narrative will instead create an intervention which will fire the target messages when it gets to trigger.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

function

optional, default value=nil

Condition function which must be passed for the trigger to fire. This function will be passed the context object from the FactionTurnStart event and the narrative trigger as two separate arguments. It must return a value that evaluates to true for the condition to pass.

If no condition function is supplied here then the condition always passes.

7

string

optional, default value=nil

Key of the faction whose turn start we should listen for. If nil is supplied here then the key of the faction to which this narrative trigger applies is used.

8

boolean

optional, default value=true

Trigger the target message(s) immediately when the event is received and the optional condition is met.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 222

narrative_triggers.dilemma_choice_made(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  string
dilemma key,
  [number
choice value]
)

Creates and starts a narrative trigger that fires when a dilemma choice is made.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

string

Key of dilemma to listen for, from the dilemmas database table.

7

number

optional, default value=nil

Integer choice value.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 292

narrative_triggers.turn_countdown(
  
string unique name,
  string
faction key,
  string
start message,
  string
target message,
  [string
cancel message],
  number
turns,
  [boolean
Immediate]
)

Creates and starts a narrative trigger that listens for a message from another narrative object, and then waits a specified number of turns (for the specified faction) before sending one or more target messages.
The target messages are always triggered immediately, with no intervention being created in singleplayer mode.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

Message on which this narrative trigger should start its turn countdown. If multiple messages are required then a table containing string message names can be supplied here instead.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead. This message/these messages will be associated with the specified target faction rather than the source faction.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

number

Number of turns to wait.

7

boolean

optional, default value=true

Trigger the target message(s) immediately when the event is received and the optional condition is met.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 388

narrative_triggers.faction_switch(
  
string unique name,
  string
faction key,
  string
start message,
  string
target message,
  [string
cancel message],
  string
target faction key
)

Creates and starts a narrative trigger that listens for a start message from another narrative object associated with one faction, and then sends one or more target messages associated with another faction. This can be useful if a desired narrative sequence flows over the player changing faction.
The target messages are always triggered immediately, with no intervention being created in singleplayer mode.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table. This should be the originator faction.

3

string

Message on which this narrative trigger should initiate the faction switch process. If multiple messages are required then a table containing string message names can be supplied here instead.

4

string

Target message or messages to trigger when this narrative trigger fires. These target message(s) will be associated with the target faction. If multiple target messages are required then a table containing string message names can be supplied here instead. This message/these messages will be associated with the specified target faction rather than the source faction.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

string

Key of the target faction, to which the outgoing target message(s) will be associated.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 483

narrative_triggers.growth_point_gained(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  [boolean
upgrade available only],
  [string
province key]
)

Creates and starts a narrative trigger that fires when the specified faction has gained a growth point in a specified province, or any controlled territory if no province is specified.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

boolean

optional, default value=false

The narrative trigger should only fire when a growth point is earned in a player-controlled region and an upgrade of the main settlement chain is available.

7

string

optional, default value=nil

Key of province in which the growth point must be earned. This can also be a table of string province keys. If left blank, then any growth point earned by the specified faction is counted.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 570

narrative_triggers.building_construction_issued(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  [function
condition]
)

Creates and starts a narrative trigger that fires when the specified faction starts construction on a building. An optional condition function may be specified which is passed the context object supplied by the underlying BuildingConstructionIssuedByPlayer script event.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

function

optional, default value=nil

Condition function which, if supplied, must be passed in order for the trigger to fire. The condition function is passed the context object supplied by the underlying BuildingConstructionIssuedByPlayer script event as well as the narrative trigger object as separate arguments, and should return a value that evaluates to a boolean.

The condition function may also return a second boolean return value, which suppresses downstream output. This can be set if the condition function handles output itself.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 653

narrative_triggers.technology_building_construction_issued(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  [function
condition]
)

Creates and starts a narrative trigger that fires when the specified faction starts construction on a building that unlocks a technology. An additional optional condition function may be specified which is passed the context object supplied by the underlying BuildingConstructionIssuedByPlayer script event.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

function

optional, default value=nil

Condition function which, if supplied, must be passed in order for the trigger to fire. The condition function is passed the context object supplied by the underlying BuildingConstructionIssuedByPlayer script event as well as the narrative trigger object as separate arguments, and should return a value that evaluates to a boolean.

The condition function may also return a second boolean return value, which suppresses downstream output. This can be set if the condition function handles output itself.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 671

narrative_triggers.general_created(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  [function
condition]
)

Creates and starts a narrative trigger that fires when a general/lord character is created for the specified faction. An optional condition function may also be specified which is passed the context object supplied by the underlying CharacterCreated script event.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

function

optional, default value=nil

Condition function which, if supplied, must be passed in order for the trigger to fire. The condition function is passed the context object supplied by the underlying BuildingConstructionIssuedByPlayer script event as well as the narrative trigger object as separate arguments, and should return a value that evaluates to a boolean.

The condition function may also return a second boolean return value, which suppresses downstream output. This can be set if the condition function handles output itself.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 795

narrative_triggers.agent_created(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  [function
condition]
)

Creates and starts a narrative trigger that fires when an agent/hero character is created for the specified faction. An optional condition function may also be specified which is passed the context object supplied by the underlying CharacterCreated script event.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

function

optional, default value=nil

Condition function which, if supplied, must be passed in order for the trigger to fire. The condition function is passed the context object supplied by the underlying BuildingConstructionIssuedByPlayer script event as well as the narrative trigger object as separate arguments, and should return a value that evaluates to a boolean.

The condition function may also return a second boolean return value, which suppresses downstream output. This can be set if the condition function handles output itself.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 813

narrative_triggers.hero_action_performed(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  [function
condition]
)

Creates and starts a narrative trigger that fires when a hero character performs a successful action for the specified faction. An optional condition function may also be specified which is passed the context object supplied by the underlying CharacterCharacterTargetAction script event.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

function

optional, default value=nil

Condition function which, if supplied, must be passed in order for the trigger to fire. The condition function is passed the context object supplied by the underlying BuildingConstructionIssuedByPlayer script event as well as the narrative trigger object as separate arguments, and should return a value that evaluates to a boolean.

The condition function may also return a second boolean return value, which suppresses downstream output. This can be set if the condition function handles output itself.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 899

narrative_triggers.any_general_won_x_battles(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  [number
victories],
  [function
condition]
)

Creates and starts a narrative trigger that fires when a lord in the specified faction has participated in a certain number of battle victories. An optional condition function may also be specified which is passed the context object supplied by the underlying CharacterCompletedBattle script event.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

number

optional, default value=1

Threshold number of victories.

7

function

optional, default value=nil

Condition function which, if supplied, must be passed in order for the trigger to fire. The condition function is passed the context object supplied by the underlying BuildingConstructionIssuedByPlayer script event as well as the narrative trigger object as separate arguments, and should return a value that evaluates to a boolean.

The condition function may also return a second boolean return value, which suppresses downstream output. This can be set if the condition function handles output itself.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 988

narrative_triggers.any_hero_won_x_battles(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  [number
victories],
  [function
condition]
)

Creates and starts a narrative trigger that fires when a hero character in the specified faction has participated in a certain number of battle victories. An optional condition function may also be specified which is passed the context object supplied by the underlying CharacterCompletedBattle script event.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

number

optional, default value=1

Threshold number of victories.

7

function

optional, default value=nil

Condition function which, if supplied, must be passed in order for the trigger to fire. The condition function is passed the context object supplied by the underlying BuildingConstructionIssuedByPlayer script event as well as the narrative trigger object as separate arguments, and should return a value that evaluates to a boolean.

The condition function may also return a second boolean return value, which suppresses downstream output. This can be set if the condition function handles output itself.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 1007

narrative_triggers.pooled_resource_gained(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  string
pooled resource key,
  number
threshold value,
  [boolean
less than]
)

Creates and starts a narrative trigger that fires when the specified faction has an amount of a specified pooled resource equal to or greater than a specified threshold.
An optional flag makes the narrative trigger instead fire when the pooled resource is less than or equal to the threshold.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

string

Key of the pooled resource to monitor, from the pooled_resources database table. this can also be a table of multiple pooled resource keys.

7

number

Threshold value that the pooled resoure must meet or exceed for subject faction for trigger to fire.

8

boolean

optional, default value=false

Trigger when the pooled resource is less than or equal to the threshold value, rather than greater than.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 1130

narrative_triggers.faction_pooled_resource_gained(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  string
pooled resource faction key,
  string
pooled resource key,
  number
threshold value,
  [boolean
less than]
)

Creates and starts a narrative trigger that fires when the specified faction has an amount of a specified pooled resource equal to or greater than a specified threshold. This differs from narrative_triggers.pooled_resource_gained as it allows the faction which is being monitored to be different from the faction with which the triggered messages are associated with.
An optional flag makes the narrative trigger instead fire when the pooled resource is less than or equal to the threshold.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction with which the triggered messages are associated with, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

string

Key of the faction whose pooled resources are being monitored, from the factions database table.

7

string

Key of the pooled resource to monitor, from the pooled_resources database table. this can also be a table of multiple pooled resource keys.

8

number

Threshold value that the pooled resoure must meet or exceed for subject faction for trigger to fire.

9

boolean

optional, default value=false

Trigger when the pooled resource is less than or equal to the threshold value, rather than greater than.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 1150

narrative_triggers.skulls_gained(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  number
threshold value,
  [boolean
less than]
)

Creates and starts a narrative trigger that fires when the specified faction has an amount of the skulls pooled resource equal to or greater than a specified threshold.
An optional flag makes the narrative trigger instead fire when the pooled resource is less than or equal to the threshold.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

number

Threshold value that the pooled resoure must meet or exceed for subject faction for trigger to fire.

7

boolean

optional, default value=false

Trigger when the pooled resource is less than or equal to the threshold value, rather than greater than.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 1171

narrative_triggers.devotion_gained(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  number
threshold value,
  [boolean
less than]
)

Creates and starts a narrative trigger that fires when the specified faction has an amount of the devotion pooled resource equal to or greater than a specified threshold.
An optional flag makes the narrative trigger instead fire when the pooled resource is less than or equal to the threshold.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

number

Threshold value that the pooled resoure must meet or exceed for subject faction for trigger to fire.

7

boolean

optional, default value=false

Trigger when the pooled resource is less than or equal to the threshold value, rather than greater than.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 1190

narrative_triggers.can_reach_faction(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  string
target faction key,
  [boolean
include armies]
)

Creates and starts a narrative trigger that fires when the specified faction starts a turn and any of its military forces can reach any of the settlements of a specified target faction to attack this turn. An optional flag also includes the target faction's armies in this assessment.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

string

Key of the target faction, from the factions database table.

7

boolean

optional, default value=false

Includes the target faction's roving armies in the can-reach check, as well as their settlements.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 1265

narrative_triggers.can_reach_settlement(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  string
target settlements,
  boolean
include agents
)

Creates and starts a narrative trigger that fires when the specified faction starts a turn and any of its military forces can reach any of the specified settlements to attack this turn. An optional flag also includes the subject faction's agents in this assessment, as well as military forces.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

string

Key of the region containing the target settlement, from the campaign_map_regions database table. If multiple target settlements are desired then a table containing multiple string keys may be supplied here.

7

boolean

Include the source faction's agents/heroes in the can-reach assessment.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 1351

narrative_triggers.corruption_in_adjacent_region(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  string
corruption type,
  number
threshold value,
  [string
culture key]
)

Creates and starts a narrative trigger that fires when the amount of corruption in any adjacent region to the specified faction reaches a specified threshold.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

string

Corruption type, from the pooled_resources database table.

7

number

Threshold value which the corruption must meet or exceed in an adjacent region for the trigger condition to be met.

8

string

optional, default value=nil

Culture key of region owner to exclude. If an eligible region has a faction owner with this culture, the region will not be included.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 1445

narrative_triggers.foreign_slot_established(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  [boolean
should be allied]
)

Creates and starts a narrative trigger that fires when the specified faction establishes a foreign slot. Whether the foreign slot should be allied to the region it's embedded in or not may optionally be specified.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

boolean

optional, default value=nil

Should the foreign slot be allied to the region its embedded in or not. If nil (or no value) is supplied here then the trigger fires in either case.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 1511

narrative_triggers.ritual_performed(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  [string
ritual keys],
  [string
ritual categories],
  [string
target faction keys]
)

Creates and starts a narrative trigger that fires when the specified faction performs a ritual. One or more optional ritual keys, ritual categories and target faction keys may be specified which the ritual performed must satisfy. Where a list of ritual keys/ritual categories/target faction keys is given, the ritual performed must match one of those in the list to qualify.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

string

optional, default value=nil

Key(s) of ritual(s), from the rituals database table. This can be a string ritual key or a table of strings. If no ritual keys are specified then any rituals match.

7

string

optional, default value=nil

Key(s) of ritual category/categories, from the ritual_categories database table. This can be a string category key or a table of strings. If no categories are specified then any rituals match.

8

string

optional, default value=nil

Key(s) of any target factions, from the factions database table. This can be a string faction key or a table of strings. If no target factions are specified then any targets match.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 1648

narrative_triggers.character_action(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  [string
ability key(s)],
  [string
target faction keys],
  [string
char subtypes],
  [boolean
must be success]
)

Creates and starts a narrative trigger that fires when a character in the specified faction performs a character action (hero action). One or more optional action keys, performing character subtypes and/or target faction keys may be specified which the action performed must satisfy. It may also be specified whether the action must have succeeded to qualify.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

string

optional, default value=nil

Key(s) of character ability/abilities, from the abilities database table. This can be a string ability key or a table of strings. If no ability keys are specified then any abilities match.

7

string

optional, default value=nil

Key(s) of any target factions, from the factions database table. This can be a string faction key or a table of strings. If no target factions are specified then any targets match.

8

string

optional, default value=nil

Key(s) of character subtypes of the performing character, from the agent_subtypes database table. This can be a string subtype key or a table of strings. If no subtypes are specified then any performing characters match.

9

boolean

optional, default value=nil

Specifies whether only successful character actions qualify.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 1794

narrative_triggers.technology_research_started(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  [string
technology key],
  [function
condition]
)

Creates and starts a narrative trigger that fires when the specified faction starts researching a technology. A list of zero or more technology keys can be supplied which the technology must be in. Additionally, a condition function may be supplied which must be passed if the trigger is to fire.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

string

optional, default value=nil

Technology key, from the technologies database table, which the subject technology must match for the trigger to fire. A table of string technology keys may be supplied here, in which case the trigger will fire if the subject technology is in the list. Additionally, nil may be specified, in which case any technology matches.

7

function

optional, default value=nil

An additional condition function which, if supplied, must be passed for the trigger to fire. The condition function will be passed the context object from the ResearchStarted event and the narrative trigger as two separate arguments, and should return true if the trigger is allowed to fire.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 1889

narrative_triggers.technology_research_completed(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  [string
technology key],
  [function
condition]
)

Creates and starts a narrative trigger that fires when the specified faction completes the research of a technology. A list of zero or more technology keys can be supplied which the technology must be in. Additionally, a condition function may be supplied which must be passed if the trigger is to fire.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

string

optional, default value=nil

Technology key, from the technologies database table, which the subject technology must match for the trigger to fire. A table of string technology keys may be supplied here, in which case the trigger will fire if the subject technology is in the list. Additionally, nil may be specified, in which case any technology matches.

7

function

optional, default value=nil

An additional condition function which, if supplied, must be passed for the trigger to fire. The condition function will be passed the context object from the ResearchCompleted event and the narrative trigger as two separate arguments, and should return true if the trigger is allowed to fire.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 1907

narrative_triggers.net_income(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  number
threshold,
  [boolean
trigger when lower]
)

Creates and starts a narrative trigger that fires when the specified faction starts a turn with a net income greater than or equal to, or less than or equal to, a specified value.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

number

Net income threshold.

7

boolean

optional, default value=false

If set to true, the narrative trigger fires when the net income is less than or equal to the specified threshold instead of greater than or equal to.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 1976

narrative_triggers.controls_provinces(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  number
threshold
)

Creates and starts a narrative trigger that fires when the number of provinces the specified faction fully controls is greater than or equal to the supplied threshold.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

number

Provinces threshold.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 2047

narrative_triggers.highest_level_settlement(
  
string unique name,
  string
faction key,
  [string
start message],
  string
target message,
  [string
cancel message],
  number
threshold
)

Creates and starts a narrative trigger that fires when the specified faction controls a settlement or camp where the level of the main settlement building is greater than or equal to a specified value.

Parameters:

1

string

Unique name amongst other declared narrative triggers.

2

string

Key of the faction to which this narrative trigger applies, from the factions database table.

3

string

optional, default value=nil

Message on which this narrative trigger should start its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead. If no start messages are specified, then the trigger will start its main listeners when it is started.

4

string

Target messages to trigger when this narrative trigger fires. If multiple target messages are required then a table containing string message names can be supplied here instead.

5

string

optional, default value=nil

Message on which this narrative trigger should cancel its main listening process. If multiple messages are required then a table containing string message names can be supplied here instead.

6

number

Settlement building level threshold.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/_narrative/wh3_narrative_trigger_templates.lua, line 2124

Last updated 12/08/2022 11:56:58