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.
P$; W$; We have 1000 flags (from 1 to 1000).
Condition Management of the first ten flags Interpretation of value in IF:Q
Pictures Types and Subtypes: Type Subtype Resource Artifact *Note:
You can calculate the IF:Q subtype number (Format SQ) with the following formula:
Example: Note: Since
IF receiver involves, at some point, text messages, be aware that a string
cannot contain the ;
,
^ characters.
Example:
!!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.
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.
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.
Ask the player a question (TEXT) IMMEDIATELY
1. Simple question
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:
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:
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:
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 ^^.
Set conditional flag #1 (from 1 to
1000) at once in the meaning #2 (1
or 0).
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.
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
Type
and subtype of Pictures using the Q command
Type (0...7)
Quantity
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
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.
!!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
!!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".
^;