Novik16

Heroes of Might&Magic: 3.2. Стратегический режим.

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

**3.2. Стратегический режим.**

При старте стратегического режима игра делает следующее:
1) Загружает файл /scripts/advmap-startup.lua и все прописанные в нем с помощью doFile скрипты
2) Вызывает функцию createAdvmapAliases()
3) Приступает к интерпретации файла скрипта текущей карты.
Кроме перечисленных выше общих функций в данном режиме доступны следующие:

3.2.1 Общая работа с параметрами игрока.

nPlayerID GetCurrentPlayer()
Возвращает ID текущего игрока. Соотв. PLAYER_? константы см. в файле /scripts/advmap-startup.lua. Коротенько – в случае кампании номер игрока-человека равен PLAYER_1 = 1.
nPlayerStateID GetPlayerState( nPlayerID )
Возвращает статус игрока nPlayerID. Бывает таким:
PLAYER_NOT_IN_GAME = 0
PLAYER_ACTIVE = 1
PLAYER_WON = 2
PLAYER_LOST = 3
number GetPlayerResource( nPlayerID, nResID )
Возвращает текущее количество ресурса nResID у игрока nPlayerID. ID ресурсов прописаны в /scripts/advmap-startup.lua и бывают такими:
WOOD = 0
ORE = 1
MERCURY = 2
CRYSTAL = 3
SULFUR = 4
GEM = 5
GOLD = 6
void SetPlayerResource( nPlayerID, nResID, nCount )
Установка текущего количества ресурса nResID в nCount для игрока nPlayerID. На основе данной функции в файле /scripts/advmap-common.lua реализован примитив более высокого уровня – void SetPlayerStartResource( nPlayerID, nResID, nCount ) который распределяет игроку стартовые ресурсы в зависимости от уровня сложности.
void SetPlayerStartResources( nPlayerID, nWoodCnt, nOreCnt, nMercuryCnt, nCrystalCnt, nSulfurCnt, nGemCnt, nGoldCnt )
Установка текущего количества ресурсов для игрока nPlayerID. В принципе данная функция эквивалентна ряду вызовов SetPlayerResource. Отличие будет видно только на интерфейсе результата миссии.
tsHeroes GetPlayerHeroes( nPlayerID )
Возвращает таблицу, содержащую имена всех героев указанного игрока.
void SetPlayerHeroesCountNotForHire( nPlayerID, nCount )
Уменьшает количество героев, которых сможет нанять игрок, на nCount. Общее количество нанимаемых устанавливается при дизайне.
nPlayerID GetObjectOwner( sObjectName )
Возвращает ID игрока, которому принадлежит объект. В качестве объекта может выступать герой, город, строение, герой и т.п. Если объект не принадлежит никому, вернет PLAYER_NONE.
void SetObjectOwner( sObjectName, nPlayerID )
Устанавливает владельца объекта sObjectName в nPlayerID.
bool IsObjectVisible( nPlayerID, sObjectName )
Возвращает, виден ли игроку nPlayerID объект с именем sObjectName. В случае, если объект занимает на карте более одного тайла, функция может работать некорректно (фактически, в этом случае она возвращает виден ли игроку центр объекта).
void OpenCircleFog( nX, nY, nFloorID, nRadius, nPlayerID )
Открывает для игрока nPlayerID туман войны в окружности с центром в указанных координатах и радиусом nRadius. Константы для nFloorID прописаны в /scripts/advmap-startup.lua и бывают такими:
GROUND = 0
UNDERGROUND = 1

3.2.2 Работа с объективами

nState GetObjectiveState( sObjectiveName, nPlayerID = PLAYER_1 )
Возвращает статус объективы sObjectiveName. Соотв. константы прописаны в /scripts/advmap-startup.lua и бывают такими:
OBJECTIVE_SCENARIO_INFO = 0
OBJECTIVE_UNKNOWN = 1
OBJECTIVE_ACTIVE = 2
OBJECTIVE_COMPLETED = 3
OBJECTIVE_FAILED = 4

void SetObjectiveState( sObjectiveName, nState, nPlayerID = PLAYER_1 )
Устанавливает статус объективы с именем sObjectiveName. Следует понимать, что не у всех объектив статус можно установить вручную – можно или нельзя, определяется дизайном карты. Если таки нельзя, то вызов ни к чему, кроме выдачи ошибки в консоль, не приведет.
Кроме того, то, какой статус можно установить объективе зависит от текущего статуса объективы. Матрица переходов следующая:
OBJECTIVE_SCENARIO_INFO -> none
OBJECTIVE_UNKNOWN -> OBJECTIVE_ACTIVE, OBJECTIVE_FAILED
OBJECTIVE_ACTIVE -> OBJECTIVE_COMPLETED, OBJECTIVE_FAILED
OBJECTIVE_COMPLETED -> OBJECTIVE_ACTIVE, OBJECTIVE_FAILED
OBJECTIVE_FAILED -> none
Если объективе выставляется статус OBJECTIVE_ACTIVE она автоматически становится видимой игроку (см. IsObjectiveVisible/SetObjectiveVisible)
**nProgress GetObjectiveProgress( sObjectiveName, nPlayerID = PLAYER_1 )
void SetObjectiveProgress( sObjectiveName, nProgress, nPlayerID = PLAYER_1 )**
Возвращает и устанавливает степень прогресса в выполнении объективы sObjectiveName в случае, если дизайн это позволяет. Типичный пример – директива «наберите армию из 1000 лучников».
**bool IsObjectiveVisible( sObjectiveName, nPlayerID = PLAYER_1 )
void SetObjectiveVisible( sObjectiveName, bVisible, nPlayerID = PLAYER_1 )**
Функции возвращают и устанавливают видимость на интерфейсе объективы с именем sObjectiveName.
3.2.3 Работа с ключами.
bool HasBorderguardKey( nPlayerID, nKeyID )
void GiveBorderguardKey( nPlayerID, nKeyID )
Функции проверяют наличие и выдают игроку ключ должного цвета. Соотв. константы для nKeyID прописаны в /scripts/advmap-startup.lua и бывают такими:
RED_KEY = 1
BLUE_KEY = 2
GREEN_KEY = 3
YELLOW_KEY = 4
ORANGE_KEY = 5
TEAL_KEY = 6
PURPLE_KEY = 7
TAN_KEY = 8

3.2.4 Работа с регионами.

void SetRegionBlocked( sRegionName, bEnable, nPlayerID = -1 )
Блокирует/разблокирует регион sRegionName для игрока nPlayerID. Если последний параметр не указан, то данное действие производится для всех игроков.
bool IsRegionBlocked( sRegionName, nPlayerID )
Возвращает, заблокирован ли регион sRegionName для игрока nPlayerID.
tsObjects GetObjectsInRegion( sRegionName, nObjectsTypeID )
Возвращает массив имен объектов в регионе с именем sRegionName. На настоящий момент второй параметр может быть только OBJECT_HERO = 0, а соотв. массив будет содержать только информацию о героях. На основе данной функции в файле /scripts/advmap-startup.lua реализован примитив более высокого уровня –
bool IsPlayerHeroesInRegion( nPlayerID, sRegionName )
nX, nY, nFloorID RegionToPoint( sRegionName )
Возвращает координаты региона в том случае, если регион состоит из одного тайла. Если нет – ничего полезного не вернет, а ошибку таки вызовет.
bool IsObjectInRegion( sHeroName, sRegionName )
Проверяет, находится ли объект sHeroName внутри региона sRegionName. На настоящий момент функция работает только для объектов одного типа – для героев.
void OpenRegionFog( nPlayerID, sRegionName )
Открывает для игрока nPlayerID туман войны, скрывающий регион sRegionName.

3.2.5 Работа с AI.

Для не AI игрока перечисленные ниже функции смысла не имеют, и при вызове приводят к ошибке.
void SetAIPlayerAttractor( sObjectName, nPlayerID, nPriority )

Устанавливает для игрока nPlayerID «точку притяжения» на объекте с именем sObjectName. Герои игрока будут бегать вокруг объекта, периодически к нему возвращаясь и пытаясь им овладеть. (Да-да, Вы правильно подумали, в качестве имени объекта в данной функции может выступать и имя героя). Поведение игрока будет тем агрессивнее, чем больше nPriority. Последний может принимать значения от -1 до 2. Значение nPriority = 0 является выделенным, и используется для того, чтобы убрать данную логику. В официальном руководстве по скрипту имеется предупреждение, что данная функция может некорректно работать для подвижных объектов.

void SetAIHeroAttractor( sObjectName, sHeroName, nPriority )
Функция аналогичная SetAIPlayerAttractor, но работает только для одного героя с именем sHeroName.
void EnableHeroAI( sHeroName, bEnable )
Включает/выключает AI героя.
void MoveHero( sHeroName, nX, nY, nFloorID = -1 )
Герой поскачет в точку с указанными координатами. В свой ход, и сообразно наличию movepoints. Если не указан этаж, то будет использован тот, на котором герой находится. АИ героя должен быть отключен. Если герой не может достичь указанного тайла (тайл занят), вызов функции приведет к ошибке. Если герою не хватает movepoints, чтобы достичь тайла, движение будет продолжено на следующий ход.
bool CanMoveHero( sHeroName, nX, nY, nFloorID = -1 )
Возвращает, может ли герой в принципе доскакать до тайла с указанными координатами.
Данная функция не работает с героями, находящимися внутри города. Если не указан этаж, то будет использован тот, на котором герой находится.
void EnableAIHeroHiring( nPlayerID, sTownName, bEnable )
Разрешает или запрещает AI игроку nPlayerID найм героев в городе sTownName. По умолчанию найм разрешен.

3.2.6 Работа с героями.

Герои – один из видов объектов. Ввиду большого количества функций, которые работают именно с ними, я рассмотрю их в отдельном разделе.
Если герой, имя которого передано в функцию, отсутствует, то вызов функции приводит к ошибке.
**nCount GetHeroStats(HeroName, nStatID)
void ChangeHeroStat( sHeroName, nStatID, nDelta )**
Получение/изменение того или иного стата героя. Соотв. константы для nStatID прописаны в /scripts/advmap-startup.lua и бывают такими:
STAT_EXPERIENCE = 0
STAT_ATTACK = 1
STAT_DEFENCE = 2
STAT_SPELL_POWER = 3
STAT_KNOWLEDGE = 4
STAT_LUCK = 5
STAT_MORALE = 6
STAT_MOVE_POINTS = 7
STAT_MANA_POINTS = 8
Обращаю внимание, что функция ChangeHeroStat не устанавливает, а изменяет стат. Т.е. третьим параметром передается не новое значение стата, а разница со старым (которая может быть и отрицательной). В отличие от прочих, STAT_EXPERIENCE не может быть уменьшен. STAT_MOVE_POINTS и STAT_MANA_POINTS представляют собой текущие значения соответствующих параметров, выставить их выше максимальных – нельзя.
Кроме указанных имеется, по крайней мере, еще один стат с ID = 9. Установить его нельзя, можно только получить. Что он из себя представляет, сказать затрудняюсь.
На основе функции ChangeHeroStat в файле /scripts/advmap-common.lua реализован примитив более высокого уровня – void GiveExp( sHeroName, nExp ).
bool HasHeroSkill( sHeroName, nSkillID )
Получение того или иного скилла/перка/фита героя. Соотв. константы SKILL_*, PERK_* и *FEAT* для nSkillID см. в /scripts/advmap-startup.lua. Сюда писать не буду ввиду большого объема. Как можно увидеть, способа получить уровень мастерства в скилле данная функция не предоставляет.
bool GiveHeroSkill( sHeroName, nSkillID )
Ввыдача того или иного скилла/перка/фита герою. Соотв. константы SKILL_*, PERK_* и *FEAT* для nSkillID см. в /scripts/advmap-startup.lua. Сюда писать не буду ввиду большого объема. В случае удачной выдачи скилла GiveHeroSkill вернет true. В противном случае (например, герой уже имеет уровень мастерства expert в данном скилле) функция вернет nil.
**void KnowHeroSpell( sHeroName, nSpellID )
void TeachHeroSpell( sHeroName, nSpellID )**
Получение/выдача того или иного заклинания герою. Соотв. константы SPELL_* для nSpellID см. в /scripts/common.lua. Сюда писать не буду ввиду большого объема. Кстати, по крайней мере четыре заклинания в lua файл таки не попало – см. содержимое /types.xml.
bool LevelUpHero( sHeroName )
Выдать герою с именем sHeroName один уровень. Точнее говоря – выдать количество exp points, которых герою не хватает до следующего уровня. Если герой уже достиг максимально возможного уровня функция вернет nil, в противном случае – true.
Функция имеет алиас с именем GiveExpToLevel.
nLevel GetHeroLevel( sHeroName )
Получить уровень героя с именем sHeroName.
bool IsHeroAlive( sHeroName )
Возвращает, жив ли герой с именем sHeroName.

void DeployReserveHero( sHeroName, nX, nY, nFloorID = GROUND )
Разместить по указанным координатам героя из резерва. Герои резервируются при дизайне карты. В таверне, соответственно, их нанять нельзя. Если указанный тайл уже занят, герой будет размещен на ближайшем свободном тайле. Если на момент вызова функции герой мертв, он все равно будет размещен по указанному тайлу в своем изначальном состоянии (т.е. с армией, указанной при дизайне карты).
Если указанный герой не был резервирован при дизайне, вызов функции приведет к ошибке.
void UnreserveHero( sHeroName )
Вывести указанного героя из резерва. Соответственно, данный герой становится доступным к найму в тавернах. Если к моменту вызова функции этот герой еще жив, и находится под контролем игрока, то из под контроля он не выводится. К найму он будет доступен только после гибели.
Если указанный герой не был резервирован при дизайне, вызов функции приведет к ошибке.
nCost CalcHeroMoveCost( sHeroName, nX, nY, nFloorID = -1 )
Возвращает количество movepoints героя, которые ему придется затратить при перемещении в точку с указанными координатами. Если в данную точку переместиться нельзя (т.е., например, путь кем-либо заблокирован), функция вернет -1. Данная функция не работает с героями, находящимися внутри города. Если не указан этаж, то будет использован тот, на котором герой уже находится.
void MoveHeroRealTime( sHeroName, nX, nY, nFloorID = -1 )
Герой поскачет в точку с указанными координатами. Безотносительно того, чей ход и наличия/отсутствия у него movepoints. Данная функция не работает с героями, находящимися внутри города. Если не указан этаж, то будет использован тот, на котором герой находится. Если герой не может достичь указанного тайла, вызов функции приведет к ошибке. Если тайл занят героем противника (и герой находится в «разрешенном» состоянии, см. SetObjectEnabled), стартует тактическая битва.
Функция немодальна – скрипт продолжит выполнение сразу после вызова функции, а не после того, как герой достигнет точки назначения. Интерфейс пользователя и действия АИ блокируются на время движения героя.
**nCount GetHeroCreatures( sHeroName, nCreatureID )
void AddHeroCreatures( sHeroName, nCreateureID, nCount )
void RemoveHeroCreatures( sHeroName, nCreatureID, nCount )**
Функции соответственно возвращают/добавляют/удаляют герою с именем sHeroName стек юнитов типа nCreatureID. Соотв. константы CREATURE_* для nCreatureID см. в /scripts/common.lua. Сюда писать не буду ввиду большого объема. Если стек должного типа отсутствует у героя, то вызов RemoveHeroCreatures к ошибке не приводит. В случае, если у героя отсутствуют стеки за исключением удаляемых, одно существо из стека герою будет оставлено.
Герой с именем sHeroName может отсутствовать на глобальной карте (например, может находиться в городе).
void GiveArtefact( sHeroName, nArtID, nBindToHero = 0 )
Выдает герою с именем sHeroName артефакт nArtID. Соотв. константы ARTIFACT_* для nArtID см. в /scripts/advmap-startup.lua. Сюда писать не буду ввиду большого объема.
Если третий параметр отличен от нуля, то передать артефакт другому герою будет нельзя.
Артефакт всегда экипируется, если это возможно, и всегда выдается в единичном количестве. Чтобы выдать два одинаковых – нужно вызвать функцию с одинаковыми параметрами дважды.
Если после выдачи артефакта подразумевается к/л немедленное продолжение работы с этим предметом (типа удаления, или проверки наличия) рекомендую писать sleep(1) сразу после GiveArtefact. Т.к. иначе предмет может не успеть выдаться. Собственно, это замечание относится ко всем функциям, в которых герою (или объекту) что-либо выдается. Отсюда мораль – ставьте sleep, он лишним не будет. Функция имеет алиас с именем GiveArtifact.
bool HasArtefact(sHeroName, nArtID)
Функция возвращает, есть ли у героя с именем sHeroName хотя бы один артефакт nArtID. Узнать, использует ли герой артефакт, или последний просто валяется в торбе, нельзя.
void RemoveArtefact( sHeroName, nArtID )
Функция удаляет у героя с именем sHeroName один артефакт nArtID. Если он у него есть. Если нет – вызов функции приводит к ошибке.
**void SetHeroLootable( sHeroName, bEnable )
bool IsHeroLootable( sHeroName )**
Функции устанавливают/возвращают «лутабельность» героя с именем sHeroName. Говоря по-простому – будет ли выпадать из героя лут при его поражении в бою.
void MarkObjectAsVisited( sObjectName, sHeroName )
Выставляет у объекта sObjectName «признак посещенности» героем с именем sHeroName на текущий день. Если объект имеет статус enabled (см. ниже IsObjectEnabled и SetObjectEnabled), вызов данной функции приводит к ошибке.
sTownName GetHeroTown( sHeroName )
Если герой с именем sHeroName находится в городе (имеется ввиду – именно внутри, а не на карте около входа), то данная функция возвращает имя города. В противном случае функция вернет nil.
sHeroName GetTownHero( sTownName )
Аналогично GetHeroTown, но в этом случае имя героя ищется по имени города.
tsObjects GetObjectsFromPath( sHeroName, nX, nY, nFloorID = -1 )
Функция возвращает массив объектов, мимо которых герой с именем sHeroName проскачет при путешествии из Петербурга в Москву… т.е. из текущего своего положения в точку с указанными координатами. Если не указан этаж, то будет использован тот, на котором герой находится.
**void GiveHeroWarMachine( sHeroName, nWarMachineID )[
void HasHeroWarMachine( sHeroName, nWarMachineID )
bool RemoveHeroWarMachine( sHeroName, nWarMachineID )**
Функции выдают/проверяют наличие/удаляют машину nWarMachineID у героя с именем sHeroName. Соотв. константы для nWarMachineID прописаны в /scripts/common.lua и бывают такими:
WAR_MACHINE_BALLISTA = 1
WAR_MACHINE_CATAPULT = 2
WAR_MACHINE_FIRST_AID_TENT = 3
WAR_MACHINE_AMMO_CART = 4
Попытка удалить несуществующую машину к ошибке не приводит. Удалить катапульту в любом случае не удастся. В случае успеха функция возвращает true, иначе – nil.
void StartCombat( sHeroName, sEnemyHeroName, nEnemyIDCount, nCreatureID1, nCount1, nCreatureID2, nCount2, ..., spScriptXDB, sFinishProc, spAdventureFlybySceneXDB = nil )
Одна из трех возможностей инициировать переход на тактическую карту непосредственно из скрипта стратегического режима. О параметрах подробнее:
sHeroName – атакующий герой.
sEnemyHeroName – защищающийся герой. Может быть nil в случае атаки нейтралов без героя.
nEnemyIDCount – количество стеков в армии защищающегося. Должно быть больше нуля.
Далее перечисляются nEnemyIDCount пар вида
nCreatureID – тип существа и nCount – количество существ в стеке.
spScriptXDB – путь к XDB файлу тактического скрипта, либо nil, если дело происходит «на автомате».
sFinishProc – имя функции, которой будет передано управлении после окончания боя (с уведомлением о результате). Обращаю внимание, что это именно строка, а не параметр типа функция. Данный callback имеет следующий прототип:
void combatDone( sHeroName, bWin )
где sHeroName – имя атакующего героя, а bWin – статус сражения относительно атакующего (nil – поражение, иначе – победа).
spAdventureFlybySceneXDB – путь к xdb, определяющему арену, на которой будет происходить сражение. Если nil, то будет взята арена, тип которой соответствует типу местности, на которой находится атакующий герой на стратегической карте.
В официальном руководстве по скриптам утверждается, что у функции есть еще один параметр – allowQuickCombat, при выставлении которого в true битва будет происходить в режиме QuickCombat (если настройки игры это позволяют). Насколько я понимаю, это является ошибкой, такого параметра нет.
void SetHeroCombatScript( sHeroName, spScriptXDB )
Функция выставляет герою с именем sHeroName скрипт, который будет работать в последующих тактических боях. Если происходит эпическая битва между двумя героями, оба из которых имеют установленный скрипт, то работает скрипт атакующего. В официальном руководстве по скрипту сказано, что навешенный скрипт будет работать только для героя под управлением АИ – это не так.
void ResetHeroCombatScript( sHeroName )
Функция сбрасывает навешенный ранее на героя скрипт. Если ничего навешено не было, то ошибки не происходит.
void SiegeTown( sHeroName, spAdvMapTownXDB, spAdventureFlybySceneXDB = nil )
Собственно, стартует осада города, путь к xdb с описанием которого задан во втором параметре, на арене, заданной третьим параметром. Если последний параметр nil, то берется арена по умолчанию.

[Bar]3.2.6 Работа с городами.

Если город, имя которого передано в функцию, отсутствует на карте, то вызов функции приводит к ошибке.
**nLevel GetTownBuildingLevel( sTownName, nBuildingID )
nLevel GetTownBuildingLimitLevel( sTownName, nBuildingID )
nLevel GetTownBuildingMaxLevel( sTownName, nBuildingID )**
Функции позволяют узнать уровень/лимит на развитие/максимальный уровень здания nBuildingID в городе с именем sTownName. Соотв. константы TOWN_BUILDING_* для nBuildingID см. в /scripts/advmap-startup.lua. Сюда писать не буду ввиду большого объема.
Уровень 0 означает, что соответствующее здание отсутствует.
void SetTownBuildingLimitLevel( sTownName, nBuildingID, nLevel )
Функция позволяет выставить лимит на уровень развития здания nBuildingID в городе с именем sTownName. При попытке выставить уровень больше максимально возможного вызов функции приводит к ошибке. Уровень 0 означает запрет на строительство здания.
void TransformTown( sTownName, nTownTypeID )
Трансформирует тип города с именем sTownName. Соотв. константы для nTownTypeID прописаны в /scripts/advmap-startup.lua и бывают такими:
TOWN_HEAVEN = 0
TOWN_PRESERVE = 1
TOWN_ACADEMY = 2
TOWN_DUNGEON = 3
TOWN_NECROMANCY = 4
TOWN_INFERNO = 5
Если в момент трансформации в городе находится герой, он погибнет.
void RazeTown( sTownName )
Разрушает город с именем sTownName. Только в том случае, если при дизайне карты город помечен как «разрушаемый» (т.е. поле razed в его свойствах корректно заполнено). Иначе вызов данной функции приводит к ошибке. Фактически город удаляется с карты и заменяется на статический объект, который занимает столько же тайлов, сколько и оригинал.

3.2.7 Работа с объектами.

Под объектом понимается практически все, что угодно – это здания, города, монстры, герои и т.п. Правда, некоторые функции работают только с определенными видами объектов (например, про работу с героями рассказано выше). Если объект, имя которого передано в функцию, отсутствует, то вызов функции приводит к ошибке.
nX, nY, nFloorID GetObjectPosition( sObjectName )
Функция возвращает позицию объекта. Функция имеет алиас с именем GetObjectPos. На основе данной функции в файле /scripts/advmap-startup.lua реализован примитив более высокого уровня – bool IsInDungeon( sObjectName ).
В качестве объекта может выступать, например, герой.
void SetObjectPosition( sObjectName, nX, nY, nFloorID = -1 )
Функция устанавливает позицию объекта. Объект должен быть перемещаемым, что определяется при дизайне этого самого объекта. Например, города перемещать нельзя.
В качестве объекта может выступать, например, герой. Если не указан этаж, то будет использован текущий, т.е. тот, на котором объект уже находится. Попытка переместить объект на уже занятый тайл приведет к ошибке.
Функция имеет алиас с именем SetObjectPos.
void RemoveObject( sObjectName )
Удаляет объект с карты. Объект должен быть перемещаемым и присутствовать на карте. Т.е., например, город удалить нельзя.
В качестве объекта может выступать, например, герой.
bool IsObjectExists( sObjectName )
Возвращает, существует ли на карте объект с данным именем. Функция имеет алиас с именем Exists. В качестве объекта может выступать, например, герой.
bool IsObjectEnabled( sObjectName )
Возвращает, находится ли объект с именем sObjectName в состоянии enabled. Если да, то объект будет взаимодействовать с героем игрока обычным образом (т.е. для города – зарядится интерфейс города, для героя противника – стартует битва и т.п.) В противном случае «атоматом» ничего происходить не будет. Это удобно, когда на объект навешен триггер OBJECT_TOUCH_TRIGGER, который должен среагировать на «тырканье» нестандартным образом.
void SetObjectEnabled( sObjectName, bEnable )
Выставляет или снимает с объекта sObjectName состояние enabled.
tsObjects GetObjectNamesByType( sObjectTypeSubstr )
Выдает массив имен объектов на карте в соответствии с подстройкой sObjectNameSubstr, которая встречается в наименовании его типа. Полностью список соответствующих строк BUILDING_*, TOWN_*, CREATURE_* и HERO_CLASS_* можно найти в файле /types.xml, ветка /Base/Tables. Обращаю внимание, что 1) параметр – именно строка и к константам в /scripts/common.lua имеет весьма опосредованное отношение 2) полного совпадения имени не требуется, достаточно совпадения куска. Например, вызовы
GetObjectNamesByType(“SAWMILL”) и GetObjectNamesByType(“BUILDING_SAWMILL”) вернут один и тот же массив.
**void AddObjectCreatures( sObjectName, nGreatureID, nCount )
nCount GetObjectCreatures( sObjectName, nCreatureID )
void RemoveObjectCreatures( sObjectName, nCreatureID, nCount )**
Позволяет добавить/получить/удалить стеки существ, охраняющих объект. В качестве объекта может выступать любой объект, допускающий наличие армии, либо монстр на карте. В последнем случае функцией AddObjectCreatures добавить можно только существ, которые уже есть в армии монстра. Если после операции удаления в армии монстра не остается ни одного существа, монстр удаляется с карты. Герой в качестве объекта выступать не может (несмотря на то, что в официальном руководстве по скриптам написано обратное). Соответствующие операции с героем осуществляются с помощью функций GetHeroCreatures/AddHeroCreatures/RemoveHeroCreatures.
**void SetObjectDwellingCreatures( sObjectName, nCreatureID, nCount )
nCount GetObjectDwellingCreatures( sTownName, nCreatureID )**
Позволяет установить/получить стеки существ, которые будут э-э-э, произрастать в объекте, если последний является точкой найма (например, городом). Уточню – изменить тип нанимаемых существ нельзя, можно управлять только их количеством. Например, при попытке вызвать SetObjectDwellingCreatures для города инферно с параметром nCreatureID=1 (крестьяне) никаких крестьян в городе не образуется. (Впрочем, к ошибке данный вызов не приводит) Т.е. данный тип стека должно в принципе быть возможным нанять в указанном месте.
void CreateArtifact( sArtName, nArtID, nX, nY, nFloorID )
Создает артефакт nArtID в точке с указанными координатами и присваивает ему имя sArtName.
void ShowFlyingSign( spTXT, sObjectName, nPlayerID = -1, nTimeSec = 1.0)
Показывает всплывающую надпись из файла spTXT над объектом sObjectName для игрока nPlayerID в течение nTimeSec секунд. Если nPlayerID = -1, то надпись показывается для всех игроков. Функция имеет алиас с именем ShowFlyMessage.
void CreateMonster( sMonsterName, nCreatureID, nCount, nX, nY, nFloorID, nMonsterMoodID, nCreatureCourageID )
Создает стек существ из nCount существ типа nCreatureID в указанных координатах и присваивает ему имя sMonsterName. Созданный стек имеет mood и courage (ага, трудности у меня с внятным переводом – настроение и кураж? Как-то не звучит…) в соответствии с константами
MONSTER_MOOD_FRIENDLY = 0
MONSTER_MOOD_AGGRESSIVE = 1
MONSTER_MOOD_HOSTILE = 2
MONSTER_MOOD_WILD = 3
и
MONSTER_COURAGE_ALWAYS_JOIN = 0
MONSTER_COURAGE_ALWAYS_FIGHT = 1
MONSTER_COURAGE_CAN_FLEE_JOIN = 2
Данные константы нигде не определены. Стек принадлежит нейтральному игроку c ID = PLAYER_NONE.
Если тайл с указанными координатами занят, монстр будет создан на ближайшем свободном тайле. Начиная с версии игры 1.3 последние два параметра функции имеют умолчательные параметры MONSTER_MOOD_AGGRESSIVE и, соответственно, MONSTER_COURAGE_CAN_FLEE_JOIN. В официальном руководстве к скриптам у функции указан еще один опциональный параметр – rotation. Однако, даже если он и есть, то на результат никак не влияет.
Функция имеет алиас с именем CreateMob.
void RemoveAllMonsters( nCreatureID )
Удаляет с карты все стеки с типом существ nCreatureID. Функция имеет алиас с именем KillMobs
void GenerateMonsters( nCreatureID, nCountGroupsMin, nCountGroupsMax, nCountInGroupMin, nCountInGroupMax )
Генерирует в рандомных местах карты от nCountGroupsMin до nCountGroupsMax стеков существ типа nCreatureID от nCountInGroupMin до nCountInGroupMax существ в каждом стеке. Созданные стеки принадлежат нейтральному игроку c ID = PLAYER_NONE.
Функция имеет алиас с именем GenerateMobs.

3.2.8 Работа с интерфейсом.

void QuestionBox( spTXT, sCallback )
Выдает немодальный QuestionBox с текстом spTXT и кнопками «Да/Отмена», по завершении в случае положительного ответа вызывает функцию с именем sCallback и пустым списком параметров. Обращаю внимание – функция немодальная. Т.е. скрипт продолжит выполнение со следующей за вызовом функции строчки, не ожидая нажатия к/л кнопки игроком. Функция имеет алиас с именем QuestionBoxInt.

void StartDialogScene( spDialogSceneXDB, sCallback = nil, sSaveName = nil )
Стартует диалоговую сцену на движке согласно первому параметру. Если второй параметр не nil, то после диалога будет вызвана функция с именем sCallback и пустым списком параметров. Если sSaveName не nil, то перед диалогом будет произведено сохранение в соотв. слот. Что мешает просто вызывать перед StartDialogScene функцию Save пока не понимаю. Возможно, дело в состоянии экрана на момент сохранения (и, соответственно, в картинке, которая ляжет в сейв).
void StartCutScene( sAnimSceneXDB, sCallback = nil, saveName = nil )
Стартует анимированную сцену на движке согласно первому параметру. Если второй параметр не nil, то после ролика будет вызвана функция с именем sCallback и пустым списком параметров. Если sSaveName не nil, то перед диалогом будет произведено сохранение в соотв. слот.
void MessageBox( spTXT, sCallback = nil, sSaveName = nil )
Выдает модальный MessageBox с текстом spTXT, по завершении вызывает функцию с именем sCallback и пустым списком параметров. Если sSaveName не nil, то перед диалогом будет произведено сохранение в соотв. слот.
**void StartDialogSceneInt( spDialogSceneXDB, sCallback, sSaveName )
void StartCutSceneInt( spAnimSceneXDB, sCallback, sSaveName )
void MessageBoxInt(spTXT, sCallback, sSaveName)**
Немодальные аналоги перечисленных выше функций. «Немодальность» означает, что во время работы интерфейсного элемента поток скрипта, вызвавшего функцию, продолжает работу. Собственно, их модальные «братья» реализованы скриптом в /scripts/advmap-startup.lua с помощью использования механизма event-ов и функции parse.
void MoveCamera( nX, nY, nFloorID, nZoom = 50, nPitch = pi/2, nYawl = 0, nNoZoom = 0, nNoRotate = 0 )
Перемещает камеру в положение, заданное параметрами. С данной функцией я не экспериментировал, посему просто изложу перевод того, что написано в официальном руководстве по скрипту:
nX, nY, nFllorID – коодинаты тайла, на котором будет сфокусирована камера.
nZoom – расстояние от камеры до этого тайла.
nPitch – угол размещения камеры в вертикальной плоскости (0 – камера смотрит горизонтально, pi/2 – вертикально)
nYawl – угол поворота камеры в горизонтальной плоскости (0 – север)
nNoZoom – если равно 1, то камера не будет менять расстояние до тайта при перемещении.
nNoRotate - если равно 1, то камера не будет вращаться при перемещении.
3.2.9 Функции общей направленности.
void Loose()
Вызов приводит к автоматическому проигрышу миссии игроком PLAYER_1 (т.е. человеком). На мультиплеерных картах функция неприменима и приводит к ошибке.
void Win()
Вызов приводит к автоматической победе игрока PLAYER_1 (т.е. человека) в миссии. На мультиплеерных картах функция неприменима и приводит к ошибке.
void BlockGame()
Блокирует интерфейс пользователя. Дабы игрок не дергал попусту мышь и клавиатуру и не сбивал режиссуру ролика с передвижением героев, камеры и т.п.
void UnblockGame()
Соответственно - разблокирует интерфейс пользователя.
void ExitGame()
Немедленный выход из игры. Без всяких промежуточных вопросов.
number GetDate( nDateID )
Возвращает текущую дату в формате согласно переданному параметру. Соотв. константы для nDateID прописаны в /scripts/advmap-startup.lua и бывают такими:
DAY = 0
WEEK = 1
MONTH = 2
DAY_OF_WEEK = 3
ABSOLUTE_DAY = DAY
Отсчет в любом случае начинается с единицы.
nX, nY GetTerrainSize()
Возвращает размер текущей карты в тайлах.
number GetMaxFloor()
На картах с подземельями данная функция возвращает 1, без оных – 0.
bool IsTilePassable( nX, nY, nFloorID = GROUND )
Возвращает, проходим ли тайл с указанными координатами.

string GetAllNames( nFilterCode )
Возвращает строку, содержащую через пробел имена сообразно переданному параметру. Т.к. в реализации языка отсутствуют функции работы со строками, предполагаю, что данная функция может использоваться исключительно для отладки. Соотв. константы для nFilterCode прописаны в /scripts/advmap-startup.lua и бывают такими:
FILTER_HEROES = 0
FILTER_OBJECTS = 1
FILTER_REGIONS = 2
FILTER_OBJECTIVES = 3
Реально работают всего два фильтра - FILTER_HEROES и FILTER_OBJECTIVES. Использование остальных ведет к получению пустой строки. Функция имеет алиас с именем names.
void SetWarfogBehaviour( nOnLand, nOnSea )
Устанавливает поведение «тумана войны» на суше и на море. Если соответствующий параметр равен 1, то герой игрока будет открывать «туман войны», иначе – нет.
void Trigger(nTriggerType, ...)
Приводит к вызову заданной параметром процедуры по наступлению того или иного события. Для останова триггера используется аналогичный по параметрам вызов Trigger, в котором вместо названия процедуры передается nil. Для каждого типа события можно установить только один перехватчик.
Функция имеет алиас с именем SetTrigger.
Для большинства событий (за исключением, разве что OBJECT_TOUCH) можно написать аналогичную конструкцию без использования функции Trigger, а с использованием проверки условия в отдельном потоке. Нужно ли это делать – практика покажет.
Формат параметров (и список параметров вызываемой процедуры) зависят от типа триггера nTriggerType (константы прописаны в прописаны в /scripts/advmap-startup.lua) Разберу их отдельно.
NEW_DAY_TRIGGER = 0
Формат вызова:
Trigger(NEW_DAY_TRIGGER, sProc)
Формат вызываемой процедуры:
void sProc()
Останов:
Trigger(NEW_DAY_TRIGGER, nil)
Процедура будет вызываться по наступлении каждого нового дня.
PLAYER_ADD_HERO_TRIGGER = 1
Формат вызова:
Trigger(PLAYER_ADD_HERO_TRIGGER, nPlayerID, sProc )
Формат вызываемой процедуры:
void sProc( sHeroName )
Останов:
Trigger(PLAYER_ADD_HERO_TRIGGER, nPlayerID, nil)
Процедура вызывается, когда игрок nPlayerID получает нового героя. Имя данного героя передается в процедуру в качестве параметра.
PLAYER_REMOVE_HERO_TRIGGER = 2
Формат вызова:
Trigger(PLAYER_REMOVE_HERO_TRIGGER, nPlayerID, sProc )
Формат вызываемой процедуры:
void sProc( sHeroNameLooser, sHeroNameWinner )
Останов:
Trigger(PLAYER_REMOVE_HERO_TRIGGER, nPlayerID, nil)
Процедура вызывается, когда игрок nPlayerID теряет героя. В процедуру передается имена двух героев – потерянного игроком и победившего в битве, вызвавшей эту потерю. В случае, если герой был просто уволен, в качестве второго параметра будет передан nil.
OBJECTIVE_STATE_CHANGE_TRIGGER = 3
Формат вызова:
Trigger(OBJECTIVE_STATE_CHANGE_TRIGGER, sObjectiveID, sProc )
Формат вызываемой процедуры:
void sProc( nPlayerID )
Останов:
Trigger(OBJECTIVE_STATE_CHANGE_TRIGGER, sObjectiveID, nil )
Процедура вызывается, когда состояние объективы sObjectiveID для какого-либо игрока меняется. Идентификатор игрока передается в процедуру в качестве параметра.
OBJECT_TOUCH_TRIGGER = 4
Формат вызова:
Trigger(OBJECT_TOUCH_TRIGGER, sObjectID, sProc )
Формат вызываемой процедуры:
void sProc( sHeroName, sObjectID )
Останов:
Trigger(OBJECT_TOUCH_TRIGGER, sObjectID, nil )
Процедура вызывается, когда игрок тыркнулся героем в объект с именем sObjectID. Имя данного героя и имя захваченного объекта передаются в процедуру в качестве параметров. См. функции IsObjectEnabled и SetObjectEnabled.
OBJECT_CAPTURE_TRIGGER = 5
Формат вызова:
Trigger(OBJECT_CAPTURE_TRIGGER, sObjectID, sProc )
Формат вызываемой процедуры:
void sProc( nPrevOwnerID, nNewOwnerID, sHeroName, sObjectID )
Останов:
Trigger(OBJECT_CAPTURE_TRIGGER, sObjectID, nil )
Процедура вызывается, когда объект с именем sObjectID меняет владельца. В процедуру передается в качестве параметров идентификатор прежнего владельца, идентификатор нового владельца, имя захватившего героя и собственно имя захваченного объекта.
REGION_ENTER_AND_STOP_TRIGGER = 6
Формат вызова:
Trigger(REGION_ENTER_AND_STOP_TRIGGER, sRegionName, sProc )
Формат вызываемой процедуры:
void sProc( sHeroName )
Останов:
Trigger(REGION_ENTER_AND_STOP_TRIGGER, sRegionName, nil )
Процедура вызывается, когда какой-либо герой останавливается в регионе с именем sRegionName. Имя данного героя передается в процедуру в качестве параметра.
REGION_ENTER_WITHOUT_STOP_TRIGGER = 7
Формат вызова:
Trigger(REGION_ENTER_WITHOUT_STOP_TRIGGER, sRegionName, sProc )
Формат вызываемой процедуры:
void sProc( sHeroName )
Останов:
Trigger(REGION_ENTER_WITHOUT_STOP_TRIGGER, sRegionName, nil )
Процедура вызывается, когда какой-либо герой попадает в регион с именем sRegionName (и не останавливается в нем). Имя данного героя передается в процедуру в качестве параметра.
HERO_LEVELUP_TRIGGER = 8
Формат вызова:
Trigger(LEVELUP_TRIGGER, sHeroName, sProc )
Формат вызываемой процедуры:
void sProc()
Останов:
Trigger(LEVELUP_TRIGGER, sHeroName, nil )
Процедура вызывается, когда герой с именем sHeroName повышает уровень.
WAR_FOG_ENTER_TRIGGER = 9
Формат вызова:
Trigger(WAR_FOG_ENTER_TRIGGER, sProc )
Формат вызываемой процедуры:
void sProc(sHeroName)
Останов:
Trigger(WAR_FOG_ENTER_TRIGGER, nil )
Процедура вызывается, когда какой-либо герой вступает в область «тумана войны». (См. функцию SetWarfogBehaviour). Все параметры взяты из официального руководства по скриптам, добиться того, чтобы данный триггер как-то работал, лично мне не удалось.

TOWN_HERO_DEPLOY_TRIGGER = 10
Формат вызова:
Trigger(TOWN_HERO_DEPLOY_TRIGGER, sTownName, sProc )
Формат вызываемой процедуры:
void sProc(sHeroName)
Останов:
Trigger(TOWN_HERO_DEPLOY_TRIGGER, sTownName, nil )
Процедура вызывается, когда герой покидает город. В процедуру передается имя героя, покинувшего город.

3.2.10 Работа со звуком.

nSoundID Play3DSound( spSoundXDB, nX, nY, nFloorID )
Проигрывает 3D звук по указанным координатам. Результат используется исключительно в функции StopPlaySound в том случае, если звук циклический. Если нет, то возвращается -1 и вызов StopPlaySound c этим параметром приведет к ошибке.
nSoundID Play2DSound( spSoundXDB )
Проигрывает 2D звук. Результат используется исключительно в функции StopPlaySound в том случае, если звук циклический. Если нет, то возвращается -1 и вызов StopPlaySound c этим параметром приведет к ошибке.
void StopPlaySound( nSoundID )
Останавливает проигрывание циклического звука.

3.2.11 Работа с освещением.

void SetCombatAmbientLight( spAmbientLightXDB )
Меняет освещение всех тактических арен карты. Функция имеет алиас с именем SetCombatLight.
void SetObjectFlashlight( sObjectName, sLightID )
Функция устанавливает точечную подсветку объекта. В sLightID должна идти ссылка на соответствующий ресурс, определяемый при дизайне карты (см. поле resources-> pointLights)
Выдача второго параметра в виде пустой строки приводит к удалению подсветки, алиас для данного варианта – ResetObjectFlashlight – прописан в scripts\advmap-common.lua.
void SetAmbientLight( nFloorID, sLightID, bFade = false, nTime = 1)
Функция меняет освещение выбранного этажа. Если bFade = true, то смена происходит постепенно, с fade эффектом, иначе – моментально. nTime определяет время смены (насколько я понял, имеет смысл только при bFade = true).
Функция имеет алиас с именем SetLight.
3.2.12 Всякие непонятки.
number CalcAverageMonstersTier()
Возвращает некое дробное число. Полагаю, используется для отладки. При чем здесь слеза (Асхи?) – не понял. Функция имеет алиас с именем CalcAverageTier.
tnTier GetGuardsTier( sObjectName )
Возвращает массив целых чисел.
**void SetStandState( sStandName, nState )
number GetStandState( sStandName )
number GetStandStatesCount( sStandName )**
Чем управляют данные три функции, не догадался. Т.к. понятия не имею, что это за тип объекта - “Stand”. Вычитанное в ресурсах игры определение «stand - several visual objects on same place switching by script» ясности не добавляет. Желающие могут посмотреть на 4-ю миссию 5-й кампании (там присутствует объект типа stand с именем TieruHut) и попытаться разобраться, чего же эти функции с ним делают.
void StopTrigger()
Что за триггер стопорит данная функция, есть ли у нее параметры – «науке пока не известно».
void PlayObjectAnimation( sObjectID, sAnimID, nAction )
Данная функция отсутствует в API, хотя официальное руководство по скриптам утверждает обратное.

Просмотров: 3 564

Комментарии пока отсутcтвуют