roblox-performance
Use when optimizing a Roblox game for better frame rates, reducing lag, improving server or client performance, diagnosing FPS drops, handling large worlds, or when asked about streaming, draw calls, object pooling, LOD, MicroProfiler, or expensive loop operations.
- Installs
- 831
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/sentinelcore/roblox-skills --skill roblox-performance- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads roblox-performance automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Roblox Performance Optimization
Quick Reference
| Technique | Impact | When to Use |
|---|---|---|
| StreamingEnabled | High | Large open worlds |
| Object pooling | High | Frequent spawn/destroy |
| Cache references outside loops | High | Heartbeat/RenderStepped |
task.wait() over wait() | Medium | All scripts |
| MeshParts over Unions | Medium | Many unique shapes |
| LOD (hide at distance) | Medium | Complex models |
| Anchor static parts | Medium | Reduce physics budget |
| Limit PointLights | High | Any scene with many lights |
StreamingEnabled
Enable for large worlds — engine sends only nearby parts to the client.
-- Studio: Workspace > StreamingEnabled = true
workspace.StreamingEnabled = true
workspace.StreamingMinRadius = 64
workspace.StreamingTargetRadius = 128
- Parts outside the radius are
nilon the client — always guard withif part then. - Set
Model.LevelOfDetail = Disabledon models that must always be present. - Pre-stream an area before a cutscene or teleport:
workspace:RequestStreamAroundAsync(targetPosition, 5) -- 5s timeout
Hot-Path Loop Optimization
RunService.Heartbeat and RenderStepped fire every frame (~60×/sec). Keep them lean.
Bad — searching the hierarchy every frame
RunService.Heartbeat:Connect(function()
local char = workspace:FindFirstChild(player.Name)
local humanoid = char and char:FindFirstChild("Humanoid")
if humanoid then humanoid.WalkSpeed = 16 end
end)
Good — cache references once, do work only when needed
local humanoid = nil
Players.LocalPlayer.CharacterAdded:Connect(function(char)
humanoid = char:WaitForChild("Humanoid")
end)
RunService.Heartbeat:Connect(function(dt)
if not humanoid then return end
humanoid.WalkSpeed = 16 -- cached reference, no search
end)
Rules:
- Cache
game:GetService()and part references outside the loop. - Never call
FindFirstChild,GetChildren, orGetDescendantsinside Heartbeat. - Throttle work that doesn't need every frame:
local TICK_INTERVAL = 0.5
local elapsed = 0
RunService.Heartbeat:Connect(function(dt)
elapsed += dt
if elapsed < TICK_INTERVAL then return end
elapsed = 0
-- expensive work here, runs 2×/sec instead of 60×/sec
end)
task Library vs Legacy Scheduler
Always use task — wait() and spawn() throttle under load and are deprecated.
| Legacy | Modern |
|---|---|
wait(n) | task.wait(n) |
spawn(fn) | task.spawn(fn) |
delay(n, fn) | task.delay(n, fn) |
coroutine.wrap(fn)() | task.spawn(fn) |
Object Pooling
Reuse instances instead of creating and destroying them every frame.
-- ObjectPool ModuleScript
local ObjectPool = {}
ObjectPool.__index = ObjectPool
function ObjectPool.new(template, initialSize)
local self = setmetatable({ _template = template, _available = {} }, ObjectPool)
for i = 1, initialSize do
local obj = template:Clone()
obj.Parent = nil
table.insert(self._available, obj)
end
return self
end
function ObjectPool:Get(parent)
local obj = table.remove(self._available) or self._template:Clone()
obj.Parent = parent
return obj
end
function ObjectPool:Return(obj)
obj.Parent = nil
table.insert(self._available, obj)
end
return ObjectPool
-- Usage
local pool = ObjectPool.new(ReplicatedStorage.Bullet, 20)
local function fireBullet(origin)
local bullet = pool:Get(workspace)
bullet.CFrame = CFrame.new(origin)
task.delay(3, function() pool:Return(bullet) end)
end
Level of Detail (LOD)
Built-in: Set Model.LevelOfDetail = Automatic — engine merges distant parts into an imposter mesh automatically.
Manual distance-based LOD:
-- LocalScript
local INTERVAL = 0.2
local LOD_DISTANCE = 150
local elapsed = 0
RunService.Heartbeat:Connect(function(dt)
elapsed += dt
if elapsed < INTERVAL then return end
elapsed = 0
local dist = (workspace.CurrentCamera.CFrame.Position - model.PrimaryPart.Position).Magnitude
local visible = dist < LOD_DISTANCE
for _, v in model:GetDescendants() do
if v:IsA("BasePart") then
v.LocalTransparencyModifier = visible and 0 or 1
end
end
end)
Reducing Draw Calls
- Merge parts that share a material into one MeshPart (export from Blender as
.fbx). - MeshParts batch better than CSG Unions (Unions re-triangulate at runtime).
- Reuse materials — 10 parts sharing
SmoothPlasticcosts far less than 10 unique textures. - Use
TextureIdon a single MeshPart instead of stacking Decals on many parts.
Profiling with MicroProfiler
- Press
Ctrl+F6in-game to open MicroProfiler. - Press
Ctrl+Pto pause and inspect a single frame. - Look for wide bars in
heartbeatSignal(Lua),physicsStepped(physics), orrender(GPU). - Label your own code:
RunService.Heartbeat:Connect(function()
debug.profilebegin("MySystem")
-- your code
debug.profileend()
end)
Common FPS Killers
| Cause | Fix |
|---|---|
| Thousands of individual parts | Merge into MeshParts |
| Unanchored static geometry | Anchored = true on anything that never moves |
Many PointLight / SpotLight instances | Limit to ~10–20 dynamic lights per area |
| High-rate ParticleEmitters | Lower Rate and Lifetime; disable when off-screen |
wait() under heavy load | Replace with task.wait() |
FindFirstChild chains inside Heartbeat | Cache on load |
| StreamingEnabled off on large maps | Enable it |
Model.LevelOfDetail = Disabled everywhere | Use Automatic where safe |
Common Mistakes
| Mistake | Fix |
|---|---|
workspace:FindFirstChild every frame | Cache reference on character/model load |
| Destroying and re-creating bullets/effects | Use an object pool |
wait() in tight loops | task.wait() |
| All parts with unique materials | Standardize to a small set of shared materials |
| ParticleEmitters enabled off-screen | Disable Enabled when particle source is not visible |
| Physics on decorative parts | Anchored = true |
FAQ
What does the roblox-performance skill do?
Use when optimizing a Roblox game for better frame rates, reducing lag, improving server or client performance, diagnosing FPS drops, handling large worlds, or when asked about streaming, draw calls, object pooling, LOD, MicroProfiler, or expensive loop operations.
How do I install roblox-performance?
Run npx skills add https://github.com/sentinelcore/roblox-skills --skill roblox-performance in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/roblox-performance/ (personal) or .claude/skills/roblox-performance/ (project).
Which AI agents can use roblox-performance?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is roblox-performance safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains roblox-performance?
It is published by sentinelcore in sentinelcore/roblox-skills. It has 831 recorded installs.
More from sentinelcore/roblox-skills
roblox-gui
sentinelcore/roblox-skills
Use when building, animating, or debugging Roblox GUI elements including HUDs, menus, world-space UI, and player labels. Triggers on: ScreenGui setup, SurfaceGui or BillboardGui placement, UDim2 sizing questions, TweenService UI animations, responsive scaling, LocalScript GUI logic, ResetOnSpawn issues, or any Frame/TextLabel/ImageButton layout work.
roblox-animations
sentinelcore/roblox-skills
Use when working with Roblox animation systems including playing, stopping, or blending animations on Humanoid characters or non-Humanoid models, handling AnimationTrack events, replacing default character animations, or debugging animation priority and blending issues.
roblox-security
sentinelcore/roblox-skills
Use when writing Roblox game scripts that handle player actions, currencies, stats, damage, or any RemoteEvent/RemoteFunction communication. Use when reviewing code for exploitable patterns, implementing anti-cheat logic, validating client requests on the server, or setting up rate limiting.
roblox-datastores
sentinelcore/roblox-skills
Use when implementing player data persistence in Roblox, saving/loading player stats or inventory, building leaderboards with ordered datastores, handling data migration between versions, diagnosing data loss issues, or adding auto-save and shutdown-safe data handling with DataStoreService.
roblox-remote-events
sentinelcore/roblox-skills
Use when implementing client-server communication in Roblox, firing events between LocalScripts and Scripts, passing data across the network boundary, syncing game state, or defending against exploits that abuse RemoteEvents or RemoteFunctions.
roblox-monetization
sentinelcore/roblox-skills
Use when developing Roblox games or experiences and need to earn Robux through Game Passes, Developer Products, UGC avatar items, or Premium Payouts — covers both Studio scripting and Creator Hub dashboard setup.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.