RouteConnector
From SA-MP Wiki
Documentation for Gamer_Z's RouteConnector Plugin.
Plugin Functions
Note | All the plugin source can be found in Route Connector Github page |
AddNode
Description:
Adds a node into the memory of the plugin, this node will be unavailable in route calculations.
(Float:X, Float:Y, Float:Z, AddToPathFinder, AddToScanner)
| Float:X | 3D coordinates from position X |
| Float:Y | 3D coordinates from position Y |
| Float:Z | 3D coordinates from position Z |
| AddToPathFinder | If set to 1 it will also make sure the graph will be updated so when searching for a route it will be added to the list |
| AddToScanner | If set to 1 the node will be available in OnPlayerClosestNodeIDChange, else not |
Return Values:
The added nodeID if sucess, or -1 if fail.
|
Note | NEVER set AddToPathFinder to 1 when a calculation is in progress! That is your own responsability if it happens! |
AddNodeEx
Description:
The only difference with AddNode is that you can specify your own NodeID here AND the node will be automaticly added to the appropriate area.
(ID, Float:X, Float:Y, Float:Z, AddToPathFinder, AddToScanner)
| ID | ID as Custom NodeID |
| Float:X | 3D coordinates from position X |
| Float:Y | 3D coordinates from position Y |
| Float:Z | 3D coordinates from position Z |
| AddToPathFinder | If set to 1 it will also make sure the graph will be updated so when searching for a route it will be added to the list |
| AddToScanner | If set to 1 the node will be available in OnPlayerClosestNodeIDChange, else not |
Return Values:
The added nodeID if sucess, or -1 if fail.
|
Note | NEVER set AddToPathFinder to 1 when a calculation is in progress! That is your own responsability if it happens! |
ConnectNodes
Description:
This will connect two nodes stored in memory, same rules as for AddNode(Ex), it won't be available in path calculations.
When you connect NodeID_one with NodeID_two it will automatically connect the opposite, no distance suplying is needed as the XYZ are supplied at node creation.
(NodeID_one, NodeID_two, AddToPathFinder, direction)
| NodeID_one | NodeID_one as NodeID |
| NodeID_two | NodeID_two as NodeID |
| AddToPathFinder | if set to 1 it will also make sure the graph will be updated so when searching for a route it will be added to the list |
| direction | you can choose to only connect nodeID one with nodeID two (1) or to connect them together (0) |
Return Values:
-1 - NodeOne is out of boundaries
-2 - NodeTwo is out of boundaries
-3 - NodeOne equals NodeTwo
-4 - NodeOne doesn't exist
-5 - NodeTwo doesn't exist
-6 - NodeOne already connected with NodeTwo
-7 - NodeTwo already connected with NodeOne
-8 - No more connection slots left or direction does not equal 1 or 0
Anything above or equal to 0 means success (the NodeOne[connectid] is retuned).
|
Note | NEVER set AddToPathFinder to 1 when a calculation is in progress! That is your own responsability if it happens! |
NearestPlayerNode
Description:
This function will get the closest player node, if you used AddNode(Ex) this nodes will also be considered.
(playerid, MaxDist, IgnoreNodeID, UseAreas)
| playerid | The playerid to count from |
| MaxDist | The maximal distance to search from the player |
| IgnoreNodeID | This node ID will not be returned as the closest one, it will be ignored in the search. |
| UseAreas | If set to 0 it will go through all nodes in memory, else if to 1 it will do just the nodes in the area where the player is (not so accurate). |
Return Values:
The closest nodeID, or -1 if no node Id is found in range.
NearestNodeFromPoint
Description:
Same as NearestPlayerNode, but here you can supply an point instead of an playerid.
(Float:X, Float:Y, Float:Z, MaxDist, IgnoreNodeID, UseAreas)
| Float:X | 3D coordinates from X |
| Float:Y | 3D coordinates from Y |
| Float:Z | 3D coordinates from Z |
| MaxDist | The maximal distance to search from the point |
| IgnoreNodeID | This node ID will not be returned as the closest one, it will be ignored in the search. |
| UseAreas | If set to 0 it will go through all nodes in memory, else if to 1 it will do just the nodes in the area where the player is (not so accurate). |
Return Values:
The closest nodeID from point, or -1 if no node Id is found in range.
WriteNodesToFile
Description:
Write all nodes, connections, contents of the memory into an loadable file, can be used by ReadNodesFromFile later.
(filename[])
| filename[] | The 'path/filename.extension' to store the information in, note that if you want to make a file in the scriptfiles folder you need to supply: WriteNodesToFile('path/filename.extension'); |
Return Values:
ReadNodesFromFile
Description:
Read all nodes, connections, contents of the file into the memory, this function will automaticly create nodes, connect them, create the virtual graph to search paths on after it has been loaded into the memory.
(filename[])
| filename[] | The 'path/filename.extension' to read the information from, note that if you want to read a file in the scriptfiles folder you need to supply: ReadNodesFromFile('scriptfiles/your.file.name'); |
GetNodePos
Description:
Get the XYZ position of the supplied NodeID.
(NodeID, &Float:X,&Float:Y,&Float:Z)
| NodeID | The The NodeID to get the position from |
| Float:X | The 3D coordinate X passed by reference |
| Float:Y | The 3D coordinate Y passed by reference |
| Float:Z | The 3D coordinate Z passed by reference |
Return Values:
0 on failure (Out Of Range?), -1 if node doesn't exist, 1 on success.
CalculatePath
Description:
Calculates the path between two nodes, this is one of the most importtants plugin's functions.
Parameters:(Start, End, RouteID, bool:CreatePolygon, PolygonWidth, bool:GrabNodePositions)
| Start | The start NodeID |
| End | The destination NodeID |
| RouteID | (optional) Here you can specify an integer value that will be passed to the callback, Along with the calculated path information, for example the PlayerID |
| CreatePolygon | Creates a polygon around the path if set to true |
| PolygonWidth | The width from the node lines to the edge of the polygon |
| bool:GrabNodePositions | If true, make sure that NodePos array is filled with usefull information. |
Return Values:
Always 1.
|
Note | Please note that this can increase the needed stack size extremely.
For storing the nodes, a polygon and all positions you need:
amount_of_nodes*4096*8+4096 bytes. The max amount of nodes I ever calculated wasn't higher than 1000. so:
3280896 bytes would be needed for the stack. Make sure to use
#pragma dynamic 4194304 //2^21 < 32772096 < 2^22, so we choose 2^22 bytes, this is 4MB of memory, so look out!
Also make sure you know how much heap you will need (global variables etc) and add this amount to the calculated value and round up to nearest power of two
Note:
if you will be using the routeID parameter for recognizing routes, make sure they all are unique,
once started route search cannot be aborted and will just be queued and the callback will still be called.
This function is Threaded, this means that if the CalculatePath search takes 3 seconds, it won't lagg your server.
Your server will continue to work normally.
Only the callback in the script which calls the plugin will get executed with this, if you do CalculatePath in Script1,
and have your callback in Script2 then it won't get executed, however if you need that, make in script1 CallRemoteFunction in the callback to call the other script.
|
IsNodeIntersection
Description:
This function checks if a node has 3 or more connections.
( NodeID)
| NodeID | The NodeID to check |
Return Values:
1 if true, 0 if false, -1 if node doesn't exists
GetAngleBetweenNodes
Description:
Gets the angle between 3 nodes (2 connections/lines).
( NodeID_one, NodeID_two, NodeID_three)
| NodeID_one | The first node ID |
| NodeID_two | The second node ID |
| NodeID_three | The third node ID |
Return Values:
0.0 if one of the three nodes doesn't exists
GetConnectedNodes
Description:
Get the amount of other nodes that are connected to this node, max is 5.
( NodeID)
| NodeID | The NodeID to get connected nodes. |
Return Values:
amount of nodes connected (0 to 5), on failure -1.
GetNextEmptyNodeID
Description:
Get the closest empty node ID (closest starting from 0 to up).
( NodeID)
| NodeID | The NodeID to get closest empty nodes. |
Example: new id = GetNextEmptyNodeID(); if(id != -1)AddNodeEx(id,X,Y,Z); //However this example results in: AddNode(X,Y,Z);
Return Values:
-1 if no more available node slots.
GetQueueSize
Description:
Gets the size of all queued path calculations to do.
(This function has no parameters)
Return Values:
Older versions: -1 if the vector was locked when tried to access (Threading crash prevention), else it returns the vector size. Update R181: always 0
GetConnectedNodeID
Description:
Gets the ID of an connection to NodeID, -1 if ConnectID has no connection, connectid must be between 0 and (MAX_CONNECTIONS-1), however there is OFB prevention check.
( NodeID, ConnectID)
| NodeID | The NodeID to get connected nodes. |
| NodeID | The Connected NodeID variable passed by reference. |
Return Values:
-1 if ConnectID has no connection
Float:GetConnectedNodeDistance
Description:
This function retrieves the distance between two connected Nodes.
( NodeID, ConnectID)
| NodeID | The first connected NodeID. |
| ConnectID | The second connected NodeID. |
Return Values:
the distance (in float) of the two connected nodes
Float:GetDistanceBetweenNodes
Description:
Gets the distance between the two nodes (NOT VIA OTHER NODES, THIS JUST DOES THE X Y Z POSITION CALCULATION).
Parameters:( NodeID_one, NodeID_two)
| NodeID_one | The first node ID |
| NodeID_two | The second node ID |
Return Values:
the distance (in float) of the two nodes
IsNodeInPathFinder
Description:
Checks if NodeID is added to the routecalculator.
Parameters:( NodeID)
| NodeID | The NodeID to check |
Return Values:
-1 if the NodeID is invalid and 0 if node is not in the route calculator, 1 if yes.
GetRouteArray
Description:
Stores an saved array with assigned ID to destination.
Parameters:( ID, destination[], size)
| ID | The ID of Route Array |
| destination | The destination which data will be stored in |
| size | The size of destination |
Return Values:
The amount of nodes in array at ID, Returns 0 if array is empty or ID doesn't exist..
GetRouteAtPos
|
Note | Optionally you can specify an variable to store the amount of nodes in it. |
Description:
Retrieves the NodeID in array[array_pos] at ID.
Parameters:(ID, array_pos, &amount_of_nodes)
| ID | The ID of Route |
| array_pos | The position of node in Route Array |
| amount_of_nodes | (optional)The size of destination by default |
Return Values:
The NodeID in array[Array_Pos] at ID.
StoreRouteArray
|
Note | Hint: Optionally you can use the returned ID in GetRouteArray or DeleteArray. |
Description:
Stores an array to the plugins vector memory.
Parameters:(amount_of_nodes, array[])
| amount_of_nodes | The amount of Nodes which will be stored |
| array | The array which will be stored in plugin's vector memory |
Return Values:
Route Array ID.
DeleteArray
|
Note | Hint: Optionally you can use the returned ID in GetRouteArray or DeleteArray. |
Description:
Remove contents of the memory at specified ID.
Parameters:(ID)
| ID | The array ID which content will be removed. |
Return Values:
This function doesn't return any value
AddExistingNodeToPathFinder
Description:
Adds an created node to the routecalculator.
Parameters:(NodeID)
| NodeID | The node to be added in routecalculator |
Return Values:
-1 if the NodeID is invalid and 0 if node id does not exist or is already added, 1 on success.
RemoveNode
Description:
Deletes an node from the memory, to use in Write data, nodes loaded into the calculator won't be deleted, connections too.
Parameters:(NodeID)
| NodeID | The node to be deleted |
Return Values:
Returns -1 if the NodeID is invalid and 0 if node id does not exist, 1 on success.
DisconnectNodeFromNode
Description:
Disconnects Node ID One from Two, please see RemoveNode for information about the calculator memory.
Parameters:(NodeID_One, NodeID_Two)
| NodeID_One | The first NodeID |
| NodeID_Two | The second NodeID |
Return Values:
-1 if the NodeID is invalid and 0 if node id does not exist, 1 on success.
DisconnectAllFromNode
Description:
Disconnects all other nodes from NodeID, and NodeID from them.
Parameters:(NodeID)
| NodeID | The NodeID which will be disconnected |
Return Values:
-1 if the NodeID is invalid and 0 if node id does not exist, 1 on success.
DeleteNodeSystemAtNode
Description:
Get ALL nodeIDs that are CONNECTED IN ANY WAY, ALSO VIA OTHER NODES to NodeID into the array[]. Useful for deleting big-not-connected chunks of nodes.
Parameters:({{{1}}})
| NodeID | The NodeID which will be the deleted in the array |
| array[] | The array which the NodeSystem will be Deleted |
| size | The size of array by default |
Return Values:
0 on failure, the array size on success.
Plugin Callbacks
|
Note | This plugin only have 2 callbacks which are essentials to the functionality in any scripts! |
OnPlayerClosestNodeIDChange
Description:
This callback is called when a player's closest nodeID changes.
Parameters:( playerid, old_NodeID, new_NodeID)
| playerid | The player which node has changed |
| old_NodeID | The previous node id |
| new_NodeID | The new node id |
GPS_WhenRouteIsCalculated
Description:
This callback is called when a path finding calculation is done.
Parameters:(routeid,node_id_array[],amount_of_nodes,Float:distance, {...} )
| routeid | The id of calculated route |
| node_id_array[] | This array is up to 1792 cells long it is build from the following information: node_id_array[0] ... node_id_array[1791] - all points (Node ID's) on the route in following order: from start, to end |
| amount_of_nodes | This is the amount of nodes the total path is, is set to 0 when it's impossible to calculate the route. |
| Float:distance | The total distance all nodes take, rounded to an integer, is -1 if it's impossible to calculate the route. |
| Float:Polygon[] | The polygon around the path, only given if you specified it at calculatepath. |
| Float:Polygon_Size/2 | amount of points in polygon. |
| Float:NodePosX[] | The specified node coordinate X. |
| Float:NodePosY[] | The specified node coordinate Y. |
| Float:NodePosZ[] | The specified node coordinate Z. |
//Example of usage: public GPS_WhenRouteIsCalculated(...) { for(new i = 0; i < amount_of_nodes; ++i) { printf("Point(%d)=NodeID(%d),position(X;Y;Z):%f;%f;%f}", i,node_id_array[i:NodePosX[i],:NodePosY[i],:NodePosZ[i]); } return 1; }
