A3D_ShowRouteForPlayer

Show a route on the radar and the map of a player as a line, which moves on as they go.

The line is made of gang zones sent straight to the client of the player. They are not gang zones of the server, so they take no memory or id there, only room among the 1024 gang zones the client shows. The line from the player to the end is whole when it takes no more than squares gang zones as wide as the line. Otherwise half of them draw the route ahead of the player without a gap, and the rest mark the way beyond as dots, down to a dot at the end. Only the gang zones that change are sent as the player goes.

A player is shown one route at a time. A route shown in place of another of the same colour and width keeps the gang zones of the way the two share, so a route found again from where the player strayed sends little. Show the new route before destroying the old one, or the line is sent whole again. A3D_OnRouteArrived, A3D_OnRouteLeft and A3D_OnRouteAdvanced tell the script that found the route when the player reaches its end, strays from it or moves along it.

native bool:A3D_ShowRouteForPlayer(
    playerid,
    Route:routeid,
    colour = 0x9966FFFF,
    Float:width = 8.0,
    squares = 128
);

Parameters

Parameter	Description	Default
playerid	Player to show the route to.
Route:routeid	Route to show.
colour	Colour of the line, as 0xRRGGBBAA.	0x9966FFFF
Float:width	Width of the line, in metres.	8.0
squares	Most gang zones the line may use, up to 512. With a width of 8 metres, 128 draw a whole line a kilometre long and 512 four kilometres long.	128

Returns

• true when the route is shown.
• false when the player or the route does not exist.

Remarks

Five times a second the component finds where the player is on the route and moves the line on: the part behind them goes, and more of the way ahead comes. Only the gang zones that change are sent, a few a second at the speed of a car.

The squares are width metres wide and stand that far apart along the route. When the rest of the route takes no more than squares of them, it is drawn whole, a kilometre with the default 128 at 8 metres. Otherwise half of them draw the way ahead without a gap and the rest mark the way beyond as dots, up to four widths big, down to a dot at the end, so the map of the pause menu shows the whole way.

A player sees one route at a time, from every script. Showing another route takes the place of the first. When both have the same colour and width, the gang zones of the way they share stay, so a route found again from where the player strayed sends only what changed. Show the new route before destroying the old one, since destroying a route that is shown hides its line. Gang zones show on the radar and the map, not in the world. Bots are never shown a route.

Example

Leads a player to the place they mark on the map.

public OnPlayerClickMap(playerid, Float:fX, Float:fY, Float:fZ) {
    new
        Float:x,
        Float:y,
        Float:z,
        Route:routeid,
        Route:shown = A3D_GetPlayerRoute(playerid)
    ;

    GetPlayerPos(playerid, x, y, z);
    routeid = A3D_FindRoute(x, y, z, fX, fY, fZ);

    if (routeid != INVALID_ROUTE_ID) {
        A3D_ShowRouteForPlayer(playerid, routeid, 0xFFCC00FF);
        A3D_DestroyRoute(shown);
    }

    return 1;
}

Related

• A3D_HideRouteForPlayer: Hide the route shown to a player.
• A3D_GetPlayerRoute: The route shown to a player.
• A3D_OnRouteArrived: A player reached the end of the route shown to them. The route stays on the map until it is hidden or destroyed.
• A3D_OnRouteLeft: A player strayed from the route shown to them.
• A3D_FindRoute: Find the best route between two points along the paths of the game.