Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.
PathfindingService
Inherits from: Instance → Object
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 Pathfinding for details on implementing character pathfinding.
Inherits from: Instance
Memory category: Instances
Tags: NotCreatable, Service, NotReplicated
Code samples: View on Creator Hub (using-the-pathfinding-service).
Properties
| Name | Type / Returns | Description |
|---|---|---|
| PathfindingService.EmptyCutoff | float | Sets the percent of a voxel has to be occupied to be considered empty. Defaults to 0.16. |
Inherited from Instance
| Name | Type / Returns | Description |
|---|---|---|
| Instance.Archivable | boolean | Determines if an Instance and its descendants can be cloned using Instance:Clone(), and can be saved/published. |
| Instance.archivable | boolean | |
| Instance.Capabilities | SecurityCapabilities | The set of capabilities allowed to be used for scripts inside this container. |
| Instance.IsInSandbox | boolean | Indicates whether the instance is inside a sandboxed container. |
| Instance.Name | string | A non-unique identifier of the Instance. |
| Instance.Parent | Instance | Determines the hierarchical parent of the Instance. |
| Instance.PredictionMode | PredictionMode | Reflects the client-side prediction mode applied to the instance under server-authoritative physics. |
| Instance.RobloxLocked | boolean | A deprecated property that used to protect CoreGui objects. |
| Instance.Sandboxed | boolean | When enabled, the instance can only access abilities in its Capabilities list. |
| Instance.UniqueId | UniqueId | A unique identifier for the instance. |
Inherited from Object
| Name | Type / Returns | Description |
|---|---|---|
| Object.ClassName | string | A read-only string representing the class this Object belongs to. |
| Object.className | string |
PathfindingService.EmptyCutoff
Deprecated. This property is deprecated, since the legacy pathfinding system using it has since been removed. Do not use it for new work.
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.
| Field | Value |
|---|---|
| type | float |
| tags | ["NotReplicated","Deprecated"] |
| security | {"read":"None","write":"None"} |
| thread safety | ReadSafe |
| category | Data |
| serialization | {"can_load":true,"can_save":false} |
| capabilities | ["Basic"] |
Methods
| Name | Type / Returns | Description |
|---|---|---|
| PathfindingService:ComputeRawPathAsync | Path | 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). |
| PathfindingService:ComputeSmoothPathAsync | Path | Computes and returns a smooth Path between two Vector3s. |
| PathfindingService:CreatePath | Path | Creates a Path object based on the given agent parameters. |
| PathfindingService:FindPathAsync | Path | Finds a Path between the two provided points. |
Inherited from Instance
| Name | Type / Returns | Description |
|---|---|---|
| Instance:AddTag | () | Applies a tag to the instance. |
| Instance:children | Instances | Returns an array of the object's children. |
| Instance:ClearAllChildren | () | This method destroys all of an instance's children. |
| Instance:Clone | Instance | Create a copy of an instance and all its descendants, ignoring instances that are not Archivable. |
| Instance:clone | Instance | |
| Instance:Destroy | () | Sets the Instance.Parent property to nil, locks the Instance.Parent property, disconnects all connections, and calls Destroy() on all children. |
| Instance:destroy | () | |
| Instance:FindFirstAncestor | Instance? | Returns the first ancestor of the Instance whose Instance.Name is equal to the given name. |
| Instance:FindFirstAncestorOfClass | Instance? | Returns the first ancestor of the Instance whose Object.ClassName is equal to the given className. |
| Instance:FindFirstAncestorWhichIsA | Instance? | Returns the first ancestor of the Instance for whom Object:IsA() returns true for the given className. |
| Instance:FindFirstChild | Instance? | Returns the first child of the Instance found with the given name. |
| Instance:findFirstChild | Instance | |
| Instance:FindFirstChildOfClass | Instance? | Returns the first child of the Instance whose ClassName is equal to the given class name. |
| Instance:FindFirstChildWhichIsA | Instance? | Returns the first child of the Instance for whom Object:IsA() returns true for the given className. |
| Instance:FindFirstDescendant | Instance? | Returns the first descendant found with the given Instance.Name. |
| Instance:GetActor | Actor? | Returns the Actor associated with the Instance, if any. |
| Instance:GetAttribute | Variant | Returns the value which has been assigned to the given attribute name. |
| Instance:GetAttributeChangedSignal | RBXScriptSignal | Returns an event that fires when the given attribute changes. |
| Instance:GetAttributes | Dictionary | Returns a dictionary of the instance's attributes. |
| Instance:GetChildren | Instances | Returns an array containing all of the instance's children. |
| Instance:getChildren | Instances | |
| Instance:GetDebugId | string | Returns a coded string of the debug ID used internally by Roblox. |
| Instance:GetDescendants | Instances | Returns an array containing all of the descendants of the instance. |
| Instance:GetFullName | string | Returns a string describing the instance's ancestry. |
| Instance:GetStyled | Variant | Returns the styled or explicitly modified value of the specified property, or else the default property value if it hasn't been styled/modified. |
| Instance:GetStyledPropertyChangedSignal | RBXScriptSignal | Returns an event that fires when the given style property changes on the instance. |
| Instance:GetTags | Array | Gets an array of all tags applied to the instance. |
| Instance:HasTag | boolean | Check whether the instance has a given tag. |
| Instance:IsAncestorOf | boolean | Returns true if an Instance is an ancestor of the given descendant. |
| Instance:IsDescendantOf | boolean | Returns true if an Instance is a descendant of the given ancestor. |
| Instance:isDescendantOf | boolean | |
| Instance:IsPropertyModified | boolean | Returns true if the value stored in the specified property is not equal to the code-instantiated default. |
| Instance:QueryDescendants | Instances | Returns an array containing all descendants of the instance that match the selector string. |
| Instance:Remove | () | Sets the object's Parent to nil, and does the same for all its descendants. |
| Instance:remove | () | |
| Instance:RemoveTag | () | Removes a tag from the instance. |
| Instance:ResetPropertyToDefault | () | Resets a property to its default value. |
| Instance:SetAttribute | () | Sets the attribute with the given name to the given value. |
| Instance:WaitForChild | Instance | Returns the child of the Instance with the given name. If the child does not exist, it will yield the current thread until it does. |
Inherited from Object
| Name | Type / Returns | Description |
|---|---|---|
| Object:GetPropertyChangedSignal | RBXScriptSignal | Get an event that fires when a given property of the object changes. |
| Object:IsA | boolean | Returns true if an object's class matches or inherits from a given class. |
| Object:isA | boolean |
PathfindingService:ComputeRawPathAsync
Deprecated. This item has been superseded by PathfindingService:FindPathAsync() which should be used in all new work instead.
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
| Name | Type | Default | Description |
|---|---|---|---|
| start | Vector3 | ||
| finish | Vector3 | ||
| maxDistance | float |
Returns
| Type | Description |
|---|---|
| Path | A Path object. |
| Field | Value |
|---|---|
| tags | ["Yields","Deprecated"] |
| security | None |
| thread safety | Unsafe |
| capabilities | ["Basic"] |
PathfindingService:ComputeSmoothPathAsync
Deprecated. This item has been superseded by PathfindingService:FindPathAsync() which should be used in all new work instead.
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
| Name | Type | Default | Description |
|---|---|---|---|
| start | Vector3 | ||
| finish | Vector3 | ||
| maxDistance | float |
Returns
| Type | Description |
|---|---|
| Path |
| Field | Value |
|---|---|
| tags | ["Yields","Deprecated"] |
| security | None |
| thread safety | Unsafe |
| capabilities | ["Basic"] |
PathfindingService: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 Class.TrussPart|TrussParts during pathfinding is allowed. |
WaypointSpacing | number | 4 | Determines the spacing between intermediate waypoints in path. |
Costs | table | {} | Table of materials or defined Class.PathfindingModifier|PathfindingModifiers and their "cost" for traversal. Useful for making the agent prefer certain materials/regions over others. |
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| agentParameters | Dictionary | nil | Lua table which lets you fine-tune the path based on various agent parameters. |
Returns
| Type | Description |
|---|---|
| Path | A Path object. |
| Field | Value |
|---|---|
| security | None |
| thread safety | Unsafe |
| capabilities | ["Basic"] |
Code samples: View on Creator Hub (pathfinding---creating-path-with-params).
PathfindingService:FindPathAsync
Deprecated. This function has been superseded by the sequential method of calling PathfindingService:CreatePath() followed by Path. This lets you create a Path object using various custom parameters and then compute or re-compute a path on the same object if any dynamic changes within the place block the path.
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 PathStatus.NoPath.
To get the waypoints of a Path object, you can use the Path:GetWaypoints() function.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| start | Vector3 | Path start coordinates. | |
| finish | Vector3 | Path finish coordinates. |
Returns
| Type | Description |
|---|---|
| Path | A Path object. |
| Field | Value |
|---|---|
| tags | ["Yields"] |
| security | None |
| thread safety | Unsafe |
| capabilities | ["Basic"] |
Events
Inherited from Instance
| Name | Type / Returns | Description |
|---|---|---|
| Instance.AncestryChanged | Fires when the Instance.Parent property of this object or one of its ancestors is changed. | |
| Instance.AttributeChanged | Fires whenever an attribute is changed on the Instance. | |
| Instance.ChildAdded | Fires after an object is parented to this Instance. | |
| Instance.childAdded | ||
| Instance.ChildRemoved | Fires after a child is removed from this Instance. | |
| Instance.DescendantAdded | Fires after a descendant is added to the Instance. | |
| Instance.DescendantRemoving | Fires immediately before a descendant of the Instance is removed. | |
| Instance.Destroying | Fires immediately before (or is deferred until after) the instance is destroyed via Instance:Destroy(). | |
| Instance.StyledPropertiesChanged | Fires whenever any style property is changed on the instance, including when a property is set to nil. |
Inherited from Object
| Name | Type / Returns | Description |
|---|---|---|
| Object.Changed | Fires immediately after a property of the object changes, with some limitations. |