DIALOGUE BOXES
List and explanations of Dialogue Box commands (IF Receiver).

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.

Example of displaying a simple message dialogue box with the M command:


!!IF:M^In this strange land, no creatures can fly, and creatures that once flew cannot be retaliated against.^;

The above will display a dialogue box on the screen with "In this strange land, no creatures can fly, and creatures that once flew cannot be retaliated against." (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.


Example of displaying a simple question with the Q command (no pictures):



!!IF:Q2^Special rules will modify this game. Would you like to choose them? (If not, one or two will be chosen randomly.)?^;

The above will display a dialogue box similar to the example above, and below it will be two buttons: OK and Cancel.
Since the number 2 was put after the Q, this means that flag number 2 will be set to true if OK was clicked and will be set to false if Cancel was clicked. Any flag number may be chosen to store a dialogue box question response. See Flags and Variables for more information about conditional flags.



Example of displaying a message and picture (no question):



!IF&1000:Q1/20/53/1^{Magic Water Mushroom}
The Magic Water Mushroom gives Expert Water Magic until the end of the week...
You inhale the spores of the magic mushroom...

You learn Expert Water Magic!^;
(Flag 1000 : Message won't appears if AI visits the object...)

Example of displaying a message and two pictures - player must click on the picture of choice before clicking the OK button:



!!IF&1000:Q1/5/0/8/141/7^Would you like to play for
{Resources} or {Artifacts}?^;


There are more combinations and options with both commands as well. See the command syntax for M and Q in the Options list below for more details.

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".  ^;

 
!!IF:XXXX;                   Dialogue Box display, including player yes/no questions, text input, checkbox selection, pictures and AVI animations.


Standard Dialogue 1: Simple Message Display
M^Text^ Show the message (Text) on the screen immediately.
The message (Text) may contain any symbols except the caret (^) and the semicolon (;).
M-1 Do not show the message on the screen.
M1/$ Set or get message text.
   M1/$ - $-index of string variable


Standard Dialogue 2: Question and Picture Display
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 ^.
Q.../10 Question type 10.
If you use IF:Q#/... command with message type 10 (choice of two pictures plus a Cancel button), the result will be stored not in the flag variable # but in the standard ERM variable (v#) but in the range of v1..v1000 only. So you will be able to take the returned value:
  0 = escape pressed
  1 = left picture is chosen
  2 = right picture is chosen
Q#1/#2/#3/#4^Text^

Show a message or request with one picture.
#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 (use this format with the !?CM trigger for right-click messages and use a value of -1 for type and subtype if you don't want any picture displayed)

Note: You must include the ^Text^ parameter or it will not work. If you don't want any text, use ^^.

Q#1/#2/#3/#4/#5/#6^Text^

Show a message or request with two pictures.
#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 (use this format with the !?CM trigger for right-click messages and use a value of -1 for type and subtype if you don't want any picture displayed)
   =7 - choose one of pictures (left=1, right=0)

Note: You must include the ^Text^ parameter or it will not work. If you don't want any text, use ^^.

Examples:
!!IF:Q1/3/100/2^Resource?^;
!!IF:Q1/4/10/1^Resource?^;
!!IF&1:Q1/10/3/27/10/7^Make your choice^;
!!IF&1:Q1/10/3/27/10/2^Make your choice^;

Q#1/#2/#3/#4/#5/#6/#7/#8^Text^ Show a message or request with three pictures.
   #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 (use this format with the !?CM trigger for right-click messages and use a value of -1 for type and subtype if you don't want any picture displayed)

Note: You must include the ^Text^ parameter or it will not work. If you don't want any text, use ^^.

Q$/.... Equal to Q...^Text^ but ^Text^ is a string variable with index = the last $


Extended Dialogue 1: Multipurpose Dialogue
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.

Example:


Here's the code:
!#VRz199:S^..\Data\Zvs\Cmp.res^;
!#VRz198:S^B21p^;
!#VRz10:S^Time to play^; 
!#VRz11:S^Name yourself^; 
!#VRz12:S^Choose your spell^; 
!#VRz13:S^%Z199\21_001.BMP^; 
!#VRz14:S^%Z199\21_002.BMP^; 
!#VRz15:S^%Z199\21_003.BMP^; 
!#VRz16:S^%Z199\21_004.BMP^; 
!#VRz17:S^Bloodlust^; 
!#VRz18:S^Bless^; 
!#VRz19:S^Magic Arrow^; 
!#VRz20:S^Slow^; 
!#VRz21:S^Your hero will start with the Bloodlust spell^; 
!#VRz22:S^Your hero will start with the Bless spell^; 
!#VRz23:S^Your hero will start with the Magic Arrow spell^; 
!#VRz24:S^Your hero will start with the Slow spell^; 
!#IF:D1/z10/z11/z12/z13/z14/z15/z16/z17/z18/z19/z20/z17/z18/z19/z20; 
!#IF:F1/z21/z22/z23/z24/0;
Give hints and disable cancel button 
!#IF:E100/1; The choice will be store in v100
!#VRz400:Sz1;
your name 
!#VRz400:H10;
Check if the string is empty and Flag 10 
!#VRz400&-10:S^Caneghem^;
if the string is empty call the hero Caneghem

Extended Dialogue 2: Single Image/Animation Dialogue
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)

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.

 

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: secondary skill pictures start from 3 which is Basic Pathfinding and go up to 86 which is Expert First Aid. All secondary skill pictures also include the level (basic, advanced or expert).

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

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

G#1/#2/#3/#4/#5(/#6/#7/#8/#9/#10/#11/#12/#13/#14/#15/#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