Debugging & Optimizing the Microprofiler for Lighting


With no documentation on the microprofiler that details any issues you may come up with, I decided to create a post with everything I have learned with the Microprofile and Lighting. Within this topic, you will find out what may be causing lag in your game, how you can fix & optimize the issues, and prevent further incidents in the future. I highly suggest reading the entire article before you reply or jump around without reading everything.

Using the Microprofiler

Many of you probably have never heard or seen the microprofiler before, or maybe you have! To view the microprofiler, you can launch a game and open your settings. Under the “Settings” tab you will see a setting titled “Micro Profiler”. Turn this on.
Pro tip: you can also use Ctrl + F6 to toggle this.

You have now enabled the Microprofiler! Do not fear this scary topbar, this is your framerate to show consistency & jumps within the frames. Larger spikes means that frame took longer to process than other frames (bad), so we should aim to resolve this.

From here, launch the Detailed Microprofiler mode, seen in the top left. The text is tiny, so you may need to squint!

This will open up a larger, scarier screen than before. This screen displays all the information you need about the frames being rendered. This looks like a mess, seen in this gif:

As you can see, we cannot read this at all. Let’s pause this menu, located in the top bar.
Pro tip: you can enable this with Ctrl + P to pause/unpause.

Excellent! Now that we have the Microprofiler paused, let’s click on a large spike in the microprofiler. This will move the entire profiler to view that entire frame, super useful!

You now know how to open and view the profiler.

Diagnosing your Issues

Starting from when we selected a large spike frame, we can diagnose to see whether this is a script related problem or a lighting one. I will be detailing the lighting issues that may arise while debugging and developing.

Roblox uses multiple Lighting Technology options that you can select from in the Lighting service in your game explorer. The biggest issues with lighting are typically found within ShadowMap and Future. Both of these Technologies are very intense and provide beautiful lighting, but what happens when they’re the main source of lag?


Let’s assume you have ShadowMap enabled, probably my least favorite Lighting Tech and the main reason why this thread has been created. As a developer, you’re probably wondering why this technology would be lagging your game. Well, in short, we can determine whether or not Lighting is an issue by opening the Micro Profiler and selecting a frame spike to view the detailed information.

Looking at this frame, we can see there’s an awfully large blue line that seems to be rendering much slower than other frames. This is the lighting being updated & recalculated. Hovering over the blue line will show you something similar to this:

This line alone can help you figure out if it’s lighting, but we should also look at the other lines beneath this. These lines are all linked to the Roblox engine rendering the Lighting. These following lines are also based on the environment, with Shadows being the most obvious line (orange) showing a larger line. There’s two main issues that could have caused this, those being listed below:

Issue #1: Scripts

The largest culprit of issues your game could be a script. As we know, Roblox updates the Lighting to match the world & cast the appropriate shadows. You may be lagging because there’s a script (like a Day/Night script) that updates the position of the sun, forcing Roblox to redraw the lighting a bunch of times too fast. Try disabling these scripts & watch the performance of your game jump!

Scripts that influence the game and force Roblox to redraw the lighting are bad, since you will have severe performance loses just for an aesthetic. This can be great for Showcases, but not for games. Most players have lower end devices on Roblox, and we should optimize our games to run as smooth as they can for all devices!

This may have resolved your issues! If it didn’t, keep reading.

Issue #2: Part.CastShadow

This is probably the most common reason why your game may be lagging. By default, every part & mesh inserted into Roblox has the property Part.CastShadow enabled. This is bad, since you are now drawing a shadow for every single part in your game unless you optimize it by disabling CastShadow and then only enabling it for parts that need it, like a roof for example.
To resolve any issues, go ahead and disable any BasePart in your game by either manually selecting each piece and disabling the CastShadow property in the properties window, or run this in your command bar to quickly disable every part with CastShadow:

for index,obj in pairs(game:GetService('Workspace'):GetDescendants()) do
	if obj:IsA('BasePart') then
			obj.CastShadow = false

Optional Solution

If all else fails, change your Lighting Technology to Voxel (my recommended favorite) for best performance gains. This is the best performant lighting that provides the best shadows for the lowest cost of performance, and works exceedingly well.


This post should have helped you resolve any issues with your game being laggy due to Lighting. If you are still having issues, I suggest making a bug report to bring more awareness to the Micro Profiler and what we can do to learn to diagnose the profiler more in-depth.

You can view the game I used here:
(Map & Day/Night script pulled from Toolbox, I do not own any of these assets)


A Roblox Staff member posted a reply to my thread on the DevForum:

one thing to note is that gpu timeline of microprofile captures is not always reliable. the second thing is gpu timeline is only important if the frame is gpu limited otherwise you should be looking at cpu performance

Keep this in mind while working with the Micro Profiler that the GPU timeline isn’t that reliable.

1 Like

Adding onto this,

Ozzypig wrote new documentation on the microprofiler! He replied to the thread, check out his two posts here:

Here’s the new documentation (to date):

1 Like