feat(extra-natives/rdr3): Add natives for train tracks

[Sage-of-Mirrors]

Goal of this PR

This PR provides three new natives for RedM for working with train tracks:

• GET_TRACK_COUNT: Returns the number of tracks that are currently loaded in the world.
• GET_TRACK_FROM_INDEX: Returns the name hash of the track at the given index, or 0 if that index is invalid.
• LOAD_TRACKS_FROM_FILE: Disposes of the currently-loaded tracks and loads new ones from a given traintracks.xml file. This allows for fully customized rail networks.

It also provides patches for three crashes that can occur when using LOAD_TRACKS_FROM_FILE:

• Track junctions that point to invalid tracks will fall through the post-processing step, meaning that trains trying to use those junctions will use invalid data and thus cause a crash. The patch removes junctions with invalid track references prior to post-processing.
• Clients can no longer call CREATE_MISSION_TRAIN() when there are 0 tracks loaded; the function returns a null train handle.
• The train tracks exist in a pool with slots for 50 of them; the function for loading track data from the XML file now bails out if the track pool is full.

This resource can be used to test the track natives. See client.lua for the list of commands.

How is this PR achieving the goal

The extra natives can be found in extra-natives-rdr3/src/TrackNatives.cpp. The patches can be found in gta-core-rdr3/src/PatchTrainTrackCrashes.cpp.

GET_TRACK_COUNT and GET_TRACK_FROM_INDEX are just directly accessing the track data.

LOAD_TRACKS_FROM_FILE is based on FiveM's LOAD_WATER_FROM_PATH.

The patches for junction crashes and preventing trains from spawning when there are 0 tracks loaded are simple trampolines.

The patch for not loading more tracks than the game has space for is an ASM patch inserted at the original exit condition check for the XML loading loop.

This PR applies to the following area(s)

RedM, Natives

Successfully tested on

Game builds: 1491.50

Platforms: Windows

Checklist

• Code compiles and has been tested successfully.
• Code explains itself well and/or is documented.
• My commit message explains what the changes do and what they are for.
• No extra compilation warnings are added by these changes.

Fixes issues

Resolves #2424.

[prikolium-cfx]

Hi. Thanks for your contribution. Can you please provide traintracks.xml for testing and describe expected behavior, so we can test it too?

[Sage-of-Mirrors]

Hi! Thank you for the response.

This resource, which I linked in the main PR message, can be used to test the changes.

Testing Steps

1. In the F8 menu, run the command track_count. This should return the message "Track count: 29".
2. In the F8 menu, run the command track_at_index 0. This should return the message "Track name hash at index 0: 3534397256".
3. In the F8 menu, run the command track_at_index 51. This should return the message "Track name hash at index 51: 0".
4. In the F8 menu, run the command load_tracks. This should return the following message:

Track count before load: 29
Track count after load: 34

5. In the F8 menu, run the command track_count. This should return the message "Track count: 34".
6. In the F8 menu, run the command spawn_trains. The game should not crash.
7. Exit the game, and navigate to traintracks.xml, which is located at <resources>/tracktest/data/. Open traintracks.xml in a text editor, and remove the contents of the <train_tracks> XML element. Save the file, and re-enter the game. In the F8 menu, run the command load_tracks. This should return the following message:

Track count before load: 29
Track count after load: 0

8. In the F8 menu, run the command spawn_trains. This should return the message "CreateMissionTrain() failed - track pool is empty!".
9. Repeat Step 7, but instead of removing the contents of the <train_tracks> element, copy one of the <train_track> elements within it and paste it multiple times - enough to push the number of <train_track> elements within the <train_tracks> node over 50. Save the file, re-enter the game, and in the F8 menu, run the command load_tracks. This should return the following message:

Track count before load: 29
Track pool is full - no more tracks can be loaded.
Track count after load: 50

Please let me know if I can provide additional information. Thank you!

[Sage-of-Mirrors]

I have updated my testing steps to include steps for testing having 0 train tracks in traintracks.xml, and having more than 50 tracks in it.

[Sage-of-Mirrors]

Hey, just checking in. Is there anything I can do to help the review process along?