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
npx skills add nonlooped/roblox-suite --skill roblox-npcs -a claude-codeWhat 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
PathfindingLinkand custom labels - scale active NPC count without dropping FPS by staggering path recomputation
- debug
ComputeAsyncerrors: agent gets stuck, paths lead into walls, modifiers are ignored
Example prompts for the agent
- Create an NPC that patrols
workspace.Waypoint1,Waypoint2, andWaypoint3, 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
PathfindingModifierwith labelWaterand cost 20 in theCoststable so NPCs avoid water.
How to install roblox-npcs
1Skills CLI (Vercel)
npx skills add nonlooped/roblox-suite --skill roblox-npcs -a claude-code2Manually: put the files in place
~/.claude/skills/roblox-npcs/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/roblox-npcs/
1Skills CLI (Vercel)
npx skills add nonlooped/roblox-suite --skill roblox-npcs -a codex2Manually: put the files in place
.agents/skills/roblox-npcs/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add nonlooped/roblox-suite --skill roblox-npcs -a cursor2Manually: put the files in place
.cursor/skills/roblox-npcs/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install nonlooped/roblox-suite roblox-npcs2Manually: put the files in place
.github/skills/roblox-npcs/SKILL.md1Skills CLI (Vercel)
npx skills add nonlooped/roblox-suite --skill roblox-npcs -a gemini-cli2Platform CLI
gemini skills install https://github.com/nonlooped/roblox-suite --path roblox-npcsManually: put the files in place
.devin/skills/roblox-npcs/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add nonlooped/roblox-suite --skill roblox-npcs -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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