feat(vehicle/pathfind) Updated some vehicle node natives (#1199)

* vehicle node natives * Update PATHFIND/GetNthClosestVehicleNode.md Co-authored-by: Dillon Skaggs <dillskaggs@gmail.com> * Update PATHFIND/GetNthClosestVehicleNodeIdWithHeading.md Co-authored-by: Dillon Skaggs <dillskaggs@gmail.com> * tweak: keep consistent language for enum --------- Co-authored-by: Dillon Skaggs <dillskaggs@gmail.com>
citizenfx · Jan 23, 2025 · 61bf52d · 61bf52d
1 parent 3e7c8f0
commit 61bf52d
Show file tree

Hide file tree

Showing 8 changed files with 96 additions and 137 deletions.
diff --git a/PATHFIND/GetClosestMajorVehicleNode.md b/PATHFIND/GetClosestMajorVehicleNode.md
@@ -5,19 +5,18 @@ ns: PATHFIND
 
 ```c
 // 0x2EABE3B06F58C1BE 0x04B5F15B
-BOOL GET_CLOSEST_MAJOR_VEHICLE_NODE(float x, float y, float z, Vector3* outPosition, float unknown1, int unknown2);
+BOOL GET_CLOSEST_MAJOR_VEHICLE_NODE(float x, float y, float z, Vector3* outPosition, float zMeasureMult, int zTolerance);
 ```
 
-```
-Get the closest vehicle node to a given position, unknown1 = 3.0, unknown2 = 0  
-```
+Same as [`GET_CLOSEST_VEHICLE_NODE`](#_0x240A18690AE96513), but with the node flag `GCNF_INCLUDE_SWITCHED_OFF_NODES` set.
 
 ## Parameters
-* **x**: 
-* **y**: 
-* **z**: 
-* **outPosition**: 
-* **unknown1**: 
-* **unknown2**: 
+* **x**: X coordinate
+* **y**: Y coordinate
+* **z**: Z coordinate
+* **outPosition**: Pointer to the found nodes coords
+* **zMeasureMult**: How strongly the difference in the Z direction should be weighted
+* **zTolerance**: How far apart the Z coords have to be before `zMeasureMult` kicks in
 
 ## Return value
+Returns the closest major vehicle node.
diff --git a/PATHFIND/GetClosestVehicleNode.md b/PATHFIND/GetClosestVehicleNode.md
@@ -5,33 +5,28 @@ ns: PATHFIND
 
 ```c
 // 0x240A18690AE96513 0x6F5F1E6C
-BOOL GET_CLOSEST_VEHICLE_NODE(float x, float y, float z, Vector3* outPosition, int nodeType, float p5, float p6);
+BOOL GET_CLOSEST_VEHICLE_NODE(float x, float y, float z, Vector3* outPosition, int nodeFlags, float zMeasureMult, float zTolerance);
 ```
 
-```
-FYI: When falling through the map (or however you got under it) you will respawn when your player ped's height is <= -200.0 meters (I think you all know this) and when in a vehicle you will actually respawn at the closest vehicle node.
-----------
-Vector3 nodePos;
-GET_CLOSEST_VEHICLE_NODE(x,y,z,&nodePos,...)
-p4 is either 0, 1 or 8. 1 means any path/road. 0 means node in the middle of the closest main (asphalt) road.
-p5, p6 are always the same:
-0x40400000 (3.0), 0
-p5 can also be 100.0 and p6 can be 2.5:
-PATHFIND::GET_CLOSEST_VEHICLE_NODE(a_0, &v_5, v_9, 100.0, 2.5)
-Known node types: simple path/asphalt road, only asphalt road, water, under the map at always the same coords.
-The node types follows a pattern. For example, every fourth node is of the type water i.e. 3, 7, 11, 15, 19, 23, 27, 31, 35, 39... 239. Could not see any difference between nodes within certain types.
-Starting at 2, every fourth node is under the map, always same coords.
-Same with only asphalt road (0, 4, 8, etc) and simple path/asphalt road (1, 5, 9, etc).
-gtaforums.com/topic/843561-pathfind-node-types
+```c
+enum eGetClosestNodeFlags {
+    GCNF_INCLUDE_SWITCHED_OFF_NODES = 1,
+    GCNF_INCLUDE_BOAT_NODES = 2,
+    GCNF_IGNORE_SLIPLANES = 4,
+    GCNF_IGNORE_SWITCHED_OFF_DEADENDS = 8,
+    GCNF_GET_HEADING = 256,
+    GCNF_FAVOUR_FACING = 512
+}
 ```
 
 ## Parameters
-* **x**: 
-* **y**: 
-* **z**: 
-* **outPosition**: 
-* **nodeType**: 
-* **p5**: 
-* **p6**: 
+* **x**: X coordinate
+* **y**: Y coordinate
+* **z**: Z coordinate
+* **outPosition**: Pointer to the found nodes coords
+* **nodeFlags**: Node flags
+* **zMeasureMult**: How strongly the difference in the Z direction should be weighted
+* **zTolerance**: How far apart the Z coords have to be before `zMeasureMult` kicks in
 
 ## Return value
+Returns the closest vehicle node matching the node flags.
diff --git a/PATHFIND/GetClosestVehicleNodeWithHeading.md b/PATHFIND/GetClosestVehicleNodeWithHeading.md
@@ -5,39 +5,20 @@ ns: PATHFIND
 
 ```c
 // 0xFF071FB798B803B0 0x8BD5759B
-BOOL GET_CLOSEST_VEHICLE_NODE_WITH_HEADING(float x, float y, float z, Vector3* outPosition, float* outHeading, int nodeType, float p6, int p7);
+BOOL GET_CLOSEST_VEHICLE_NODE_WITH_HEADING(float x, float y, float z, Vector3* outPosition, float* outHeading, int nodeFlags, float zMeasureMult, int zTolerance);
 ```
 
-```
-p5, p6 and p7 seems to be about the same as p4, p5 and p6 for GET_CLOSEST_VEHICLE_NODE. p6 and/or p7 has something to do with finding a node on the same path/road and same direction(at least for this native, something to do with the heading maybe). Edit this when you find out more.  
-p5 is either 1 or 12. 1 means any path/road. 12, 8, 0 means node in the middle of the closest main (asphalt) road.  
-p6 is always 3.0  
-p7 is always 0.  
-Known node types: simple path/asphalt road, only asphalt road, water, under the map at always the same coords.   
-The node types follows a pattern. For example, every fourth node is of the type water i.e. 3, 7, 11, 15, 19, 23, 27, 31, 35, 39... 239. Could not see any difference between nodes within certain types.   
-Starting at 2, every fourth node is under the map, always same coords.  
-Same with only asphalt road (0, 4, 8, etc) and simple path/asphalt road (1, 5, 9, etc).  
-gtaforums.com/topic/843561-pathfind-node-types  
-Example of usage, moving vehicle to closest path/road:  
-Vector3 coords = ENTITY::GET_ENTITY_COORDS(playerVeh, true);  
-Vector3 closestVehicleNodeCoords;   
-float roadHeading;   
-PATHFIND::GET_CLOSEST_VEHICLE_NODE_WITH_HEADING(coords.x, coords.y, coords.z, &closestVehicleNodeCoords, &roadHeading, 1, 3, 0);   
-ENTITY::SET_ENTITY_HEADING(playerVeh, roadHeading);  
-ENTITY::SET_ENTITY_COORDS(playerVeh, closestVehicleNodeCoords.x, closestVehicleNodeCoords.y, closestVehicleNodeCoords.z, 1, 0, 0, 1);  
-VEHICLE::SET_VEHICLE_ON_GROUND_PROPERLY(playerVeh);  
-------------------------------------------------------------------  
-C# Example (ins1de) : pastebin.com/fxtMWAHD  
-```
+Same as [`GET_CLOSEST_VEHICLE_NODE`](#_0x240A18690AE96513), but with the node flag `GCNF_GET_HEADING` set, causing the native to also return the heading.
 
 ## Parameters
-* **x**: 
-* **y**: 
-* **z**: 
-* **outPosition**: 
-* **outHeading**: 
-* **nodeType**: 
-* **p6**: 
-* **p7**: 
+* **x**: X coordinate
+* **y**: Y coordinate
+* **z**: Z coordinate
+* **outPosition**: Pointer to the found nodes coords
+* **outHeading**: Pointer to the found nodes heading
+* **nodeFlags**: Node flags, see [`GET_CLOSEST_VEHICLE_NODE`](#_0x240A18690AE96513)
+* **zMeasureMult**: How strongly the difference in the Z direction should be weighted
+* **zTolerance**: How far apart the Z coords have to be before `zMeasureMult` kicks in
 
 ## Return value
+Returns the closest vehicle node with its heading.
diff --git a/PATHFIND/GetNthClosestVehicleNode.md b/PATHFIND/GetNthClosestVehicleNode.md
@@ -5,18 +5,20 @@ ns: PATHFIND
 
 ```c
 // 0xE50E52416CCF948B 0xF125BFCC
-BOOL GET_NTH_CLOSEST_VEHICLE_NODE(float x, float y, float z, int nthClosest, Vector3* outPosition, Any unknown1, Any unknown2, Any unknown3);
+BOOL GET_NTH_CLOSEST_VEHICLE_NODE(float x, float y, float z, int nthClosest, Vector3* outPosition, int nodeFlags, cs_type(Any) float zMeasureMult, cs_type(Any) float zTolerance);
 ```
 
+Same as [`GET_CLOSEST_VEHICLE_NODE`](#_0x240A18690AE96513), but returns the nth closest node instead of the first.
 
 ## Parameters
-* **x**: 
-* **y**: 
-* **z**: 
-* **nthClosest**: 
-* **outPosition**: 
-* **unknown1**: 
-* **unknown2**: 
-* **unknown3**: 
+* **x**: X coordinate
+* **y**: Y coordinate
+* **z**: Z coordinate
+* **nthClosest**: The index of the node to return
+* **outPosition**: Pointer to the found nodes coords
+* **nodeFlags**: Node flags, see [`GET_CLOSEST_VEHICLE_NODE`](#_0x240A18690AE96513)
+* **zMeasureMult**: How strongly the difference in the Z direction should be weighted
+* **zTolerance**: How far apart the Z coords have to be before `zMeasureMult` kicks in
 
 ## Return value
+Returns the nth closest vehicle node.
diff --git a/PATHFIND/GetNthClosestVehicleNodeFavourDirection.md b/PATHFIND/GetNthClosestVehicleNodeFavourDirection.md
@@ -5,27 +5,24 @@ ns: PATHFIND
 
 ```c
 // 0x45905BE8654AE067 0x928A4DEC
-BOOL GET_NTH_CLOSEST_VEHICLE_NODE_FAVOUR_DIRECTION(float x, float y, float z, float desiredX, float desiredY, float desiredZ, int nthClosest, Vector3* outPosition, float* outHeading, int nodetype, cs_type(Any) float p10, Any p11);
+BOOL GET_NTH_CLOSEST_VEHICLE_NODE_FAVOUR_DIRECTION(float x, float y, float z, float desiredX, float desiredY, float desiredZ, int nthClosest, Vector3* outPosition, float* outHeading, int nodeFlags, cs_type(Any) float zMeasureMult, cs_type(Any) float zTolerance);
 ```
 
-```
-See gtaforums.com/topic/843561-pathfind-node-types for node type info. 0 = paved road only, 1 = any road, 3 = water  
-p10 always equal 0x40400000  
-p11 always equal 0  
-```
+Like [`GET_CLOSEST_VEHICLE_NODE_WITH_HEADING`](#_0xFF071FB798B803B0), but returns the nth closest node instead of the first.
 
 ## Parameters
-* **x**: 
-* **y**: 
-* **z**: 
-* **desiredX**: 
-* **desiredY**: 
-* **desiredZ**: 
-* **nthClosest**: 
-* **outPosition**: 
-* **outHeading**: 
-* **nodetype**: 
-* **p10**: 
-* **p11**: 
+* **x**: X coordinate
+* **y**: Y coordinate
+* **z**: Z coordinate
+* **desiredX**: The X direction to favour
+* **desiredY**: The Y direction to favour
+* **desiredZ**: The Z direction to favour
+* **nthClosest**: The index of the node to return
+* **outPosition**: Pointer to the found nodes coords
+* **outHeading**: Pointer to the found nodes heading
+* **nodeFlags**: Node flags, see [`GET_CLOSEST_VEHICLE_NODE`](#_0x240A18690AE96513)
+* **zMeasureMult**: How strongly the difference in the Z direction should be weighted
+* **zTolerance**: How far apart the Z coords have to be before `zMeasureMult` kicks in
 
 ## Return value
+Returns the nth closest vehicle node with its heading favouring the desired direction.
diff --git a/PATHFIND/GetNthClosestVehicleNodeId.md b/PATHFIND/GetNthClosestVehicleNodeId.md
@@ -5,20 +5,17 @@ ns: PATHFIND
 
 ```c
 // 0x22D7275A79FE8215 0x3F358BEA
-int GET_NTH_CLOSEST_VEHICLE_NODE_ID(float x, float y, float z, int nth, int nodetype, float p5, float p6);
-```
-
-```
-Returns the id.  
+int GET_NTH_CLOSEST_VEHICLE_NODE_ID(float x, float y, float z, int nthClosest, int nodeFlags, float zMeasureMult, float zTolerance);
 ```
 
 ## Parameters
-* **x**: 
-* **y**: 
-* **z**: 
-* **nth**: 
-* **nodetype**: 
-* **p5**: 
-* **p6**: 
+* **x**: X coordinate
+* **y**: Y coordinate
+* **z**: Z coordinate
+* **nthClosest**: The index of the node to return
+* **nodeFlags**: Node flags, see [`GET_CLOSEST_VEHICLE_NODE`](#_0x240A18690AE96513)
+* **zMeasureMult**: How strongly the difference in the Z direction should be weighted
+* **zTolerance**: How far apart the Z coords have to be before `zMeasureMult` kicks in
 
 ## Return value
+Returns the nth closest vehicle nodes id.
diff --git a/PATHFIND/GetNthClosestVehicleNodeIdWithHeading.md b/PATHFIND/GetNthClosestVehicleNodeIdWithHeading.md
@@ -5,19 +5,19 @@ ns: PATHFIND
 
 ```c
 // 0x6448050E9C2A7207 0xC1AEB88D
-int GET_NTH_CLOSEST_VEHICLE_NODE_ID_WITH_HEADING(float x, float y, float z, int nthClosest, Vector3* outPosition, cs_type(float) float* outHeading, Any p6, float p7, float p8);
+int GET_NTH_CLOSEST_VEHICLE_NODE_ID_WITH_HEADING(float x, float y, float z, int nthClosest, Vector3* outPosition, cs_type(float) float* outHeading, int nodeFlags, float zMeasureMult, float zTolerance);
 ```
 
-
 ## Parameters
-* **x**: 
-* **y**: 
-* **z**: 
-* **nthClosest**: 
-* **outPosition**: 
-* **outHeading**: 
-* **p6**: 
-* **p7**: 
-* **p8**: 
+* **x**: X coordinate
+* **y**: Y coordinate
+* **z**: Z coordinate
+* **nthClosest**: The index of the node to return
+* **outPosition**: Pointer to the found nodes coords
+* **outHeading**: Pointer to the found nodes heading
+* **nodeFlags**: Node flags, see [`GET_CLOSEST_VEHICLE_NODE`](#_0x240A18690AE96513)
+* **zMeasureMult**: How strongly the difference in the Z direction should be weighted
+* **zTolerance**: How far apart the Z coords have to be before `zMeasureMult` kicks in
 
 ## Return value
+Returns the nth closest vehicle nodes id with its heading.
diff --git a/PATHFIND/GetNthClosestVehicleNodeWithHeading.md b/PATHFIND/GetNthClosestVehicleNodeWithHeading.md
@@ -5,34 +5,22 @@ ns: PATHFIND
 
 ```c
 // 0x80CA6A8B6C094CC4 0x7349C856
-BOOL GET_NTH_CLOSEST_VEHICLE_NODE_WITH_HEADING(float x, float y, float z, int nthClosest, Vector3* outPosition, float* heading, int* totalLanes, int searchFlags, float zMeasureMult, float zTolerance);
+BOOL GET_NTH_CLOSEST_VEHICLE_NODE_WITH_HEADING(float x, float y, float z, int nthClosest, Vector3* outPosition, float* outHeading, int* totalLanes, int nodeFlags, float zMeasureMult, float zTolerance);
 ```
 
-Get the nth closest vehicle node with its heading and total lane count.
-If you need specific forward and backward lane counts use [GET_CLOSEST_ROAD](#_0x132F52BBA570FE92)
-
-```c
-enum eNodeFlags {
-	NONE = 0,
-	INCLUDE_SWITCHED_OFF_NODES = 1,
-	INCLUDE_BOAT_NODES = 2,
-	IGNORE_SLIPLANES = 4,
-	IGNORE_SWITCHED_OFF_DEAD_ENDS = 8,
-}
-```
+Get the nth closest vehicle node with its heading and total lane count. If you need specific forward and backward lane counts use [`GET_CLOSEST_ROAD`](#_0x132F52BBA570FE92).
 
 ## Parameters
-* **x**: x position 
-* **y**: y position
-* **z**: z position
-* **nthClosest**: nth closest node
-* **outPosition**: returned position of the found node
-* **heading**: returned heading of the found node
-* **totalLanes**: total lanes (forward + backward) of the found node
-* **searchFlags**: Flags used when searching for a node, see `eNodeFlags`
-* **zMeasureMult**: How strongly the difference in z direction should be weighted (defaults to 3.0)
-* **zTolerance**: How far apart the Z coords have to be before the zMeasureMult kicks in
-
+* **x**: X coordinate
+* **y**: Y coordinate
+* **z**: Z coordinate
+* **nthClosest**: The index of the node to return
+* **outPosition**: Pointer to the found nodes coords
+* **outHeading**: Pointer to the found nodes heading
+* **totalLanes**: Pointer to the total lanes (forward + backward) of the found node
+* **nodeFlags**: Node flags, see [`GET_CLOSEST_VEHICLE_NODE`](#_0x240A18690AE96513)
+* **zMeasureMult**: How strongly the difference in the Z direction should be weighted
+* **zTolerance**: How far apart the Z coords have to be before `zMeasureMult` kicks in
 
 ## Return value
 Returns `true` if the node was found, or `false` if the node was not found, or was not streamed in.