The advanced features of the Heroes IV map editor can be a bit daunting, considering the lack of proper documentation. Fortunately, it's surprisingly easy to find some help with scripting, especially at the Round Table's Mapmaking Guild. But if you are looking for a good reference to help you get started, you need to take a look at Thelonious' new guide, The Basics of Scripting. He lists all the scripts found in the editor, describes what they do and how you can use them in your map, and highlights the most useful ones. The article might even provide some inspiration for your next map -- after all, how many maps out there were born with a cool idea with a script?
If you need more help with your Heroes IV map, check out the Celestial Heavens mapmaking tips section. Mapmakers such as Ururam Tururam, Charles Watkins and Vladimir Kuzmanov are waiting for you there.
The Basics of Scripting
Yes, you all read it perfectly. This is article is not about mapmaking. This one is about scripting. And that is a whole different thing. Also you might have noticed that this article doesn’t have one of those cheesy or demoralising titles such as: ‘Scripting for dummies’ or ‘n00b scripting.’ This article is different, because it explains the various scripts, gives examples and makes you understand the scripts. Note that I’m using HoMM IV standard edition version 3.0. Now, let’s start scripting!
The first thing you’ll need is a test map. Go to the editor and create a new map, for simplicity, a small one. An underground is not needed, but if you want, you can add this in order to see that scripts do affect both layers.
Now if you have this new map, you’d best call it ‘Test map’ or something like that, this way you can easily see that this is where you test scripts. Also you should note that this map shouldn’t have to be deleted after you’ve gone through this article. A test map is going to be your best friend as you (the mapmaker) will eventually use advanced scripts that need testing, this is preferably done on a test map, so a script on the end of a map will not require you to play through the whole map.
Now back to scripting. One of the things that can be hard is to figure out how you need to script something, and in some cases if it can be scripted at all. This creates problems for basic mapmakers, and thus it is useful to know what the scripts do. That way you can set up a plan to make the script you need for your action. The scripts are in alphabetical order, and various important scripts have been put in Italics. The names of the scripts have been typed exactly, so searching is made easier, the exception are the Decrease and Increase statistic, as the do the same save for a different statistic, as explained.. Also note that some scripts are found only under certain tabs of certain objects, this is noted for all things, but for the script that have to be used under the If of the Conditional Action script. You probably wouldn’t want to use them anywhere else anyway.
The list of scripts:
And
This is found under the script Conditional Action and enables you to make 2 prerequisites for the event to occur. If you click on it, 2 fields appear where other scripts can be chosen. Of course an And under an And will create more open spaces for prerequisites.
Ask Question
This script enables you to let the player make a choice. In the first field a question must be typed, then under ‘If yes’ scripts can be placed that will run if the player chooses yes, under ‘If no’ scripts can be placed in case the player chooses no. This can be an interesting script for moderating difficulty or for example when the player needs to pay for something (artefact) he can be asked if he wants to pay now or return later.
Can Give Skill
This script checks if a hero can receive a skill, though this one’s buggy and will be true when it should be false. It can be found under the events tab of a hero.
Certain Hero is Dead
This script allows you to check in game whether a hero is dead, this is a useful script in RPG maps where the player has to defeat a ‘villain’ and you want the player to win after he’s defeated the villain. Note that the hero who gets checked has to have a custom name, or else you can use this script.
Certain Hero is in Prison
This script allows you to check whether a hero is in prison. That hero (like the Certain Hero is Dead script) has to have a custom name.
Change Owner
This script allows you to change the colour of a stack. Do note that this script does not stick to a hero, and seems to be lost when a hero and a stack combine and then separate again. If you want to change a hero’s colour over and over again, via various variables you should remove this script as variables mostly stay true and the hero would then change to 2 colour which will probably make the game crash.
Clear Loss Condition Description
This clears the loss condition description, useful in RPG maps where new goals have been added or goals have been changed.
Clear Loss Message
This clears the message that is shown when a player loses. By default this is nothing, so you’d have to set one in order to remove one.
Clear Victory Condition Description
This clears the victory condition description, useful in RPG maps were goals have been changed or added. This way a new one can be set.
Clear Victory Message
Clears the message that is shown when the player is victorious.
Combat
This script allows you to script a battle. Do note that you cannot use this script for battles with Heroes. This is a buggy script; the defeated and victorious don’t work. In order for then to work properly you have use a different script. See further for the Condition Action script, which is included in this little script.
If
Total number of heroes in This army Equals 0(This means the hero has fled)
Then
Do Nothing
Else
Give 1 ghost to This army
Take 1 ghost from This army
If
Number of ghosts in This army = 0Then(the hero was victorious, put the victory scripts here)Else(the hero has lost, put the lost scripts here)
This script works because an army cannot exist of less than 1 creature. Because you give the ghost to the army (it doesn’t really matter that this is a ghost, it can be any creature) it can’t be taken if you have lost because then you army has creatures once more, and an army can’t consist of less then 1 creature. If you have won, your army already consists of more than one creature and thus you can take the ghost.
(Thanks to GhostWriter for this script)
Conditional Action
This is one of the most important scripts, if not the most important. This script allows you to set a prerequisite and then tie consequences to it. Under ‘IF’ you can set the prerequisite and under ‘Then’ what has to happen when this prerequisite is met. Under Else you can set what has to happen if the prerequisite is not met. A simple example:
If
Material Quantity = Greater Than or Equals 500
Then
Ask QuestionDo you want to but this ring?
If yesSequenceIf noTake Materials 500 gold
Give Wizards Ring
Display Message ‘Pleasure doing business with you!’Do Nothing
Else Display Message ‘You could buy a beautiful ring here, but you don’t have enough money.’
This is a simple merchant script, but you can change and expand this as much as you want.
Construct Building
This script can only be found under the events tab in a town. It allows you to construct a building, even when the town have no alignment at the start. The names of the buildings fit to what alignment (so even no alignment has specific names) that town is.
Current Day
This checks the day, and stores it as a number. As an example, if the current day is day 4 of week 2 of month 2 the number stored is 46. This can be useful if you make a map that has to be completed within a certain amount of days.
Current Day of the Week
This checks the current day of the. This can be useful if you want certain gates opened only on Mondays, day 1 of each week. This way you won’t have to set a timed event, and use extra variables, which is the kind of thing you want to evade.
Current Month
This checks the current month, certain areas could be made accessible only in certain months.
Current Week
This checks the week number, so if you want an script to run on week 6, the Current Week should be equal to 6
Current Week of the Month
This checks the number of the week in the month. This means that week 6 is week 2 of month 2
Decrease Statistic (attack, defence, etc.)
Decreases a statistic of a hero. You cannot exactly specify which hero, but the options given to you make it possible to decrease the statistic of the hero you mean to decrease the statistic from. Also make sure when you use Decrease Spell Points that you use the right one, one is for the spell points the hero currently has, the other is for the maximum spell points the hero can have.
Decrease Dwelling Population
This script can only be found under the events tab in towns, not in out of town dwellings. It decreases the number of creatures in a dwelling by a certain number.
Delete Adventure Objects
This script allows you to delete everything from mountain to complete towns. On the adventure map you place a ‘dynamite’ (under Adventure objects, miscellaneous) to which you give a name, BOOM for instance. Then you go to your event, and select this script, and under Select Marker Name choose BOOM, don’t type it, it is already in the list, just click on the little arrow and a drop down menu lists all the different markers on the map. This will avoid spelling errors, and thus early bugs. Also, if you want several things to be deleted at the same time you can name several ‘dynamites’ the same so they all blow up at the same time.
Disable Standard Victory Condition
This disables the standard victory condition that allows the player who defeats all other players win. It can be disabled right from the start, without this script.
Display Message
This is a way of including messages in certain scripts. Also you can add side scripts to the message such as Take Materials
Divided By
This divides a number or variable by another number or variable. Do note that this number is stored as an integer, which means that it is a whole number (1, 2, 3 etc.) and it is rounded up to the nearest whole number. For example, if you use Divided By, and fill in 1 in the upper field, and 3 in the lower field, the number that comes out of the script is 1, and not 1/3.
Do Nothing
You might think this is a useless script, but it is everywhere. Absolutely everywhere. That is everywhere you don’t want anything to happen, and that can be in a lot of cases when you use Conditional Action
Enable Standard Victory Condition
This enables the player to win when he has defeated all other players.
Equals
This will be set to True when one variable = another variable. This is a way to check if a player has indeed 50 gold. Do note that if the player has 51 gold Equals is set to False.
An example:
If
Current day of the Week Equals 1
Then
Display message ‘This day is called Monday’
Else
Do Nothing
This way every first day of the week a message will be displayed saying ‘This day is called Monday’
False
This set a Variable to False, which means that a prerequisite is not True. For example: You have a hero that may not have a Chaos magic, so if that hero has Chaos Magic, the variable ChaosMagic is set to true. (To check for a skill see Skill Mastery further on, and Variable on how to implement a variable in a script)
If
ChaosMagic = False
Then
Do nothing
Else
Lose
Give Artifacts
This script enables you to give artefacts to a player.
Give Creatures
This script enables you to give a certain amount of certain creatures to a player, this can only be found under the events tab in towns, armies and heroes.
Give Materials
This script give a certain amount of specified materials to a player, do note that in my map editor crystal is named ore, and it is the second ore you stumble upon. This can is most probably a bug.
Give Skill
This script can be found under the event tab of heroes and creatures. This gives a skill with specified mastery to the player.
Give Spell
This script gives a spell to the player, which ends up in the heroes spell book
Greater Than
This script checks if a variable is greater than another.
Greater Than or Equals
This script checks if a variable is greater that, or equalled to another variable.
Has Artifact
This script checks if an army has a certain artefact.
Increase Statistic (attack, defense, etc.)
Increases the statistic of a hero. You cannot exactly specify which hero, but the options given to you make it possible to increase the statistic of the hero you mean to increase the statistic from. Also make sure when you use Increase Spell Points that you use the right one, one is for the spell points the hero currently has, the other is for the maximum spell points the hero can have.
Increase Current Movement
This is mentioned separately because there is no decrease script to counter it. It decreases the movement on the hero on the adventure map.
Increase Dwelling Population
Increases the number of creatures in a dwelling, can be found under the event tab of a town.
Increase Experience Level
This increases the experience level of a hero; this one is mentioned separately because it is a big buggy. If you for example increase the level by 10 the actual levels the hero gets is around 6 – 7. This is probably because it calculates the amount of experience needed for the first extra level and then repeats this progress 10 times. In order to really increase the level by ten one should repeat it ‘manually’ 10 times.
Increase Skill
Increase the level of a certain skill by a certain amount.
Less Than
This is used to check if one variable is less than another. This can be useful when scripting a quest. For example, let’s say you want a quest where you need to hunt down at least 5 packs of wolves. The script would look like this: Under the tab Triggered Script of the quest hut –
Set Numeric Variable ‘PacksOfWolves’ to 6
Under the events tab of the wolves, choose defeated and then enter this script:
Set Numeric Variable ‘PackOfWolves’ to ‘PackOfWolves’ Minus 1
(Check the Minus script and the Variable script on how to do this.)
Then under the Completion tab of the quest hut:
If
‘PackOfWolves’ Less Than 3
(choose Less Than first, and enter the variables in the fields)
Then
(quest completed)
Else
Do Nothing(quest uncompleted)
You can set the total amount of PackOfWolves to a higher number, and change the limit to complete the quest. And another tip: if you don’t want to copy the script a dozen times, do the script on 1 pack of wolves, and check if it works properly. Then put that pack back into the object pallet (where all the adventure object, landscape object etc. are) and then place that pack of wolves a dozen time on your map. This saves a lot of time, and creates dozen correct scripts.
Less Than or Equals
This script checks if a variable is less than or equal to another variable.
Lose
You might not think this is a script you’d use often, but in an RPG map it’s vital even if you only use it 3 times. It enables you to make a player lose – this means you can make a player lose if a specific character is defeated.
Material Quantity
This allows you to check the quantity of a material. It has a drop down menu that lets you choose the material. It is often used in combination with Greater Than or Less Than or Equals etc.
Minus
This let’s you subtract a variable from another. If you use this, choose Minus, and enter 2 variables in the field, the upper field is the variable which gets the other variable subtracted from.
Negate
A pretty useless script as it changes a number from + to – and the other way around. This could only be useful in situations where you don’t know what a number will be and want to change it from + to – (or the other way around) anyways. Though you could also use the Times script and multiply with -1.
Not
This can be useful if you use a variable for something you don’t want to happen.
Number
This let’s you set a number, which you can use to calculate with numeric variables.
Number of Creatures in Army
This lets you see how many creatures an army has of a certain type. Do note that if you want to use this script to take a certain amount of creatures, you can also use Total Number of Creatures in Army to make sure the player doesn’t use a trick to gain 1 creature from the script. Example: you want to take 5 medusas and the player sends just those 5 medusas to the quest. Then the player gets a tiny bonus because 1 medusa is left. To work around this use this little script:
If
Number of Creatures in Army, Medusas, is Greater Than or Equals 5
And (choose this option first and put these scripts in the upper and lower field)
Total Number of Creatures in Army is Greater Than 5(this means 6 or higher)
Then
(Completion scripts)
Else
Do Nothing
This way there always has to be 1 extra creature.
Or
This script enables you to give two prerequisites while only one has to be met.
Player ID
This script is, from what I’ve found through my testing, quite useless. It is a value given to a player, but it is always 0, even different colours have the same value, as do different alignments, or if the computer is an AI player. So in short, this is a bugged script that serves no real purpose.
Player is certain Alignment
Checks whether the player is a certain alignment.
Player is certain Color
Enables you to check if the player is a certain colour.
Player is Computer
Check if the player is operated by the AI.
Player owns certain Hero
Checks if a player has a certain hero in it’s army. It has to be a hero with a custom name though.
Player owns certain Town
Checks if a player owns a town, the town in question has to have a custom name though.
Plus
Adds one value to another, these values can be variables.
Random Number
Sets a random number between specified borders.
Remainder
This calculates the remainder when dividing. Though you must note that this function sometimes does not work. The actual calculation is this one:
Remainder = Variable 1 - (Variable 1 / Variable 2) * Variable 2
For example: Variable 1 = 15, Variable 2 = 3
15 – (15 / 3) * 3 => 15 – 5*3 => 15 – 15 => the Remainder is 0
Remove Script
One of the most important scripts as it allows you to stop a script and remove it so it won’t be ran again, useful when using placed events.
Remove This Object
This can only be found when using a Pandora’s box; it removes the box from the map.
Sequence
This is one of the most important scripts as it allows you to put several scripts in one big script. The scripts are done according to the order you put them in list. The first one in the list being done first.
Set Boolean (True / False) Variable
This is an important script as it allows you to set a true or false variable, which you can use in Condition Action. Use this in situations where the player only needs to get the information once, or abstract things such as (in an RPG map) getting a key for a quest gate.
Set Loss Condition Description
This enables you to put a special description under the map specifications to update when a player looses. This can be in useful when a player must complete a quest he has gained from the map.
Set Loss Message
This sets a message that is displayed when the player looses.
Set Numeric Variable
This sets a variable that can hold any number you want. This can be used in calculations or difficulty settings.
Set Victory Condition Description
Sets a victory condition description. This can be in useful when a player has to complete a quest that he has gained on the adventure map – the victory description could then include the quest completion condition.
Set Victory Message
Sets a message that appears when a player wins.
Skill Mastery
Checks the mastery of a skill. This works a bit peculiar: if a hero doesn’t have the skill this value is -1, Basic is 0, Advanced is 1, Expert is 2, Master is 3 and Grand Master is 4.
Take Artifacts
Enables you to take artefacts from an army.
Take Creatures
Enables you to take creatures from an army.
Take Materials
Enables you to take materials from an army.
Times
Multiplies one variable with another.
Total Number of Creatures in Army
Counts the total number of creatures in an army. This can be useful on a RPG map where you want only the hero to go to a location.
Total Number of Heroes in Army
Counts the number of heroes in an army.
Trigger Custom Event
This triggers an event under the triggered events tab of the map specifications. It can come in useful if you want to trigger something more complicated or twice under different conditions.
True
Enables you to set a Boolean (True / False) variable to true.
Variable
Enables you to check if a Boolean (True / False) variable is true in a conditional action. Very useful and used many, many times.
Win
Enables you to make a player win under another condition than to defeat all the other players.
With this list you should be able to figure out how to script what you want. If you want to do it right the first time, and thus save testing time; always clearly write down what you want done, and then what step have to be taken to get it done. If that still doesn’t work, check the Mapmaking Guild for answers, make a new thread for other mapmakers to answer your question. Do always check if the problem has been addressed to earlier, as it saves doubles threads.
If you under stand the basics, and want to move on, check this thread for some tips and tricks. Questions about advanced scripting can also be asked there. Happy scripting!
This was Thelonious, over and out.
