When new game is started Adventure mode is the first LUA environment that is loaded as that is the first game mode presented to the player. The game does the following:
- The main script /scripts/advmap-startup.lua is started, which besides initialization loads all follow up adventure mode scripts through doFile function.
- Calls the createAdvmapAliases () function
- Starts interpreting the script file of the current map
In addition to the common functions, the following are available in this mode:
Player functions[]
nPlayerID GetCurrentPlayer ()[]
Returns the ID from 0 to 8 of the current player. Where the number is the ? ID of the player in PLAYER_?. Mapping is done in /scripts/advmap-startup.lua.
-- Player IDs
--
PLAYER_NONE = 0
PLAYER_1 = 1
PLAYER_2 = 2
PLAYER_3 = 3
PLAYER_4 = 4
PLAYER_5 = 5
PLAYER_6 = 6
PLAYER_7 = 7
PLAYER_8 = 8
In the case of a campaign, the number of a human player is PLAYER_1 = 1.
nPlayerStateID GetPlayerState (nPlayerID)[]
Returns player status nPlayerID. Mapping is defined in /scripts/advmap-startup.lua as follows:
-- Player states
--
PLAYER_NOT_IN_GAME = 0
PLAYER_ACTIVE = 1
PLAYER_WON = 2
PLAYER_LOST = 3
number GetPlayerResource (nPlayerID, nResID)[]
Returns the current amount of the nResID resource for player nPlayerID. Resource ID mapping is defined in /scripts/advmap-startup.lua as follows:
-- Kinds of resources -- WOOD = 0 ORE = 1 MERCURY = 2 CRYSTAL = 3 SULFUR = 4 GEM = 5 GOLD = 6
void SetPlayerResource (nPlayerID, nResID, nCount)[]
Set the current amount of the nResID resource to nCount for player nPlayerID.
SetPlayerStartResource( nPlayer, nRes, nAmount )[]
Set the current amount of the nResID resource to nCount for player nPlayerID which are also multiplied by a factor based on map difficulty level. Function is defined in the /scripts/advmap-common.lua and is based on function SetPlayerResource.
void SetPlayerStartResources (nPlayerID, nWoodCnt, nOreCnt, nMercuryCnt, nCrystalCnt, nSulfurCnt, nGemCnt, nGoldCnt)[]
Set the current amount of resources for player nPlayerID. This function is similar to a series of calls to SetPlayerResource. The difference will only be visible on the mission result interface.
tsHeroes GetPlayerHeroes (nPlayerID)[]
Returns a table containing the names of all the heroes of the specified player.
void SetPlayerHeroesCountNotForHire (nPlayerID, nCount)[]
Reduces the number of heroes a player can hire by nCount. The total number of employees is set during design.
nPlayerID GetObjectOwner (sObjectName)[]
Returns the ID of the player to which the object belongs. The object may be a hero, city, building, hero, etc. If the object does not belong to anyone, it will return PLAYER_NONE.
void SetObjectOwner (sObjectName, nPlayerID)[]
Sets the owner of the sObjectName object to nPlayerID.
bool IsObjectVisible (nPlayerID, sObjectName)[]
Returns whether object with name sObjectName is visible to the player nPlayerID. If the object occupies more than one tile on the map, the function may not work correctly because the comparison is done based on if the center square of the object is visible to the player.
void OpenCircleFog (nX, nY, nFloorID, nRadius, nPlayerID)
For player nPlayerID, the Fog of War is opened in a circle with center coordinates nX, nY and radius nRadius. Constants for nFloorID are defined in /scripts/advmap-startup.lua as follows:
-- Floors names -- GROUND = 0 UNDERGROUND = 1
Map Object functions[]
nState GetObjectiveState (sObjectiveName, nPlayerID = PLAYER_1)[]
Returns the status of sObjectiveName lenses. Object states are defined in /scripts/advmap-startup.lua as follows:
-- Objective state`s IDs -- OBJECTIVE_SCENARIO_INFO = 0 OBJECTIVE_UNKNOWN = 1 OBJECTIVE_ACTIVE = 2 OBJECTIVE_COMPLETED = 3 OBJECTIVE_FAILED = 4
void SetObjectiveState (sObjectiveName, nState, nPlayerID = PLAYER_1)[]
Sets the state of quest objective with name sObjectiveName for player nPlayerID . The new state that the objective transitions to depends on the current state of the objective. Allowed transitions:
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
If objective is set to OBJECTIVE_ACTIVE, it automatically becomes visible to the player (see IsObjectiveVisible / SetObjectiveVisible)
void SetObjectiveProgress (sObjectiveName, nProgress, nPlayerID = PLAYER_1)[]
Sets sObjectiveName objective progress, where nProgress is a step out of total amount of steps that need to be done in order the player to fulfill objective state requirements. For example, if objective is "Get 1000 archers", every time archer count increases the code should execute SetObjectiveProgress ("get_archers", archer_value, PLAYER_1) to update Quest box progress.
nProgress GetObjectiveProgress (sObjectiveName, nPlayerID = PLAYER_1)[]
Returns sObjectiveName objective progress value.
bool IsObjectiveVisible (sObjectiveName, nPlayerID = PLAYER_1)[]
Returns if objective with name sObjectiveNameis is visible to player with id nPlayerID .
SetObjectiveVisible (sObjectiveName, bVisible, nPlayerID = PLAYER_1) []
Toggles objective with name sObjectiveName visibility for player with id nPlayerID where bVisible is True or False.
Borderguards functions[]
void GiveBorderguardKey (nPlayerID, nKeyID)[]
Gives key with id nKeyID to player nPlayerID. Key definitions are in /scripts/advmap-startup.lua.
-- Borderguard key colors -- RED_KEY = 1 BLUE_KEY = 2 GREEN_KEY = 3 YELLOW_KEY = 4 ORANGE_KEY = 5 TEAL_KEY = 6 PURPLE_KEY = 7 TAN_KEY = 8
bool HasBorderguardKey (nPlayerID, nKeyID)[]
Checks whether player nPlayerID has key with id nKeyID.
Regions functions[]
void SetRegionBlocked (sRegionName, bEnable, nPlayerID = -1)[]
Enables or disables sRegionName region for player nPlayerID. If the last parameter is not specified, then this action is performed for all players.
bool IsRegionBlocked (sRegionName, nPlayerID)[]
Returns whether region sRegionName is blocked for player nPlayerID.
tsObjects GetObjectsInRegion (sRegionName, nObjectsTypeID)[]
Returns an array of object names in the region named sRegionName. The second parameter nObjectsTypeID can be set to OBJECT_HERO = 0, in that case the array will contain only the heroes in that region.
bool IsPlayerHeroesInRegion (nPlayerID, sRegionName)[]
Returns if player nPlayerID has heroes in region sRegionName. This function is defined in /scripts/advmap-startup.lua and is based on function GetObjectsInRegion.
nX, nY, nFloorID RegionToPoint (sRegionName)[]
Returns the coordinates nX, nY of the region if the region consists of one tile. If region is larger than one tile it error message will be returned.
bool IsObjectInRegion (sHeroName, sRegionName)[]
Checks if hero sHeroName is inside region sRegionName. Currently, the function works correctly only for objects that are 1 tile in size.
void OpenRegionFog (nPlayerID, sRegionName)[]
Removes the Fog of War in region sRegionName region for player nPlayerID.
AI functions[]
For a non-AI player, the functions listed below do not make sense, and when called, lead to an error.
void SetAIPlayerAttractor (sObjectName, nPlayerID, nPriority)[]
Sets AI nPlayerID player “force attraction” to object sObjectName. AI heroes will patrol around the object and visit it occasionally. The higher nPriority value the more aggressive the AI player behavior will be. Value range can be from -1 to 2. nPriority = 0 is used to disable previously set attractor commands. There is a warning in the official script manual that this function may not work correctly for moving objects.
void SetAIHeroAttractor (sObjectName, sHeroName, nPriority)[]
A function similar to SetAIPlayerAttractor, but only works for one AI hero sHeroName.
void EnableHeroAI (sHeroName, bEnable)[]
Turns on / off the AI of the hero.
void MoveHero (sHeroName, nX, nY, nFloorID = -1)[]
This function orders the hero to move to the specified location. If the floor number is not specified, the hero is supposed to go to the point with the specified coordinates on the floor he or she already stands on. This function can only be invoked for heroes controlled by the AI players, with their AI turned off. If the specified location is inaccessible, the function generates an error. If the hero’s movement points are depleted en route, the movement will be continued in the next turn.
bool CanMoveHero (sHeroName, nX, nY, nFloorID = -1)[]
This function returns true if the specified point can be reached by the hero. Otherwise it returns false. If the floor is not specified, the one in which the hero is currently located is used. This function can only be invoked for heroes controlled by the AI players. This function does not work with heroes located inside the city.
void EnableAIHeroHiring (nPlayerID, sTownName, bEnable)[]
Enables or disables the AI player nPlayerID hiring heroes in sTownName. By default, hiring is allowed.
Heroes functions[]
Due to the large number of functions available for heroes, they have a separate section. As a rule of the thumb if a function is called with hero name that does not exist, function will return error message.
void ChangeHeroStat (sHeroName, nStatID, nDelta)[]
Changes stat nStatID of hero sHeroName by value nDelta. nStatID definitions are registered in /scripts/advmap-startup.lua and can be as follows:
-- Hero stat`s IDs
--
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
nDelta is added to the current value of the stat. It can be positive or negative number.
Oddities about some of the stats include:
- STAT_EXPERIENCE cannot be reduced.
- STAT_MOVE_POINTS and STAT_MANA_POINTS represent the current values of the corresponding parameters, you can not set them higher than the maximum.
- There is a stat with ID = 9. It cannot be set. But can be get. There is no information of its meaning.
nCount GetHeroStats (HeroName, nStatID)[]
Return stat nStatID of hero HeroName. Check ChangeHeroStat description for details.
GiveExp (sHeroName, nExp)[]
Increases hero sHeroName experience by nExp. This function is defined in /scripts/advmap-common.lua and is based on function ChangeHeroStat.
bool HasHeroSkill (sHeroName, nSkillID)[]
Gives hero sHeroName skill with id nSkill, where skill ID is a number that relates to a particular skill or perk. ID to skill mapping is available in /scripts/advmap-startup.lua, look for entries that begin with SKILL_ *, PERK_ * and * FEAT * . This function does not provide a way to get the skill mastery level.
bool GiveHeroSkill (sHeroName, nSkillID)[]
Returns if hero sHeroName has skill nSkill, where skill ID is a number that relates to a particular skill or perk internal name. ID to skill mapping is available in /scripts/advmap-startup.lua, look for entries that begin with SKILL_ *, PERK_ * and * FEAT * . Each consecutive execution increases skill mastery level for the hero. Function returns FALSE if the hero already has ‘EXPERT’ mastery of this skill, or there is no space space for the skill to be learned.
void KnowHeroSpell (sHeroName, nSpellID)[]
Returns if hero sHeroName has spell with id nSpellID, where skill id is number that relates to a particular spell internal name. IDs to internal spell names are defined in /scripts/common.lua and begin with SPELL_ * .
Note: At least four spells didn’t get into the lua file - missing ones can be found in data.pak/types.xml.
void TeachHeroSpell (sHeroName, nSpellID)[]
Teaches hero sHeroName spell with id nSpellID, where skill id is number that relates to a particular spell internal name. IDs to internal spell names are defined in /scripts/common.lua and begin with SPELL_ * . If the hero already knows that spell, the function returns nil, otherwise it returns not nil.
Note: At least four spells didn’t get into the lua file - missing ones can be found in data.pak/types.xml.
bool LevelUpHero (sHeroName) /// GiveExpToLevel[]
Levels up hero sHeroName by gives the number of exp points to hero that he lacks to the next level one level. If the hero has already reached the maximum possible level, the function will return nil, otherwise - true. The function has an alias named GiveExpToLevel.
nLevel GetHeroLevel (sHeroName)[]
This function returns the current level of hero sHeroName.
bool IsHeroAlive (sHeroName)[]
If there is a hero sHeroName this function returns not nil, else it returns nil. A hero is considered as alive if belongs to any of the active players (for whom GetPlayerState() returns true). It does not matter where the hero is during the inquiry: on the surface, in the underground, in the town, or on a boat.
void DeployReserveHero (sHeroName, nX, nY, nFloorID = GROUND)[]
Puts hero sHeroName who has been in the player’s reserve onto the map coordiantes nX, nY on floor nFloorID. Heroes are reserved when designing a map. Reserved heroes cannot be hired in the tavern. If the specified tile is already taken, the hero will be placed on the nearest free tile. If the hero is dead at the time the function is called, he will still be placed on the specified tile in his original state (i.e. with the army specified in the map design). If the specified character was not reserved during design, a function call will result in an error.
void UnreserveHero (sHeroName)[]
Removes hero sHeroName from reserved heroes list so hero becomes available for hire in taverns. If at the time of calling the function this hero is still alive and is under the control of the player, then he is not taken out of control of the player. For hire, he will be available only after the death. If the specified character was not reserved during design, a function call will result in an error.
nCost CalcHeroMoveCost (sHeroName, nX, nY, nFloorID = -1)[]
Returns the number of movepoints of hero sHeroName that he will have to spend when moving to a point with coordinates nX, nY. If it is impossible to move to this point (i.e., for example, the path is blocked by someone), the function will return -1. This function does not work with heroes located inside the city. If the floor is not specified, then the one on which the hero is already located will be used.
void MoveHeroRealTime (sHeroName, nX, nY, nFloorID = -1)[]
Hero sHeroName will move to point with coordinates nX, nY on floor nFloorID . If the floor number is not specified, the hero is supposed to go to the point with the specified coordinates on the floor he or she already stands on. If the specified location is inaccessible, the function generates an error. The movement begins immediately after the command has been invoked, regardless of whose turn it is now. The script continues its work immediately after the command is executed, without waiting for the hero to reach the destination. The user interface and the AI’s actions are blocked while the hero moves. If the hero’s movement points are depleted, or the hero encounters an obstacle, he or she stops without interacting with the object (which, in particular, means that the hero is unable to use teleports, boats, etc. This function does not work with heroes located inside the city.
nCount GetHeroCreatures (sHeroName, nCreatureID)[]
This function returns the number of creatures of type nCreatureID under hero sHeroName command. Where nCreatureID is a number related to a creature internal name. Mapping is defined in /scripts/common.lua
-- Creatures IDs
--
CREATURE_UNKNOWN = 0
CREATURE_PEASANT = 1
CREATURE_MILITIAMAN = 2
CREATURE_ARCHER = 3
CREATURE_MARKSMAN = 4
CREATURE_FOOTMAN = 5
...
void AddHeroCreatures (sHeroName, nCreateureID, nCount)[]
Adds nCount quantity of creatures of nCreateureID type to the army of the hero sHeroName. The command works regardless of where the hero is: he may be absent from the map (being in a town or among the dead). Only creatures, and not war machines (ballista, catapulta, etc.) can be added.
void RemoveHeroCreatures (sHeroName, nCreatureID, nCount)[]
Remove nCount quantity of creatures of the nCreatureID type from the army of the hero sHeroName. If the number of creatures of the specified type in the hero’s army is lower than that set in the quantity parameter, all such creatures are removed from his or her army. If there are no other creatures except those to be removed in the hero’s army, the command removes them all except one. If the hero does not have the proper type of stack there will not be an error.
void GiveArtefact (sHeroName, nArtID, nBindToHero = 0)[]
Grants an artifact nArtID to the hero sHeroName where nArtiD is number that is related to artifact internal name that begins with ARTIFACT_* . Mapping is defined in /scripts/advmap-startup.lua.
-- Artifact type IDs
--
ARTIFACT_SWORD_OF_RUINS = 1
ARTIFACT_GREAT_AXE_OF_GIANT_SLAYING = 2
ARTIFACT_WAND_OF_X = 3
ARTIFACT_UNICORN_HORN_BOW = 4
ARTIFACT_TITANS_TRIDENT = 5
ARTIFACT_STAFF_OF_VEXINGS = 6
ARTIFACT_SHACKLES_OF_WAR = 7
...
The artifact is always equipped, if possible, and is always issued in a single quantity. If nBindToHero is nonzero, then transferring the artifact to another hero will not be possible. To produce two identical ones, you need to call a function with the same parameters twice. If, after giving an artifact, code try to immediately continue utilize this item (such as deleting it, or checking if it exists), it is recommended to add sleep (1) function immediately after GiveArtefact. Otherwise the artifact may not have time to appear before being processed by the next piece of code. This remark applies to all functions in which something is issued to the hero (or object). The function has an alias named GiveArtifact.
bool HasArtefact (sHeroName, nArtID)[]
The function returns whether hero sHeroName has at least one artifact of type nArtID . The function does not give information whether the artifact is equipped or not.
void RemoveArtefact (sHeroName, nArtID)[]
The function deletes a single artifact nArtID from a hero sHeroName. If hero does not own the artifact, calling the function results in an error.
void SetHeroLootable (sHeroName, bEnable)[]
The function enables the hero sHeroName artifact inventory to be looted after another hero defeats him.
bool IsHeroLootable (sHeroName)[]
Returns whether hero sHeroName is possible to be looted artifacts from other heroes that defeat him.
void MarkObjectAsVisited (sObjectName, sHeroName)[]
Sets inoperative/disabled object sObjectName state to "visited” by a hero named sHeroName. If the object has the enabled status (see IsObjectEnabled and SetObjectEnabled below), calling this function will result in an error.
sTownName GetHeroTown (sHeroName)[]
If a hero named sHeroName is in the city (meaning - it is inside, and not on the map near the entrance), then this function returns the name of the city. Otherwise, the function will return nil.
sHeroName GetTownHero (sTownName)[]
Returns the name of the hero that is inside (and not on the map near the entrance) town sTownName. If there is no hero in town, the function will return nil.
tsObjects GetObjectsFromPath (sHeroName, nX, nY, nFloorID = -1)[]
The function returns an array of objects that hero sHeroName will pass by when traveling from his current position to point with coordinates nX, nY. If the floor is not specified, then the one on which the hero is located will be used.