Ways to refer to a hero in a script

Jump to: navigation, search

A Hero By Any Other Name[edit]

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

Walkabout rank[edit]

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?

Changing-hero-order.png Walkabout-rank-with-different-hero-order.png

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".

Changing-hero-order-with-no-gap.png Walkabout-rank.png

Changing-hero-order-with-a-gap.png Walkabout-rank.png

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[edit]

Also, commands that return walkabout rank numbers:

Party slot[edit]

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.

Team-menu-party-slots.png Team-menu-party-slots-rearranged.png

Note that empty slots count! This is one of the most important differences between walkabout rank and party slot.

Team-menu-empty-slots.png Walkabout-rank-0-party-slot-2.png

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)

Setheropicture-will-not-work.png Setheropicture-works-fine.png

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.

Changing-hero-order-with-no-gap.png Compare-slot-and-rank-same.png

Changing-hero-order-with-a-gap.png Compare-slot-and-rank-different.png

List of commands that expect party slot[edit]

Also, commands that return hero party slot numbers:

Name or ID[edit]

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[edit]

Also, commands that return hero ID

Converting between the three[edit]

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))