LUA common functions

A list of functions available in all three game modes - Adventure, Combat and Town.

number sqrt (number)

Returns the square root of number.

number random (n)

Returns a random number from 0 to n-1. n must be greater than 0, otherwise the function will throw an error.

void sleep (n)

n is a number which says to the game how many cycles the game to wait executing the thread where 1 cycle = 1/20 second. It is usually used inside an event-tracking thread to allow the game multiplex multiple threads or to wait for the results of a function with an effect on the game interface.

fProc parse (sToEval)

Returns a function that interprets the s string. It is the function that returns, and not its result.

parse (”print (123)”) ()
## 123

Those who want to see a more useful example can look into /scripts/advmap-startup.lua - there this function is used to create their modal analogs from modeless interface functions (that is, those that do not return control until they work out completely)

void print (s1, s2, ...)

Prints its arguments to the console.

void print_to (sFileName, v1, s2, ...)

Prints s2 string into file with path sFileName.

• If no s2 is given the sFileName file will be created but empty.
• if sFileName does not specify path, it will be created in <game folder>/bin directory.
• Path syntax uses direct slashes ( / ) instead of backslashes ( \ )

Note: This function is removed from the API after Heroes V 1.3 or later

sFileName create_file (sFileName)

Creates a file called sFileName. If already exists, the file is recreated.Note: This function is removed from the API after Heroes V 1.3 or later

sFileName open_file (sFileName)

If there was no file with the same name, creates it. Note: This function is removed from the API after Heroes V 1.3 or later

void _ERRORMESSAGE (sMsg)

The function issues an sMsg error message to the console, emulating a script error.

void errorHook (fCallback)

Sets an error trap. By default, when a script error occurs, the current thread terminates. Thanks to this function, you have the opportunity to correct this behavior - before stopping, control will be passed to the fCallback function.

function onError ()

   print ("Error occurred");

end;

function SetArtefactUntrans (nArtefactName)

   errorHook (onError)

   RemoveArtefact ("Berein", nArtefactName)

   GiveArtefact ("Berein", nArtefactName, 1)

end

When an error occurs in the SetArtefactUntrans function (for example, the hero does not have the required artifact), the string "Error occurred" will be displayed in the console. Have in mind that this very informative line will stop the runtime of the script (will issue a diagnostics in console). The hook will work in all script threads (not just the caller) until errorHook is called with the nil parameter.It is to be noted that the hook only works on runtime errors; it does not affect errors in the interpreter made by incorrect syntax. As for the given example, it is much more reasonable instead of using a hook to check the hero for the presence of the proper artifact.

void startThread (fProc, vParam1, vParam2, ...)

The function starts a new thread and passes its parameters to the streaming function. Adventure mode environment:

function setNewObjective (nArtID)

  while (1) do

    local heroes = GetPlayerHeroes (PLAYER_1)

    for i, h in heroes do

      if HasArtefact (h, nArtID) then

        SetObjectiveState ("obj1", OBJECTIVE_COMPLETED);

        break

      end

    end

    sleep (5)

  end

end

startThread (setNewObjective, ARTIFACT_RING_OF_MAGI)

The above fragment launches a stream that periodically checks for the player’s artifact. As soon as the player finds it, the function sets the lens proper to the “done” state and completes its work.

void doFile (spFileLUA)

Loads (and executes) a script file from the path specified.

nDifficulty GetDifficulty ()

Returns the difficulty level of the game. This number is from 0 to 3, respectively. DIFFICULTY_ * constants are written in /scripts/common.lua.

DIFFICULTY_EASY = 0

DIFFICULTY_NORMAL = 1

DIFFICULTY_HARD = 2

DIFFICULTY_HEROIC = 3

void consoleCmd (sCmd)

Executes the sCmd console command. In Adventure and Combat mode, the function has an alias named ExecConsoleCommand.

void SetGameVar (sVarName, sValue) //

SetGameVar defines a global variable. Global variables can be use to transfer data between campaign maps.

string GetGameVar (sVarName)

GetGameVar provides a way to get a global variable that was set with SetGameVar. If the variable is not set, an empty string will be returned.

void Save (sSaveName)

Creates a save game with name sSaveName.

void Load (sSaveName)

Loads a game from save with name sSaveName. If sSaveName is not defined as a save name during the map runtime, it will be interpreted as a regular file name. If defined, then the actual file name and description of the save game (i.e. the line that appears in the menu) will be taken from the corresponding. xdb.

void TutorialSetBlink( sID, nOn ); void TutorialMessageBox( sID ); bool IsTutorialMessageBoxOpen(); bool IsTutorialItemEnabled( sID ); void TutorialActivateHint( sID ); void TutorialSetBlink( sID, nBlink )

Functions that manipulate tutorial messages. Not much research is put into this area but various sIDs are listed in /UI/uiconsts.(UIGameConstsH5).xdb under /GameOptions/TutorialOptions/Hints/Item/ScriptID