roblox-npcs — скилл для Claude Code: навигация и поведение NPC в Roblox
Скилл roblox-npcs для Claude Code создаёт и отлаживает навигацию NPC в Roblox через PathfindingService. Настраивает патрулирование, преследование и обход препятствий.
MIT 518 установок ★ 36 обновлён 2026-10-22
npx skills add nonlooped/roblox-suite --skill roblox-npcs -a claude-codeЧто делает roblox-npcs
Скилл учит агента работать с PathfindingService: вычислять маршруты по навигационной сетке, настраивать параметры агента (радиус, высоту, способность прыгать и лазать), обрабатывать модификаторы стоимости проходимости (PathfindingModifier, PathfindingLink). Внутри три Lua-скрипта: NPCPathFollower.lua следует по маршруту и перестраивает его при блокировке, PatrolBehavior.lua реализует машину состояний для патруля и погони, PathfindingUtility.lua даёт вспомогательные функции.
Агент знает про лимиты движка (дистанция прямой видимости ≤ 3000 стадов, бюджет вычислений ≈ 20000 узлов) и советует размазывать пересчёт маршрутов по времени, чтобы не нагружать сервер. Для streaming-миров скилл напомнит проверить workspace.PersistentLoaded перед вычислением пути на клиенте.
Требует понимания API Roblox — Humanoid, Path, Attachment — и серверной логики для авторитетного ИИ.
Какие задачи решает
- создать NPC, который патрулирует контрольные точки и перестраивает маршрут при блокировке
- настроить преследование игрока с проверкой прямой видимости и дистанции на сервере
- провести NPC через воду или телепорт с помощью
PathfindingLinkи кастомных меток - масштабировать количество активных NPC без просадки FPS: размазать пересчёт маршрутов
- отладить ошибки
ComputeAsync: агент застревает, маршрут строится в стену, игнорируются модификаторы
Примеры запросов агенту
- Создай NPC, который патрулирует три точки:
workspace.Waypoint1,Waypoint2,Waypoint3, и перестраивает маршрут, если путь блокирован. - Добавь в
PatrolBehavior.luaсостояние Chase: NPC преследует игрока, если дистанция меньше 50 стадов и есть прямая видимость. - Настрой
PathfindingModifierс меткойWaterи стоимостью 20 в таблицеCosts, чтобы NPC избегал воды.
Как установить roblox-npcs
1Через Skills CLI (Vercel)
npx skills add nonlooped/roblox-suite --skill roblox-npcs -a claude-code2Вручную: положить файлы
~/.claude/skills/roblox-npcs/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/roblox-npcs/
1Через Skills CLI (Vercel)
npx skills add nonlooped/roblox-suite --skill roblox-npcs -a codex2Вручную: положить файлы
.agents/skills/roblox-npcs/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add nonlooped/roblox-suite --skill roblox-npcs -a cursor2Вручную: положить файлы
.cursor/skills/roblox-npcs/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install nonlooped/roblox-suite roblox-npcs2Вручную: положить файлы
.github/skills/roblox-npcs/SKILL.md1Через Skills CLI (Vercel)
npx skills add nonlooped/roblox-suite --skill roblox-npcs -a gemini-cli2Командой платформы
gemini skills install https://github.com/nonlooped/roblox-suite --path roblox-npcsВручную: положить файлы
.devin/skills/roblox-npcs/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add nonlooped/roblox-suite --skill roblox-npcs -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о roblox-npcs
Как установить roblox-npcs в Claude Code?
Выполни npx skills add nonlooped/roblox-suite --skill roblox-npcs -a claude-code, скилл установится в ~/.claude/skills/roblox-npcs/SKILL.md.
Что делает скилл roblox-npcs?
Учит агента строить маршруты для NPC через PathfindingService, настраивать параметры агента, обрабатывать модификаторы стоимости и линки, реализовывать паттерны поведения (патруль, преследование, машина состояний).
Какие лимиты PathfindingService нужно учитывать?
Прямая видимость ≤ 3000 стадов, бюджет вычислений ≈ 20000 узлов, координата Y точки маршрута от −65536 до +65536. Скилл напоминает ставить Path.CalculationSecondsTimeout и размазывать пересчёт для многих агентов.
Исходный текст
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