PathfindingService
PathfindingService is used to find logical paths between two points, ensuring that characters can move between the points without running into walls or other obstacles. By default, the shortest path is calculated, but you can implement pathfinding modifiers to compute smarter paths across various materials, around defined regions, or through obstacles.
See Character Pathfinding for usage details.
Summary
Properties
Sets the percent of a voxel has to be occupied to be considered empty. Defaults to 0.16.
Methods
Properties
EmptyCutoff
This function worked with the legacy pathfinding system. The pathfinding system currently uses a navigation grid and the EmptyCutoff is unused.
When the PathfindingService computes a path using PathfindingService:ComputeRawPathAsync() or PathfindingService:ComputeRawPathAsync() it uses the voxel representation of the world. A voxel is one cube in a grid overlaid on the world. In this case the voxels being used are 4x4x4. This property sets the percent of a voxel has to be occupied to be considered empty. Defaults to 0.16.
Methods
CreatePath
Creates a Path object based on various agent parameters. Valid keys and values in the agentParameters table are as follows:
| Key | Type | Default | Description |
|---|---|---|---|
| AgentRadius | integer | 2 | Determines the minimum amount of horizontal space required for empty space to be considered traversable. |
| AgentHeight | integer | 5 | Determines the minimum amount of vertical space required for empty space to be considered traversable. |
| AgentCanJump | boolean | true | Determines whether jumping during pathfinding is allowed. |
| AgentCanClimb | boolean | false | Determines whether climbing TrussParts during pathfinding is allowed. |
| WaypointSpacing | number | 4 | Determines the spacing between intermediate waypoints in path. |
| Costs | table | {} | Table of materials or defined PathfindingModifiers and their "cost" for traversal. Useful for making the agent prefer certain materials/regions over others. See here for details. |
Parameters
Luau table which lets you fine-tune the path for the size of the agent (the humanoid that will move along the path). See above for valid keys, types, and descriptions.
Returns
Code Samples
Demonstrates creating a path using PathfindingService:CreatePath()
'PathOptions' represents a Model with three paths made of different materials. When creating the path we define a large 'Cost' for two of the three paths materials. This will ensure the path created steers towards the path with the material of the lowest 'Cost'.
Once the path is created, small parts are created at each waypoint to visualize the path.
local Workspace = game:GetService("Workspace")
local PathfindingService = game:GetService("PathfindingService")
-- This model contains a start, end and three paths between the player can walk on: Snow, Metal and LeafyGrass
local PathOptionsModel = script.Parent.PathOptions
local startPosition = PathOptionsModel.Start.Position
local finishPosition = PathOptionsModel.End.Position
-- Create a path that avoids Snow and Metal materials
-- This will ensure the path created avoids the Snow and Metal paths and guides
-- the user towards the LeafyGrass path
local path = PathfindingService:CreatePath({
AgentRadius = 3,
AgentHeight = 6,
AgentCanJump = false,
Costs = {
Snow = math.huge,
Metal = math.huge,
},
})
-- Compute the path
local success, errorMessage = pcall(function()
path:ComputeAsync(startPosition, finishPosition)
end)
-- Confirm the computation was successful
if success and path.Status == Enum.PathStatus.Success then
-- For each waypoint, create a part to visualize the path
for _, waypoint in path:GetWaypoints() do
local part = Instance.new("Part")
part.Position = waypoint.Position
part.Size = Vector3.new(0.5, 0.5, 0.5)
part.Color = Color3.new(1, 0, 1)
part.Anchored = true
part.CanCollide = false
part.Parent = Workspace
end
else
print(`Path unable to be computed, error: {errorMessage}`)
end
ComputeRawPathAsync
This function computes and returns a Path between two Vector3s. If the given MaxDistance is greater than 512, an error will be thrown. (MaxDistance is too large).
Parameters
Returns
ComputeSmoothPathAsync
This function computes and returns a smooth Path between two Vector3s. This function fulfills the same purpose as PathfindingService:ComputeRawPathAsync(), but creates a much smoother path for an NPC to follow in comparison.
Parameters
Returns
FindPathAsync
This function is used to find a Path between two provided points. This path uses the navigation grid created by PathfindingService and makes sure that the path can be followed by a regular-sized Roblox character.
This function returns a Path object which contains the coordinates of the path. If no path is found between the two points, this function will still return a Path object, but that object's Path.Status will be Enum.PathStatus.NoPath.
To get the waypoints of a Path object, you can use the Path:GetWaypoints() function.
Parameters
Path start coordinates.
Path finish coordinates.