PathfindingService

Show Deprecated
Not Creatable
Service
Not Replicated

PathfindingService is used to find paths between two points. These paths make sure that characters can move between the points without running into walls or other obstacles. Paths can be used for both player-controlled characters and non-player characters.

This service has one function, CreatePath(), which creates a Path object based on various parameters.

Navigation Mesh

PathfindingService generates a "navigation mesh" over all parts in a place while the game is running. Any path that is created with the service will stay within the mesh. If the geometry of the place changes — for example, if a part is created or a part moves — the navigation mesh will be recalculated.

To see the navigation mesh for a place:

  1. Open the place in Studio.
  2. Navigate to FileSettings....
  3. In the Studio tab, under Visualization, toggle on the Show Navigation Mesh setting. The mesh will then show up in the 3D view.

The purple areas show where a character can walk, while the non-colored areas are considered blocked. Studio also displays arrows on top of the mesh which show where a character would have to jump to reach one part of the mesh from another.

Summary

Properties

Events

Methods

CreatePath(agentParameters: table): Instance  


FindPathAsync(start: Vector3, finish: Vector3): Instance  YIELDS

Finds a Path between the two provided points.

Properties

Events

Methods

CreatePath

Creates a Path object based on various agent parameters (see below).

Agent parameters

KeyTypeDefaultDescription
AgentRadiusinteger2Determines the minimum amount of horizontal space required for empty space to be considered traversable.
AgentHeightinteger5Determines the minimum amount of vertical space required for empty space to be considered traversable.
AgentCanJumpbooleantrueDetermines whether jumping during pathfinding is allowed.
AgentCanClimbbooleanfalseDetermines whether climbing `Class.TrussPart|TrussParts` during pathfinding is allowed.
WaypointSpacingnumber4Determines the spacing between intermediate waypoints in path.
Coststable{}Table of materials or defined PathfindingModifier|PathfindingModifiers and their "cost" for traversal. Useful for making the agent prefer certain materials/regions over others.

Pathfinding Costs

By default, all walkable (navmesh) areas have a pathfinding cost of 1.0 (jumps have a cost of 4.0), which is exactly how pathfinding worked before the introduction of PathfindingModifiers.

Since not all characters have the same movement abilities or constraints, it is desirable to provide a way to customize them. For example, a regular car always wants to avoid water, while an amphibian vehicle might not have such restriction.

To assign different pathfinding costs to different named areas/volumes and/or materials, for a particular AI character (including the player character in the Click to Move mode), just add an optional parameter Costs of type dictionary to CreatePath(.). It maps Pathfinding Modifier areas/volumes and materials to their pathfinding costs. For example:


1local path = PathfindingService:CreatePath{
2 AgentRadius = agentRadius,
3 AgentHeight = agentHeight,
4 AgentCanJump = agentCanJump,
5
6 -- New parameter --
7 Costs = {
8 Grass = 10
9 }
10}
11

Parameters

agentParameters: table

Lua table which lets you fine-tune the path for the size of the agent (the humanoid that will move along the path).

Default Value: "nil"

Returns

FindPathAsync

Yields

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

start: Vector3

Path start coordinates.

finish: Vector3

Path finish coordinates.


Returns

A Path object.