Ways to refer to a hero in a script
A Hero By Any Other Name
When you write a script to control your heroes, you will find that there are three totally different ways to refer to a hero. This can be confusing, because different commands expect you to refer to heroes in different ways. The three different ways are Walkabout rank, Party slot and Name/ID
Commands that move heroes around on the map expect you to refer to the hero by walkabout rank. This is also known as walkabout order, walkabout slot caterpillar position, caterpillar rank or a few other variations on those themes.
Here is a visual representation of walkabout rank. Note that the constant me means the same thing as 0 and is often used in scripts to refer to the first hero walkabout rank.
Pretty simple so far, right? Well, what if we change the order of the heroes from the Order menu?
Notice that the walkabout rank numbers now point to different heroes because the hero order has changed.
So what if there is a gap in the party? Using the order menu, we can rearrange the party so there is a gap. This gap will show up in battle, but it will now show up in the walkabout rank or "caterpillar".
The gap in the party is ignored when numbering walkabout rank. The fact that gaps are ignored is the most important difference between walkabout rank numbering and party slot numbering.
List of commands that expect rank
- walk hero
- wait for hero
- set hero direction
- hero direction
- set hero frame
- hero frame
- set hero position
- hero X
- hero Y
- set hero z
- walk hero to x
- walk hero to y
- check hero wall
- set hero speed
- get hero speed
- hero is walking
- put hero
- hero pixel X
- hero pixel Y
- camera follows hero
- hero by rank
Also, commands that return walkabout rank numbers:
Most plotscripting commands that work with heroes refer to them by their party slot. This is also known as party position, position in party, battle position, battle slot and similar phrases.
Party slots are numbered from 0 to 3 for the active party, and 4-40 for heroes in the reserve.
If you rearrange the party, the party slot numbers do not change.
Note that empty slots count! This is one of the most important differences between walkabout rank and party slot.
If you try to use an empty slot number for a command that expects a party slot, the command will not work.
One very common mistake is to use 0, and assume that it work work for the first hero in the party. That works for commands that expect walkabout rank, but the assumption that 0 is the leader is only sometimes true for party slot. Consider this example:
# This won't work! set hero picture(0, 59)
Actually, sometimes this will work, but only if your first hero happens to be in the first slot. If your first slot is empty, nothing will happen. If you want to make sure you have the slot number of the first hero regardless of whether or not there are any gaps, you can use "find hero(leader)"
# This works fine! >:) set hero picture(find hero(leader), 59)
Sometimes walkabout rank and party slot happen to be exactly the same. Because of this, you might accidentally write a script that works perfectly when you test it, but fails when somebody else plays because they changed the order of their party.
List of commands that expect party slot
- status screen
- spells menu
- equip menu
- swap by position
- force equip
- equip where
- check equipment
- get default weapon
- set default weapon
- give experience
- teach spell
- forget spell
- read spell
- write spell
- knows spell
- can learn spell
- spells learnt
- outside battle cure
- get hero name
- set hero name
- rename hero by slot
- hero levelled
- total experience
- experience to next level
- experience to level
- set hero picture
- set hero palette
- get hero picture
- get hero palette
- hero by slot
- get hero stat
- set hero stat
- set capped hero stat
- get hero level
- set hero level
- set experience
- get level MP
- set level mp
Also, commands that return hero party slot numbers:
Name or ID
Each hero has an ID number. This is the number you see in the hero editor in CUSTOM
Some commands use the hero's ID number. You can also use the hero's name, in the form of hero:name, so for example, looking at the screenshot above, hero:Hilda would be the same as 3
You can look in your HSI file and see all the available hero: constants for your game.
Also note that the name used to refer to a hero in a script will be the name specified in the hero editor even if the player has renamed the hero to something else.
List of commands that expect Name or ID
Also, commands that return hero ID
Converting between the three
- find hero converts hero ID number into party position.
- hero by slot converts party position into hero ID number.
- hero by rank converts walkabout rank into hero ID number.
- rank in caterpillar converts hero ID number into walkabout rank.
|From ID/Name||From Party Slot||From Caterpillar rank|
|To ID/Name||id := hero by slot(slot)||id := hero by rank(rank)|
|To Party Slot||slot := find hero(id)||slot := find hero(hero by rank(rank))|
|To Caterpillar Rank||rank := rank in caterpillar(id)||rank := rank in caterpillar(hero by slot(slot))|