К основному содержанию
скилл CX Codex

roblox-npcs — скилл для Claude Code: навигация и поведение NPC в Roblox

Скилл roblox-npcs для Claude Code создаёт и отлаживает навигацию NPC в Roblox через PathfindingService. Настраивает патрулирование, преследование и обход препятствий.

MIT 518 установок ★ 36 обновлён 2026-10-22

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add nonlooped/roblox-suite --skill roblox-npcs -a claude-code
Открыть на GitHub

Что делает 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-code

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/roblox-npcs/

По шагам, с командами для каждой платформы: Как установить скилл в 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

Похожие скиллы

Все скиллы по теме «Геймдев и 3D: Unity, Unreal, Godot, Blender» →
roblox-npc-ai EL4CTEO Скилл roblox-npc-ai для Claude Code помогает создавать ИИ врагов, питомцев и других NPC в Roblox. Используется для настройки поиска пути, преследования, атак и поведения персонажей, а также для исправления застревающих NPC. CX Codex +1 1 200установок scenario-roblox-gameplay scenario-labs Скилл scenario-roblox-gameplay для Claude Code помогает собирать игровые системы Roblox: ИИ NPC, боевые механики, снаряды и транспорт. Включается при разработке логики геймплея и разборе проблем с путями NPC, хитбоксами или физикой машин. CX Codex +1 357установок roblox-ui gamedev-skills Скилл roblox-ui для Claude Code помогает проектировать интерфейсы Roblox с учётом экранов телефонов и геймпадов. CX Codex +1 9 900установок roblox-characters gamedev-skills Скилл roblox-characters для Claude Code помогает чинить скрипты персонажей Roblox, их анимации и управление движением. Активируется при сбоях после возрождения, проблемах с репликацией или конфликте спринта с Humanoid. CX Codex +1 9 300установок roblox-animation-vfx TabooHarmony Скилл roblox-animation-vfx для ИИ-агента, который помогает писать и чинить анимации, партиклы, лучи, трейлы и твины в Roblox. CX Codex +1 4 200установок roblox-monetization TabooHarmony Скилл roblox-monetization для Claude Code: работа с покупками в Roblox (Game Passes, Developer Products, подписки, приватные серверы). Помогает отследить, почему покупка не выдала предмет. CX Codex +1 3 400установок

Из того же набора16

Весь набор →
roblox-gamepasses Скилл roblox-gamepasses помогает агенту собрать монетизацию в Roblox: пассы, developer products, подписки и переводы Robux — с выдачей бонусов только на сервере. CX Codex +1 547установок roblox-core Скилл roblox-core для Claude Code помогает выбирать сервисы Roblox, места для скриптов и контексты выполнения. Он подключается к вопросам о типах Luau, сериализации, загрузке модулей и обмене данными между клиентом и сервером. CX Codex +1 546установок roblox-datastores Скилл roblox-datastores помогает реализовать и отладить сохранение данных игроков в Roblox: профили, OrderedDataStore для лидербордов, миграции и выбор между DataStore и MemoryStore. CX Codex +1 544установок roblox-audio Скилл roblox-audio помогает собирать и отлаживать аудиосистемы Roblox: от позиционного звука до преобразования речи. Пригодится при настройке аудиографа или миграции со старого Sound. CX Codex +1 522установок roblox-physics Скилл roblox-physics помогает собирать и отлаживать физику в Roblox: механизмы, транспорт, констрейнты и сетевое владение. CX Codex +1 521установок roblox-rojo Скилл roblox-rojo настраивает проекты Rojo 7 для синхронизации файлов с диска в Roblox Studio, генерации сборок и карт исходников. CX Codex +1 519установок roblox-teleport Скилл roblox-teleport переносит игроков Roblox между местами, серверами и зарезервированными серверами через TeleportAsync. Подскажет, как передать данные, обработать ошибки и настроить лобби. CX Codex +1 519установок roblox-open-cloud Справочник по REST API Roblox Open Cloud для внешней автоматизации, CI/CD и работы с Data Stores без запуска игры. CX Codex +1 497установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой