Callback: Autoreplace vehicle selection

Autoreplace vehicle selection (34)

This callback is called whenever an old vehicle needs replacing. It returns the vehicle IDs to upgrade the current vehicle to. The vehicle variables are available as usual to decide which IDs would be appropriate to upgrade to.

The callback is repeatedly called, with the iteration number stored in lowest byte of variable 10.  The .grf file should return all possible IDs one by one, with the best ones listed first.  The patch will use the first vehicle from the list that is available to the player and has the required minimum reliability as set by the autoreplace switch, and abort the callback sequence at this point.

The callback sequence is also aborted when the returned ID is equal to the current vehicle ID. This is to prevent downgrading, and so you must take care to always return the ID of the vehicle for which the callback is called at the appropriate place in the sequence.

If the callback fails, i.e. if no suitable ID could be found by any of the callbacks in the generic chain, the vehicle is not upgraded, and is simply renewed instead.  If an ID is available but the player lacks the cash to upgrade, the patch waits for the cash to become available instead of either picking a worse engine or renewing the vehicle.

For trains, each engine head will be replaced by one vehicle of the new type.  As such, it is advisable for only return "compatible" IDs for trains that require a particular construction or arrangement of engine heads.

The callback is always used when defined, no bit in the action 0 property needs to be set to activate it.