Try next candidates after blocking exits

[Murreey]

Description

Refactoring to keep all candidates, in priority order, rather than just finding the best one and discarding the rest. Enables us to ignore the best one for any reason, and fallback to the next in the list.

• Change getBestCandidate to be sortValidCandidates, so it keeps the whole list in distance order
• Refactor the candidate choosing logic to loop through all of them, rather than only checking the first one

Motivation and Context

Currently, we only check the blocked exits once, after we've picked a best candidate. If the best candidate does get blocked, we return null. This means there might be other good candidates that get ignored if the best one is in a blocked direction. So instead, we want to keep all the candidates in a sorted order, and find the first one that's a valid move.

Fixes a bug where the best candidate might be outside a container behind a blocked exit, but there is another second best candidate that should be chosen instead.

i.e. here, UP from 6 should go to 2, but 3 is a better candidate. Previously it tries to go to 3, sees the blocked exit, then stops completely. Now it will discard 3, and try again successfully to move you to 2.

How Has This Been Tested?

Updated the template file to expose the behaviour, and added an integration test for it

Checklist:

• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new and existing tests passed.