Skip to main content
skill CX Codex

roblox-npcs — Claude Code skill: NPC navigation and behavior in Roblox

roblox-npcs — a skill for building and debugging NPC navigation in Roblox using PathfindingService. Use when you need patrol, chase, or obstacle avoidance logic.

MIT 518 installs ★ 36 updated 2026-10-22

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add nonlooped/roblox-suite --skill roblox-npcs -a claude-code
Open on GitHub

What roblox-npcs does

The skill teaches the agent to work with PathfindingService: compute paths on the navigation mesh, configure agent parameters (radius, height, jump and climb capabilities), and handle cost modifiers (PathfindingModifier, PathfindingLink). It includes three Lua scripts: NPCPathFollower.lua follows waypoints and recomputes paths when blocked, PatrolBehavior.lua implements a state machine for patrol and chase, and PathfindingUtility.lua provides helper functions.

The agent knows engine limits (line-of-sight distance ≤ 3,000 studs, computation budget ≈ 20,000 nodes) and recommends staggering path recomputation to avoid server load. For streaming worlds, the skill reminds you to check workspace.PersistentLoaded before computing client-side paths.

Requires familiarity with Roblox APIs — Humanoid, Path, Attachment — and server-side logic for authoritative AI.

What it helps with

  • build an NPC that patrols waypoints and recomputes paths when blocked
  • set up player chase with server-side line-of-sight and distance checks
  • route NPCs through water or teleporters using PathfindingLink and custom labels
  • scale active NPC count without dropping FPS by staggering path recomputation
  • debug ComputeAsync errors: agent gets stuck, paths lead into walls, modifiers are ignored

Example prompts for the agent

  • Create an NPC that patrols workspace.Waypoint1, Waypoint2, and Waypoint3, recomputing the path if blocked.
  • Add a Chase state to PatrolBehavior.lua: NPC pursues the player if distance is under 50 studs and line-of-sight is clear.
  • Configure a PathfindingModifier with label Water and cost 20 in the Costs table so NPCs avoid water.

How to install roblox-npcs

1Skills CLI (Vercel)

npx skills add nonlooped/roblox-suite --skill roblox-npcs -a claude-code

2Manually: put the files in place

~/.claude/skills/roblox-npcs/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/roblox-npcs/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about roblox-npcs

How do I install roblox-npcs in Claude Code?

Run npx skills add nonlooped/roblox-suite --skill roblox-npcs -a claude-code and the skill installs to ~/.claude/skills/roblox-npcs/SKILL.md.

What does the roblox-npcs skill do?

It teaches the agent to compute paths for NPCs using PathfindingService, configure agent parameters, handle cost modifiers and links, and implement behavior patterns like patrol, chase, and state machines.

What PathfindingService limits should I know?

Line-of-sight distance ≤ 3,000 studs, computation budget ≈ 20,000 nodes, waypoint Y coordinate between −65,536 and +65,536 studs. The skill reminds you to set Path.CalculationSecondsTimeout and stagger recomputation for many agents.

Source text

SKILL.md · MIT
---
name: roblox-npcs
description: "Build or debug Roblox NPC navigation and behavior. Use for PathfindingService, modifiers and links, blocked paths, patrol or chase logic, streaming, and scaling NPC counts."
last_reviewed: 2026-06-17
---

# roblox-npcs

**Official sources:**
- https://create.roblox.com/docs/en-us/characters/pathfinding
- https://create.roblox.com/docs/en-us/workspace/streaming
- Engine classes: `PathfindingService`, `Path`, `PathWaypoint`, `PathfindingModifier`, `PathfindingLink`, `Humanoid`

Use PathfindingService for navigation on Roblox's navigation mesh. Build patrol, chase, and other behavior around its computed paths.

## PathfindingService basics

Create a path:

```lua
local PathfindingService = game:GetService("PathfindingService")

local path = PathfindingService:CreatePath({
    AgentRadius = 2,
    AgentHeight = 5,
    AgentCanJump = true,
    AgentCanClimb = false,
    WaypointSpacing = 4,
    Costs = {
        Water = 20,
        DangerZone = math.huge,
    }
})
path.CalculationSecondsTimeout = 1
```

Compute and follow:

```lua
local humanoid = character:WaitForChild("Humanoid")
local rootPart = character:WaitForChild("HumanoidRootPart")

local success, err = pcall(function()
    path:ComputeAsync(rootPart.Position, endPos)
end)

if success and path.Status == Enum.PathStatus.Success then
    local waypoints = path:GetWaypoints()
    -- follow waypoints with Humanoid:Move()
end
```

## Agent parameters

| Parameter | Default | Purpose |
| --- | --- | --- |
| `AgentRadius` | 2 studs | Minimum clearance from obstacles |
| `AgentHeight` | 5 studs | Vertical clearance |
| `AgentCanJump` | true | Allows jump waypoints |
| `AgentCanClimb` | false | Allows climbing truss parts |
| `WaypointSpacing` | 4 studs | Distance between intermediate waypoints |
| `Costs` | nil | Material/region/link traversal cost |

`Path.CalculationSecondsTimeout` limits how long the solver may run per `ComputeAsync` call. Set it after `CreatePath` and before computing.

## PathWaypoint actions

Each waypoint has a `Position` and an `Action`:
- `Enum.PathWaypointAction.Walk`: normal movement.
- `Enum.PathWaypointAction.Jump`: trigger jump.
- Custom labels like `"Climb"` or `"UseBoat"` from PathfindingModifiers/Links.

## Pathfinding modifiers

`PathfindingModifier` instances on anchored, non-colliding parts let you influence path cost:
- `Label`: key used in `Costs` table.
- `PassThrough`: if `true`, the volume is ignored by the navmesh and treated as traversable empty space (e.g., zombies "hearing" through doors).

Example:

```lua
local path = PathfindingService:CreatePath({
    Costs = {
        Water = 20,
        DangerZone = math.huge,
        UseBoat = 2,
    }
})
```

## Pathfinding links

`PathfindingLink` connects two `Attachment`s with a custom label and cost, allowing paths across normally untraversable gaps.

Use for:
- Boats across water
- Teleporters
- Ladders
- One-way jumps

Your movement code checks the waypoint label and runs the custom traversal logic.

## Movement patterns

### Follow

Continuously recompute a path to a moving target. Throttle recomputation (e.g., every 0.5–1 s) and only recompute if the target moved far enough.

### Patrol

Cycle through a list of fixed points. Recompute when blocked.

### Chase

Like follow, but validate line-of-sight and distance server-side. Don't trust client-reported positions for authoritative AI.

### State machine

Common NPC states: Idle, Patrol, Chase, Attack, Return. Each state handles its own path computation and Humanoid control.

## Streaming compatibility

- Server-side scripts have full world state and can compute paths to any part.
- Client-side scripts may fail if the destination has streamed out. Use `workspace.PersistentLoaded` and persistent models for client path destinations.
- Recompute paths when dynamic/streamed obstacles block the way.

## Limitations

- Direct line-of-sight distance ≤ 3,000 studs.
- Computation node budget ≈ 20,000 nodes.
- Waypoint Y coordinate must be between -65,536 and +65,536 studs.
- Incompatible parameters (e.g., `AgentCanJump = false` to a jump-only destination) will fail.

## Performance at scale

- Recompute paths on a staggered schedule, not every frame.
- Share target positions across similar NPCs when possible.
- Use `WaypointSpacing = math.huge` to reduce intermediate waypoints for long straight runs.
- Consider simplifying agent geometry or using fewer active agents.
- For very large worlds, split into regions or use local patrol paths.

## Common mistakes

- Computing paths every frame.
- Ignoring blocked-path events and letting NPCs walk into walls.
- Trusting client position for authoritative AI.
- Forgetting `pcall` around `ComputeAsync`.
- Using material names incorrectly in `Costs` (must match `Enum.Material` names as strings).

## Scripts

- `scripts/NPCPathFollower.lua`: Humanoid-based path follower with blocked-path recompute, custom-label support, and connection cleanup.
- `scripts/PatrolBehavior.lua`: state-driven patrol/chase behavior with spatial detection and throttled recomputation.
- `scripts/PathfindingUtility.lua`: helpers for throttled recomputation and waypoint formatting.

## Best practices

- Set `Path.CalculationSecondsTimeout` after `CreatePath` to cap solver time.
- Always set an explicit `Humanoid:MoveTo` timeout and cancel it when the waypoint is reached or the follower is stopped.
- Detect targets with spatial queries such as `workspace:GetPartBoundsInRadius` instead of scanning every player each frame.
- Stop path followers and clean up `Heartbeat` connections when the `Humanoid` dies or the NPC is destroyed.
- For respawning NPCs, create a new behavior instance for the new character model and `Destroy` the old one.
- Use `PathfindingLink` labels to trigger custom traversal logic (boats, teleporters, ladders). The follower invokes a registered handler; if none exists, the waypoint falls back to normal movement.
- To enable climbing, set `AgentCanClimb = true` and provide `TrussPart` surfaces. Climb waypoints have the `Label` `"Climb"`.
- `PathfindingModifier` parts must be `Anchored = true` and `CanCollide = false`.

## How to proceed

1. Define the agent's size and movement abilities.
2. Build the world with modifiers/links for special regions.
3. Implement a path-follower that handles waypoints, jumps, and blocked events.
4. Layer a state machine for complex behaviors.
5. Run on the server for authoritative AI; use client only for visual prediction.
6. Profile with MicroProfiler and stagger recomputation for many agents.

<!-- catalog:references:start -->
## Reference index

- [modifiers-links-and-streaming.md](references/modifiers-links-and-streaming.md): Route NPCs through special regions or handle streamed geometry.
- [npc-behavior-patterns.md](references/npc-behavior-patterns.md): Implement patrol, chase, combat, or state transitions.
- [pathfinding-service-details.md](references/pathfinding-service-details.md): Configure agents, compute paths, or handle blocked waypoints.
- [performance-and-scaling.md](references/performance-and-scaling.md): Reduce pathfinding and simulation cost as NPC counts grow.
<!-- catalog:references:end -->

© nonlooped · MIT · nonlooped/roblox-suite

Similar skills

All skills for Game dev and 3D: Unity, Unreal, Godot, Blender →

From the same set16

The whole set →
roblox-gamepasses roblox-gamepasses walks your agent through Roblox monetization: game passes, developer products, subscriptions and Robux transfers, with every benefit granted on the server. CX Codex +1 547installs roblox-core roblox-core is a Claude Code skill for choosing Roblox services, script locations, and execution contexts. It handles questions about Luau types, serialization, module loading, streaming, and client-server data. CX Codex +1 546installs roblox-datastores roblox-datastores is a Claude Code skill that implements and debugs persistent player data in Roblox, including concurrent writes, leaderboards, migrations, and storage choices. CX Codex +1 544installs roblox-audio This skill helps build and debug Roblox audio graphs, spatial sound, effects, and speech features. Use it when setting up playback or deciding whether to move from Sound to the audio graph. CX Codex +1 522installs roblox-physics roblox-physics guides agents on building and debugging Roblox assemblies, vehicles, mover constraints, and network ownership. CX Codex +1 521installs roblox-rojo roblox-rojo sets up Rojo 7 to sync local filesystem code with Roblox Studio, build place files, and export places back to disk. CX Codex +1 519installs roblox-teleport roblox-teleport moves Roblox players between places, public servers, and reserved servers using TeleportAsync. Shows how to pass data, handle failures, and set up lobby flows. CX Codex +1 519installs roblox-open-cloud Reference skill for Roblox Open Cloud REST API to handle external automation, CI/CD deployments, and Data Store operations. CX Codex +1 497installs

Project sponsors

Companies that keep this analytics open