Skip to main content
skill CX Codex

roblox-npc-ai · el4cteo — Claude Code skill for Roblox NPC AI

The roblox-npc-ai Claude Code skill helps build AI for Roblox enemies, pets, and other NPCs. It covers pathfinding, chasing, attacks, and fixes for NPCs that get stuck or jitter.

MIT 1,200 installs ★ 131 updated 2026-11-03

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

What roblox-npc-ai does

The skill explains server-side NPC logic and pathfinding with PathfindingService. It covers idle, chase, attack, and return states, target visibility checks, path recalculation, and handling blocked routes. NPCs can move directly toward a target when they have a clear line of sight.

For larger NPC groups, it describes driving characters from a shared update loop instead of giving each one its own endless loop. It also covers spawning, reuse, and spreading work across updates. A path is limited to 3,000 studs from start to goal, with a 20,000-node search budget. Clients only pathfind against streamed-in geometry, so path calculations belong on the server.

What it helps with

  • set up Roblox NPC pathfinding across a map
  • make an enemy chase and attack a target
  • send an NPC back home when it leaves its area
  • debug NPCs that get stuck or jitter
  • coordinate updates for many NPCs

Example prompts for the agent

  • Build a Roblox enemy that finds, chases, and attacks players.
  • Set up a pet NPC that follows its owner and returns home.
  • Find why an NPC gets stuck and causes server lag.

How to install roblox-npc-ai

1Skills CLI (Vercel)

npx skills add EL4CTEO/roblox-skills --skill roblox-npc-ai -a claude-code

2Manually: put the files in place

~/.claude/skills/roblox-npc-ai/SKILL.md

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

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

Questions about roblox-npc-ai

How do I install roblox-npc-ai in Claude Code?

Run npx skills add EL4CTEO/roblox-skills --skill roblox-npc-ai -a claude-code. The skill file is at ~/.claude/skills/roblox-npc-ai/SKILL.md.

What does roblox-npc-ai do?

It guides an AI coding agent through Roblox NPC behavior, including pathfinding, pursuit, attacks, target perception, and state-based logic. It also covers handling larger NPC groups.

Where should Roblox NPC paths be computed?

On the server. Client pathfinding only sees geometry streamed to that client.

Source text

SKILL.md · MIT
---
name: roblox-npc-ai
description: NPCs and enemy AI - PathfindingService (CreatePath, ComputeAsync, costs, modifiers, links, blocked paths), chase/follow loops, state machines, perception and line of sight, spawning/pooling, scaling to many NPCs. Use when creating enemies, pets, followers, shopkeepers, wave spawners, or fixing NPCs that get stuck, jitter, or lag the server.
---

# NPCs and AI

## Architecture

- NPC **logic runs on the server** (authoritative targets, damage, drops). Visual extras (idle
  animations, nameplates, effects) can run on clients.
- One NPC service drives all NPCs from a single loop (e.g. 5–10 Hz "think" rate, staggered), not one
  script + `while true` per NPC. Tag NPC models (`CollectionService`) and keep per-NPC state in a table.
- Server-owned physics: `npc.PrimaryPart:SetNetworkOwner(nil)` after spawning, so NPCs don't stutter
  when ownership moves between nearby players (and exploiters can't push them).
- Use `Humanoid` for NPCs that need walking/jumping/climbing; for simple movers (turrets, floating
  enemies, crowds) use an `AnimationController` + `Animator` and move with constraints or CFrames.

## Pathfinding

```luau
--!strict
local PathfindingService = game:GetService("PathfindingService")

local path = PathfindingService:CreatePath({
	AgentRadius = 2,
	AgentHeight = 5,
	AgentCanJump = true,
	AgentCanClimb = false,
	WaypointSpacing = 4,
	Costs = {
		Water = 20, -- avoid water (Enum.Material name)
		DangerZone = math.huge, -- PathfindingModifier.Label: never cross
	},
})

-- Walk `humanoid` to `goal`. Returns true on arrival, false if unreachable or interrupted.
local function walkTo(humanoid: Humanoid, goal: Vector3): boolean
	local root = humanoid.RootPart
	if not root then
		return false
	end
	local ok = pcall(function()
		path:ComputeAsync(root.Position, goal)
	end)
	if not ok or path.Status ~= Enum.PathStatus.Success then
		return false -- NoPath: try a fallback (direct MoveTo, new goal, teleport if stuck long)
	end

	local waypoints = path:GetWaypoints()
	local blocked = false
	local blockedConnection = path.Blocked:Connect(function(blockedIndex)
		blocked = true -- an obstacle appeared on a waypoint ahead; caller recomputes
		print("path blocked at waypoint", blockedIndex)
	end)

	for index = 2, #waypoints do
		local waypoint = waypoints[index]
		if waypoint.Action == Enum.PathWaypointAction.Jump then
			humanoid.Jump = true
		end
		humanoid:MoveTo(waypoint.Position)
		local reached = humanoid.MoveToFinished:Wait() -- false after 8 s timeout
		if not reached or blocked or humanoid.Health <= 0 then
			blockedConnection:Disconnect()
			return false
		end
	end
	blockedConnection:Disconnect()
	return true
end

return walkTo
```

- `CreatePath` + `ComputeAsync` is the current API (`FindPathAsync` is superseded). Reuse `Path` objects
  per agent type; `ComputeAsync` yields — never call it every frame for every NPC.
- **Chasing moving targets**: recompute when the target moved more than a few studs since the last
  compute or every ~0.5–1 s, and skip pathfinding entirely when there's a clear line of sight
  (`workspace:Raycast` from NPC to target) — just `MoveTo` the target.
- `PathfindingModifier` (child of a part/region, `Label` matching a `Costs` key, `PassThrough` for doors)
  and `PathfindingLink` (between two attachments, e.g. ladders, teleporters, boats; the waypoint has
  `Label` and `Action = Custom`) shape paths.
- Limits: start→goal straight-line distance ≤ 3,000 studs, 20,000-node budget; far goals need
  intermediate targets. Visualize the navmesh with Studio's **Navigation Mesh** visualization option.
- On clients, pathfinding sees only streamed-in geometry: compute paths on the server.

## Behavior: state machine

```luau
--!strict
type State = "Idle" | "Chase" | "Attack" | "Return"

type Npc = {
	model: Model,
	humanoid: Humanoid,
	home: Vector3,
	state: State,
	target: Model?,
	lastAttack: number,
}

local AGGRO_RANGE = 40
local ATTACK_RANGE = 5
local LEASH_RANGE = 80
local ATTACK_COOLDOWN = 1.2

local losParams = RaycastParams.new()
losParams.FilterType = Enum.RaycastFilterType.Exclude

local function hasLineOfSight(from: Vector3, target: BasePart, ignore: { Instance }): boolean
	losParams.FilterDescendantsInstances = ignore
	local result = workspace:Raycast(from, target.Position - from, losParams)
	return result == nil or result.Instance:IsDescendantOf(target.Parent :: Instance)
end

local function think(npc: Npc, findTarget: (Vector3, number) -> Model?)
	local root = npc.humanoid.RootPart
	if not root or npc.humanoid.Health <= 0 then
		return
	end
	local targetRoot = npc.target and npc.target:FindFirstChild("HumanoidRootPart") :: BasePart?
	local distance = if targetRoot then (targetRoot.Position - root.Position).Magnitude else math.huge

	if npc.state == "Idle" then
		npc.target = findTarget(root.Position, AGGRO_RANGE)
		if npc.target then
			npc.state = "Chase"
		end
	elseif npc.state == "Chase" then
		if not targetRoot or (root.Position - npc.home).Magnitude > LEASH_RANGE then
			npc.state = "Return"
		elseif distance <= ATTACK_RANGE then
			npc.state = "Attack"
		elseif hasLineOfSight(root.Position, targetRoot, { npc.model }) then
			npc.humanoid:MoveTo(targetRoot.Position)
		end -- else: request a path (throttled) via walkTo in a separate thread
	elseif npc.state == "Attack" then
		if not targetRoot or distance > ATTACK_RANGE * 1.5 then
			npc.state = "Chase"
		elseif os.clock() - npc.lastAttack >= ATTACK_COOLDOWN then
			npc.lastAttack = os.clock()
			local targetHumanoid = npc.target and npc.target:FindFirstChildOfClass("Humanoid")
			if targetHumanoid then
				targetHumanoid:TakeDamage(10)
			end
		end
	elseif npc.state == "Return" then
		npc.target = nil
		npc.humanoid:MoveTo(npc.home)
		if (root.Position - npc.home).Magnitude < 4 then
			npc.state = "Idle"
		end
	end
end

return think
```

For complex AI (many behaviors, priorities), use a behavior tree or utility AI; keep the same "think
at a fixed rate, act through small primitives" structure. See [references/scaling-npcs.md](references/scaling-npcs.md)
for spawning, pooling, and performance with hundreds of NPCs.

## Perception tips

- Find targets with `workspace:GetPartBoundsInRadius` against a collision group/filter containing only
  characters, or iterate `Players:GetPlayers()` (cheaper for small counts) and compare squared distances.
- Add reaction delays and field-of-view checks (`root.CFrame.LookVector:Dot(direction.Unit) > 0.5`)
  so NPCs feel fair.
- Stagger thinking: `npcIndex % 5 == frame % 5` spreads work across frames.

## Related skills

`roblox-characters-animation` (humanoids, animation), `roblox-physics` (ownership, raycasts),
`roblox-performance` (profiling, parallel Luau), `roblox-game-systems` (waves, combat, drops).

© EL4CTEO · MIT · EL4CTEO/roblox-skills

Similar skills

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

roblox-npc-ai by other authors comes first.

roblox-npc-ai TabooHarmony roblox-npc-ai — a skill for Claude Code, Codex, Cursor, Copilot, Gemini CLI and OpenCode. Adds Roblox PathfindingService knowledge, NPC state machines, line-of-sight detection and server-side AI loops to the agent. CX Codex +1 3,400installs roblox-npcs nonlooped roblox-npcs — a skill for building and debugging NPC navigation in Roblox using PathfindingService. Use when you need patrol, chase, or obstacle avoidance logic. CX Codex +1 518installs scenario-roblox-gameplay scenario-labs The scenario-roblox-gameplay Claude Code skill covers Roblox gameplay systems, from NPC AI and combat to projectiles and vehicles. It activates for gameplay implementation and troubleshooting pathfinding, hit detection, or vehicle physics. CX Codex +1 357installs game-ai gamedev-skills The game-ai skill for Claude Code helps design and debug engine-neutral AI for enemies and NPCs. It triggers when you need to create or fix character behavior logic, perception, navigation, or steering. CX Codex +1 14,100installs godot-navigation-pathfinding thedivergentai godot-navigation-pathfinding teaches your AI assistant to handle path planning, crowd movement, and runtime navmesh generation in Godot. Prevents stuttering and silent bugs in RTS or stealth projects. CX Codex +1 499installs mm2-roblox-analytics-tracker reason-machines The mm2-roblox-analytics-tracker skill tracks Murder Mystery 2 inventory and gameplay metrics, then turns them into reports and dashboard views. Use it when you need structured collection or role analysis. CX Codex +1 2,300installs mm2-analytics-roblox-toolkit reason-machines mm2-analytics-roblox-toolkit — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that connects agents to a Murder Mystery 2 analytics dashboard. CX Codex +1 2,300installs

From the same set22

The whole set →
roblox-open-cloud This Claude Code skill covers Roblox Open Cloud APIs and HttpService. It applies to external tools, bots, CI/CD, and web requests from a game. CX Codex +1 1,200installs roblox-text-chat roblox-text-chat is a Claude Code and Cursor skill that configures TextChatService and text filtering in Roblox for adding chat, commands, or player-authored signs. CX Codex +1 1,200installs roblox-monetization This Claude Code skill covers Roblox monetization and purchase troubleshooting. It activates for work on shops, passes, subscriptions, rewarded ads, or paid random items. CX Codex +1 1,200installs roblox-physics The roblox-physics skill for Claude Code manages physics simulations and spatial queries. Use it when setting up raycasts, collisions, and vehicle mechanics. CX Codex +1 1,200installs roblox-teleport-matchmaking roblox-teleport-matchmaking — a skill for Claude Code handles player teleports and matchmaking flows in Roblox via TeleportService. CX Codex +1 1,200installs roblox-input roblox-input — a Claude Code skill for Roblox player controls and cameras. It comes into play when adding keybinds, abilities, vehicle controls, touch buttons, or a custom camera. CX Codex +1 1,200installs roblox-analytics-liveops roblox-analytics-liveops — a skill for Claude Code sets up game analytics, funnels, economy, and live ops for Roblox. Runs when instrumenting gameplay, economy tuning, or setting up A/B tests. CX Codex +1 1,200installs roblox-audio The roblox-audio Claude Code skill covers sound in Roblox, from music and effects to spatial audio. It activates for audio setup or when a sound fails to play. CX Codex +1 1,200installs

Project sponsors

Companies that keep this analytics open