TRIGGERS
List and Definition of All Triggers

Jump to Triggers List

Introduction
Whenever a player activates a trigger, it causes some actions on one or more receivers. A trigger can be an event, object or hero that a hero visits, or it could be an ERM function called by other ERM code or even a timer set up to trigger at a specific time or interval (e.g., every 14 days). Receivers can be events, heroes, map objects or other things. Since many things in the game can be used as a trigger or receiver, it's important to not confuse which is which.

How to Use Triggers
The properties of the trigger event or object do not matter for purposes of it being a trigger. The action of the trigger must be described in a timed event. In an ERM script, the trigger functions as the header, and following after the trigger on subsequent lines are one or more receivers that are executed one at a time in sequence. If you place more than one trigger in the same timed event, it's important to realize that there is no "end trigger" code; a new trigger signals the end of one triggered script and the start of the next.

Trigger Syntax
Every trigger begins with an exclamation mark/question mark combination (!?) and ends with a semicolon (;). Immediately following the !? is a two-letter trigger name which must be entered in capital letters, e.g., BA, OB or HE. Following the trigger name are one or more parameters shown as # in the list below. Each parameter notation (#) must be replaced by an integer number in your code, e.g., !?HE47;. The meaning and allowable range of these numbers is different for each type of trigger. For the HE trigger, the number is the hero number (the number used by the  game to reference a particular hero), while for the LE trigger, the numbers specifies the x, y and level coordinates of a local event on the adventure map.

Using Variables in Triggers
Trigger-based local variables:

y-1...y-100 are integer vars
e-1...e-100 are floating point vars

You may use them in the same places that you use y and e vars now.

Specific features:
1. They are NOT saved in the saved game. Actually every trigger section will run completely and you cannot save and load a game being inside a trigger section.
2. These vars are local for every trigger and if even one trigger works out inside another trigger section, they will have a different set of vars. As you can see you cannot pass values from trigger to trigger using these vars.
3. All vars are set to 0 at any trigger start, so you can use this as a default value.

Duplicate Triggers
If the exact same trigger is used more than once in a map, ALL receivers following all occurrences of that trigger are executed, starting with the first trigger (earliest timed event and first trigger reference within that event) and ending with the last trigger.
Note that !?BA0; is a different trigger from !?BA1; and likewise !?HE47; is a different trigger from !?HE48;.

Conditional Triggers
A condition can be added to a trigger so that the receivers following it only execute if the condition is true. To do this, place an ampersand sign (&) immediately after the last parameter and before the semicolon. After the &, put your conditional statement. This statement must consist of either a flag or a variable followed by a comparison symbol (=, >, <, >=, <=, or <>) and either a second variable or an integer value.
Example: !?BA0&v10=51; This means that the receivers following the BA0 trigger will only execute if v10 has a value of 51. You can include multiple tests as well by separating each subsequent condition check by a slash (/) e.g., !?BA0&v10=51/v2>=5; The BA0 trigger receivers will now only execute if v10 is equal to 51 and if v2 is equal to 5 or higher. See the Flags and Variables section for more details about flags, variables and conditional checks. Adding a second trigger of the same type but with a conditional check part way through a script is one easy way of only executing the rest of the script if certain conditions are true.

TRIGGERS LIST:
Syntax Triggers
!?AE#;
 
Equip/Unequip artifact trigger:
!?AE0;
Take off an artifact
!?AE1; Put on an artifact

The current Hero (!!HE-1) is a Hero-owner
   v998 keeps an artifact number
   v999 keeps a position (slot) number

Comments.
It does not work for backpack.
If you change one artifact to another, it produces some extra
triggers call. Here it is:
   1. AE0 (prev)
   2. AE1 (prev)
   3. AE0 (prev)
   4. AE1 (new)
   5. AE0 (new)
   6. AE1 (new)
If you take an artifact from a backpack and a slot that this
artifact may be placed is busy, you will get the next sequence for
every slot this artifact may be placed:
   1. AE0 (prev)
   2. AE1 (prev)
So be careful and do not count that if a specific artifact is
not taken off, you will not have AE0 trigger switched for this art.

!?BA#; This will be called when any battle occurs.
# = 0 Turn on at start of every battle.
# = 1 Turn on at end of every battle.
# = 50 !?BA50; is the equivalent of !?BA0; but runs only on the defending side in a multiplayer network battle, and runs *instead of !?BA0; on that side (on the defending computer).
# = 51
Likewise, !?BA51; runs instead of !?BA1; on the defending computer in a network battle.
Network service: !?BG and !?BF work at both sides and if the variables are the same, they will give you the identical effect at both sides. Only user related actions are not synchronous for both sides and BA0/BA50 and BA1/BA51 triggers make a difference.
New BA triggers:
# = 52 - called at a battle start at both sides
# = 53 - called at a battle end at both sides
So at a battle start:
1. If it is an attacker's PC (or non MP game) BA0 is called
2. If it is a defender's PC BA50 is called
3. BA52 is called.
At battle end:
1. If it is an attacker's PC (or non MP game) BA1 is called
2. If it is a defender's PC BA51 is called
3. BA53 is called.

This means that if you want to have an identical code for BA0 and BA50, you just need to make
one section with BA52 header.

NOTE. If you want to test scripts in MP mode you cannot do it at the first game turn (day 1).
You need to pass one day so all players will have an identical environment.

To set up a battle, use the BA Receiver.
Note:You may use indirect reference to heroes (copies of info):
!!HE-10:... apply changes to the copy of attacker hero info.
!!HE-20:... apply changes to the copy of defender hero info.
!?BF; This will be called when a battlefield is prepared for a battle prior to the combat beginning. It may be used in conjunction with the BF Receiver to set up a custom battlefield.
Suggestion: do not use !!BU:R command in !?BF trigger and before it.
!?BG; This combat trigger occurs at every action taken by any stack or by the hero (for spell casting, retreating and surrendering).
!?BG0 is called before the action occurs. (Same as !?BG)
!?BG1 is called after the action occurs.

Variable v997 keeps the number of the current turn:
   0 - start turn (after Tactics phase)
   1 - second turn
   2 - third turn
   ...
Comments:
You can use this with the BG Receiver to find a monster stack number (BG:N) and use this number to get access to this monster's set up (!!BR...).
!?BR; This trigger occurs every turn of a battle (for the first turn it occurs twice). Variable v997 keeps the number of the current turn:
  -1 - start turn (before Tactics phase)
   0 - start turn (after Tactics phase)
   1 - second turn
   2 - third turn
   ...
Comments:
1.
The starting turn (-1,0) goes in "darkness" and you will not be able to show any message, though you can take actions.

2.
The turn of a battle (v997) may be not the same if a Tactics phase took place. For the full sequence of triggers, see the detailed listing following the Triggers List.
Sequence of Combat Triggers
!?CM#; The trigger occurs when you click the mouse button.
 It sets up an internal ERM structure that can be used with the CM Receiver to get information about the area clicked as well as disabling the standard right-click function.
Comments:
Data in the structure will not be saved. This means that you can use it in a receiver section of this trigger.
!?CM0;  Right-mouse click on the adventure map
!?CM1;  Mouse manager trigger for town screen.
The trigger occurs when you click mouse button
You can also use !!CM receivers with the next commands: TSIFAR and cannot use P.
The trigger works for left mouse push (subtype=12), left mouse release (subtype=13) and right mouse push (subtype=14) and also has a corresponding bit in flags.
!?CM2; Mouse manager trigger for Hero information screen.
The current hero !!HE-1:... is an active one
!?CM3; Mouse manager trigger for Heroes meeting screen.
!?CM4; Mouse manager trigger for battle field.
Get the number of position on the battle field (and heroes image)
!?CM5; Left-mouse click on the adventure map
It may be used with all CM receiver commands that you use for right-mouse click: T, S, I, F, A, P, R.
!?CO#; Commander
!?CO0; is called before opening the Commander Dialog
!?CO1; is called after closing the Commander Dialog
!?CO2; is called after buying a Commander in a Town
!?CO3; is called after reviving a Commander in a Town

Flag 1000 set to 1 only if the owner of the hero is a human player who sits before the screen.
Flag 999 as usual shows whether this turn is a human player who sits before the screen.

You can use !!HE-1:... to get the current hero info and !!CO-1:...to get current Commander info.

Vars v998,v999,v1000 as usual shows the position of the current hero on the map.

!?FU#; Function with # (integer value 1-30000) called within a block of ERM code by an FU Receiver and followed by code that's part of the function.
!?GE#; This is a "global" event with number #. The # must be first in the Event text (the event title doesn't matter).
This number WON'T APPEAR later in message text in the game as long as it's used by a trigger.
Example:
Text "1230There you are!" transforms to "There you are!" with number 1230.
To change a global event, use the GE Receiver.
!?GM#; Saving/Loading trigger.
# = 0 - is called right after loading a saved game but before showing the map.
# = 1 - is called right before saving the game but after choosing the game to save.
!?HE#; This will be called when any hero attacks an enemy hero or visits/trades with an allied hero having the specified hero #. (see format H)
To change characteristics of a hero, use the HE Receiver.
!?HL#; Will be triggered whenever a hero gains a level.
   #=number of hero (-1 = all, see format H)
If you have !?HL-1 and !?HL5, for example, first will be processed all receivers for all heroes (HL-1) and then a particular hero (HL5).
To change the primary and secondary skills available when a hero gains a level, use the HL Receiver.
!?HM#; Take control over every step a hero takes. It is triggered before the hero takes each step (not after). So if you check v998, v999, v1000, you get a coordinate of the point the Hero will move to. This movement cannot be cancelled.
   #=number of hero (-1 = all, see format H)
At triggering moment you can find:
HE-1 will refer to a hero who moves.
   v998,v999,v1000 = x,y and level of the point of destination. Also, flag1000 is set to gamer (1) or AI (0) as usual.
If you have !?HM-1 and !?HM5 for example, first will be processed all receivers for all heroes (HM-1) and then a particular hero (HM5).
Example:
!?HM-1;
!!IF:M^Moving!^;
!?HM0;
!!IF:M^Personal Orin's Moving!^;
!?IP#; Multiplayer support.
If one player's hero attacks another player's hero, there
will be the next sequence:
a) !?BA0 trigger for "A"(attacker) player switches;
b) !?IP0; trigger switches for "A" player
c) data transferred to "D"(defender) player:
- "A" player's Hero info;
- "A" player's Hero Commander info (completely);
- v vars set v9001-v10000;
- all potentially changed monster statistics;
d) all sent data received at "D" player side;
e) !?IP1; trigger switches for "D" player;
f) !?BA0; trigger switches for "D" player;
Now the battle takes place.
If "A" player wins, no WoG data transferred.
if "D" player wins, there will be the next sequence:
a) "A" player goes to wait until "D" player gains levels;
b) "D" player's Hero and Commander gain levels;
c) !?IP2; trigger switches for "D" player;
d) data transferred tp "A" player:
- "D" player's Hero sec. skills (all 28), level and exp.;
- "D" player's Hero Commander info (completely);
- v vars set v9001-v10000;
e) !?BA1; trigger switches for "D" player;
f) "A" player goes from waiting until "D" player gains levels;
g) all sent data received at "A" player side;
h) !?IP3; trigger switches for "A" player;
i) !?BA1; trigger switches for "A" player;

As you can see, monsters, heroes and Commanders statistics should be identical now. As a side effect I can say that 10 sec. skills for Hero is a multiplayer safe rule. All 28 sec. skills transferred in both directions if needed.
!?LE#1/#2/#3; An Event on the map can be a Trigger. The contents and features of the Event are not significant in any way. The event won't be changed. It is used as an Event Trigger only. 
   #1- X position of the Event on the map
   #2- Y position on the map, 
   #3- level (0-ground, 1-underground). 
An Event must exist at that position on the adventure map.

You can refer to the  exact position of the event in receivers following the trigger: x,y and level will be stored  in v998,v999 and v1000 when the trigger activates.

Example:
?!LE10/21/0;
This will identify an event at the location x=10, y=21 on the surface map level (0) as a trigger. If a hero trips this event, then all ERM statements following the trigger code will be executed.
To change the properties of an event, use the LE Receiver.
!$LE... Post visit LE trigger
!?MF1; Trigger for a stack taking physical damage(before an action)
used with
MF Receiver
!?MG0;
!?M
G1;
Spell casting on the adventure map
!?MG0; - pre trigger
!?MG1; - post trigger
Sequence:
- player clicks the "cast spell" icon
- !?MG0; works out (you can adjust current hero spells)
- Magic Book appears and a player chooses a spell
- Spell casting
- !?MG1; works out (the cast spell number is stored in v997)
Example:
ZVSE

!?MG0;
!!IF:M^Magic is ready to cast^;

!?MG1;
!!VRy-10:Sv997;
!!IF:M^Magic was cast. Spell number: %Y-10^;


Comments:
This doesn't work for AI heroes, only human players.
!?MM;
!?MM0;
For control over scroll text during a battle
This trigger works when WoG is trying to show hint text in the scroll field (e.g., "fly here").
(See MM Receiver)

Comments:
The !?MM0 trigger only functions prior to an action being chosen. So, for example, if I cast a spell, the display hints that show up while choosing a target don't occur within the !?MM0 trigger at all. Once the target's been chosen and the spell's been cast, it returns to using the !?MM0 trigger until the next action is taken.
!?MM1; Now you can trigger ERM code when a player moves the mouse pointer inside the town screen. It will work when you go over a section and when you go off a section.

This trigger works out after standard behavior (usually hint text displaying).
(
See CM Receiver)
!?MR; !?MR0; Stack Resistance ERM control:!?MR0;!?MR1;
!?MR0; works out just before calculating a resistance correction for a stack. And !?MR1 works out after calculating. So here is the sequence:
- we have a basic damage from a spell (M,S,D);
- !?MR0 is called (M,S,D,F[=D]);
- WoG calculates a standard resistance correction (S,M, D->F);
- !?MR1 is called (M,S,D,F);
- end of correction (F).
Here M means a monster type, S means a spell number, D means the basic damage, F means the corrected damage.
Standard WoG correction function calculated F from D and returned it.
For creatures that have no resistance F=D.
(See MR Receiver)

!?MR2 Dwarf-style Magic Resistance
!?MR2; will work out when the game calculates dwarf-style magic resistance.
You may use !!MR and other triggers.
!!MR:N, !!MR:M works as before (described in !?MR0 and !?MR1 trigger
section). The !!MR:F here is used as a percentage (0..100) of a chance
for the spell to work.
Example:
ZVSE
!?MR2;
!!MR:F0;
all creatures are completely immune to all

!?MR1;
!?MR2;
!?MW0; Trigger for Wandering Monsters
Called when monster reaches a destination point/hero
Comments:
It will be called a next turn after monster really reached a position or just before attacking a Hero. Called if only a corresponding flag is set. v997 keep a number of WM that is a caller.
(See MW Receiver)
!?MW1; Trigger for Wandering Monsters, called when a monster is killed.
Comments:
It will be called the turn after a monster is really killed. It's only called if the corresponding flag is set. v997 keep the number of the WM that is the caller.
(See MW Receiver)
!?OB#1/#2/#3; This trigger works for any object that has an "entrance" (yellow square in editor). Note: this includes monsters, artifacts, and resource piles too but does not include other heroes (use the HL trigger for heroes).
   #1- X position of entrance on the map
   #2- Y position on the map, 
   #3- level (0-Surface, 1-Underground). 

Important. The sequence of finding object triggers:
!?OB$; common by type
!?OB$/$; common by type and subtype
!?OB$/$/$; particular object

You can refer to the exact position of the object in receivers following the trigger: x,y and level will be stored in v998,v999 and v1000 when the trigger activates.
Example:
!?OB101; come here for any chest on the map
!!CH998:...
change whatever you want
using indexed variables as a position x,y,l for a 
particular chest at x,y,l.

To set up or change the properties of an object, use the appropriate Object Receiver or the general OB Receiver


For a more detailed and explained version of OB trigger, read the OB trigger & receiver easily explained (ERM for dummies, by Qurqirish Dragon)

!?OB#1; Alternate format for OB trigger. Turns on for any objects of #1 type. See Format OB.
!?OB#1/#2; Alternate format 2 for OB trigger. Turns on for any objects of #1 type and #2 subtype. (See Format OB.)
!$OB#1/#2/#3; Post visit trigger is added.
It works now for objects only yet.
Syntax is !$OB... then all as usual.
Note: can work with a type format only (no subtype) as well as x/y/l and type/subtype
!$OB#1/#2; Alternate format 2 for Post visit trigger
Turns on for any objects of #1 type and #2 subtype. (See Format OB).
!?PI; Post Instruction.
   This trigger works out a bit later than instruction are executed but after the majority of settings are done for the map.
   The other specific thing here is that this trigger works out ONLY if you start a new game but not if you load a saved game (so the same way as instructions do).
Example:
ZVSE
!#IF:M^Instr^;

!?PI;
!!IF:M^Post Instr^;
   If you start this map, you will have two messages: "Instr" and then "Post Instr". When the first message appears, almost no settings are done for the map and when the second message appears, the most settings are done already. If you load a saved game, you will have no messages at all.
!?SN; In-game sound effects trigger
This triggers for any sound (WAV or M82, but NOT MP3). It triggers every time the game is trying to produce any sound. There is a corresponding receiver: !!SN.
For the sound effects list, please see Format SN.
!?TM#; This is the ERM equivalent of timed events.
   # - from 1 to 100 - the number of a timer.
To set up a timer, use the TM Receiver.
!?TH#; Two Triggers for Town Hall access. !?TH#;
   !?TH0; is called when you enter a Town Hall
   !?TH1; is called when you leave a Town Hall

Comments:
   1. You could use the TH1 trigger to check for a new building built in a town.
   2. You could also use it to reset the build flag with the CA:R command to allow additional building the same day.

Sequence of Combat Triggers with and without a Tactics phase:
Also a sequence of triggers is now:
(without tactic)
BA0 (on the map screen)
(in darkness)
BR(-1)
BF0
(show battle field)
BR(0)
(all actions of first round)
BG0-BG1
BG0-BG1
...
BG0-BR(1)-BG1 (second round started)
(all actions of first round)
BG0-BG1
BG0-BG1
...
BG0-BR(2)-BG1 (third round started)
and so on.
BA1 (on the map screen)

(with tactic)
BA0 (on the map screen)
(in darkness)
BR(-1)
BF0
(show battle field)
(all actions of first tactic round)
BG0-BG1
BG0-BG1
...
BG0-BR(-2)-BG1 (second tactic round started)
(all actions of second tactic round)
BG0-BG1
BG0-BG1
...
BG0-BR(-3)-BG1 (third tactic round started)
and so on
*BR(0)
(all actions of first round)
BG0-BG1
BG0-BG1
...
BG0-BR(1)-BG1 (second round started)
(all actions of first round)
BG0-BG1
BG0-BG1
...
BG0-BR(2)-BG1 (third round started)
and so on.
BA1 (on the map screen)

  Note:
1. A new round starts between BG0 and BG1.
2. *BR(0) may have two form. If a player has a tactic phase, this will be:
   BG0-BG1
   BR(0)
   Though if AI has a tactic phase, this will be:
   BG0-BR(0)-BG1
   So if you do not use BG1 trigger it will be the same.
   I did not test it for both AIs and both players, but think this
will be the same cases.