• If you are citizen of an European Union member nation, you may not use this service unless you are at least 16 years old.

  • You already know Dokkio is an AI-powered assistant to organize & manage your digital files & messages. Very soon, Dokkio will support Outlook as well as One Drive. Check it out today!


AdvancedMessageBox Documentation

Page history last edited by James Koppel 4 years, 8 months ago

There are many dialog boxes in HoMM II. Some of them display images; some of them have questions or two choices. 


The HoMM II source code has a very complicated function called NormalDialog with 10 parameters, which has all these options. 


For your common dialog needs, you can use MessageBox or QuestionBox or InputBox. For a few more common variants, such as displaying a dialog box with one or two images, you can use the functions in the AdvMessageBox Lua module. For common uses that aren't in that module, make a request, and we'll add to that module. But if you really need to do something different, you can use the raw AdvancedMessageBox function.


If this function doesn't make sense, that's not because you're stupid. It's because this function doesn't make sense.


Thank you to forum user DarkAtom and Ironfist team member Matt Jones for their work reverse-engineering this function.



AdvancedMessageBox(text, dialogtype, position1, position2, img1type, img1arg, img2type, img2arg, writeOr, a10)

text: A string or a variable that contains a string to be displayed
dialogtype: An integer (will be explained below)
position1 and position2: Controls the alignment of the message box. Explained below.
imgtype and imgarg: The image parameters will be explained below.
writeOr: If you set this to DIALOG_OR (1) then an 'or' text will appear in the middle of the box, between the 2 pictures. If only one picture is used, the 'or' text is displayed on top of it. If anything else is passed for this parameter, the "or" will not be shown.
a10:  This parameter is ignored always set to 0.below.

Returns: Depends on the dialog type. Some dialog types present multiple options, and AdvancedMessageBox will return true or false accordingly. For others, it will return true. See the documentation under Dialog types.




If you enclose text between curly braces {} then the text becomes golden.


Dialogue types:

  • 0 or anything below 0 (DIALOG_EMPTY): A window with no buttons, can't get rid of it
  • 1 (DIALOG_OKAY): A window with an OK button
  • 2 (DIALOG_YES_NO): A window with Yes/No buttons. Returns true if Yes was pressed, and false if No was pressed.
  • 3: A window with a Cancel button
  • 4: A window with no buttons, can get rid of it by clicking anywhere (this is probably for right-clicks)
  • 5: Same as 1
  • 6: Appears to be the same as 3. The game uses this internally for things like the "Waiting too connect to other player" dialog. Returns false if Cancel was pressed. This is intended to return true if the window is closed without pressing Cancel (as this dialog type is used in the game for things like waiting to connect), but there is currently no API for this to be possible.
  • 7: A window with 2 'Learn' buttons (like in the level-up screen). Returns true if the left Learn button is pressed, and false if the right one is.
  • 8: A window with a 'Learn' button on the left and nothing on the right
  • 9 and above: Same as 0


For now (Ironfist 1.3.0), none of the dialog types return anything, so it only makes sense to use types 1/5 and 3/6.




The third parameter, position1, changes the position of the messagebox on a horizontal axis. Setting the parameter to 0 moves it to the complete left of the screen and setting it to -1 moves it completely to the right. The higher the negative value, the more to the left it moves, and the higher the positive value the more to the right it moves. If you move a messagebox completely off screen it will wrap around to the other side of the screen. 


Changing the position2 parameter moves it on a vertical axis. However, on this one -1 lowers the message box and 0 raises it. The higher you set the value in the positive direction, the box will move down on the vertical axis. If you change the integer value below -1 the game will crash.

Image types:

The fifth and sixth parameter deal with displaying images in the message box. The fifth decides which "group" the images will be pulled from, and then the sixth parameter determines which image from that group should be displayed. The range for this stops at -1. Anything below it causes a crash. The value -1 itself displays no image. Here is an index for each image group:

  • -1 (IMAGE_EMPTY): No image
  • 0 (IMAGE_WOOD): Wood
  • 1 (IMAGE_MERCURY): Mercury
  • 2 (IMAGE_ORE): Ore
  • 3 (IMAGE_SULFUR): Sulfur
  • 4 (IMAGE_CRYSTALS): Crystal
  • 5 (IMAGE_GEMS): Gems
  • 6 (IMAGE_GOLD): Gold
  • 9 (IMAGE_GROUP_PLAYERS): Player color
  • 10 (IMAGE_LUCK): Good Luck
  • 11 (IMAGE_BADLUCK): Bad Luck
  • 12 (IMAGE_GOOD_MORALE): Good Morale
  • 13 (IMAGE_BAD_MORALE): Bad Morale
  • 14 (IMAGE_EXP): Experience
  • 15 (IMAGE_GROUP_HERO): Hero Portrait
  • 16: Not used (if you use it, game will freeze/crash)
  • 17 (IMAGE_GROUP_SECONDARY_SKILLS): Secondary Skill
  • 18 (IMAGE_GROUP_UNIT): Creature
  • 19-24: Same as -1
  • 25 (IMAGE_GROUP_PRIMARY_SKILLS): Primary Skill
  • 26+: Same as 16

Image subtypes (the number in the list represents the type for which the subtype applies)

  • -1: Put 0 to be safe
  • 0: Quantity (if you put 0 it will not show any number)
  • 1: Quantity (if you put 0 it will not show any number)
  • 2: Quantity (if you put 0 it will not show any number)
  • 3: Quantity (if you put 0 it will not show any number)
  • 4: Quantity (if you put 0 it will not show any number)
  • 5: Quantity (if you put 0 it will not show any number)
  • 6: Quantity (if you put 0 it will not show any number)
  • 7: Which artifact (use artifact name from the wiki)
  • 8: Which spell (use spell name from the wiki)
  • 9: Which color (blue-0, green-1, red-2, yellow-3, orange-4, purple-5)
  • 10: Doesn't matter
  • 11: Doesn't matter
  • 12: Doesn't matter
  • 13: Doesn't matter
  • 14: Quantity (works with negatives as well)
  • 15: Which portrait (start from 0, it's the same order as when you scroll through them in the editor)**
  • 16: As I said above, game crashes, so don't use it
  • 17: Which skill * (look at the asterisk below)
  • 18: Which creature (take their ID from \data\creatures.xml)
  • 19-24: Put 0 to be safe
  • 25: 0-3 (Attack, Defense, Spell Power, Knowledge) (100-103 displays a +1 skill)
  • 26+: Don't use it

Skills: Count the skills in the order from the wiki starting from 0 and stop at the one desired. Then multiply by 3 to get the basic picture. Add 1 for advanced, or 2 for expert.
Hero portraits: To display town captains, use 90-95 (knight, barbarian, sorceress, warlock, wizard, necromancer)


Resources: If you choose image type resource (0-6), you can set the subtype as negative and it will show the qty/day thing like from the mines. So if I set it to -6, for example, the message will show 6/day.


If you want to show negative values (like when taking resources), put the subtype -x-100000, where x is the value. So -100050 would show -50. If you put exactly -100000, it shows 100k/day, not -0.

Comments (0)

You don't have permission to comment on this page.