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)


Not sure why you are using a pcall there since it can’t error, BasePart has .CastShadow

Secondly, correct me if I’m wrong however disabling Lighting.GlobalShadows is probably the same as Disabling CastShadow on all BaseParts, please let me know.

Overall it’s a great tutorial, I just wanted to point out some thing I noticed just incase I can learn something from it

This isn’t what I propose in my article. I mention that you can select parts to enabled .CastShadow so you can still make use of the Lighting that you have enabled. Completely disabling that is quite useless.

And my code shouldn’t even be an issue, I don’t know why you go after that to start your reply.

You shouldn’t be showing bad coding examples, new and inexperience Scripters will be mislead.

Be reminded that you are posting in #resources, your examples should be the best possible

You also did game:GetService(“Workspace”), instead of workspace and using index instead of _ for a variable that is not used, but I decided not to nitpick there.

I get that, I was only asking if it was the same, just incase some people want to disable Shadows altogether they can do it with an easier way. Is that true?

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


That’s a great point, but I also want to bring up that this should be documented. I’m glad you shared this information with me so I can further my own use cases with the Micro Profiler, but is there any update on when the micro profiler will be documented? Knowing that the GPU timeline can be unreliable is definitely something I haven’t heard elsewhere. All of what I know from the micro profiler has been primarily me just playing around with it & pushing the engine to it’s limits and watching the profiler react to that (lighting being my most obvious use case).

As a developer who regularly uses this tool, it would help a ton if there was documentation that revolved around these little details & letting us know what each timeline provided and how accurate it can be to trust. This[1] has[2] been[3] requested[4] numerous times now, and even been mentioned that there would be documentation released back in May (below) with no further updates.

This is actually hilarious timing because just yesterday I published the update to the article, but didn’t announce it yet. Having some image asset issues with it, but the content is there.

(It now covers standard use of the MicroProfiler, but it doesn’t go too into depth on strategies for diagnosing performance issues or addressing them. That is for a different article.)

Update 1 hour later: the assets are working properly on the page! What was published yesterday is visible now.


First, Happy birthday, second, this is awesome! I absolutely love this, and will be super excited for the next article. Thanks for creating this, many users on the platform are definitely going to be using this such as me, and I’ll be linking this around to help out others.


Thanks! :cake:

To be fully transparent, we’ve got content for a good portion of Task Scheduler activity (seen in MicroProfiler timeline labels), but we’re not all there yet. There’s just a ton of them to talk about, plus we’re aiming to have strong recommendations for certain labels getting a bit too fat. Obviously, it’s a complicated topic that has a lot of nuance many cases. I would’ve liked all this to come with the base MicroProfiler page update, but one had to come before the other.

It’s that, and we’re actively trying to find the best way to present it on the page in the most useful way.


That is true, but on Roblox automatically changes the lighting technology to Voxel on low graphics quality settings. Players with lower-end devices should be turning their graphics quality to low, so ShadowMap vs. Voxel isn’t a good argument (there’s no difference if you have your graphics quality down).

But the rest of the tutorial is very useful. I had no idea how microprofiler worked before reading this.