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

Label your own code in the MicroProfiler and memory views:

--!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.

--!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

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; MeshParts 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:

--!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.

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).