fivem icon indicating copy to clipboard operation
fivem copied to clipboard

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

Open Sage-of-Mirrors opened this issue 2 months ago • 4 comments

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

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

Fixes issues

Resolves #2424.

Sage-of-Mirrors avatar Jun 03 '24 20:06 Sage-of-Mirrors