FindPathExplanation

An illustrated example of the [find_path] WML tag's results.

Imagine an Elvish Scout standing on the Player 1 start, this unit has 9 MP and needs 3 MP for each shallow water tile, so it can reach every village without needing a multi-turn move. Each of the villages might be considered to be the "nearest", because:

• "lake" is 3 hexes, 7 MP and 4 steps away
• "spur" is 5 hexes, 5 MP and 6 steps away
• "u_turn" is 2 hexes, 8 MP and 9 steps away

The movement_cost is how many movement points the unit will need to get to that hex.

The hexes is best explained by the U-turn village - although it needs a lot of movement points, the village is only 2 hexes away from Player 1's start.

The steps is the length of the path.step array. This always includes the starting hex.

Multi-turn moves

If the unit needs more than one turn to reach the destination, the cost includes any wasted MP at the end of a turn.

Consider an Elvish Archer instead of an Elvish Scout. This unit has 5 MP, so to get to the "lake" village it needs 2 turns, the first turn it moves on to first water hex but must end turn there, and the second turn is a water hex and a grass hex, for a total of 9 MP.

Consider the same Elvish Archer, but first we move 1 hex south, and then back to the starting point. [find_path] will now say that the path costs 7 MP, because the elf is already reduced to 0 MP before it ends the first turn.

The cost doesn't take account of capturing the village using up the unit's remaining movement.

Which village will [find_path] choose?

If [find_path] is used with a Standard Location Filter that matches multiple hexes, it will return a path to one of them. For example, when using an SLF that matches villages there are 3 possible destination hexes, and each one is "nearest" by one type of measurement.

In 1.14, it's unclear which of the three will be chosen.

(Version 1.15.2 and later only) the option nearest_by chooses between "movement_cost" (default), "steps" and "hexes".