IF - CONDITIONAL
RECEIVER

Used for management of conditional flags, asking players yes/no type questions (Gamer Related Model), displaying messages and pictures, hero variable selection, extended dialog boxes and CMD setup.

!!IF:XXXX; Management of conditional flags (1-1000), player questions (GRM), plus message and picture display.

OPTIONS

B#/$1/$2; Use this command to set up or change a Single Image/Animation Extended Dialogue Box to be displayed with the IF:P command.
   # - number of dialogue (1..100)
   $1 - index of string variable that stores the name of an image (BMP, GIF or JPG) or AVI file
   $2 - for AVI to repeat continuously (1) or not (0)
D#/$1...$15; Use this command to set up or change a Multipurpose Extended Dialogue Box to be displayed with the IF:E command.
   # - number of dialogue (1..100)
   ($=index of z variable that holds text to use)
   $1 - Title Text (White) at top of dialogue box.
   $2 - Right Legend (Yellow) above input box.
   $3 - Left Legend (Yellow) of 4 checkboxes..
   $4 - Pic/AVI 1 (left) File in Heroes3/Maps folder.
   $5 - Pic/AVI 2 - File in Heroes3/ Maps folder.
   $6 - Pic/AVI 3 - File in Heroes3/ Maps folder.
   $7 - Pic/AVI 4 (right) File in Heroes3/ Maps folder.
   $8 - Legend of Picture 1 (mouse-over hint)
   $9 - Legend of Picture 2 (mouse-over hint)
   $10 - Legend of Picture 3 (mouse-over hint) 
   $11 - Legend of Picture 4 (mouse-over hint)
   $12 - Choice 1 (checkbox) - button text.
   $13 - Choice 2 (checkbox) - button text.
   $14 - Choice 3 (checkbox) - button text.
   $15 - Choice 4 (checkbox) - button text.
Comments:
If you use 0 or an empty parameter it means do not change. If you use a null string ^^ for a prompt it means no prompt. A full path name (up to 256 character) may be included for the picture files but remember that it starts in the MAPS directory so use ".." to go up one directory if required. e.g., ^../data/mypic.bmp^. Maximum picture size is 100*100 but may be less (if less, the picture will be centered automatically). Setup information will not be saved when game is saved, so always do setup immediately before using IF:E command.
E$1/$2; Use this command to display a Multipurpose Extended Dialogue box, previously set up with the IF:D (and also possibly IF:F) commands. 
   $1 - an index of a v variable to store a selection
   $2 - number of extended dialogue
Comments:
Variable will receive 1,2,3,4 if one of the buttons was selected and -1 if none were selected (just exit). The text answer always (even if there was no prompt) will be stored in the z1 variable.
F$1/$2/$3/$4/$5/$6; Use this command to add hint text to checkboxes in a Multipurpose Extended Dialogue Box. This command is an extension to the IF:D command.
   #1=number of dialog (1..100)
   $2=hint for checkbox 1 - index of z variable
   $3=hint for checkbox 2 - index of z variable
   $4=hint for checkbox 3 - index of z variable
   $5=hint for checkbox 4 - index of z variable
   $6=enable Cancel/ESC button (1) or not (0)
Comments:
Setup information will not be saved when game is saved so always do setup immediately before using IF:E command.

G#1/#2/#3/#4/#5/(up to #16);

Set up Radio or Checkbox Dialogue (Up to 12 choices)
   #1= 1 - Radio buttons (one choice) 
          0 - Check boxes (multiple choice)
   #2= Number of v var that receive a result.
   #3= Initial state of buttons
   #4= Number of z var with a window header.
   #5= Number of z var with a name of the first item
          0-do not show
   #6= Number of z var with a name of the second item
          0-do not show
   ...
   #16= Number of z var with a name of the twelve item
          0-do not show
Comments:
1. State that received an stored is "one bit for one item".
  Item1=1,
  item2=2,
  item3=4,
  item4=8,
  item5=16...
So to set all items val=4095
To set item 2,4,5,8 and 10 val=2+8+16+128
All reset val=0

Example:

L^text^
L$
Add a message to a screen log.
    L^text^ - will add text
    L$ - will add contents of z[$] variable.
Comments:
    It looks as though you press Tab, type a message and press <Enter>.
    The message pops up a previous message.
    You have up to 20 message on the screen.
    Every message stays on the screen for 20 seconds.
    It may work at adventure screen and in a battle.
    When you go to a battle or from a battle, the message should left on the screen.
M^TEXT^;
M1/$;
Show the message (Text) or contents of z$ variable on the screen immediately.
The message may contain any symbols except the caret (^) and the semicolon (;).
Example
M$/#1/#2 Show message immediately. Extended.
  $ - variable to receive reply item
  #1 - type of dialogue:
     = 1 - standard Ok
     = 2 - Yes/No (Ok/Cancel)
     = 4 - right mouse info (is visible while right mouse button isn't released)
     = 7 - choice from two options (not supported yet)
     = 10 - choice from two options with escape (not supported yet)
  #2 - message (direct text or index of any Z variable)
N...; IF Receiver command for 8 picture message box.
A message with text and up to 8 pictures of any internal types.
Fisrt, you must set pictures to show by N#1/#2/#3/#4/#5/#6/#7/#8/
#9
/#10/#11/#12/#13/#14/#15/#16;

And after that show the dialog with prepared pictures and ^text^ by N^text^; command.
If you set more than 3 parameters, the interpreter treats it as pictures types/numbers the same way as for the IF:Q dialog.
You may set up to 8 pictures (16 parameters) and minimum 2 pictures.
No dialog is shown, just preparation phase.
So:
!!IF:N3/8/10/2/11/3/13/2/17/
1000/21/99/22/4;
means that the first picture (3/8) is a resource - sulfur with quantity 8. The next one is (10/2) a flag of Tan player, then Luck and so on. You can see that here we have 7 pictures.

If you have less than 4 parameters, the interpreter treats it as a command to show the dialog that was prepared with the previous syntax.
The only parameter here is the text to display:
!!IF:N^text^; - direct text
or
!!IF:N1/$;- z var (standard, local or extended)
In any case, the text is parsed for any format commands and as a result you will not see something like this "Hi %Z10!" but "Hi Slava!".

There is one limitation to the text: it can not have too many lines. This example is close to the maximum:
!!IF:N^This
is
a
looo...
..
..
..
..
..
oong
Text
^;
If you have more lines, the game crashes.

P$;

Use this command to display a Single Image/Animation Extended Dialogue Box, previously set up with the IF:B command.
  # - number of dialogue to display.
Q...; Ask the player a question (TEXT) IMMEDIATELY
1. Simple question
Q#^Text^
Ask the player a question (TEXT)
The answer (Ok=1, Cancel=0) is put into conditional flag # (from 1 to 10). The message (TEXT) may contain any symbols except ^.

Example:

Show a message or request with one picture.
Q#1
/#2/#3/#4^Text^
#1 - number of flag
#2 - type of the picture (see list below)
#3 - subtype of the picture
#4 - type of message
    =1 - message (FLAG #1 WILL NOT BE SET!!!)
    =2 - request yes/no (stored to the flag)
    =4 - message with no buttons, visible until button is released
Example:

Show a message or request with two pictures.
Q#1/#2/#3/#4/#5/#6^Text^

#1 - number of flag
#2 - type of the picture 1
#3 - subtype of the picture 1
#4 - type of the picture 2
#5 - subtype of the picture 2
#6 - type of message
   =1 - message (FLAG #1 WILL NOT BE SET!!!)
   =2 - request yes/no (stored to the flag)
   =4 - message with no buttons, visible until button is released
   =7 - choose one of pictures (left=1, right=0)
   =10 - choose one of pictures, save result in v#1 (left=1, right=2, escape=0)
Example:

Show a message or request with three pictures.
Q#1/#2/#3/#4/#5/#6/#7/#8^Text^

#1 - number of flag
#2 - type of the picture 1
#3 - subtype of the picture 1
#4 - type of the picture 2
#5 - subtype of the picture 2
#6 - type of the picture 3
#7 - subtype of the picture 3
#8 - type of message
   =1 - message (FLAG #1 WILL NOT BE SET!!!)
   =2 - request yes/no (stored to the flag)
   =4 - message with no buttons, visible until button is released
   =10 - choose one of pictures, save result in v#1 (left=1, right=2, escape=0)

Note: You must include the ^Text^ parameter or it will not work. If you don't want any text, use ^^.
V#1/#2; Set conditional flag #1 (from 1 to 1000) at once in the meaning #2 (1 or 0).

W$;

Set number of hero-recipient of w-variables.
Every hero has 200 w-variables
Comments:
They are called w# (#=1...200)
They may be used everywhere when f...t variables.
You should set the hero you refer to by these vars:
($=1...155,-1=current)

Every time you apply W$ command, you will refer then to a particular hero's variables.
!!IF:W-1 refers to the current hero.
(see also Flags&Variables section and VR section)
X$; Answer the gamer Sphinx question
   $ - number of question (-1 = random)
Comments:
This brings up the Sphinx question dialog box.
All Questions and answers are taken from ZSphinx.txt
file. If you have not the TxtEditor, you can use a CmdEditor to add something there. 
First column - question,
second column - answer.
For now the exact coincidence of gamer answer with written one means correct. ERM Flag1 will be set to 1 if answer is correct and 0 if answer is wrong.

We have 1000 flags (from 1 to 1000).

Condition Management of the first ten flags

AXXXX Set all 10 flags at once. The line XXXX consists of 10 zeroes and ones. 
Example:
A0100010000
- set all conditional flags into 0 but the second and six. At the beginning of game all the flags set into zero.
RXXXX Set off the pointed out flags.
The line XXXX consist of 10 zeroes and ones.
Example:
R0100010000 set second and six into zero, the rest are not changed.
SXXXX Set the pointed out of the ten flags.
The line XXXX consists of 10 zeroes and ones.
Example:
S0100010000 set second and six into one, the rest are not changed.

Interpretation of value in IF:Q
The game interprets negative value for all resources as a -value/day. But. If you subtract another -100000, it will be interpreted as +value+100000.
So:
   !#IF:Q1/6/200/1^Message^; -> Gold: 200
   !#IF:Q1/6/-200/1^Message^; -> Gold: 200/day
   !#IF:Q1/6/-100200/1^Message^; -> Gold: -200

The same for money:
   !#IF:Q1/36/-100/1^Message^; -> 100/day
   !#IF:Q1/36/-100100/1^Message^; -> -100

For monsters you can set their numbers:
subtype=Nums*65536+subtype.
   !#IF:Q1/21/327686/1^Message^; -> 5 Swordsmen 65536*5+6
   !#IF:Q1/21/65542/1^Message^; -> 1 Swordsman 65536*1+6
   !#IF:Q1/21/6/1^Message^; -> Swordsmen

And for secondary skills you can set skill and level:
subtype = (Skill Number * 3) + Skill Level + 2.
   !#IF:Q1/20/45/1^Message^; -> Basic Fire Magic 14*3+1+2
   !#IF:Q1/20/41/1^Message^; -> Expert Necromancy 12*3+3+2

Pictures Types and Subtypes:

Type and subtype of Pictures using the Q command
 

Type 

Subtype 

Resource

Type (0...7) Quantity

Artifact

8 Number of artifact
Spell 9 Number of spell
Flag 10 Number of flag
Luck (positive) 11 + of luck
Luck (neutral) 12 no matter
Luck (negative) Not supported in heroes. 13  - of luck
Morale (positive) 14 + of Morale
Morale (neutral) 15 no matter
Morale (negative) 16  - of Morale
Experience 17 Quantity
Secondary Skill 20 Skill + level *
Monster 21 Type of monster
Buildings in Towns 22....30
=0..8 by town type
(Format T)
Type of building
(Format U)
Primary skill 31...34 (0..3) Quantity
Spell Points 35 Quantity
Money 36 Quantity

*Note: You can calculate the IF:Q subtype number (Format SQ) with the following formula:

   Subtype = (Skill Number (from Format SS) * 3) + Skill Level + 2.

   For example, let's say you want to display the picture for Basic Fire Magic. Fire Magic is skill number 14 (Format SS), and Basic is skill level 1, therefore: 14*3=42 +1=43 +2=45 (Format SQ). So you would use IF:Q with a type of 20 and subtype of 45.

   This formula should be used to calculate the Format SQ number (for IF:Q display) in your script when you DON'T know the specific skill number and level ahead of time, for example if you're displaying a randomly chosen skill.

Description

Introduction
Whenever you want to display a message on the screen, ask the player a question, display pictures or animations for the player or ask the player to select between different options or type some input (e.g., a name or the answer to a riddle), you will need to use a Dialogue Box.

Types of Dialogue Boxes
There are two main types of dialogue boxes that can be accessed through ERM. The first is the standard dialogue, which is the one you see in regular Heroes games. The second is the extended dialogue, which is used for displaying external picture and animation files, accepting typed input, and displaying options with checkboxes. Which one you use will depend on the type of information you wish to display. Both types may be used to display information only, or may be used to display a message or picture and ask for user input in one form or another, which may be as simple as choosing between clicking OK or clicking Cancel. The standard dialogue box is simpler to use than the extended dialogue box which requires an additional command or two to set up.

Using Standard Dialogue Boxes
There are basically only two commands used for standard dialogue boxes: M which is used for simple message display, and Q which is used for asking Yes/No type questions and also for displaying messages with pictures. In both cases there are format variations, depending on exactly what you want to do.

The command IF:M^text^ will display a dialogue box on the screen with "text" (without the quotes) in white text, centered. At the bottom of the box will be a single OK button that the user must click (or press Enter) to continue playing.

Using Extended Dialogue Boxes 1 - Multipurpose Dialogue

If you want to accept typed user input, let a user select from up to four checkboxes, and/or display up to four custom pictures or animations, you will need to use an extended dialogue box. In general, you'll need to store some text in z variables and then use either one or two setup commands, followed by the command that displays the dialogue box.  The IF:D and IF:F commands are used to set up a multipurpose extended dialogue box and IF:E is used to display it. Any combination of the following options may be combined in a multipurpose extended dialogue box:

1. Displaying Pictures: Unlike the standard dialogue box, the extended dialogue box cannot display internal pictures, but only pictures that are stored externally to the program in an appropriate directory and of a specified type and size. If you need to display an internal Heroes picture, you'll have to extract it or screen-capture it and save it as an external image file first. The directory and file path for custom pictures (up to four per dialogue box) can be up to 256 characters long and starts in the Heroes3\Maps directory. The pictures may be BMPs, GIFs or JPGs with a maximum size of 100 x 100 pixels. If an image is smaller than the maximum size, it will be centred in the space. If the image is larger, only a 100 x 100 pixel portion will be shown. For BMPs, the upper-left pixel will be interpreted as the transparent colour. For GIFs, see the example GIF (ZObj001.gif) that can be found in your Heroes III directory (Heroes3\erm_help\images\Castle\ZObj001.gif). You can mix and match the picture formats as you wish. The IF:D command is used to set up pictures for a multipurpose extended dialogue box.

Example:
!!VRz10:S^The lands you travel through are mesmerizing.^;
!!VRz11:S^green forest.jpg^;
!!VRz12:S^sparkling lake.bmp^;
!!VRz13:S^rainbow.gif^;
!!VRz14:S^mountains.jpg^;
!!VRz15:S^Murky Forest^;
!!VRz16:S^Crystal Lake^;
!!VRz17:S^Mystic Rainbow^;
!!VRz18:S^Misty Mountains^;
!!IF:D5/10/0/0/11/12/13/14/15/16/17/18/0/0/0/0;
!!IF:E1/5;


In the above example, z10 stores title text for the dialogue, z11..z14 store file names of images placed in the maps directory, and z15..z18 are the mouse-over hint text for each of the pictures. The dialogue box number we decide to use is 5 (first parameter), followed by the z variable index holding the title text (10), followed by two zeroes, indicating we're not using/changing the next two parameters. After that are the z variable indexes for the file names (11..14) and the z variable indexes for the hint text (15..18). The last four parameters are also unused in this example and so we fill them with zeroes.
Once the dialogue box is set up with the IF:D command, the !!IF:E1/5; command on the next line displays it on the screen. The first number (in this case, "1") is the index for the variable that will store the selection. In the above example, this is basically just a dummy number since we haven't included any checkboxes for a selection to be made. The second number (in this case, "5") is the number of the extended dialogue box as declared in the IF:D command (the first parameter after the "D").



2. Displaying an Animation: You can use the extended dialogue box to display an animation or movie clip in AVI format. An AVI animation can be displayed instead of any picture and may be combined with pictures (e.g., you could display two AVI animations, a JPG and a BMP in a single multipurpose extended dialogue). AVI animations must be stored in uncompressed format or they won't work. Like pictures, animations are also limited to 100 x 100 pixels. Again, IF:D is used to set up animations for a multipurpose extended dialogue box.

3. Checkboxes: If you want a player to have a choice between four (or fewer) options, you can use checkboxes. Above the checkboxes, you can put a title message (appearing in bold yellow). Each checkbox will have a text label identifying it, and can also have hint text (shows up on the bottom of the dialogue when you do a mouse-over of the checkbox). And although you can't put pictures on the checkboxes themselves, you can match the checkbox selections to pictures displayed above if you wish. When the dialogue first displays, no boxes are checked. The user can select only one checkbox; selecting another unchecks the previous selection. After the user clicks OK, you can check which checkbox was selected; the number will be stored in a v variable. Like picture and animation setup, IF:D is used to set up checkboxes and IF:F is used to add hint text (mouse-over text) to the checkboxes, if desired.

4. Text Input: If you want to get a typed response from a player, you can display an input box. Above the input box you can put a title message (appearing in bold yellow). The text entered by a player in an input box is stored in a string variable (z variable) and could be used to name a hero or town, replace hint text, appear on a sign, appear as part of another message, or could be checked to see if it correctly answers a riddle or question. You can also use input text in combination with the UN:N lookup command to do a kind of reverse-lookup and search for a matching artifact name, monster name, town building, or skill name. IF:D is used to set up text input.

5. Title Text: Title text (in white) that appears at the top of the dialogue box can be set with the IF:D command, and the yellow text for checkboxes can be used even if you don't use checkboxes in the dialogue.

6. Cancel Button: The IF:F command can be used to disable or enable the cancel button (and keyboard escape key) for a multipurpose extended dialogue box.
Example:
!#IF:F1/z21/z22/z23/z24/0; Give hints and disable cancel button

Using Extended Dialogue Boxes 2 - Single Image/Animation Dialogue
If you wish to display a single image (BMP, GIF or JPG) or a single AVI animation file, you can use the second type of extended dialogue box instead. This dialogue is simpler to set up than the multi-purpose dialogue (fewer parameters) and has the advantage that it can display an image or video of almost any size. The main disadvantage is that you can't include any text with the image or animation. When you call this dialogue, you get a simple message box, with the image or AVI centred and an OK button below. The command to set up this dialogue is IF:B and the command to display it is IF:P. There is, however, some overlap with the IF:D command (used to set up the multi-purpose extended dialogue box) -- if you use the IF:D command instead of IF:B, the first picture or AVI in the parameter list is the one that will be displayed with IF:P and additional pictures or animations will be ignored. If you use both IF:D and IF:B, whichever command occurs last before the IF:P command will be the one that sets the picture or animation to display.

Extended Dialogue 3: Radio or Checkbox Dialogue (Up to 12 choices)



Example:
!#VRz1:S^1111111111^;
!#VRz2:S^222222^;
!#VRz3:S^333333333333333^;
!#VRz4:S^4444444^;
!#VRz5:S^55555555555^;
!#VRz6:S^666666666666666^;
!#VRz7:S^7777777^;
!#VRz8:S^88888888^;
!#VRz9:S^999999999999^;
!#VRz10:S^AAAAAAAAAA^;
!#VRz11:S^BBBBBBBBBBBB^;
!#VRz12:S^CCCCCCCC^;
!#VRz25:S^Set you choice in forward order (all are set):^;
!#IF:G0/100/4095/25/1/2/3/4/5/6/7/8/9/10/11/12;
!#IF:M^Your choice is: %V100^;

!#VRz25:S^Set you choice in backward order (all are reset):^;
!#IF:G0/100/0/25/12/11/10/9/8/7/6/5/4/3/2/1;
!#IF:M^And now your choice is: %V100^;

!#VRz25:S^Set you choice for selected items:^;
!#IF:G0/100/4095/25/1/0/3/4/0/0/7/8/9/0/0/0;
!#IF:M^Your choice is: %V100^;

!#VRz25:S^Set you choice for RADIO Buttons:^;
!#IF:G1/100/8/25/1/2/3/4/5;
!#IF:M^Your choice is: %V100^;


Message Handling
Inside ERM messages (M and Q commands of IF receiver) you can use special syntax:
"%%" -> "%"
"%V#" -> current value of # flag.
"%Vf"..."%Vt" -> current value of corresponding variable.
"%W1"..."%W100" -> current value of corresponding hero variable.
"%X1"..."%X16" -> current value of corresponding function parameter.
"%Y1"..."%Y100" -> current value of corresponding local variable.
"%Z1"..."%Z500" -> current value of corresponding string variable.
"%$macro$" -> macro name of corresponding variable
"%Dd" -> current day of week
"%Dw" -> current week
"%Dm" -> current month
"%Da" -> current day from beginning of the game
"%Gc" -> the color of current gamer in text

Lookup Command
Sometimes you will know the number of a monster, artifact, town building, secondary skill or spell, but won't know the name of it (especially true if it's generated randomly). In this situation, you can use the UN receiver's lookup command. This command lets you enter a number and get back the a text name that will be stored in a z variable and may be included in a message dialogue. For details on the lookup command, see the N command on the UN Receiver page.


Dialogue Box Command Syntax

 Note: Since IF receiver involves, at some point, text messages, be aware that a string cannot contain the ; , ^ characters. Example:
!!IF:M^this is a wrong text ; it contains ^special elements^.  ^;
!!VRz567:S^wrong text ; it contains ^special elements^. ^;
!!IF:M^this is a correct  text. It contains no "special elements".  ^;