Skip to main content
skill CX Codex

roblox-performance · el4cteo — Claude Code skill: what it does, how to install

roblox-performance — a skill for Claude Code that diagnoses Roblox game performance, detects memory leaks, and fixes frame rate drops. Used when games lag, stutter, drop FPS, or experience high ping.

MIT 1,300 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-performance -a claude-code
Open on GitHub

What roblox-performance does

Identifies bottlenecks in server computation, rendering, memory, and network using tools such as the MicroProfiler, Script Profiler, and Scene Analysis. Code can be annotated with debug.setmemorycategory and profiled using debug.profilebegin. It helps optimize Luau hot paths, configure Parallel Luau with Actors, and handle game.ServerLowMemoryWarning events on servers.

Targets 60 FPS on mid-range mobile devices while keeping client memory well below 1.5 GB to prevent out-of-memory crashes. Diagnostics rely on the Developer Console via F9, the MicroProfiler via Ctrl+Alt+F6, and live performance stats via Ctrl+Alt+F7.

Before optimizing hot code or during severe frame drops, measure metrics using the built-in profiling tools to identify exact memory and CPU costs.

What it helps with

  • detect memory leaks and unparented instances
  • fix client FPS drops and stuttering
  • optimize Luau hot paths and loops
  • inspect network replication costs
  • handle server low memory warnings

Example prompts for the agent

  • Diagnose frame rate drops and find heavy scripts
  • Find a memory leak in the Luau heap
  • Optimize the hot path using Parallel Luau

How to install roblox-performance

1Skills CLI (Vercel)

npx skills add EL4CTEO/roblox-skills --skill roblox-performance -a claude-code

2Manually: put the files in place

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

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

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

Questions about roblox-performance

How to install roblox-performance in Claude Code?

Run npx skills add EL4CTEO/roblox-skills --skill roblox-performance -a claude-code, then check ~/.claude/skills/roblox-performance/SKILL.md.

What does roblox-performance do?

It diagnoses and optimizes Roblox game performance, targeting memory leaks, lag spikes, low FPS, network issues, and Luau bottlenecks.

What built-in tools are supported for profiling?

The Developer Console, MicroProfiler, Script Profiler, Scene Analysis, Luau heap snapshots, and the Network Simulator.

Source text

SKILL.md · MIT
---
name: roblox-performance
description: Performance diagnosis and optimization - MicroProfiler, Script Profiler, Developer Console, Scene Analysis, Luau heap and memory categories, memory leaks, network/replication cost, rendering and physics cost, streaming, native codegen, Parallel Luau with Actors. Use when a game lags, stutters, drops FPS, crashes on mobile, has high ping, or before optimizing hot code.
---

# Roblox performance

**Measure before optimizing.** Identify whether the bottleneck is server compute, client compute
(CPU/GPU), memory, network, or load time, then use the matching tool.

## Tools

| Tool | Open | Use for |
| --- | --- | --- |
| Developer Console | F9 (in game) | Errors, server/client memory by category, network, script activity. Works in live servers. |
| MicroProfiler | Ctrl+Alt+F6 (⌘⌥F6); Dev Console for server | Per-frame timing; spikes; dump a frame for detail. |
| Script Profiler | Studio / Dev Console | Which functions consume Luau time (sampling). |
| Luau heap snapshots | Dev Console → Memory → Luau Heap | What tables/closures/instances are held and by what (leaks). |
| Scene Analysis | Studio | Script memory, unparented instances (leaks), instance composition, audio/animation memory, triangles. Also `SceneAnalysisService` via Studio MCP. |
| Performance Stats / Debug Stats | Ctrl+Alt+F7 / Shift+Ctrl+F1–F5 | Live CPU/GPU/memory/network overlays. |
| Network Simulator | Studio Device Simulator toolbar | Test with latency, jitter, packet loss (3G/4G/Wi-Fi profiles). |
| Performance dashboard | Creator Hub | Live aggregate FPS, server heartbeat, memory, crash rates by device. |

Label your own code in the MicroProfiler and memory views:

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

debug.setmemorycategory("EnemyAI") -- memory allocated by this thread is attributed to "EnemyAI"

RunService.Heartbeat:Connect(function(_deltaTime)
	debug.profilebegin("EnemyAI.think") -- shows as a labeled bar in the MicroProfiler
	-- ... work ...
	debug.profileend()
end)
```

## Targets

- Client: 60 FPS on mid-range phones (≈16.6 ms/frame); many players are on low-end Android.
- Server: heartbeat near 60 Hz; `Stats` (`workspace:GetRealPhysicsFPS()`, Dev Console Server Stats).
- Memory: mobile clients crash from OOM first. Keep client memory well under ~1–1.5 GB on low-end
  devices; watch `PlaceMemory`, `LuaHeap`, `GraphicsTexture`, `Sounds`, `Animation` categories.
- Server OOM: `game.ServerLowMemoryWarning` fires (server only, live servers and Team Test, not Studio
  playtests) when memory leaves normal levels, then every 60 s while it stays high. Use it to free memory
  fast (destroy debris/effects, pause spawning, unload empty map areas) and log it; it frees nothing itself.

```luau
--!strict
game.ServerLowMemoryWarning:Connect(function()
	warn("Server memory high: cleaning up")
	-- e.g. destroy temporary effects, pause NPC/item spawners until memory recovers
end)
```

## Most common problems → fixes

| Symptom | Usual cause | Fix |
| --- | --- | --- |
| Memory grows over time | Leaked connections, tables keyed by players/instances, destroyed-but-referenced instances, unparented instances | Disconnect/clean up per player & per character; clear tables on `PlayerRemoving`; use Scene Analysis "unparented instances" and heap snapshots. |
| Server lag with many players | Per-player loops each frame, `while true do task.wait() end` loops, heavy remote handlers, physics of many unanchored parts | Event-driven code, one scheduler loop, throttled think rates, anchor static parts, server-own fewer assemblies. |
| Client FPS drops | Too many parts/draw calls, shadows from many lights, transparency/particles overdraw, per-frame UI updates | Merge/instance meshes, `CastShadow = false` on small parts, fewer shadowed lights, limit particles, update UI on change only. |
| Spikes every N seconds | Autosave/GC bursts, synchronized loops across players, big `Clone()`s | Stagger with random offsets; pool objects; spread work across frames. |
| High ping / rubber banding | Remote spam, large payloads, replicating many property changes | Batch, delta-compress, throttle; tween on clients; see `roblox-networking`. |
| Long join times | Huge place, many unique assets, no streaming | Streaming, SLIM LOD, fewer unique meshes/textures, `ContentProvider:PreloadAsync` only for critical assets. |

## Luau hot paths

- Cache services, instances, and `RaycastParams` outside loops; avoid `FindFirstChild`/`GetDescendants`
  per frame. Replace `GetDescendants` scans with tags (`CollectionService`) or maintained sets.
- Use `deltaTime` from `Heartbeat`/`PreSimulation` rather than `task.wait()` loops for per-frame work.
- Avoid creating closures/tables per frame in hot loops; reuse buffers with `table.clear`.
- `--!native` (whole script) or `@native` (per function) for math-heavy code; typed parameters help
  the native compiler. Don't blanket-enable: compile time and a global native-code memory limit.
- `--!optimize 2` is how Roblox compiles live games already; don't rely on Studio timings for micro-benchmarks.

## Rendering and assets

- Parts: fewer, larger parts; `MeshPart`s with shared `MeshId` are instanced (cheap); unions (`PartOperation`)
  can be expensive — check triangle counts in Scene Analysis.
- `RenderFidelity = Automatic`/`Performance` for detailed meshes; `CollisionFidelity = Box`/`Hull` for
  decorative meshes; `CanCollide/CanQuery/CanTouch = false` for pure decoration.
- Lights: limit shadow-casting `PointLight`/`SpotLight`/`SurfaceLight`; limit `ParticleEmitter.Rate`
  and particle size (overdraw); `Beam`/`Trail` counts.
- Textures/images: reuse, keep resolutions reasonable (1024² max for most); `SurfaceAppearance` sparingly.
- Enable streaming (`roblox-architecture`), `Model.LevelOfDetail = SLIM` for static models, and let
  `StreamOutBehavior = Opportunistic` free memory.

## Physics

- Anchor everything that doesn't need to move. Welded decorative parts on moving assemblies add cost.
- Fewer, simpler collisions (`CollisionFidelity`, collision groups to skip pairs); `CanTouch = false`
  where `Touched` isn't needed.
- Avoid setting `CFrame` of unanchored parts every frame; use constraints or anchor + CFrame.
- `workspace:BulkMoveTo(parts, cframes, Enum.BulkMoveMode.FireCFrameChanged)` to move many anchored parts.
- Adaptive timestepping (`PhysicsSteppingMethod = Adaptive`) reduces physics CPU.

## Parallel Luau

Scripts under different `Actor` instances can run in parallel:

```luau
--!strict
-- Script parented under an Actor (one Actor per logical unit, e.g. per NPC group or chunk).
local RunService = game:GetService("RunService")

local results: { number } = {}

RunService.Heartbeat:ConnectParallel(function(_deltaTime)
	-- Parallel phase: read-only access to most instances, pure computation, thread-safe APIs (raycasts).
	for i = 1, 100 do
		results[i] = math.noise(i / 10, os.clock())
	end
	task.synchronize()
	-- Serial phase: write to instances, fire events, call thread-unsafe APIs.
end)
```

- `task.desynchronize()` / `task.synchronize()` switch phases; `ConnectParallel` starts in parallel.
- Scripts in the **same** Actor run serially relative to each other: split work across many Actors.
- Can't `require` or modify most instances while desynchronized. Communicate with `Actor:SendMessage` /
  `BindToMessageParallel` or `SharedTable` (`SharedTableRegistry`).
- Good fits: raycast validation, procedural generation, pathfinding-adjacent math, large simulations.
  Bad fits: tiny tasks (sync overhead), instance-heavy work.

Profiling walkthrough and memory-leak hunting: [references/profiling.md](references/profiling.md).

## Related skills

`roblox-architecture` (streaming), `roblox-networking` (bandwidth), `roblox-physics`, `roblox-npc-ai`,
`roblox-studio-mcp` (Roblox's `rbx-perf-profiling`/scene analysis via MCP).

© EL4CTEO · MIT · EL4CTEO/roblox-skills

Similar skills

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

roblox-performance by other authors comes first.

roblox-performance TabooHarmony roblox-performance is a skill for profiling Roblox games. It helps coding agents investigate frame drops, server lag, and memory leaks. CX Codex +1 3,600installs roblox-performance sentinelcore An agent skill for hunting down Roblox performance problems: frame drops, extra draw calls, heavy loops. CX Codex +1 911installs scenario-roblox-performance scenario-labs scenario-roblox-performance — a skill for Claude Code and Cursor that diagnoses performance issues, frame drops, memory leaks, and lag in Roblox games. CX Codex +1 363installs roblox-performance-audit LihFolk roblox-performance-audit is a Claude Code skill that diagnoses bottlenecks, memory leaks, and network overhead in Roblox experiences using measured profiles. CX Codex +1 ★ 98repo stars roblox-testing nonlooped roblox-testing is a Claude Code skill for debugging, profiling, and testing Roblox Studio projects with TestEZ, Luau type checking, and engine diagnostics. CX Codex +1 560installs roblox-datastores gamedev-skills A skill for Claude Code automates Roblox DataStoreService persistence, profile loading, and conflict prevention. Use it when player data goes missing or items duplicate after teleportation. CX Codex +1 11,400installs roblox-physics gamedev-skills Claude Code skill for Roblox physics and spatial queries, managing assemblies, constraints, and network ownership. CX Codex +1 9,100installs roblox-building TabooHarmony roblox-building — a skill for building geometry, maps and props in Roblox Studio through MCP or plain Luau. It keeps you from guessing coordinates and pushes each build to a verifiable result. CX Codex +1 4,200installs

From the same set22

The whole set →
roblox-world-building roblox-world-building — a skill for Claude Code and other platforms that automates world-building and 3D environment generation in Roblox. Invoked when creating maps, lighting effects, or procedural levels. CX Codex +1 1,400installs roblox-code-review The roblox-code-review Claude Code skill reviews Roblox code for security flaws, data loss, and lifecycle bugs. It runs for PR or script reviews, game audits, and legacy-code updates. CX Codex +1 1,300installs roblox-security roblox-security — a skill for Claude Code enforces server-authoritative security for Roblox experiences. Runs during reviews of remote event handlers, combat calculations, inventory transactions, and character physics. CX Codex +1 1,300installs roblox-characters-animation roblox-characters-animation — a Claude Code skill for Roblox characters and animation. It applies to work on movement, damage, respawns, avatars, weapons, and tweens. CX Codex +1 1,300installs roblox-game-systems roblox-game-systems — a skill for Claude Code and Codex providing server-authoritative Roblox gameplay recipes. Activates when building currencies, inventory, weapons, round loops, or progression. CX Codex +1 1,300installs roblox-luau The roblox-luau Claude Code skill supports writing and explaining Roblox scripts in Luau. It activates for script creation, refactoring, type-error fixes, and updates to older Lua code. CX Codex +1 1,300installs roblox-ui roblox-ui — a skill for Claude Code and Codex constructs responsive Roblox interfaces. Runs when building HUDs, inventories, storefronts, or fixing layouts across mobile devices and consoles. CX Codex +1 1,300installs roblox-testing The roblox-testing Claude Code skill covers testing Roblox code and checking gameplay changes. It applies when adding tests, configuring a runner, or setting up CI. CX Codex +1 1,300installs

Project sponsors

Companies that keep this analytics open