Roblox PathfindingService: How to Make NPCs Navigate Your Map

[ice]

Roblox PathfindingService: How to Make NPCs Navigate Your Map

Pathfinding is the process of moving a character or object along a logical path around obstacles to reach a destination. In Roblox, PathfindingService handles the heavy lifting: it computes a path around walls, floors, and other geometry, then gives you a list of waypoints to follow. This guide covers the basics of setting up pathfinding for NPCs, handling blocked paths, and customizing the agent behavior.

Core Concepts

PathfindingService works by building a navigation mesh of your world. The mesh marks which areas are walkable, which require jumping, and which are blocked. When you ask for a path, the service computes the shortest route from a start point to a destination, then returns a table of waypoints. Each waypoint has a Position (Vector3) and an Action (PathWaypointAction) that tells you what the agent needs to do at that point.

Creating a Path

You start by calling PathfindingService:CreatePath() with a table of agent parameters:

Code: Select all

local PathfindingService = game:GetService("PathfindingService")

local path = PathfindingService:CreatePath({
    AgentRadius = 2,
    AgentHeight = 5,
    AgentCanJump = true,
    AgentCanClimb = false,
    Costs = {
        Water = 20
    }
})

The key parameters are:[2]

• AgentRadius (default 2): Minimum horizontal space required for a path to be considered traversable. Increase this for larger NPCs.
• AgentHeight (default 5): Minimum vertical space required. If the space under a platform is smaller than this value, the pathfinder treats it as non-traversable.
• AgentCanJump (default true): Whether the agent can jump during pathfinding. Set to false if your NPC cannot jump.
• AgentCanClimb (default false): Whether the agent can climb TrussParts. Enable this for NPCs that need to use ladders or climbable geometry.
• Costs (default {}): A table of material names or PathfindingModifier labels with numeric traversal costs. Higher costs make the pathfinder avoid those areas.

Computing and Following a Path

Once you have a Path object, call ComputeAsync() with a start position and a destination:

Code: Select all

local waypoints = path:GetWaypoints()

for _, waypoint in ipairs(waypoints) do
    npc.Humanoid:MoveTo(waypoint.Position)
    npc.Humanoid.MoveToFinished:Wait()

    if waypoint.Action == Enum.PathWaypointAction.Jump then
        npc.Humanoid.Jump = true
    end
end

ComputeAsync() returns a Path object with a Status property. Check that path.Status == Enum.PathStatus.Success before trying to use the waypoints. If the computation fails, the Status will be Enum.PathStatus.NoPath.[2]

Handling Blocked Paths

If a path becomes blocked while the NPC is moving (a door closes, a part falls, another player builds a wall), the Path.Blocked event fires. You can connect to it and recompute the path:

Code: Select all

path.Blocked:Connect(function(blockedWaypointIndex)
    if blockedWaypointIndex > currentWaypointIndex then
        path:ComputeAsync(npc.HumanoidRootPart.Position, destination)
        if path.Status == Enum.PathStatus.Success then
            waypoints = path:GetWaypoints()
            currentWaypointIndex = 1
        end
    end
end)

The blockedWaypointIndex parameter tells you which waypoint is blocked. If it is behind the NPC (already passed), you can ignore it. If it is ahead, recompute the path from the NPC's current position.[2]

Customizing with PathfindingModifier

PathfindingModifier lets you mark regions as preferred or avoided. Insert a PathfindingModifier into a part, set its Label to a meaningful name like "DangerZone", then add a matching key to the Costs table:

Code: Select all

local path = PathfindingService:CreatePath({
    AgentRadius = 2,
    AgentHeight = 5,
    Costs = {
        DangerZone = math.huge
    }
})
[/font]

Setting a cost to math.huge makes the pathfinder treat that region as non-traversable. Lower costs (like 2 or 5) make the pathfinder prefer or avoid those areas without fully blocking them.[2]

Limitations

[*]The maximum path distance is 3,000 studs. Longer paths will fail.
[*]The node budget is 20,000. Complex mazes or large open worlds can exhaust this before reaching the destination.
[*]If the agent parameters cannot be resolved (for example, AgentCanJump is false but the only path requires jumping), the computation fails.
[*]Pathfinding only works within a vertical boundary of -65,536 to 65,536 studs.[2]

Sources

[1] Pathfinding - Roblox Creator Hub Documentation
[2] PathfindingService - Roblox Creator Hub Reference