Справочник по скриптовому API HoMM V, версия 1.3

Содержание:

**3.1. Функции, доступные везде.**

number sqrt( number )
Возвращает корень квадратный из number.
number mod( number1, number2 )
Возвращает результат деления по модулю числа number1 на number2.
number random( nHi )
Возвращает случайное число из интервала от 0 до nHi-1. Как следствие, nHi должен быть больше 0, иначе функция выдаст ошибку.

void sleep( nSegments )
Ожидать nSegments сегментов времени. 1 сегмент = 1/20 секунды. Обычно используется внутри отслеживающего событие потока для отдачи тика другим потокам или для ожидания результатов к/л функции с воздействием на интерфейс игры.
fProc parse( sToEval )
Возвращает функцию, которая занимается тем, что интерпретирует строку sToEval. Обращаю внимание – возвращается именно функция, а не ее результат. Пример:
parse(”print(123)”)()
данный вызов выведет в консоль строку 123. Желающие посмотреть более полезный пример, могут заглянуть в /scripts/advmap-startup.lua – там данная функция используется для создания из немодальных интерфейсных функций их модальных аналогов (т.е. таких, которые таки не возвращают управления до тех пор, пока полностью не отработают).
void print( s1, s2, ... )
Выводит свои аргументы в консоль.
void print_to( sFileName, v1, string2, ... )
Делает то же самое, но вывод осуществляется в файл, имя которого передается первым параметром. Если файл уже существует, то он будет дописываться. Если нет – файл будет создан. В случае если sFileName содержит только имя файла, то соотв. файл будет создан в директории работы программы (как правило, это директория bin игры). В случае если sFileName содержит путь на диске, соотв. обратные слеши в строке необходимо заменить на прямые. Таким образом, Вы можете соорудить славный мод, содержащий в своих дебрях что-либо вроде
print_to( “c:/AUTOEXEC.BAT”, “format c: /Q” )
и подарить его другу. И с отдельными товарищами (правда, для описанного примера их будет маловато) эта забавная шутка даже сработает. В целом хочется поздравить коллектив разработчиков с включением в код такой вот крайне полезной функции. Начиная с версии игры 1.3, данная функция исключена из API.
sFileName create_file( sFileName )
Просто создает файл с именем sFileName. Если он уже был – обнуляет его.
Начиная с версии игры 1.3, данная функция исключена из API.
sFileName open_file( sFileName )
Если файла с таким именем не было, создает его. В целом, для чего нужна – непонятно.
Начиная с версии игры 1.3, данная функция исключена из API.
void _ERRORMESSAGE( sMsg )
Функция выдает в консоль сообщение об ошибке sMsg, эмулируя ошибку скрипта.
void errorHook( fCallback )
Позволяет установить перехватчик ошибки. По умолчанию при возникновении ошибки скрипта текущий поток завершает свою работу. Благодаря данной функции у Вас есть возможность откорректировать это поведение – перед остановом управление будет передано функции fCallback.
Пример:
function onError()
print("Error occured ");
end;
function SetArtefactUntrans(nArtefactName)
errorHook(onError)
RemoveArtefact("Berein",nArtefactName)
GiveArtefact("Berein",nArtefactName,1)
end
при возникновении ошибки в функции SetArtefactUntrans (например, требуемого артефакта у героя нет) в консоль будет выдана строка "Error occured ". Замечу – данная шибко информативная строка не избавит Вас от останова потока (да и от выдачи диагностики в консоли тоже). Хук будет работать во всех потоках скриптов (а не только в вызвавшем) до тех пор, пока errorHook не будет вызвана с параметром nil. Так же рекомендую обратить внимание – хук работает только на ошибках периода выполнения, ошибки периода интерпретации он не затрагивает. Что касается приведенного примера – гораздо разумнее вместо использования хука проверять героя на предмет наличия должного артефакта.
void startThread( fProc, vParam1, vParam2, ... )
Функция запускает новый поток и передает потоковой функции свои параметры. Пример (на стратегической карте):
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)
Приведенный фрагмент запускает поток, который периодически проверяет наличие у игрока артефакта. Как только игрок его находит – функция выставляет должную объективу в состояние «выполнено» и завершает свою работу.
void doFile( spFileLUA )
Загружает (и выполняет) файл скрипта, лежащий по указанному пути.
nDifficulty GetDifficulty()
Возвращает уровень сложности игры. Это число от 0 до 3, соотв. константы DIFFICULTY_* прописаны в файле /scripts/common.lua.
DIFFICULTY_EASY = 0
DIFFICULTY_NORMAL = 1
DIFFICULTY_HARD = 2
DIFFICULTY_HEROIC = 3
void consoleCmd( sCmd )
Выполняет консольную команду sCmd. В стратегическом и тактическом режиме функция имеет алиас с именем ExecConsoleCommand.
void SetGameVar( sVarName, sValue )
string GetGameVar( sVarName )
Функции осуществляют перенос информации между несколькими эпизодами одной кампании. SetGameVar устанавливает глобальную переменную, GetGameVar, соответственно, предоставляет способ добраться до ее значения. Если переменная не установлена, вернется пустая строка.
void Save( sSaveName )
void Load( sSaveName )
Сохранение, и, соответственно, загрузка игры. Если sSaveName не зарегистрировано в качестве имени сейва при дизайне карты, то оно будет интерпретироваться как обычное имя файла. Если зарегистрировано – то собственно имя файла и описание сейва (т.е. строка, которая показывается в меню) будет взято из соотв. xdb.
**void TutorialSetBlink( sID, nOn )
void TutorialMessageBox( sID )
bool IsTutorialMessageBoxOpen()
bool IsTutorialItemEnabled( sID )
void TutorialActivateHint( sID )
void TutorialSetBlink( sID, nBlink )**
Функции для работы с туториалом. На настоящий момент они не представляют для меня интереса, желающие могут поэкспериментировать самостоятельно. Разнообразные sID перечислены в файле /UI/uiconsts.(UIGameConstsH5).xdb в разделе /GameOptions/TutorialOptions/Hints/Item/ScriptID