|
| Thread: Undocumented scripting functions |  This thread is pages long: 1 2 · NEXT» |
|
Maurice
Hero of Order
Part of the furniture
|
posted September 30, 2007 11:03 PM |
 bonus applied. |
Edited by Maurice at 00:38, 01 Oct 2007.
|
Undocumented scripting functions
I noticed (see the Modding Wiki topic) that the documentation from the game doesn't contain all Scripting functions that actually exist. A number are left out, for mysterious reasons. I've taken a look at the game files, and extracted a few more, that perform interesting tasks.
CalcAverageMonstersTier()
This function calculates the average Tier of all monsters (i.e., Neutrals) on the entire map, down to 2 decimals. Not sure what use it could have, but hey, it's there  . This function takes no arguments.
CreateArtifact(arg1, Artifact_ID, X, Y, Floor_ID)
This function creates an artifact on the map of type Artifact_ID (see the artifact listing for the numbers) at location (X, Y) on the surface (Floor_ID = 0) or underground (Floor_ID = 1). I have no clue what arg1 actually is, in my trials it didn't matter what I filled in for it - just that it was there, to make the other arguments match.
DisableCameraFollowHeroes(arg1)
Arg1 can be either 0 or 1. When it is 0, the camera will follow the Heroes as they move around, when set to 1 the camera will remain where it is while the Heroes move about.
ExitGame()
Does exactly what it says: it exits the game, returning you to your desktop. The game will not be saved. This function takes no arguments.
GetDifficulty()
This gets the difficulty level of the game, returning a value ranging from 0 (Easy) to 3 (Heroic). The function takes no arguments.
GetGuardsTier(object_name)
This function actually returns an array containing the creature's Tiers of all creatures in the garrison structure (can be any garrisonable object, apparently: garrison, town or mine). Note that the Tier in this array is composed; it also includes the upgrade status according to the following formula: Tier * 2 + upg_status, where upg_status = 0 for the base creature and 1 for the upgraded version. As such, the range is from 2 (unupgraded Tier 1 creature) to 15 (upgraded Tier 7 creature). It does not distinguish between creatures of different factions, nor does it count the various stacksizes. Note that the GetObjectCreatures function pretty much does the same thing, but then with more detail.
GetHeroTown(Hero_name)
Returns the name of the Town in which the Hero with Hero_name is garrisoned. Note that the Hero must actually be garrisoned in a Town; a visiting Hero will not work for this function.
GetMaxFloor()
Returns 0 when the map has only 1 layer, returns 1 when the map has both a surface and a dungeon below it. The function takes no argument. It seems superfluous, since the map maker would have to know how many floors there are, before writing the script. But hey, it's there anyway .
GetObjectDwellingCreatures(Town_name, Dwelling_Tier)
This function returns the number of creatures available for recruitment in a given town, for the requested Tier. Note that it requires a composed Tier, which includes the upgrade status as well, according to this formula: Tier * 2 + upg_status, where upg_status = 0 for the base creature and 1 for the upgraded version. As such, the range is from 2 (unupgraded Tier 1 creature) to 15 (upgraded Tier 7 creature). This function works *only* on towns, not on external dwellings, unfortunately. It returns -1 if the corresponding creature dwelling does not exist in the specified town.
GetObjectNamesByType(arg1)
I couldn't figure out what this function does. It exists, takes 1 argument, but the return string was empty in all my attempts. If anyone figures out more, feel free to fill this one in .
GetObjectsFromPath(Hero_name, X, Y, Floor_ID)
This function returns an array of objects that are blocking the Hero with Hero_name from reaching the tile with coordinates X, Y on the surface (Floor_ID = 0) or underground (Floor_ID = 1). I've managed to have it report Monsters here as well, but their definition is cryptic: "<Floor_ID>-<X-coord>-<Y-coord>--<some_number>". However, this definition is NOT an object name, whereas the return value for other objects is their factual name. Further analysis is required.
GetPlayerState(Player_ID)
This function returns the status of the specified player. I haven't fully explored this function, but found out it returns a value of 1 if the player exists on the map and is alive, and it returns 3 if it has been defeated. I didn't check other values.
GetStandState(arg1)
I could not get this one to work. It refers to a "Stand", but I don't know what it means by that.
GetStandStatesCount(arg1)
Same deal here.
GetTerrainSize()
Returns a string containing the X and Y dimensions of the map. Seems superfluous, because by the time the map maker is working on scripting, the map dimensions are known.
GiveBorderguardKey(Player_ID, Key_type)
This gives the player of Player_ID the key of Key_type. For exact Key values, check the "HasBorderguardKey" function that is documented.
IsTilePassable(X, Y, Floor_ID)
Returns 1 if the tile at (X, Y) on the surface (Floor_ID = 0) or underground (Floor_ID = 1) is passable, or "nil" when it is blocked. It takes the mask in consideration, but ignores temporary blockades (like a Monster stack, a player Hero, etc ...).
LevelUpHero(Hero_name)
Gives the Hero with Hero_name exactly enough experience to reach the next level up.
RemoveAllMonsters(CreatureType_ID)
When called, this function removes any and all neutral creatures on the map corresponding to the used CreatureType_ID. Other neutral stacks are not affected.
SetCombatAmbientLight(arg1)
I guess this is identical to the function "SetCombatLight", which I actually didn't see in my search. Could this be a typo in the manual? Anyway, arg1 refers to the lightsource to use.
SetHeroesExpCoef(arg1)
Once set, multiplies the experience yield by all Heroes by arg1. The value of arg1 can vary from 0 to 10, with decimal values allowed. The default state is 1.
SetObjectDwellingCreatures(Town Name, Tier, Qty)
Sets the amount of creatures available for hire of the town with Town_name, for the Tier specified, and it sets (not adds!) it to Qty. Note that the Tier is composed according to the following formula: Tier * 2 + upg_status, where upg_status = 0 for the base creature and 1 for the upgraded version. As such, the range is from 2 (unupgraded Tier 1 creature) to 15 (upgraded Tier 7 creature). This function works *only* on towns, not on external dwellings, unfortunately. It does nothing when the chosen Tier is not available in the specified town. Note furthermore that if the upgraded dwelling exists, changing the unupgraded version will automatically also change the number of the upgraded version and vice-versa.
SetPlayerHeroesCountNotForHire(Player_ID, nr)
Sets the amount of slots locked from hiring a Hero for player of Player_ID by nr amount. The value of nr has to be between 0 (all 8 slots open for a Hero to be hired) and 8 (the player can not hire any Hero). Note that this limitation does not count for Heroes acquired in other ways than hiring from a Tavern.
SetTrigger()
Didn't really inspect this one. It's used exactly once, in C4M2 and I suspect it's the same function as "Trigger".
StopTrigger()
Didn't inspect this one either, it's never used in the campaigns. Might be redundant, as Triggers are stopped by adding a "nil" to a Trigger command.
|
|
Moonlith
Bad-mannered
Supreme Hero
If all else fails, use Fiyah!
|
posted October 01, 2007 01:05 AM |
|
Edited by Moonlith at 01:06, 01 Oct 2007.
|
*jumps up and down hyperactively* Weeeee I can make scripts! See? See?
Trigger(NEW_DAY_TRIGGER, "Power")
function Power()
LevelUpHero(Hero_Name)
end;
For the lazy man who doesn't want to bother scavenging XP. (Or a campaign mission where you need to rush before your enemy grows too powerfull )
|
|
Neckie
Hired Hero
|
|
posted October 01, 2007 03:00 PM |
|
|
Quote:
GetStandState(arg1)
I could not get this one to work. It refers to a "Stand", but I don't know what it means by that.
GetStandStatesCount(arg1)
Same deal here.
Those are for Stand Objects. The only one available is the Tieru's object(forgot the name and don't have access on the editor) but its the one that is in the campaign map with islands where Agrael must find Tieru.
The point in this object type is to change the model/effect on a building with the option of adding multiple visual effects while doing it.
The SetStandState(object_name, number) will trigger the state change if the number you give isn't the current stand state.
|
|
Maurice
Hero of Order
Part of the furniture
|
|
posted October 07, 2007 06:45 PM |
|
Edited by Maurice at 18:51, 07 Oct 2007.
|
Quote:
GetObjectNamesByType(arg1)
I couldn't figure out what this function does. It exists, takes 1 argument, but the return string was empty in all my attempts. If anyone figures out more, feel free to fill this one in .
Ok, I figured this one out. It takes names like BUILDING_ABANDONED_MINE, TOWN_NECROMANCY and CREATURE_GENIE as arguments. They need to be between quotes, otherwise the command doesn't work.
What the function returns is an array, filled with adventure map references: a name if the object has one, otherwise its generic name, like "1-210-199-AdvMapDwelling-27624". You can refer to this by using the array index. For instance:
Imp_Cruc_Array=GetObjectNamesByType("BUILDING_IMP_CRUCIBLE");
Imp_Cruc_Pos_X,Imp_Cruc_Pos_Y,Imp_Cruc_Pos_Floor=GetObjectPosition(Imp_Cruc_Array[1]);
This will put the location of the first Imp Crucible found on the map into the variables of Imp_Cruc_Pos respectively. Note that this works on Towns, Monsters and Buildings on the adventure map. It doesn't seem to work on resources or artifacts, unfortunately.
|
|
Lord_Evil
Famous Hero
Evil lolcat
|
|
posted October 07, 2007 09:14 PM |
|
|
Wow this Thread can realy help me! 
|
|
Kronos1000
Promising
Supreme Hero
Fryslân Boppe
|
|
posted November 07, 2007 10:59 PM |
|
|
I'm sorry for reviving this rather old Thread, but I was wondering if there is a way to carry the value of a Variable from one Map to another? I mean I set a Variable in Map 1 and I wish to use it in Map 2. I wanted to create a file containing it and then use the value and then delete it, but this does not seem to be possible in Heroes  So is there an undocumented script function to do this?
____________
Hwær cwom mearg? Hwær cwom mago?
Hwær cwom maþþumgyfa? - 'The Wanderer'
|
|
Maurice
Hero of Order
Part of the furniture
|
|
posted November 07, 2007 11:07 PM |
|
|
I've seen something like a "print_to" function that they used to print to an external file, but the function definition itself is void now. So it would seem possible to at least export something.
If you package the files into a custom campaign, however, you should be able to use the "SetGameVar" and "GetGameVar" commands. The variables specified there carry over between missions in a campaign, if I understood correctly - it's the way they saved Artifacts from sets between missions in the TotE campaigns.
|
|
Kronos1000
Promising
Supreme Hero
Fryslân Boppe
|
|
posted November 07, 2007 11:12 PM |
|
|
Now that would be great does it also work from one Campaign into another? I mean from Campaign 1 Map 5 to Campaign 2 Map 1 for example.
____________
Hwær cwom mearg? Hwær cwom mago?
Hwær cwom maþþumgyfa? - 'The Wanderer'
|
|
Maurice
Hero of Order
Part of the furniture
|
|
posted November 07, 2007 11:26 PM |
|
Edited by Maurice at 23:35, 07 Nov 2007.
|
By the way, new functions in TotE, not yet listed above, not listed in the documentation either:
ChangeResource(Resource Type, Amount, Hero Name)
This changes the amount of resources for the player owning the Hero with Hero name, of the given type. A message will fly off the Hero, indicating the resource change (just as if the Hero picked up a resource pile from the map).
CreateStatic(Scripted name, Reference to data file, X-coord, Y-coord, Floor)
The function adds the static referred to in the data file, on the coordinates specified. The name of the static can be chosen freely and is usable in other scripts afterwards. Scripted name needs to be in ".
doFile(Filename)
Calls an external file for additional scripting functions. Any functions specified in the external source will be considered along with the standard script functions. Note that the doFile command does not add these functions when called from the command line of the console; it only works when it is called from the actual mapscript itself.
EnableDynamicBattleMode()
This function is used once throughout all the campaigns and single scenario's. As a result, I couldn't figure out what it does.
errorHook(Function name)
Whenever this is specified in a function, it will be triggered when that function encounters an error. The command will consequently trigger the function specified as its parameter. Parameter has to be specified between ".
GetLastSavedCombatIndex()
Returns the index of the last combat that has been fought. This value can be used in further functions that handle the aftermath of a combat. Can be used to compare different battles with one another.
GetSoundTimeInSleeps(Sound file)
The function determines the length of the sound file specified, and returns the number of seconds that it plays. In TotE it is often used when a Hero is speaking on the map, to determine how long the game has to be locked. The reference to the sound file has to be specified in ".
IsTutorialEnabled()
Checks if the Tutorial is currently on and returns true, otherwise it returns false.
OverrideAdvMapDialogPos(Dialog index, Floor, X-coord, Y-coord, Z-coord)
This function overrides the specified values for the given Dialog Index. Essentially, it changes the location where the adventure map dialog is supposed to take place, as opposed to the default specified in the map's data files.
UpgradeTownBuilding(Town Name, Building Type)
This function upgrades a Town Building in the specified town by 1 level. If the building did not exist but is available for the town, it will be built. If the building is unavailable (because it is a special building of another town type), an error will be thrown. Note that in order to upgrade the Mage Guild, the Town Hall, the Fort, the Market Place and all Creature Dwellings, the function needs to be called several times for the same Building Type.
|
|
Maurice
Hero of Order
Part of the furniture
|
|
posted November 07, 2007 11:28 PM |
|
|
Quote:
Now that would be great does it also work from one Campaign into another? I mean from Campaign 1 Map 5 to Campaign 2 Map 1 for example.
I honestly don't know. I would think so, since the Artifact sets collected by Kujin and Gotai carry over from their campaign to the last campaign with Zehir.
|
|
sfidanza
Promising
Supreme Hero
|
|
posted November 09, 2007 01:48 PM |
|
|
First, nice list of undocumented functions, which really deserves a QP. 
I obviously missed it end september, so good digging by Kronos, and good follow-up by Maurice with the ToE functions.
If someone gets the time, these functions could be added on the wiki, so everything can be found on the same place.
And about Kronos' question, I assume you'll be packaging your campaigns as a mod (as there is no way to chain multiple campaigns in an .h5c file - or you should explain me how ). In which case, it will simply take the place of the standard ToE campaigns, and you should have access to the same functions.
|
|
Maurice
Hero of Order
Part of the furniture
|
|
posted November 09, 2007 03:28 PM |
|
|
I'll see what I can do about the Wiki - I already registered an account for the Wiki  . While I don't mind adding some stuff there, I noticed there's still a *lot* to be added. Just takes time, something I'm not sure about having plenty of, in the coming period.
|
|
sfidanza
Promising
Supreme Hero
|
|
posted November 10, 2007 12:20 AM |
|
|
Of course. The only way to do it is going one thing at a time. In this case the functions you present here. You don't need to fill in all the blanks.
And as I wrote, anyone can help.
|
|
sfidanza
Promising
Supreme Hero
|
|
posted November 23, 2007 12:19 PM |
|
|
Here's a useful function for mapmakers, should the map path change at some point:
GetMapDataPath()
returns the path to the map (like "Maps/Singleplayer/A2S5/" - with the final /). I advise to use it whenever you need to access files in the map folder, for example:
SetHeroBiography("Biara", GetMapDataPath().."new_Biara_bio.txt");
MessageBox(GetMapDataPath().."my_message.txt");
|
|
bknight2602
Hired Hero
|
|
posted October 10, 2013 05:23 AM |
|
|
I have a question about coding. Has anyone ever coded a combat?
I tried but when the code was compiled I got errors that the function was nill.
I'm trying to use AddCreature(1, 44, 100, 1, 13);
____________
|
|
frostymuaddib
Promising
Supreme Hero
育碧是白痴
|
|
posted December 05, 2013 06:36 PM |
bonus applied by Galaad on 21 Apr 2018. |
|
Hello. I'm sorry for reviving an old thread, but I found some hidden combat funcions, and I think that they need to be documented somwhere.
combatStarted()
Returns nil if combat is in tactics phase, 1 otherwise.
combatStarted(arg)
Pauses combat if arg is not nil, resumes when arg is nil.
combatPlayEmotion(side, animation)
side: 0 - attacker, 1 - defender
animation: not sure about this one, it should be some value that specifies animation
Plays specified animation for attacker's/defender's units.
playAnimation(name,animation)
name: unit's in-combat name.
animation: not sure about this one, it should be some value that specifies animation
Plays specified unit's animation.
unitNames()
Returns a string that is actually concatenation of creatures' (including heroes and warmachines) in-combat names.
GetUnits(side, type)
side: 0 - attacker, 1 - defender
type: 0 - hero, 1 - creatures 2 - war machines
Returns array of unit in-combat names for specified size and type.
exist(name)
name: unit's in-combat name.
Returns nil if unit with given name doesn't exist on the battlefield.
setATB(name,val)
Sets the ATB value for the named unit.
commandMove(name, X, Y)
name: unit's in-combat name
X, Y: battlefield coordinates.
Orders unit with given name to move to specified location, ignoring unit's speed and turn.
displace(name, X, Y)
Similar as commandMove, but moves unit instantly ('teleports it').
commandDoSpell(name, spell_id, X,Y)
name: unit's in-combat name
spell_id: spell's id
X, Y: battlefield coordinates.
Orders unit with given name to cast a spell at location (X,Y). Unit must have that spell. If spell requires specific target (like Lightning bolt), target must be present at that location.
UnitCastAimedSpell(name, spell_id, target_name);
UnitCastAreaSpell(name, spell_id, x,y);
UnitCastGlobalSpell(name, spell_id);
Similar as above, but for specific kind of spells.
commandShot(attacker, target)
attacker, target: in-combat unit name
Orders attacker to perform ranged attack on target.
commandAttack(attacker, target)
attacker, target: in-combat unit name
Orders attacker to attack target.
commandDefend(name)
Orders unit to defend.
removeUnit(name)
Removes given unit.
GetUnitType(name)
GetUnitSide(name)
name: unit's in-combat name
Returns unit type/side.
GetRageLevel(name)
name: unit's in-combat name
Returns rage level of the unit.
GetRagePoints(name)
name: unit's in-combat name
Returns unit's rage points.
GetUnitMaxManaPoints(name)
GetUnitManaPoints(name)
name: unit's in-combat name
Get unit's maximum/current mana.
SetUnitManaPoints(name,mana)
name: unit's in-combat name
mana: integer value for new mana
Sets unit's current mana (can exceed maximum).
showHighlighting(arg)
Shows combat grid if arg is not nil. Hides it if nil.
EnableDynamicBattleMode(arg)
Enables dynamic battle when arg is not nil, disables it when arg is nil.
Break()
Immidiately stops the combat without winner or looser. All casualties during the combat are negated. (Basically returns you to the moment that was before the combat started.)
|
|
lotihoti
Famous Hero
|
|
posted April 25, 2015 08:13 PM |
bonus applied by Galaad on 21 Apr 2018. |
|
OK  me again...
I push this thread because i found new script functions durin hex editing.
I tested none of them but if someone is willing to do it or to help me - message back.
Ok what i found so far:
1. CreateTreasure
2. GetPlayerNecroEnergy
3. GiveHeroBattleBonus
4. WarpHeroExp
5. WarpToMap
6. IsPlayerLost
7. IsTeamCurrent
8. IsPlayerWaitingForTurn
9. IsPlayerInGhostMode
10. IsPlayerCurrent
11. DisableCameraFollowHeroesForPlayers
12. MoveCameraForPlayers
13. SetAmbientLightForPlayers
14. Play3DSoundForPlayers
15. Play2DSoundForPlayers
16. QuestionBoxInt
17. MessageBoxInt
18. GetPlayerRace
Thats all i found so far... Some intresting new stuff. I couldnt do some tests right now... Will do that tomorrow.
|
|
magnomagus
Admirable
Legendary Hero
modding wizard
|
|
posted April 25, 2015 11:30 PM |
|
|
Excellent job, some things I never heard of before.
A lot however was reported in this tread (everything under new functions does not work in QAI31j, but most of the stuff under changes to existing documentation does:
http://www.celestialheavens.com/forums/viewtopic.php?t=9728
|
|
lotihoti
Famous Hero
|
|
posted April 26, 2015 09:07 AM |
|
|
Thanx
I tested them only in mapeditor window - so i can c if the font turns red. And it does...
Found many other things too, but they didnt turn red when i use them in editor - thats why i didnt post them (around 40 - 50 "functions").
It is possible that they are variables or ids like "PLAYER_1".
I will search them again and post them here.
|
|
magnomagus
Admirable
Legendary Hero
modding wizard
|
|
posted April 26, 2015 12:05 PM |
|
|
Quote:
Found many other things too, but they didnt turn red when i use them in editor
That is not conclusive, I have used functions that don't turn red in the editor. BTW if you accidentally happen to find the valuables for RMG monster strength, please let me know.
|
| |
|
|
