New scripting functions for 3.1 - the list

[Franzy]

The guy from Nival said they did not document new functions. However, -he provided a list and encouraged mapmakers "to experiment!":
---------------------------------------
Here is the list of additional parameters for some existing functions:

+ added additional param to select teleport's effect in script command SetObjectPosition() (only applicable for heroes now, default param value is -1 ~ as if no param behaviour)
+ extended param for script commands: AddHeroCreatures, RemoveHeroCreatures, AddObjectCreatures, RemoveObjectCreatures (param name "desiredSlot", default value is -1)
+ added GetSoundTimeInSleeps() for combat scripts
+ voice-overs script functions (see game maps scripts)
+ added new script triggers types: HERO_ADD_SKILL_TRIGGER, HERO_REMOVE_SKILL_TRIGGER, function HeroGotSkill( heroName, skill, mastery ) print( "Hero ", heroName, " got skill #", skill, " at mastery level #", mastery ); end;
+ additional hero trigger (HERO_TOUCH_TRIGGER), only works for disabled heroes

--------------------------------------
Here is the list of new functions:

GetPlayerRace( player_id ), returns town type id (see advmap-startup.lua)
IsAIPlayer( player_id ), returns 0 if specified player is human, and 1 otherwise
type,count = GetObjectArmySlotCreature( objName, slotIndex );
GetPlayerTeam( playerID )
GetPlayerNecroEnergy( playerID )
WarpToMap( mapdbid, playerID = -1 )
WarpHeroExp( heroName, exp )
GiveHeroBattleBonus( heroName, bonusType, amount )
GetTownRace( townName )

TalkBoxForPlayers( playersFilter, iconRef, iconTooltipRef, textRef, addTextRef, callback, mode, titleTextRef, selectTextRef, defaultOption, optionTextRef [, optionTextRef, ...] )
//
// iconRef: empty or non-existing for default icon
// iconTooltipRef: no tooltip if empty
// textRef: constructed texts supported
// addTextRef: constructed texts supported
// callback param values: 0 = cancelled, 1+ = option ID, (-1) = auto-closed (turn time limit exceed/etc.)
// modes: 0 = ok only (default), 1 = ok/cancel
// titleTextRef: plain text ref, non-string or empty/non-existing string to leave default
// selectTextRef: plain text ref, non-string or empty/non-existing string to leave default
// defaultOption: 0 = no default, 1+ = option ID
// optionTextRef: constructed texts supported
// ... up to 5 options supported (may be extended in future)
//

floor(n)
ceil(n)
intg(n)
frac(n)
round(n)
---------------------------
Apparently, some testing will be needed to find out what they do...

[Asheera]

TalkBoxForPlayers seems a pretty interesting function, but I can't understand most parameters

[Franzy]

I'll try to make an example map with most of these functions... In a few days.

[Asheera]

Hey Franzy, are you the legendary CrazyPill at HC who managed to decode some parts of the exe?

[Franzy]

No. I always use only one nick. If you see 'Franzy' anywhere, it's very likely me. This is my Internet alias

[Asheera]

I just thought that because CrazyPill also posted these functions at HC

[Franzy]

Originally they were posted on nival forum and ag.ru forum... Anyway, I suddenly realized I don't want to make a demo map. I've made some experiments, and here are some additional explanations and examples.

---------------------------------------
SetObjectPosition(obj,x,y,z,style)

Additional parameter (style) controls video effect of teleportation (as far as I could make it out, works only for heroes). Default value is -1.
style = -1,0 - Standard effect (astral gate)
= 1 - no effect, instant teleportation
= 2,3 - no effect plus a little delay (about 1 sleep)
= 4 - town portal effect
--------------------------------------------

TalkBoxForPlayers( playersFilter, iconRef, iconTooltipRef, textRef, addTextRef, callback, mode, titleTextRef, selectTextRef, defaultOption, optionTextRef [, optionTextRef, ...] )

playersFilter - Whom the dialog will be shown to, use constants from advmap-startup.lua, like in MessageBoxForPlayers.

iconRef - a ref to dxb file pointing to a texture, Icon that will be shown in top left corner of dialog. If ='' or nil, big white square will be shown (very gay).
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 envoked when player hits OK button.
titleTextRef - Caption text in the upper part of dialog (not mandatory)
selectTextRef - Text that will be shown above options (not mandatory)
optionTextRef - text for options. You must enter separate parameter for each option, up to 5 options possible.

Here is an example. I use Sphinx face as an icon.


function choiceisdone(playerid,answer)
--'playerid' holds id of player who sent the callback (as the talkbox could be shown to several players at once)
--'answer' holds option number. 1 for first option. 2 for second, etc. If player hit 'Cancel', answer will hold 0. If TalkBox timed out (in multiplayer games only), it will hold -1.

end;

path= GetMapDataPath();

TalkBoxForPlayers( PLAYERFLT_ALL, '/Textures/Interface/Sphinx/SphinxIcon.(Texture).xdb#xpointer(/Texture)', '', path..'maintext.txt', path..'addtext.txt', 'choiceisdone', 0, path..'captiontext.txt', path..'selecttext.txt', 0, path..'option1.txt', path..'option2.txt',path..'option3.txt')

-------------------------------
Other functions have selfexplanatory names. Ask if confused. The only mystery for me is WarpToMap. It's not clear how to appoint map ids...

[Franzy]

Important note: if you miss something in TalkBox or pass a wrong parameter, THE GAME WILL NOT GENERATE ERROR, nor it will say anything in console, talkbox won't be shown, and script won't be interrupted.

[rdeford]

@ Franzy -- what about that multi-option question box you were talking about being in 3.1? I don't see it listed. The editor has a QuestionBoxInt() function I don't recall being there before. Could that be it? If so, what is the syntax and the parameters?

[Asheera]

Isn't TalkBoxForPlayers a message box with multiple options?

[Franzy]

Isn't TalkBoxForPlayers a message box with multiple options?

Excatly. Talkbox is question box with up to five possible answers (and with picture of your choice...)

[Franzy]

Anyone,
who downloaded english patch 3.1
Could you please check one thing?

Locate file a2p1-data.pak in data folder, open it as zip-archive, and see if there is file UI/CommonBoxes/TalkBox/text.txt.

Reply here.

[Avonu]

I see only xdb files.

[Asheera]

Anyone,
who downloaded english patch 3.1
Could you please check one thing?

Locate file a2p1-data.pak in data folder, open it as zip-archive, and see if there is file UI/CommonBoxes/TalkBox/text.txt.

Reply here.

You meant a2p1-texts.pak, right?

And yes, there is a file like that. It contains:

<h4><color_bright><value=text>

[Franzy]

Very well, that means 'no main text' bug in talk box applies to Russian version only Thankfully, it can be easily corrected.