There’s a new interesting function in 3.1 (undocumented by Nival)

It allows you to create a complex message box with up to 5 options to choose from (and on top of that a ok/cancel button, or just an ok one). Maybe you’ll find it useful for some quests and other things

TalkBoxForPlayers(playersFilter, iconRef, iconTooltipRef, textRef, addTextRef, callback, mode, titleTextRef, selectTextRef, defaultOption, optionTextRef1 [, optionTextRef2 [, optionTextRef3 [, optionTextRef4 [, optionTextRef5] ] ] ])

playersFilter - Whom the dialog will be shown to, use constants from advmap-startup.lua, like in MessageBoxForPlayers (this is useful for Multiplayer, as the box may show for multiple players at the same time)

These are those constants: PLAYERFLT_1 = 1
PLAYERFLT_2 = 2
PLAYERFLT_3 = 4
PLAYERFLT_4 = 8
PLAYERFLT_5 = 16
PLAYERFLT_6 = 32
PLAYERFLT_7 = 64
PLAYERFLT_8 = 128
PLAYERFLT_ALL = 255

Alternatively you can use the GetPlayerFilter(player) function. The player parameter is the player ID (1, 2, 3, etc) and it will return the appropriate filter from above.

iconRef - a ref to xdb file pointing to a texture, Icon that will be shown in top left corner of dialog. If it’s " or nil, big white square will be shown.

iconTooltipRef - ref to txt file with text that will appear when hovering mouse above icon.

textRef - text that would be shown beside icon. HOWEVER, it does not show. A BUG, probably. You may as well leave it empty (nil or ").

addTextRef - text that is shown below the buttons with options

callback - name of a function that will be called when player hits OK/Cancel button.

mode - 0 = ok only; 1 = ok/cancel

titleTextRef - Caption text in the upper part of dialog (not mandatory)

selectTextRef - Text that will be shown above options (not mandatory)

defaultOption - 0 = no default; 1+ = Option ID (which one you want to be selected by default)

optionTextRef - text for options. You must enter separate parameter for each option, up to 5 options possible.

The callback function has two parameters, the first is the player ID (the one who pressed ok/cancel) and the second the choice ID. 1 for first option, 2 for second, etc. If player hits Cancel, the second parameter will be 0. If TalkBox timed out (in multiplayer only), it will be -1.

Here is an example from the script I wrote for Elvin’s Duel Map:
path = GetMapDataPath()

function NecroGive(player_id, choice)
local Heroes = GetPlayerHeroes(player_id)
local creature = 40
local amount = 4

if choice == 1 then creature = 152; amount = 130
elseif choice == 2 then creature = 154; amount = 30
elseif choice == 3 then creature = 155; amount = 13
elseif choice == 4 then creature = 156; amount = 6 end

AddHeroCreatures(Heroes[0], creature, amount)
end

TalkBoxForPlayers(GetPlayerFilter(player), "/Textures/HeroScreen/Skills/Necromancy_4.xdb#xpointer(/Texture)", nil, nil, path..“NecroDefault.txt”, “NecroGive”, 0, path..“NecroTitle.txt”, path..“NecroRaise.txt”, 5, path..“NecroRaise1.txt”, path..“NecroRaise2.txt”, path..“NecroRaise3.txt”, path..“NecroRaise4.txt”, path..“NecroRaise5.txt”)

In the above script the player will have 5 options to choose from, and each one will give the player different creatures in different numbers. It has no Cancel button.
In our case, the player will have the option to get 130 Skeleton Warriors, 30 Poltergeists, 13 Vampire Lords, 6 Lich Masters OR 4 Wraiths.

Written by Asheera