A3D_FindRoute

Find the best route between two points along the paths of the game.

Each end goes to the nearest point of a path the route can use, within reach. Height counts twice, so a road on a bridge overhead is farther than a road beside. When the nearest paths do not connect, the ends go to the nearest paths of the main network instead. The route keeps its points and its turns until A3D_DestroyRoute, or until the script unloads.

A3D_ROUTE_FASTEST takes the least time and A3D_ROUTE_SHORTEST the least distance. A3D_ROUTE_ANY_WAY takes the least time driving one way streets both ways, as the emergency services do. A3D_ROUTE_TRAFFIC keeps to the roads the traffic of the game drives, which leaves out dirt roads, tracks and alleys. A3D_ROUTE_BOAT keeps to the lanes for boats, and A3D_ROUTE_WALK to the paths of pedestrians, or the roads where there are none. With the navigation mesh, a walk shorter than 500 metres goes the shortest way on the mesh, and a longer one walks on the mesh from its start to the paths and from the paths to its end.

native Route:A3D_FindRoute(
    Float:fromX,
    Float:fromY,
    Float:fromZ,
    Float:toX,
    Float:toY,
    Float:toZ,
    A3D_ROUTE:type = A3D_ROUTE_FASTEST,
    Float:heading = -1.0,
    Float:reach = 300.0
);

Parameters

Parameter	Description	Default
Float:fromX	Start on the X axis.
Float:fromY	Start on the Y axis.
Float:fromZ	Start on the Z axis.
Float:toX	End on the X axis.
Float:toY	End on the Y axis.
Float:toZ	End on the Z axis.
A3D_ROUTE:type	How the route weighs the paths.	A3D_ROUTE_FASTEST
Float:heading	Direction the vehicle faces at the start, as GetVehicleZAngle gives it, or -1.0 for none. Starting against it costs a turn back.	-1.0
Float:reach	How far from each end to look for a path, in metres.	300.0

Returns

• The route.
• INVALID_ROUTE_ID when no path is within reach, or the ends are not connected.

Remarks

The route is found at once, inside the native, in some tens of microseconds for a route across the map. There is no thread and no callback to wait for. In the first second after the server starts, while the contraction hierarchies are built, a route takes about a millisecond instead and comes out the same.

Each end goes to the nearest point of a road or a path, along the line between its nodes, so a route starts beside the player and ends beside the destination. The points of the route are those of the paths it follows, from where the start meets them to where the end meets them. A walk with the navigation mesh also walks from the start to the paths and from the paths to the end.

heading matters for a vehicle that is already moving. A car facing the wrong way turns back first, and the route says so with an A3D_TURN_BACK turn at its first point. See Turns.

The route belongs to the script that found it, and is destroyed when that script unloads. Each route keeps its points, so destroy the routes that are no longer needed.

Example

Leads a player to a place with a line on the radar, by road in a vehicle and on foot otherwise.

stock bool:LeadPlayer(playerid, Float:x, Float:y, Float:z) {
    new
        Float:fromX,
        Float:fromY,
        Float:fromZ,
        Float:heading = -1.0,
        vehicleid = GetPlayerVehicleID(playerid),
        Route:routeid,
        Route:shown = A3D_GetPlayerRoute(playerid)
    ;

    GetPlayerPos(playerid, fromX, fromY, fromZ);

    if (vehicleid != 0) {
        GetVehicleZAngle(vehicleid, heading);
    }

    routeid = A3D_FindRoute(fromX, fromY, fromZ, x, y, z, vehicleid != 0 ? A3D_ROUTE_FASTEST : A3D_ROUTE_WALK, heading);

    if (routeid == INVALID_ROUTE_ID) {
        return false;
    }

    A3D_ShowRouteForPlayer(playerid, routeid);
    A3D_DestroyRoute(shown);

    return true;
}

Related

• A3D_DestroyRoute: Destroy a route, and hide it from the players it is shown to.
• A3D_MeasureRoute: Measure the best route between two points without keeping it, which is faster than finding it.
• A3D_GetRoutePoints: Copy points of a route into three arrays.
• A3D_ShowRouteForPlayer: Show a route on the radar and the map of a player as a line, which moves on as they go.
• A3D_GetRouteProgress: Find where a point is along a route: the distance left, the distance from the route and the next turn.