How to find and fix memory leaks on Roblox transcript

This video covers memory leaks in Roblox experiences, what they are, identifying them, and avoiding them in the first place. Let's dive in. Hi everyone, it's Andrew from Roblox. Memory leaks occur when programs allocate memory to run some code, but then fail to release that memory after it's no longer needed. This causes memory usage to grow over time, sometimes quickly, sometimes slowly. Memory leaks are one of those classic problems in programming, even in languages with built-in garbage collection like Luau.

When a leak causes the Roblox server or client to run out of memory, well, you get a crash. In fact, lack of memory is the most common cause of crashes on Roblox today. You might be asking which is worse, a server crash or a client crash. And like so many things in this world, the unfortunate answer is that it depends. If the server runs out of memory and crashes, it disconnects all players. If the client runs out of memory and crashes, it only affects the one player.

So, in that sense, at least, a server leak is worse. However, the server starts at 6.25 GB of memory and goes up from there based on player count, which can make it more tolerant to leaks than a low-end mobile device. An old phone might only have 2 GB of memory, 700 megabytes of which is already in use by the operating system and background processes. To further complicate matters, not all leaks are the same. The simplest type of memory leak is just more and more memory usage for the lifespan of the application, such as the server adding data to a table each time a player joins the game. and not cleaning it up when they leave.

Usage grows over time, even as the garbage collector periodically reclaims memory through normal operations. Depending on where they occur in your code, though, leaks can be a problem not because they never get cleaned up, but because they don't get cleaned up quickly enough. Consider this more complex example. You have a round-based game. The server leaks memory for the duration of each round, and the memory is eventually reclaimed when the round resets.

If rounds are short or the leak is small, you might never notice. But if rounds last for an undefined duration, such as until an objective is met, or maybe the size of the leak varies based on what's happening in game, you can run into hard to isolate crashes. Peak memory usage could usually be below the limit until it isn't. As my crude graphs suggest, identifying memory leaks requires precise, detailed information over time.

The performance dashboard is great for providing aggregated information, but might not be granular enough for troubleshooting. Likewise, the memory tab in the developer console is awesome, but only shows a graph for a short duration. It can be hard to spot trends unless they're quite extreme. For troubleshooting memory leaks, the best option is the Luau heap tab in the developer console. You can take detailed snapshots of memory usage at this very moment.

We'll wait a bit, take another snapshot, and then compare the two. Take a handful of snapshots. Take dozens. The tool is incredibly powerful though, so sorting through the heaps of information can be a bit daunting. To use the tool, press F9 and choose Luo Heap. First, you can take snapshots on either the server or the client. Here, I have a few server snapshots. Choose your baseline snapshot and then hit compare on the snapshot you want to compare it against.

Negative numbers are colored green, aka good, indicating memory usage is down compared to the other snapshot. Positive numbers are red, indicating you're using more memory. All numbers are in bytes, so it's very granular. The default tab, the graph tab, is the most complex of them all. It shows a tree view of how objects are linked to each other within the Lua virtual machine registry, which is the top item in the graph.

When it comes to interpreting the meaning of each row, there are a few important ones. Function name, line, and script can help you identify particular functions in your code. Module at path is the value returned by the particular module script. Up value indicates a reference to a variable outside of the function. Self is the size of well the element itself. Size includes the memory used by each element in the table.

So self is always less than or equal to size. Armed with this knowledge, we know we're looking for a problematic up value in the leak memory function of leak script. Sure enough, there's an ever growing table outside of the function. We can also see a large block of allocated memory from the leak module module script. And indeed, the return value here is comically large. Back to the user interface, the other views are simpler.

Object tags lets you see memory usage by luau type, which is probably dominated by tables and functions. Memory category gives you a breakdown by script name, which is an excellent starting point for an investigation. You can also use the debug set memory category method to subdivide threads within the same script that would ordinarily be grouped together. Object classes is what it sounds like with a big caveat. This tab shows the memory taken up by the Roblox engine classes inside the Lua VM, not inside the engine.

So if the numbers seem suspiciously low, they are. As such, the utility of this tab is a bit limited. Moving on, the final two tabs are related. Both show instances referenced by the Luau VM that aren't parented to the data model. The unique references tab shows instances that are only referenced by Luo scripts and aren't held by any Roblox system. You can see here that I've created a UI, not parented it to anything, and held on to it for a while.

It shows up in this tab until the garbage collector cleans it up when the script finishes running. The other tab shows unparented instances that weren't included under unique references. Just like the rest of Luo heap, if we expand the row, the tool is pretty explicit about where this memory usage is coming from. You can see here that I have a player mouse instance that the VM is hanging on to since I stuck the event into run service.

If I move the code and restart, it no longer shows up. There's a critical caveat to this entire video. Code has to be loaded into memory to run. So memory usage going up is not a problem. It's supposed to go up. What it's not supposed to do is never go down. In fact, healthy memory usage often presents as a sawtooth pattern. When you use the Luo heap tool to take snapshots and investigate memory usage, you're looking for trends over time, high watermarks, or situations which memory goes up unexpectedly.

Staring at this screen and trying to claw back every bite of memory cuz you think it could have been garbage collected a moment earlier just isn't productive. As Owen put it so eloquently in our performance optimization video, you have to stay focused on the big picture. In Roblox experiences, there are a couple situations in which memory leaks pop up again and again. Connecting functions but never disconnecting them and adding data to tables but never removing it.

Active connections of events and code inside the connected instances, connected functions, and referenced values are out of scope for the garbage collector even after the events are fired. Make sure you run disconnect on the connection, destroy on the instance the event belongs to, or destroy the object that the connection traces back to. Although events are disconnected when the instance they belong to is destroyed, this doesn't necessarily apply to player objects.

Consider enabling the workspace player character destroy behavior property so that player objects and character models are automatically destroyed after players leave an experience. You can also clean them up manually like so. Not properly handling players and characters can result in very significant server memory leaks over time as thousands of users join and leave the experience. So don't neglect this step. For tables, the process is similar.

If you add player data to a local table for some reason, delete that data after the player leaves, probably after writing it to a data store. Memory usage and memory leaks are a big topic. The good news is that they're a universal topic. So there is an incredible number of online resources if you want to learn more. And of course, for more information on reducing memory usage in scripts and using the Luau heap tool, check out the documentation at create.roll.com.

Thanks for watching.