Memory Usage

Every building and scripting component that you add to your experience consumes memory. When the memory usage reaches to the engine limits, the user's device or server may crash, so you need to actively monitor the memory usage and take actions for optimization. Developer Console provides two tools for monitoring memory usage, including:

• Memory — View real-time memory consumption by usage categories, including memory usage by both your custom components and the engine internal processes.

• Luau Heap — Create snapshots on the heap memory, which refers to the memory allocation to your scripts. This tool provides various memory allocation views to help you identify current memory allocation and issues from different perspectives, such as object types and engine classes. It also allows you to create multiple snapshots to compare differences in memory usage over time.

Opening Developer Console

You can open Developer Console during a testing or live experience session using any of the following ways:

• Press F9.
• Type /console into the chat.
• Use the in-experience menu:

  1. Open the in-experience Roblox Menu.

     

  2. Select the Settings tab.

  3. Scroll down to Developer Console and click Open.

Memory

The Memory tool categorizes and displays real-time memory usage. It displays memory usage in MB of each category and generates a chart on usage change over time.

To view memory allocation:

1. Open Developer Console.

2. Expand the tools dropdown to select Memory.

   

3. Expand the client-server dropdown to select Client or Server.

4. Browse the memory usage categories and items. For categories or items that you want to see the over-time usage pattern, expand the category to display the chart.

   • CoreMemory — Memory usage by the core building processes of the engine, including networking, avatars, and GUI (Graphical User Interface) elements that you don't have direct control over.

   • PlaceMemory — Memory usage based on how you build your experience, including models, terrain, parts, scripts, and all other custom elements that you add to your experience.

     PlaceMemory Reference

     Category	Description
     HttpCache	Assets (images, meshes, etc.) loaded from Roblox servers and now held in a cache in memory.
     Instances	Instances in the place.
     Signals	Signals that fire between instances (an event firing on one instance to trigger an event on another instance).
     LuaHeap	Heap memory for both core scripts (scripts that ship with the Roblox client) and custom scripts.
     Script	Lua Scripts.
     PhysicsCollision	Collision data for physics simulations.
     PhysicsParts	Physics geometry and kinetics.
     GraphicsSolidModels	Graphics data to render solid models.
     GraphicsMeshParts	Graphics for MeshPart objects.
     GraphicsParticles	Graphics for particle systems.
     GraphicsParts	Graphics for parts.
     GraphicsSpatialHash	General rendering.
     GraphicsTerrain	Graphics for terrain.
     GraphicsTexture	Texture memory.
     GraphicsTextureCharacter	Texture memory for characters.
     Sounds	In-memory sounds.
     StreamingSounds	Streaming sounds.
     TerrainVoxels	Terrain voxels.
     TerrainPhysics	Terrain physics.
     Gui	Memory used by common GUI elements.
     Animation	Memory used for animation data, such as poses and KeyframeSequence cached data for avatar animations.
     Navigation	Memory used by supporting structures for PathfindingService.

   • UntrackedMemory — Memory allocations that the system can't easily attribute to a particular source.

   • PlaceScriptMemory — Memory usage of your scripts with insights into how individual scripts and custom memory tags contribute to overall memory usage.

   • CoreScriptMemory — Memory usage by internal engine scripts that you don't have direct control over.

   Among these categories, PlaceMemory and PlaceScriptMemory are the most important ones for performance optimization, because they help you understand how your building and scripting choices affect memory consumption and potential areas for optimization. For more insights into PlaceScriptMemory, you can use the Luau Heap tool to create snapshots and analyze memory allocation by different metrics.

Luau Heap

The Luau Heap tool allows you to create snapshots on the current allocation of heap memory, which refers to the memory allocation to Luau scripts for storing variables, tables, functions, and other runtime data structures. This tool provides various memory allocation views to help you identify memory allocation and issues from different perspectives, such as object types and engine classes. It also allows you to create multiple snapshots to compare differences in memory usage over time.

Creating Snapshots

To create a snapshot of your memory allocation:

1. Open Developer Console.

2. Expand the tools dropdown to select LuauHeap.

   

3. Expand the client-server dropdown to select Client or Server.

4. Click the Create Snapshot button.

Analyzing Memory Usage

The tool provides five views that you can select from to view your Luau memory allocation based on different views:

• Graph — Shows an aggregated memory usage tree with each node representing an object with memory allocated.
• Object Tags — Shows memory sizes and counts by runtime types, such as function, table, and thread.
• Memory Categories — Shows memory sizes and counts by the engine-assigned memory categories. The engine assigns a memory category to an object at allocation time.
• Object Classes — Shows memory sizes and counts by engine classes that your scripts use and store their instances, such as EnumItem, Animation, CFrame.
• Unique References — Shows counts and total numbers of instances that don't have a parent in the data model and are only reachable by scripts, along with all paths that pin the instance object.

Graph

The Graph view is the most detailed and complex view among all Luau Heap views. It shows an aggregated memory usage tree with each node representing an object with memory allocated. The tree shows how objects connect to each other and derives the shortest path between object references. It has the following columns of memory size: Size — The self memory usage plus the memory usage by contents within the data structure. Self — The memory directly allocated for the data structure itself, excluding the memory usage by any content it contains.

The root of the tree graph is registry, which stores all engine and Luau references, such as functions connected to signals or the task library, tables returned by module scripts, and global functions, tables and classes. It usually parents the following common entries:

• Module @Path.To.Module is the table returned by a module script.
• name:123 =Path.To.Module is a function inside a specified script. Anonymous functions don't have names. The top level node often refers to the global script function. Anonymous functions don't have names. Example: :1= Workspace.[Username].Animate.
• upvalue is a reference for captured functions. See Capturing Local Scope for more information.
• env refers to the environment of a function. For most cases, it's a table representing the global scope of a script.
• globals refers to the environment of a thread.
• [key] represents objects that serve as table keys.
• array represents an array.
• stack refers to the array that stores all function locals.
• constants represents all constant values that functions use.

Memory Categories

The Memory Categories view shows memory sizes and counts by memory categories, which the engine assigns to objects at allocation time. By default, the memory category has the same name as the script, or you can assign custom memory category names using the debug.setmemorycategory function.

Unique References

The Unique References view shows memory usage of instances that don't have a parent in the data model and are only reachable by scripts, along with all paths that pin the instance object. This view has two metrics:

• Count — Shows the number of instances with the same name that are reachable from the same path, such as multiple instances named Dragon in the same table.
• Total Instances — Shows the total number of objects inside those roots, such as all parts, scripts, and sound objects that construct a Dragon instance.

This view is useful for identifying unnecessary connected instances, which you need to disconnect when you no longer need them. If you see many unexpected instances in this view, check out the paths holding them and evaluate whether they are necessary.