Path

Show Deprecated
Not Creatable
Not Replicated

Path objects store the result of paths created by PathfindingService:CreatePath().

Once a path object is created, you can call Path:ComputeAsync() with a starting point and ending point. This will attempt to compute a valid path for a character to move along, based on default or custom parameters passed to CreatePath(). If ComputeAsync() successfully finds a path, the Path object will have a Path.Status value of PathStatus.Success. Otherwise the status will be PathStatus.NoPath which can occur if there are obstacles between the two points (and no way around) or if the points are inside of solid objects.

In addition to ComputeAsync(), Path objects have the GetWaypoints() method which returns a list of waypoints representing the points a character should follow in sequence to get from the beginning to the end of the path.

Finally, Path objects can be connected to the Path.Blocked event. This event will fire if, at any time during the path's existence, the path is blocked. Note that this can occur behind a character moving along the path, not just in front of it.

Summary

Properties

The success of the generated Path.

READ ONLY
NOT REPLICATED

Events

Blocked(blockedWaypointIdx: number): RBXScriptSignal  


Unblocked(unblockedWaypointIdx: number): RBXScriptSignal  


Methods


Returns an array of points in the path.

CheckOcclusionAsync(start: number): number  YIELDS

Checks if a path is blocked starting at a specific waypoint.

ComputeAsync(start: Vector3, finish: Vector3): void  YIELDS

Computes a Path from a start position to an end position.

Properties

Read Only
Not Replicated

The success of the generated Path.

Events

Blocked

Parameters

blockedWaypointIdx: number

Unblocked

Parameters

unblockedWaypointIdx: number

Methods

GetWaypoints

This function returns an array of all the PathWaypoints in a Path, as computed by Path:ComputeAsync().

Each waypoint in the array specifies a Vector3 position and action to take when this PathWaypoint is reached. The array is arranged in the order of waypoints from the path start to path end.

If a path could not be computed, this function will return an empty array.


Returns

An array of PathWaypoints ordered from path start to path end.

Code Samples

Get Path Waypoints

1local PathfindingService = game:GetService("PathfindingService")
2
3local path = PathfindingService:CreatePath()
4
5local PATH_START = Vector3.new(0, 1, 0)
6local PATH_END = Vector3.new(100, 1, 25)
7
8path:ComputeAsync(PATH_START, PATH_END)
9
10if path.Status == Enum.PathStatus.Success then
11 local waypoints = path:GetWaypoints()
12 for _, waypoint in pairs(waypoints) do
13 print(waypoint.Position)
14 end
15end

CheckOcclusionAsync

Yields

This function checks if a path is blocked starting at the waypoint indicated by start.

It returns the first waypoint of occlusion if blocked, -1 if not. it returns an error if start is less than 0 or greater than the number of waypoints in the Path.

Parameters

start: number

Returns

ComputeAsync

void
Yields

This function computes a Path from a start position to an end position. This function is not automatically called when a path is created and must be invoked each time the path needs to be updated.

Once the Path is computed, it will have a series of waypoints that, when followed, can lead a character along the path. These points are gathered with the Path:GetWaypoints() function.

Parameters

start: Vector3

The world position where the computed path begins.

finish: Vector3

The world position where the computed path finishes.


Returns

void

Code Samples

Using the Pathfinding Service

1local PathfindingService = game:GetService("PathfindingService")
2
3local agentParams = {
4 AgentRadius = 2.0,
5 AgentHeight = 5.0,
6 AgentCanJump = false,
7}
8local currentWaypointIdx = 1
9
10local path = PathfindingService:CreatePath(agentParams)
11
12local humanoidRootPart = script.Parent:FindFirstChild("HumanoidRootPart")
13local targetPosition = Vector3.new(50, 0, 50)
14path:ComputeAsync(humanoidRootPart.Position, targetPosition)
15
16-- When the path is blocked...
17local function OnPathBlocked(blockedWaypointIdx)
18 -- Check if the obstacle is further down the path
19 if blockedWaypointIdx > currentWaypointIdx then
20 -- Recompute the path
21 path:ComputeAsync(humanoidRootPart.Position, targetPosition)
22 if path.Status == Enum.PathStatus.Success then
23
24 -- Retrieve update waypoint list with path:GetWaypoints()
25 -- and Continue walking towards target
26 else
27 -- Error, path not found
28 end
29 end
30end
31
32path.Blocked:Connect(OnPathBlocked)