Path
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 Enum.PathStatus.Success. Otherwise the status will be Enum.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.
Methods
Returns an array of points in the path.
Checks if a path is blocked starting at a specific waypoint.
Computes a Path from a start position to an end position.
Events
Fires when the computed path becomes blocked.
Fires when a computed path that was blocked becomes unblocked.
Properties
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
The example below demonstrates how to create a Path and it's PathWaypoints using the PathService.
It tries to Path:ComputeAsync() a path between two Vector3 positions, from pathStart to pathEnd. If a path is successfully created, indicated by it's Enum.PathStatus, the code block gets an array of its waypoints using Path:GetWaypoints(). Then, it loops through the array and prints each waypoint's position.
local PathfindingService = game:GetService("PathfindingService")
local path = PathfindingService:CreatePath()
local PATH_START = Vector3.new(0, 1, 0)
local PATH_END = Vector3.new(100, 1, 25)
path:ComputeAsync(PATH_START, PATH_END)
if path.Status == Enum.PathStatus.Success then
local waypoints = path:GetWaypoints()
for _, waypoint in pairs(waypoints) do
print(waypoint.Position)
end
endCheckOcclusionAsync
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
Returns
ComputeAsync
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
The world position where the computed path begins.
The world position where the computed path finishes.
Returns
Code Samples
The code sample below explores how to move an NPC along a more complex path or around obstacles. This is known as pathfinding.
local PathfindingService = game:GetService("PathfindingService")
local agentParams = {
AgentRadius = 2.0,
AgentHeight = 5.0,
AgentCanJump = false,
}
local currentWaypointIdx = 1
local path = PathfindingService:CreatePath(agentParams)
local humanoidRootPart = script.Parent:FindFirstChild("HumanoidRootPart")
local targetPosition = Vector3.new(50, 0, 50)
path:ComputeAsync(humanoidRootPart.Position, targetPosition)
-- When the path is blocked...
local function OnPathBlocked(blockedWaypointIdx)
-- Check if the obstacle is further down the path
if blockedWaypointIdx > currentWaypointIdx then
-- Recompute the path
path:ComputeAsync(humanoidRootPart.Position, targetPosition)
if path.Status == Enum.PathStatus.Success then
-- Retrieve update waypoint list with path:GetWaypoints()
-- and Continue walking towards target
else
-- Error, path not found
end
end
end
path.Blocked:Connect(OnPathBlocked)Events
Blocked
Fires when the computed path becomes blocked. Note that paths may become blocked somewhere behind the agent, such as a pile of rubble falling on a path as the agent runs away. See Handling Blocked Paths for details on checking the forward waypoint progress of an agent along a path.
Parameters
Unblocked
Fires when a computed path that was blocked becomes unblocked. Note that a blocked path may become unblocked somewhere behind the agent, effectively making reaction to this event unnecessary. See Handling Blocked Paths for details on checking the forward waypoint progress of an agent along a path.